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.
SPI.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2015 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 #ifndef MBED_SPI_H 00017 #define MBED_SPI_H 00018 00019 #include "platform/platform.h" 00020 00021 #if defined (DEVICE_SPI) || defined(DOXYGEN_ONLY) 00022 00023 #include "platform/PlatformMutex.h" 00024 #include "hal/spi_api.h" 00025 #include "platform/SingletonPtr.h" 00026 #include "platform/NonCopyable.h" 00027 00028 #if DEVICE_SPI_ASYNCH 00029 #include "platform/CThunk.h" 00030 #include "hal/dma_api.h" 00031 #include "platform/CircularBuffer.h" 00032 #include "platform/FunctionPointer.h" 00033 #include "platform/Transaction.h" 00034 #endif 00035 00036 namespace mbed { 00037 /** \addtogroup drivers */ 00038 00039 /** A SPI Master, used for communicating with SPI slave devices 00040 * 00041 * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz 00042 * 00043 * Most SPI devices will also require Chip Select and Reset signals. These 00044 * can be controlled using DigitalOut pins 00045 * 00046 * @note Synchronization level: Thread safe 00047 * 00048 * Example: 00049 * @code 00050 * // Send a byte to a SPI slave, and record the response 00051 * 00052 * #include "mbed.h" 00053 * 00054 * // hardware ssel (where applicable) 00055 * //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel 00056 * 00057 * // software ssel 00058 * SPI device(p5, p6, p7); // mosi, miso, sclk 00059 * DigitalOut cs(p8); // ssel 00060 * 00061 * int main() { 00062 * // hardware ssel (where applicable) 00063 * //int response = device.write(0xFF); 00064 * 00065 * device.lock(); 00066 * // software ssel 00067 * cs = 0; 00068 * int response = device.write(0xFF); 00069 * cs = 1; 00070 * device.unlock(); 00071 * 00072 * } 00073 * @endcode 00074 * @ingroup drivers 00075 */ 00076 class SPI : private NonCopyable<SPI> { 00077 00078 public: 00079 00080 /** Create a SPI master connected to the specified pins 00081 * 00082 * mosi or miso can be specified as NC if not used 00083 * 00084 * @param mosi SPI Master Out, Slave In pin 00085 * @param miso SPI Master In, Slave Out pin 00086 * @param sclk SPI Clock pin 00087 * @param ssel SPI chip select pin 00088 */ 00089 SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC); 00090 virtual ~SPI(); 00091 00092 /** Configure the data transmission format 00093 * 00094 * @param bits Number of bits per SPI frame (4 - 16) 00095 * @param mode Clock polarity and phase mode (0 - 3) 00096 * 00097 * @code 00098 * mode | POL PHA 00099 * -----+-------- 00100 * 0 | 0 0 00101 * 1 | 0 1 00102 * 2 | 1 0 00103 * 3 | 1 1 00104 * @endcode 00105 */ 00106 void format(int bits, int mode = 0); 00107 00108 /** Set the spi bus clock frequency 00109 * 00110 * @param hz SCLK frequency in hz (default = 1MHz) 00111 */ 00112 void frequency(int hz = 1000000); 00113 00114 /** Write to the SPI Slave and return the response 00115 * 00116 * @param value Data to be sent to the SPI slave 00117 * 00118 * @returns 00119 * Response from the SPI slave 00120 */ 00121 virtual int write(int value); 00122 00123 /** Write to the SPI Slave and obtain the response 00124 * 00125 * The total number of bytes sent and received will be the maximum of 00126 * tx_length and rx_length. The bytes written will be padded with the 00127 * value 0xff. 00128 * 00129 * @param tx_buffer Pointer to the byte-array of data to write to the device 00130 * @param tx_length Number of bytes to write, may be zero 00131 * @param rx_buffer Pointer to the byte-array of data to read from the device 00132 * @param rx_length Number of bytes to read, may be zero 00133 * @returns 00134 * The number of bytes written and read from the device. This is 00135 * maximum of tx_length and rx_length. 00136 */ 00137 virtual int write(const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length); 00138 00139 /** Acquire exclusive access to this SPI bus 00140 */ 00141 virtual void lock(void); 00142 00143 /** Release exclusive access to this SPI bus 00144 */ 00145 virtual void unlock(void); 00146 00147 /** Set default write data 00148 * SPI requires the master to send some data during a read operation. 00149 * Different devices may require different default byte values. 00150 * For example: A SD Card requires default bytes to be 0xFF. 00151 * 00152 * @param data Default character to be transmitted while read operation 00153 */ 00154 void set_default_write_value(char data); 00155 00156 #if DEVICE_SPI_ASYNCH 00157 00158 /** Start non-blocking SPI transfer using 8bit buffers. 00159 * 00160 * This function locks the deep sleep until any event has occurred 00161 * 00162 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, 00163 * the default SPI value is sent 00164 * @param tx_length The length of TX buffer in bytes 00165 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, 00166 * received data are ignored 00167 * @param rx_length The length of RX buffer in bytes 00168 * @param callback The event callback function 00169 * @param event The logical OR of events to modify. Look at spi hal header file for SPI events. 00170 * @return Zero if the transfer has started, or -1 if SPI peripheral is busy 00171 */ 00172 template<typename Type> 00173 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) 00174 { 00175 if (spi_active(&_spi)) { 00176 return queue_transfer (tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type) * 8, callback, event); 00177 } 00178 start_transfer(tx_buffer, tx_length, rx_buffer, rx_length, sizeof(Type) * 8, callback, event); 00179 return 0; 00180 } 00181 00182 /** Abort the on-going SPI transfer, and continue with transfer's in the queue if any. 00183 */ 00184 void abort_transfer(); 00185 00186 /** Clear the transaction buffer 00187 */ 00188 void clear_transfer_buffer(); 00189 00190 /** Clear the transaction buffer and abort on-going transfer. 00191 */ 00192 void abort_all_transfers(); 00193 00194 /** Configure DMA usage suggestion for non-blocking transfers 00195 * 00196 * @param usage The usage DMA hint for peripheral 00197 * @return Zero if the usage was set, -1 if a transaction is on-going 00198 */ 00199 int set_dma_usage(DMAUsage usage); 00200 00201 protected: 00202 /** SPI IRQ handler 00203 * 00204 */ 00205 void irq_handler_asynch(void); 00206 00207 /** Common transfer method 00208 * 00209 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, 00210 * the default SPI value is sent 00211 * @param tx_length The length of TX buffer in bytes 00212 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, 00213 * received data are ignored 00214 * @param rx_length The length of RX buffer in bytes 00215 * @param bit_width The buffers element width 00216 * @param callback The event callback function 00217 * @param event The logical OR of events to modify 00218 * @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full 00219 */ 00220 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); 00221 00222 /** 00223 * 00224 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, 00225 * the default SPI value is sent 00226 * @param tx_length The length of TX buffer in bytes 00227 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, 00228 * received data are ignored 00229 * @param rx_length The length of RX buffer in bytes 00230 * @param bit_width The buffers element width 00231 * @param callback The event callback function 00232 * @param event The logical OR of events to modify 00233 * @return Zero if a transfer was added to the queue, or -1 if the queue is full 00234 */ 00235 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); 00236 00237 /** Configures a callback, spi peripheral and initiate a new transfer 00238 * 00239 * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, 00240 * the default SPI value is sent 00241 * @param tx_length The length of TX buffer in bytes 00242 * @param rx_buffer The RX buffer which is used for received data. If NULL is passed, 00243 * received data are ignored 00244 * @param rx_length The length of RX buffer in bytes 00245 * @param bit_width The buffers element width 00246 * @param callback The event callback function 00247 * @param event The logical OR of events to modify 00248 */ 00249 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); 00250 00251 private: 00252 /** Lock deep sleep only if it is not yet locked */ 00253 void lock_deep_sleep(); 00254 00255 /** Unlock deep sleep in case it is locked */ 00256 void unlock_deep_sleep(); 00257 00258 00259 #if TRANSACTION_QUEUE_SIZE_SPI 00260 00261 /** Start a new transaction 00262 * 00263 * @param data Transaction data 00264 */ 00265 void start_transaction(transaction_t *data); 00266 00267 /** Dequeue a transaction 00268 * 00269 */ 00270 void dequeue_transaction(); 00271 static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer; 00272 #endif 00273 00274 #endif 00275 00276 protected: 00277 spi_t _spi; 00278 00279 #if DEVICE_SPI_ASYNCH 00280 CThunk<SPI> _irq; 00281 event_callback_t _callback; 00282 DMAUsage _usage; 00283 bool _deep_sleep_locked; 00284 #endif 00285 00286 void aquire(void); 00287 static SPI *_owner; 00288 static SingletonPtr<PlatformMutex> _mutex; 00289 int _bits; 00290 int _mode; 00291 int _hz; 00292 char _write_fill; 00293 00294 private: 00295 /* Private acquire function without locking/unlocking 00296 * Implemented in order to avoid duplicate locking and boost performance 00297 */ 00298 void _acquire(void); 00299 }; 00300 00301 } // namespace mbed 00302 00303 #endif 00304 00305 #endif
Generated on Tue Aug 9 2022 00:37:20 by
