Kev Mann / mbed-dev-OS5_10_4

RTC auf true

drivers/SPI.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

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