Andrew SaLoutos / mbed-dev-STM-lean

From Ben Katz mbed-dev library. Removed unnecessary target files to reduce the overall size by a factor of 10 to make it easier to import into the online IDE.

Dependents:   motor_driver motor_driver_screaming_fix

drivers/SPI.h@0:083111ae2a11, 2020-11-26 (annotated)

Committer:
saloutos
Date:
Thu Nov 26 04:08:56 2020 +0000
Revision:
0:083111ae2a11
first commit of leaned mbed dev lib

Who changed what in which revision?

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