Thomas Lyp / DevLibMemoryController

Initial commit

Dependencies:   FastPWM

mbed-dev-master/hal/spi_api.h@0:bb348c97df44, 2020-09-16 (annotated)

Committer:
lypinator
Date:
Wed Sep 16 01:11:49 2020 +0000
Revision:
0:bb348c97df44
Added PWM

Who changed what in which revision?

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