Morpheus / mbed-hal

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   target-freescale

api/SPI.h@7:4fdb3a44f646, 2016-03-31 (annotated)

Committer:
Christopher Haster
Date:
Thu Mar 31 12:35:07 2016 -0500
Revision:
7:4fdb3a44f646
Parent:
0:9c59db1fbc9e
Child:
13:d6551a5dcbbf
Integrated Function throughout the api

Who changed what in which revision?

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