ON Semiconductor / mbed-os

5.2.1 - Updated I2C files

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

hal/spi_api.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-onsemi 0:098463de4c5d 1
group-onsemi 0:098463de4c5d 2 /** \addtogroup hal */
group-onsemi 0:098463de4c5d 3 /** @{*/
group-onsemi 0:098463de4c5d 4 /* mbed Microcontroller Library
group-onsemi 0:098463de4c5d 5 * Copyright (c) 2006-2013 ARM Limited
group-onsemi 0:098463de4c5d 6 *
group-onsemi 0:098463de4c5d 7 * Licensed under the Apache License, Version 2.0 (the "License");
group-onsemi 0:098463de4c5d 8 * you may not use this file except in compliance with the License.
group-onsemi 0:098463de4c5d 9 * You may obtain a copy of the License at
group-onsemi 0:098463de4c5d 10 *
group-onsemi 0:098463de4c5d 11 * http://www.apache.org/licenses/LICENSE-2.0
group-onsemi 0:098463de4c5d 12 *
group-onsemi 0:098463de4c5d 13 * Unless required by applicable law or agreed to in writing, software
group-onsemi 0:098463de4c5d 14 * distributed under the License is distributed on an "AS IS" BASIS,
group-onsemi 0:098463de4c5d 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
group-onsemi 0:098463de4c5d 16 * See the License for the specific language governing permissions and
group-onsemi 0:098463de4c5d 17 * limitations under the License.
group-onsemi 0:098463de4c5d 18 */
group-onsemi 0:098463de4c5d 19 #ifndef MBED_SPI_API_H
group-onsemi 0:098463de4c5d 20 #define MBED_SPI_API_H
group-onsemi 0:098463de4c5d 21
group-onsemi 0:098463de4c5d 22 #include "device.h"
group-onsemi 0:098463de4c5d 23 #include "hal/dma_api.h"
group-onsemi 0:098463de4c5d 24 #include "hal/buffer.h"
group-onsemi 0:098463de4c5d 25
group-onsemi 0:098463de4c5d 26 #if DEVICE_SPI
group-onsemi 0:098463de4c5d 27
group-onsemi 0:098463de4c5d 28 #define SPI_EVENT_ERROR (1 << 1)
group-onsemi 0:098463de4c5d 29 #define SPI_EVENT_COMPLETE (1 << 2)
group-onsemi 0:098463de4c5d 30 #define SPI_EVENT_RX_OVERFLOW (1 << 3)
group-onsemi 0:098463de4c5d 31 #define SPI_EVENT_ALL (SPI_EVENT_ERROR | SPI_EVENT_COMPLETE | SPI_EVENT_RX_OVERFLOW)
group-onsemi 0:098463de4c5d 32
group-onsemi 0:098463de4c5d 33 #define SPI_EVENT_INTERNAL_TRANSFER_COMPLETE (1 << 30) // Internal flag to report that an event occurred
group-onsemi 0:098463de4c5d 34
group-onsemi 0:098463de4c5d 35 #define SPI_FILL_WORD (0xFFFF)
group-onsemi 0:098463de4c5d 36
group-onsemi 0:098463de4c5d 37 #if DEVICE_SPI_ASYNCH
group-onsemi 0:098463de4c5d 38 /** Asynch SPI HAL structure
group-onsemi 0:098463de4c5d 39 */
group-onsemi 0:098463de4c5d 40 typedef struct {
group-onsemi 0:098463de4c5d 41 struct spi_s spi; /**< Target specific SPI structure */
group-onsemi 0:098463de4c5d 42 struct buffer_s tx_buff; /**< Tx buffer */
group-onsemi 0:098463de4c5d 43 struct buffer_s rx_buff; /**< Rx buffer */
group-onsemi 0:098463de4c5d 44 } spi_t;
group-onsemi 0:098463de4c5d 45
group-onsemi 0:098463de4c5d 46 #else
group-onsemi 0:098463de4c5d 47 /** Non-asynch SPI HAL structure
group-onsemi 0:098463de4c5d 48 */
group-onsemi 0:098463de4c5d 49 typedef struct spi_s spi_t;
group-onsemi 0:098463de4c5d 50
group-onsemi 0:098463de4c5d 51 #endif
group-onsemi 0:098463de4c5d 52
group-onsemi 0:098463de4c5d 53 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 54 extern "C" {
group-onsemi 0:098463de4c5d 55 #endif
group-onsemi 0:098463de4c5d 56
group-onsemi 0:098463de4c5d 57 /**
group-onsemi 0:098463de4c5d 58 * \defgroup hal_GeneralSPI SPI Configuration Functions
group-onsemi 0:098463de4c5d 59 * @{
group-onsemi 0:098463de4c5d 60 */
group-onsemi 0:098463de4c5d 61
group-onsemi 0:098463de4c5d 62 /** Initialize the SPI peripheral
group-onsemi 0:098463de4c5d 63 *
group-onsemi 0:098463de4c5d 64 * Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral
group-onsemi 0:098463de4c5d 65 * @param[out] obj The SPI object to initialize
group-onsemi 0:098463de4c5d 66 * @param[in] mosi The pin to use for MOSI
group-onsemi 0:098463de4c5d 67 * @param[in] miso The pin to use for MISO
group-onsemi 0:098463de4c5d 68 * @param[in] sclk The pin to use for SCLK
group-onsemi 0:098463de4c5d 69 * @param[in] ssel The pin to use for SSEL
group-onsemi 0:098463de4c5d 70 */
group-onsemi 0:098463de4c5d 71 void spi_init(spi_t *obj, PinName mosi, PinName miso, PinName sclk, PinName ssel);
group-onsemi 0:098463de4c5d 72
group-onsemi 0:098463de4c5d 73 /** Release a SPI object
group-onsemi 0:098463de4c5d 74 *
group-onsemi 0:098463de4c5d 75 * TODO: spi_free is currently unimplemented
group-onsemi 0:098463de4c5d 76 * This will require reference counting at the C++ level to be safe
group-onsemi 0:098463de4c5d 77 *
group-onsemi 0:098463de4c5d 78 * Return the pins owned by the SPI object to their reset state
group-onsemi 0:098463de4c5d 79 * Disable the SPI peripheral
group-onsemi 0:098463de4c5d 80 * Disable the SPI clock
group-onsemi 0:098463de4c5d 81 * @param[in] obj The SPI object to deinitialize
group-onsemi 0:098463de4c5d 82 */
group-onsemi 0:098463de4c5d 83 void spi_free(spi_t *obj);
group-onsemi 0:098463de4c5d 84
group-onsemi 0:098463de4c5d 85 /** Configure the SPI format
group-onsemi 0:098463de4c5d 86 *
group-onsemi 0:098463de4c5d 87 * Set the number of bits per frame, configure clock polarity and phase, shift order and master/slave mode.
group-onsemi 0:098463de4c5d 88 * The default bit order is MSB.
group-onsemi 0:098463de4c5d 89 * @param[in,out] obj The SPI object to configure
group-onsemi 0:098463de4c5d 90 * @param[in] bits The number of bits per frame
group-onsemi 0:098463de4c5d 91 * @param[in] mode The SPI mode (clock polarity, phase, and shift direction)
group-onsemi 0:098463de4c5d 92 * @param[in] slave Zero for master mode or non-zero for slave mode
group-onsemi 0:098463de4c5d 93 */
group-onsemi 0:098463de4c5d 94 void spi_format(spi_t *obj, int bits, int mode, int slave);
group-onsemi 0:098463de4c5d 95
group-onsemi 0:098463de4c5d 96 /** Set the SPI baud rate
group-onsemi 0:098463de4c5d 97 *
group-onsemi 0:098463de4c5d 98 * Actual frequency may differ from the desired frequency due to available dividers and bus clock
group-onsemi 0:098463de4c5d 99 * Configures the SPI peripheral's baud rate
group-onsemi 0:098463de4c5d 100 * @param[in,out] obj The SPI object to configure
group-onsemi 0:098463de4c5d 101 * @param[in] hz The baud rate in Hz
group-onsemi 0:098463de4c5d 102 */
group-onsemi 0:098463de4c5d 103 void spi_frequency(spi_t *obj, int hz);
group-onsemi 0:098463de4c5d 104
group-onsemi 0:098463de4c5d 105 /**@}*/
group-onsemi 0:098463de4c5d 106 /**
group-onsemi 0:098463de4c5d 107 * \defgroup SynchSPI Synchronous SPI Hardware Abstraction Layer
group-onsemi 0:098463de4c5d 108 * @{
group-onsemi 0:098463de4c5d 109 */
group-onsemi 0:098463de4c5d 110
group-onsemi 0:098463de4c5d 111 /** Write a byte out in master mode and receive a value
group-onsemi 0:098463de4c5d 112 *
group-onsemi 0:098463de4c5d 113 * @param[in] obj The SPI peripheral to use for sending
group-onsemi 0:098463de4c5d 114 * @param[in] value The value to send
group-onsemi 0:098463de4c5d 115 * @return Returns the value received during send
group-onsemi 0:098463de4c5d 116 */
group-onsemi 0:098463de4c5d 117 int spi_master_write(spi_t *obj, int value);
group-onsemi 0:098463de4c5d 118
group-onsemi 0:098463de4c5d 119 /** Check if a value is available to read
group-onsemi 0:098463de4c5d 120 *
group-onsemi 0:098463de4c5d 121 * @param[in] obj The SPI peripheral to check
group-onsemi 0:098463de4c5d 122 * @return non-zero if a value is available
group-onsemi 0:098463de4c5d 123 */
group-onsemi 0:098463de4c5d 124 int spi_slave_receive(spi_t *obj);
group-onsemi 0:098463de4c5d 125
group-onsemi 0:098463de4c5d 126 /** Get a received value out of the SPI receive buffer in slave mode
group-onsemi 0:098463de4c5d 127 *
group-onsemi 0:098463de4c5d 128 * Blocks until a value is available
group-onsemi 0:098463de4c5d 129 * @param[in] obj The SPI peripheral to read
group-onsemi 0:098463de4c5d 130 * @return The value received
group-onsemi 0:098463de4c5d 131 */
group-onsemi 0:098463de4c5d 132 int spi_slave_read(spi_t *obj);
group-onsemi 0:098463de4c5d 133
group-onsemi 0:098463de4c5d 134 /** Write a value to the SPI peripheral in slave mode
group-onsemi 0:098463de4c5d 135 *
group-onsemi 0:098463de4c5d 136 * Blocks until the SPI peripheral can be written to
group-onsemi 0:098463de4c5d 137 * @param[in] obj The SPI peripheral to write
group-onsemi 0:098463de4c5d 138 * @param[in] value The value to write
group-onsemi 0:098463de4c5d 139 */
group-onsemi 0:098463de4c5d 140 void spi_slave_write(spi_t *obj, int value);
group-onsemi 0:098463de4c5d 141
group-onsemi 0:098463de4c5d 142 /** Checks if the specified SPI peripheral is in use
group-onsemi 0:098463de4c5d 143 *
group-onsemi 0:098463de4c5d 144 * @param[in] obj The SPI peripheral to check
group-onsemi 0:098463de4c5d 145 * @return non-zero if the peripheral is currently transmitting
group-onsemi 0:098463de4c5d 146 */
group-onsemi 0:098463de4c5d 147 int spi_busy(spi_t *obj);
group-onsemi 0:098463de4c5d 148
group-onsemi 0:098463de4c5d 149 /** Get the module number
group-onsemi 0:098463de4c5d 150 *
group-onsemi 0:098463de4c5d 151 * @param[in] obj The SPI peripheral to check
group-onsemi 0:098463de4c5d 152 * @return The module number
group-onsemi 0:098463de4c5d 153 */
group-onsemi 0:098463de4c5d 154 uint8_t spi_get_module(spi_t *obj);
group-onsemi 0:098463de4c5d 155
group-onsemi 0:098463de4c5d 156 /**@}*/
group-onsemi 0:098463de4c5d 157
group-onsemi 0:098463de4c5d 158 #if DEVICE_SPI_ASYNCH
group-onsemi 0:098463de4c5d 159 /**
group-onsemi 0:098463de4c5d 160 * \defgroup AsynchSPI Asynchronous SPI Hardware Abstraction Layer
group-onsemi 0:098463de4c5d 161 * @{
group-onsemi 0:098463de4c5d 162 */
group-onsemi 0:098463de4c5d 163
group-onsemi 0:098463de4c5d 164 /** Begin the SPI transfer. Buffer pointers and lengths are specified in tx_buff and rx_buff
group-onsemi 0:098463de4c5d 165 *
group-onsemi 0:098463de4c5d 166 * @param[in] obj The SPI object that holds the transfer information
group-onsemi 0:098463de4c5d 167 * @param[in] tx The transmit buffer
group-onsemi 0:098463de4c5d 168 * @param[in] tx_length The number of bytes to transmit
group-onsemi 0:098463de4c5d 169 * @param[in] rx The receive buffer
group-onsemi 0:098463de4c5d 170 * @param[in] rx_length The number of bytes to receive
group-onsemi 0:098463de4c5d 171 * @param[in] bit_width The bit width of buffer words
group-onsemi 0:098463de4c5d 172 * @param[in] event The logical OR of events to be registered
group-onsemi 0:098463de4c5d 173 * @param[in] handler SPI interrupt handler
group-onsemi 0:098463de4c5d 174 * @param[in] hint A suggestion for how to use DMA with this transfer
group-onsemi 0:098463de4c5d 175 */
group-onsemi 0:098463de4c5d 176 void spi_master_transfer(spi_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint8_t bit_width, uint32_t handler, uint32_t event, DMAUsage hint);
group-onsemi 0:098463de4c5d 177
group-onsemi 0:098463de4c5d 178 /** The asynchronous IRQ handler
group-onsemi 0:098463de4c5d 179 *
group-onsemi 0:098463de4c5d 180 * Reads the received values out of the RX FIFO, writes values into the TX FIFO and checks for transfer termination
group-onsemi 0:098463de4c5d 181 * conditions, such as buffer overflows or transfer complete.
group-onsemi 0:098463de4c5d 182 * @param[in] obj The SPI object that holds the transfer information
group-onsemi 0:098463de4c5d 183 * @return Event flags if a transfer termination condition was met; otherwise 0.
group-onsemi 0:098463de4c5d 184 */
group-onsemi 0:098463de4c5d 185 uint32_t spi_irq_handler_asynch(spi_t *obj);
group-onsemi 0:098463de4c5d 186
group-onsemi 0:098463de4c5d 187 /** Attempts to determine if the SPI peripheral is already in use
group-onsemi 0:098463de4c5d 188 *
group-onsemi 0:098463de4c5d 189 * If a temporary DMA channel has been allocated, peripheral is in use.
group-onsemi 0:098463de4c5d 190 * If a permanent DMA channel has been allocated, check if the DMA channel is in use. If not, proceed as though no DMA
group-onsemi 0:098463de4c5d 191 * channel were allocated.
group-onsemi 0:098463de4c5d 192 * If no DMA channel is allocated, check whether tx and rx buffers have been assigned. For each assigned buffer, check
group-onsemi 0:098463de4c5d 193 * if the corresponding buffer position is less than the buffer length. If buffers do not indicate activity, check if
group-onsemi 0:098463de4c5d 194 * there are any bytes in the FIFOs.
group-onsemi 0:098463de4c5d 195 * @param[in] obj The SPI object to check for activity
group-onsemi 0:098463de4c5d 196 * @return Non-zero if the SPI port is active or zero if it is not.
group-onsemi 0:098463de4c5d 197 */
group-onsemi 0:098463de4c5d 198 uint8_t spi_active(spi_t *obj);
group-onsemi 0:098463de4c5d 199
group-onsemi 0:098463de4c5d 200 /** Abort an SPI transfer
group-onsemi 0:098463de4c5d 201 *
group-onsemi 0:098463de4c5d 202 * @param obj The SPI peripheral to stop
group-onsemi 0:098463de4c5d 203 */
group-onsemi 0:098463de4c5d 204 void spi_abort_asynch(spi_t *obj);
group-onsemi 0:098463de4c5d 205
group-onsemi 0:098463de4c5d 206
group-onsemi 0:098463de4c5d 207 #endif
group-onsemi 0:098463de4c5d 208
group-onsemi 0:098463de4c5d 209 /**@}*/
group-onsemi 0:098463de4c5d 210
group-onsemi 0:098463de4c5d 211 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 212 }
group-onsemi 0:098463de4c5d 213 #endif // __cplusplus
group-onsemi 0:098463de4c5d 214
group-onsemi 0:098463de4c5d 215 #endif // SPI_DEVICE
group-onsemi 0:098463de4c5d 216
group-onsemi 0:098463de4c5d 217 #endif // MBED_SPI_API_H
group-onsemi 0:098463de4c5d 218
group-onsemi 0:098463de4c5d 219 /** @}*/