Simon Cooksey / mbed-os

Pinned to some recent date

drivers/SPI.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Simon Cooksey 0:fb7af294d5d9 1 /* mbed Microcontroller Library
Simon Cooksey 0:fb7af294d5d9 2 * Copyright (c) 2006-2015 ARM Limited
Simon Cooksey 0:fb7af294d5d9 3 *
Simon Cooksey 0:fb7af294d5d9 4 * Licensed under the Apache License, Version 2.0 (the "License");
Simon Cooksey 0:fb7af294d5d9 5 * you may not use this file except in compliance with the License.
Simon Cooksey 0:fb7af294d5d9 6 * You may obtain a copy of the License at
Simon Cooksey 0:fb7af294d5d9 7 *
Simon Cooksey 0:fb7af294d5d9 8 * http://www.apache.org/licenses/LICENSE-2.0
Simon Cooksey 0:fb7af294d5d9 9 *
Simon Cooksey 0:fb7af294d5d9 10 * Unless required by applicable law or agreed to in writing, software
Simon Cooksey 0:fb7af294d5d9 11 * distributed under the License is distributed on an "AS IS" BASIS,
Simon Cooksey 0:fb7af294d5d9 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Simon Cooksey 0:fb7af294d5d9 13 * See the License for the specific language governing permissions and
Simon Cooksey 0:fb7af294d5d9 14 * limitations under the License.
Simon Cooksey 0:fb7af294d5d9 15 */
Simon Cooksey 0:fb7af294d5d9 16 #ifndef MBED_SPI_H
Simon Cooksey 0:fb7af294d5d9 17 #define MBED_SPI_H
Simon Cooksey 0:fb7af294d5d9 18
Simon Cooksey 0:fb7af294d5d9 19 #include "platform/platform.h"
Simon Cooksey 0:fb7af294d5d9 20
Simon Cooksey 0:fb7af294d5d9 21 #if DEVICE_SPI
Simon Cooksey 0:fb7af294d5d9 22
Simon Cooksey 0:fb7af294d5d9 23 #include "platform/PlatformMutex.h"
Simon Cooksey 0:fb7af294d5d9 24 #include "hal/spi_api.h"
Simon Cooksey 0:fb7af294d5d9 25 #include "platform/SingletonPtr.h"
Simon Cooksey 0:fb7af294d5d9 26
Simon Cooksey 0:fb7af294d5d9 27 #if DEVICE_SPI_ASYNCH
Simon Cooksey 0:fb7af294d5d9 28 #include "platform/CThunk.h"
Simon Cooksey 0:fb7af294d5d9 29 #include "hal/dma_api.h"
Simon Cooksey 0:fb7af294d5d9 30 #include "platform/CircularBuffer.h"
Simon Cooksey 0:fb7af294d5d9 31 #include "platform/FunctionPointer.h"
Simon Cooksey 0:fb7af294d5d9 32 #include "platform/Transaction.h"
Simon Cooksey 0:fb7af294d5d9 33 #endif
Simon Cooksey 0:fb7af294d5d9 34
Simon Cooksey 0:fb7af294d5d9 35 namespace mbed {
Simon Cooksey 0:fb7af294d5d9 36 /** \addtogroup drivers */
Simon Cooksey 0:fb7af294d5d9 37 /** @{*/
Simon Cooksey 0:fb7af294d5d9 38
Simon Cooksey 0:fb7af294d5d9 39 /** A SPI Master, used for communicating with SPI slave devices
Simon Cooksey 0:fb7af294d5d9 40 *
Simon Cooksey 0:fb7af294d5d9 41 * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz
Simon Cooksey 0:fb7af294d5d9 42 *
Simon Cooksey 0:fb7af294d5d9 43 * Most SPI devices will also require Chip Select and Reset signals. These
Simon Cooksey 0:fb7af294d5d9 44 * can be controlled using <DigitalOut> pins
Simon Cooksey 0:fb7af294d5d9 45 *
Simon Cooksey 0:fb7af294d5d9 46 * @Note Synchronization level: Thread safe
Simon Cooksey 0:fb7af294d5d9 47 *
Simon Cooksey 0:fb7af294d5d9 48 * Example:
Simon Cooksey 0:fb7af294d5d9 49 * @code
Simon Cooksey 0:fb7af294d5d9 50 * // Send a byte to a SPI slave, and record the response
Simon Cooksey 0:fb7af294d5d9 51 *
Simon Cooksey 0:fb7af294d5d9 52 * #include "mbed.h"
Simon Cooksey 0:fb7af294d5d9 53 *
Simon Cooksey 0:fb7af294d5d9 54 * // hardware ssel (where applicable)
Simon Cooksey 0:fb7af294d5d9 55 * //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
Simon Cooksey 0:fb7af294d5d9 56 *
Simon Cooksey 0:fb7af294d5d9 57 * // software ssel
Simon Cooksey 0:fb7af294d5d9 58 * SPI device(p5, p6, p7); // mosi, miso, sclk
Simon Cooksey 0:fb7af294d5d9 59 * DigitalOut cs(p8); // ssel
Simon Cooksey 0:fb7af294d5d9 60 *
Simon Cooksey 0:fb7af294d5d9 61 * int main() {
Simon Cooksey 0:fb7af294d5d9 62 * // hardware ssel (where applicable)
Simon Cooksey 0:fb7af294d5d9 63 * //int response = device.write(0xFF);
Simon Cooksey 0:fb7af294d5d9 64 *
Simon Cooksey 0:fb7af294d5d9 65 * device.lock();
Simon Cooksey 0:fb7af294d5d9 66 * // software ssel
Simon Cooksey 0:fb7af294d5d9 67 * cs = 0;
Simon Cooksey 0:fb7af294d5d9 68 * int response = device.write(0xFF);
Simon Cooksey 0:fb7af294d5d9 69 * cs = 1;
Simon Cooksey 0:fb7af294d5d9 70 * device.unlock();
Simon Cooksey 0:fb7af294d5d9 71 *
Simon Cooksey 0:fb7af294d5d9 72 * }
Simon Cooksey 0:fb7af294d5d9 73 * @endcode
Simon Cooksey 0:fb7af294d5d9 74 */
Simon Cooksey 0:fb7af294d5d9 75 class SPI {
Simon Cooksey 0:fb7af294d5d9 76
Simon Cooksey 0:fb7af294d5d9 77 public:
Simon Cooksey 0:fb7af294d5d9 78
Simon Cooksey 0:fb7af294d5d9 79 /** Create a SPI master connected to the specified pins
Simon Cooksey 0:fb7af294d5d9 80 *
Simon Cooksey 0:fb7af294d5d9 81 * mosi or miso can be specfied as NC if not used
Simon Cooksey 0:fb7af294d5d9 82 *
Simon Cooksey 0:fb7af294d5d9 83 * @param mosi SPI Master Out, Slave In pin
Simon Cooksey 0:fb7af294d5d9 84 * @param miso SPI Master In, Slave Out pin
Simon Cooksey 0:fb7af294d5d9 85 * @param sclk SPI Clock pin
Simon Cooksey 0:fb7af294d5d9 86 * @param ssel SPI chip select pin
Simon Cooksey 0:fb7af294d5d9 87 */
Simon Cooksey 0:fb7af294d5d9 88 SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel=NC);
Simon Cooksey 0:fb7af294d5d9 89
Simon Cooksey 0:fb7af294d5d9 90 /** Configure the data transmission format
Simon Cooksey 0:fb7af294d5d9 91 *
Simon Cooksey 0:fb7af294d5d9 92 * @param bits Number of bits per SPI frame (4 - 16)
Simon Cooksey 0:fb7af294d5d9 93 * @param mode Clock polarity and phase mode (0 - 3)
Simon Cooksey 0:fb7af294d5d9 94 *
Simon Cooksey 0:fb7af294d5d9 95 * @code
Simon Cooksey 0:fb7af294d5d9 96 * mode | POL PHA
Simon Cooksey 0:fb7af294d5d9 97 * -----+--------
Simon Cooksey 0:fb7af294d5d9 98 * 0 | 0 0
Simon Cooksey 0:fb7af294d5d9 99 * 1 | 0 1
Simon Cooksey 0:fb7af294d5d9 100 * 2 | 1 0
Simon Cooksey 0:fb7af294d5d9 101 * 3 | 1 1
Simon Cooksey 0:fb7af294d5d9 102 * @endcode
Simon Cooksey 0:fb7af294d5d9 103 */
Simon Cooksey 0:fb7af294d5d9 104 void format(int bits, int mode = 0);
Simon Cooksey 0:fb7af294d5d9 105
Simon Cooksey 0:fb7af294d5d9 106 /** Set the spi bus clock frequency
Simon Cooksey 0:fb7af294d5d9 107 *
Simon Cooksey 0:fb7af294d5d9 108 * @param hz SCLK frequency in hz (default = 1MHz)
Simon Cooksey 0:fb7af294d5d9 109 */
Simon Cooksey 0:fb7af294d5d9 110 void frequency(int hz = 1000000);
Simon Cooksey 0:fb7af294d5d9 111
Simon Cooksey 0:fb7af294d5d9 112 /** Write to the SPI Slave and return the response
Simon Cooksey 0:fb7af294d5d9 113 *
Simon Cooksey 0:fb7af294d5d9 114 * @param value Data to be sent to the SPI slave
Simon Cooksey 0:fb7af294d5d9 115 *
Simon Cooksey 0:fb7af294d5d9 116 * @returns
Simon Cooksey 0:fb7af294d5d9 117 * Response from the SPI slave
Simon Cooksey 0:fb7af294d5d9 118 */
Simon Cooksey 0:fb7af294d5d9 119 virtual int write(int value);
Simon Cooksey 0:fb7af294d5d9 120
Simon Cooksey 0:fb7af294d5d9 121 /** Acquire exclusive access to this SPI bus
Simon Cooksey 0:fb7af294d5d9 122 */
Simon Cooksey 0:fb7af294d5d9 123 virtual void lock(void);
Simon Cooksey 0:fb7af294d5d9 124
Simon Cooksey 0:fb7af294d5d9 125 /** Release exclusive access to this SPI bus
Simon Cooksey 0:fb7af294d5d9 126 */
Simon Cooksey 0:fb7af294d5d9 127 virtual void unlock(void);
Simon Cooksey 0:fb7af294d5d9 128
Simon Cooksey 0:fb7af294d5d9 129 #if DEVICE_SPI_ASYNCH
Simon Cooksey 0:fb7af294d5d9 130
Simon Cooksey 0:fb7af294d5d9 131 /** Start non-blocking SPI transfer using 8bit buffers.
Simon Cooksey 0:fb7af294d5d9 132 *
Simon Cooksey 0:fb7af294d5d9 133 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 134 * the default SPI value is sent
Simon Cooksey 0:fb7af294d5d9 135 * @param tx_length The length of TX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 136 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 137 * received data are ignored
Simon Cooksey 0:fb7af294d5d9 138 * @param rx_length The length of RX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 139 * @param callback The event callback function
Simon Cooksey 0:fb7af294d5d9 140 * @param event The logical OR of events to modify. Look at spi hal header file for SPI events.
Simon Cooksey 0:fb7af294d5d9 141 * @return Zero if the transfer has started, or -1 if SPI peripheral is busy
Simon Cooksey 0:fb7af294d5d9 142 */
Simon Cooksey 0:fb7af294d5d9 143 template<typename Type>
Simon Cooksey 0:fb7af294d5d9 144 int transfer(const Type *tx_buffer, int tx_length, Type *rx_buffer, int rx_length, const event_callback_t& callback, int event = SPI_EVENT_COMPLETE) {
Simon Cooksey 0:fb7af294d5d9 145 if (spi_active(&_spi)) {
Simon Cooksey 0:fb7af294d5d9 146 return queue_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event);
Simon Cooksey 0:fb7af294d5d9 147 }
Simon Cooksey 0:fb7af294d5d9 148 start_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type)*8, callback, event);
Simon Cooksey 0:fb7af294d5d9 149 return 0;
Simon Cooksey 0:fb7af294d5d9 150 }
Simon Cooksey 0:fb7af294d5d9 151
Simon Cooksey 0:fb7af294d5d9 152 /** Abort the on-going SPI transfer, and continue with transfer's in the queue if any.
Simon Cooksey 0:fb7af294d5d9 153 */
Simon Cooksey 0:fb7af294d5d9 154 void abort_transfer();
Simon Cooksey 0:fb7af294d5d9 155
Simon Cooksey 0:fb7af294d5d9 156 /** Clear the transaction buffer
Simon Cooksey 0:fb7af294d5d9 157 */
Simon Cooksey 0:fb7af294d5d9 158 void clear_transfer_buffer();
Simon Cooksey 0:fb7af294d5d9 159
Simon Cooksey 0:fb7af294d5d9 160 /** Clear the transaction buffer and abort on-going transfer.
Simon Cooksey 0:fb7af294d5d9 161 */
Simon Cooksey 0:fb7af294d5d9 162 void abort_all_transfers();
Simon Cooksey 0:fb7af294d5d9 163
Simon Cooksey 0:fb7af294d5d9 164 /** Configure DMA usage suggestion for non-blocking transfers
Simon Cooksey 0:fb7af294d5d9 165 *
Simon Cooksey 0:fb7af294d5d9 166 * @param usage The usage DMA hint for peripheral
Simon Cooksey 0:fb7af294d5d9 167 * @return Zero if the usage was set, -1 if a transaction is on-going
Simon Cooksey 0:fb7af294d5d9 168 */
Simon Cooksey 0:fb7af294d5d9 169 int set_dma_usage(DMAUsage usage);
Simon Cooksey 0:fb7af294d5d9 170
Simon Cooksey 0:fb7af294d5d9 171 protected:
Simon Cooksey 0:fb7af294d5d9 172 /** SPI IRQ handler
Simon Cooksey 0:fb7af294d5d9 173 *
Simon Cooksey 0:fb7af294d5d9 174 */
Simon Cooksey 0:fb7af294d5d9 175 void irq_handler_asynch(void);
Simon Cooksey 0:fb7af294d5d9 176
Simon Cooksey 0:fb7af294d5d9 177 /** Common transfer method
Simon Cooksey 0:fb7af294d5d9 178 *
Simon Cooksey 0:fb7af294d5d9 179 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 180 * the default SPI value is sent
Simon Cooksey 0:fb7af294d5d9 181 * @param tx_length The length of TX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 182 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 183 * received data are ignored
Simon Cooksey 0:fb7af294d5d9 184 * @param rx_length The length of RX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 185 * @param bit_width The buffers element width
Simon Cooksey 0:fb7af294d5d9 186 * @param callback The event callback function
Simon Cooksey 0:fb7af294d5d9 187 * @param event The logical OR of events to modify
Simon Cooksey 0:fb7af294d5d9 188 * @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full
Simon Cooksey 0:fb7af294d5d9 189 */
Simon Cooksey 0:fb7af294d5d9 190 int transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event);
Simon Cooksey 0:fb7af294d5d9 191
Simon Cooksey 0:fb7af294d5d9 192 /**
Simon Cooksey 0:fb7af294d5d9 193 *
Simon Cooksey 0:fb7af294d5d9 194 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 195 * the default SPI value is sent
Simon Cooksey 0:fb7af294d5d9 196 * @param tx_length The length of TX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 197 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 198 * received data are ignored
Simon Cooksey 0:fb7af294d5d9 199 * @param rx_length The length of RX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 200 * @param bit_width The buffers element width
Simon Cooksey 0:fb7af294d5d9 201 * @param callback The event callback function
Simon Cooksey 0:fb7af294d5d9 202 * @param event The logical OR of events to modify
Simon Cooksey 0:fb7af294d5d9 203 * @return Zero if a transfer was added to the queue, or -1 if the queue is full
Simon Cooksey 0:fb7af294d5d9 204 */
Simon Cooksey 0:fb7af294d5d9 205 int queue_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event);
Simon Cooksey 0:fb7af294d5d9 206
Simon Cooksey 0:fb7af294d5d9 207 /** Configures a callback, spi peripheral and initiate a new transfer
Simon Cooksey 0:fb7af294d5d9 208 *
Simon Cooksey 0:fb7af294d5d9 209 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 210 * the default SPI value is sent
Simon Cooksey 0:fb7af294d5d9 211 * @param tx_length The length of TX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 212 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
Simon Cooksey 0:fb7af294d5d9 213 * received data are ignored
Simon Cooksey 0:fb7af294d5d9 214 * @param rx_length The length of RX buffer in bytes
Simon Cooksey 0:fb7af294d5d9 215 * @param bit_width The buffers element width
Simon Cooksey 0:fb7af294d5d9 216 * @param callback The event callback function
Simon Cooksey 0:fb7af294d5d9 217 * @param event The logical OR of events to modify
Simon Cooksey 0:fb7af294d5d9 218 */
Simon Cooksey 0:fb7af294d5d9 219 void start_transfer(const void *tx_buffer, int tx_length, void *rx_buffer, int rx_length, unsigned char bit_width, const event_callback_t& callback, int event);
Simon Cooksey 0:fb7af294d5d9 220
Simon Cooksey 0:fb7af294d5d9 221 #if TRANSACTION_QUEUE_SIZE_SPI
Simon Cooksey 0:fb7af294d5d9 222
Simon Cooksey 0:fb7af294d5d9 223 /** Start a new transaction
Simon Cooksey 0:fb7af294d5d9 224 *
Simon Cooksey 0:fb7af294d5d9 225 * @param data Transaction data
Simon Cooksey 0:fb7af294d5d9 226 */
Simon Cooksey 0:fb7af294d5d9 227 void start_transaction(transaction_t *data);
Simon Cooksey 0:fb7af294d5d9 228
Simon Cooksey 0:fb7af294d5d9 229 /** Dequeue a transaction
Simon Cooksey 0:fb7af294d5d9 230 *
Simon Cooksey 0:fb7af294d5d9 231 */
Simon Cooksey 0:fb7af294d5d9 232 void dequeue_transaction();
Simon Cooksey 0:fb7af294d5d9 233 static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer;
Simon Cooksey 0:fb7af294d5d9 234 #endif
Simon Cooksey 0:fb7af294d5d9 235
Simon Cooksey 0:fb7af294d5d9 236 #endif
Simon Cooksey 0:fb7af294d5d9 237
Simon Cooksey 0:fb7af294d5d9 238 public:
Simon Cooksey 0:fb7af294d5d9 239 virtual ~SPI() {
Simon Cooksey 0:fb7af294d5d9 240 }
Simon Cooksey 0:fb7af294d5d9 241
Simon Cooksey 0:fb7af294d5d9 242 protected:
Simon Cooksey 0:fb7af294d5d9 243 spi_t _spi;
Simon Cooksey 0:fb7af294d5d9 244
Simon Cooksey 0:fb7af294d5d9 245 #if DEVICE_SPI_ASYNCH
Simon Cooksey 0:fb7af294d5d9 246 CThunk<SPI> _irq;
Simon Cooksey 0:fb7af294d5d9 247 event_callback_t _callback;
Simon Cooksey 0:fb7af294d5d9 248 DMAUsage _usage;
Simon Cooksey 0:fb7af294d5d9 249 #endif
Simon Cooksey 0:fb7af294d5d9 250
Simon Cooksey 0:fb7af294d5d9 251 void aquire(void);
Simon Cooksey 0:fb7af294d5d9 252 static SPI *_owner;
Simon Cooksey 0:fb7af294d5d9 253 static SingletonPtr<PlatformMutex> _mutex;
Simon Cooksey 0:fb7af294d5d9 254 int _bits;
Simon Cooksey 0:fb7af294d5d9 255 int _mode;
Simon Cooksey 0:fb7af294d5d9 256 int _hz;
Simon Cooksey 0:fb7af294d5d9 257 };
Simon Cooksey 0:fb7af294d5d9 258
Simon Cooksey 0:fb7af294d5d9 259 } // namespace mbed
Simon Cooksey 0:fb7af294d5d9 260
Simon Cooksey 0:fb7af294d5d9 261 #endif
Simon Cooksey 0:fb7af294d5d9 262
Simon Cooksey 0:fb7af294d5d9 263 #endif
Simon Cooksey 0:fb7af294d5d9 264
Simon Cooksey 0:fb7af294d5d9 265 /** @}*/