ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'doc-fix-spi' of ssh://github.com/paul-szczepanek-arm/mbed-os into rollup

pull/8552/head
Cruz Monrreal II 2018-10-26 11:43:01 -05:00
parent 14ce8f2721 fa09fff283
commit b364dcb48e
1 changed files with 135 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
drivers/SPI.h
View File

@ -36,39 +36,44 @@
namespace mbed { namespace mbed {
/** \addtogroup drivers */ /** \addtogroup drivers */
/** A SPI Master, used for communicating with SPI slave devices /** A SPI Master, used for communicating with SPI slave devices.
* *
* The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz.
* *
* Most SPI devices will also require Chip Select and Reset signals. These * Most SPI devices will also require Chip Select and Reset signals. These
* can be controlled using DigitalOut pins * can be controlled using DigitalOut pins.
* *
* @note Synchronization level: Thread safe * @note Synchronization level: Thread safe
* *
* Example: * Example of how to send a byte to a SPI slave and record the response:
* @code * @code
* // Send a byte to a SPI slave, and record the response
*
* #include "mbed.h" * #include "mbed.h"
* *
* // hardware ssel (where applicable) * SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK)
* //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
* *
* // software ssel * DigitalOut chip_select(SPI_CS);
* SPI device(p5, p6, p7); // mosi, miso, sclk
* DigitalOut cs(p8); // ssel
* *
* int main() { * int main() {
* // hardware ssel (where applicable)
* //int response = device.write(0xFF);
*
* device.lock(); * device.lock();
* // software ssel * chip_select = 0;
* cs = 0;
* int response = device.write(0xFF);
* cs = 1;
* device.unlock();
* *
* int response = device.write(0xFF);
*
* chip_select = 1;
* device.unlock();
* }
* @endcode
*
* Example using hardware Chip Select line:
* @code
* #include "mbed.h"
*
* SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS)
*
* int main() {
* device.lock();
* int response = device.write(0xFF);
* device.unlock();
* } * }
* @endcode * @endcode
* @ingroup drivers * @ingroup drivers
@ -77,22 +82,22 @@ class SPI : private NonCopyable<SPI> {
public: public:
/** Create a SPI master connected to the specified pins /** Create a SPI master connected to the specified pins.
* *
* mosi or miso can be specified as NC if not used * @note You can specify mosi or miso as NC if not used.
* *
* @param mosi SPI Master Out, Slave In pin * @param mosi SPI Master Out, Slave In pin.
* @param miso SPI Master In, Slave Out pin * @param miso SPI Master In, Slave Out pin.
* @param sclk SPI Clock pin * @param sclk SPI Clock pin.
* @param ssel SPI chip select pin * @param ssel SPI Chip Select pin.
*/ */
SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC); SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC);
virtual ~SPI(); virtual ~SPI();
/** Configure the data transmission format /** Configure the data transmission format.
* *
* @param bits Number of bits per SPI frame (4 - 16) * @param bits Number of bits per SPI frame (4 - 16).
* @param mode Clock polarity and phase mode (0 - 3) * @param mode Clock polarity and phase mode (0 - 3).
* *
* @code * @code
* mode | POL PHA * mode | POL PHA
@ -105,51 +110,50 @@ public:
*/ */
void format(int bits, int mode = 0); void format(int bits, int mode = 0);
/** Set the spi bus clock frequency /** Set the SPI bus clock frequency.
* *
* @param hz SCLK frequency in hz (default = 1MHz) * @param hz Clock frequency in Hz (default = 1MHz).
*/ */
void frequency(int hz = 1000000); void frequency(int hz = 1000000);
/** Write to the SPI Slave and return the response /** Write to the SPI Slave and return the response.
* *
* @param value Data to be sent to the SPI slave * @param value Data to be sent to the SPI slave.
* *
* @returns * @return Response from the SPI slave.
* Response from the SPI slave
*/ */
virtual int write(int value); virtual int write(int value);
/** Write to the SPI Slave and obtain the response /** Write to the SPI Slave and obtain the response.
* *
* The total number of bytes sent and received will be the maximum of * The total number of bytes sent and received will be the maximum of
* tx_length and rx_length. The bytes written will be padded with the * tx_length and rx_length. The bytes written will be padded with the
* value 0xff. * value 0xff.
* *
* @param tx_buffer Pointer to the byte-array of data to write to the device * @param tx_buffer Pointer to the byte-array of data to write to the device.
* @param tx_length Number of bytes to write, may be zero * @param tx_length Number of bytes to write, may be zero.
* @param rx_buffer Pointer to the byte-array of data to read from the device * @param rx_buffer Pointer to the byte-array of data to read from the device.
* @param rx_length Number of bytes to read, may be zero * @param rx_length Number of bytes to read, may be zero.
* @returns * @return
* The number of bytes written and read from the device. This is * The number of bytes written and read from the device. This is
* maximum of tx_length and rx_length. * maximum of tx_length and rx_length.
*/ */
virtual int write(const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length); virtual int write(const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length);
/** Acquire exclusive access to this SPI bus /** Acquire exclusive access to this SPI bus.
*/ */
virtual void lock(void); virtual void lock(void);
/** Release exclusive access to this SPI bus /** Release exclusive access to this SPI bus.
*/ */
virtual void unlock(void); virtual void unlock(void);
/** Set default write data /** Set default write data.
* SPI requires the master to send some data during a read operation. * SPI requires the master to send some data during a read operation.
* Different devices may require different default byte values. * Different devices may require different default byte values.
* For example: A SD Card requires default bytes to be 0xFF. * For example: A SD Card requires default bytes to be 0xFF.
* *
* @param data Default character to be transmitted while read operation * @param data Default character to be transmitted during a read operation.
*/ */
void set_default_write_value(char data); void set_default_write_value(char data);
@ -157,17 +161,20 @@ public:
/** Start non-blocking SPI transfer using 8bit buffers. /** Start non-blocking SPI transfer using 8bit buffers.
* *
* This function locks the deep sleep until any event has occurred * This function locks the deep sleep until any event has occurred.
* *
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent * the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes * @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed, * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored * received data are ignored.
* @param rx_length The length of RX buffer in bytes * @param rx_length The length of RX buffer in bytes.
* @param callback The event callback function * @param callback The event callback function.
* @param event The logical OR of events to modify. Look at spi hal header file for SPI events. * @param event The event mask of events to modify. @see spi_api.h for SPI events.
* @return Zero if the transfer has started, or -1 if SPI peripheral is busy *
* @return Operation result.
* @retval 0 If the transfer has started.
* @retval -1 If SPI peripheral is busy.
*/ */
template<typename Type> template<typename Type>
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) 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)
@ -179,75 +186,85 @@ public:
return 0; return 0;
} }
/** Abort the on-going SPI transfer, and continue with transfer's in the queue if any. /** Abort the on-going SPI transfer, and continue with transfers in the queue, if any.
*/ */
void abort_transfer(); void abort_transfer();
/** Clear the transaction buffer /** Clear the queue of transfers.
*/ */
void clear_transfer_buffer(); void clear_transfer_buffer();
/** Clear the transaction buffer and abort on-going transfer. /** Clear the queue of transfers and abort the on-going transfer.
*/ */
void abort_all_transfers(); void abort_all_transfers();
/** Configure DMA usage suggestion for non-blocking transfers /** Configure DMA usage suggestion for non-blocking transfers.
* *
* @param usage The usage DMA hint for peripheral * @param usage The usage DMA hint for peripheral.
* @return Zero if the usage was set, -1 if a transaction is on-going *
*/ * @return Result of the operation.
* @retval 0 The usage was set.
* @retval -1 Usage cannot be set as there is an ongoing transaction.
*/
int set_dma_usage(DMAUsage usage); int set_dma_usage(DMAUsage usage);
protected: protected:
/** SPI IRQ handler /** SPI interrupt handler.
* */
*/
void irq_handler_asynch(void); void irq_handler_asynch(void);
/** Common transfer method /** Start the transfer or put it on the queue.
* *
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent * the default SPI value is sent
* @param tx_length The length of TX buffer in bytes * @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed, * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored * received data are ignored.
* @param rx_length The length of RX buffer in bytes * @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width * @param bit_width The buffers element width in bits.
* @param callback The event callback function * @param callback The event callback function.
* @param event The logical OR of events to modify * @param event The event mask of events to modify.
* @return Zero if the transfer has started or was added to the queue, or -1 if SPI peripheral is busy/buffer is full *
*/ * @return Operation success.
* @retval 0 A transfer was started or added to the queue.
* @retval -1 Transfer can't be added because queue is full.
*/
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); 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);
/** /** Put a transfer on the transfer queue.
* *
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent * the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes * @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed, * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored * received data are ignored.
* @param rx_length The length of RX buffer in bytes * @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width * @param bit_width The buffers element width in bits.
* @param callback The event callback function * @param callback The event callback function.
* @param event The logical OR of events to modify * @param event The event mask of events to modify.
* @return Zero if a transfer was added to the queue, or -1 if the queue is full *
*/ * @return Operation success.
* @retval 0 A transfer was added to the queue.
* @retval -1 Transfer can't be added because queue is full.
*/
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); 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);
/** Configures a callback, spi peripheral and initiate a new transfer /** Configure a callback, SPI peripheral, and initiate a new transfer.
* *
* @param tx_buffer The TX buffer with data to be transfered. If NULL is passed, * @param tx_buffer The TX buffer with data to be transfered. If NULL is passed,
* the default SPI value is sent * the default SPI value is sent.
* @param tx_length The length of TX buffer in bytes * @param tx_length The length of TX buffer in bytes.
* @param rx_buffer The RX buffer which is used for received data. If NULL is passed, * @param rx_buffer The RX buffer which is used for received data. If NULL is passed,
* received data are ignored * received data are ignored.
* @param rx_length The length of RX buffer in bytes * @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width * @param bit_width The buffers element width.
* @param callback The event callback function * @param callback The event callback function.
* @param event The logical OR of events to modify * @param event The event mask of events to modify.
*/ */
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); 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);
#if !defined(DOXYGEN_ONLY)
private: private:
/** Lock deep sleep only if it is not yet locked */ /** Lock deep sleep only if it is not yet locked */
void lock_deep_sleep(); void lock_deep_sleep();
@ -258,44 +275,63 @@ private:
#if TRANSACTION_QUEUE_SIZE_SPI #if TRANSACTION_QUEUE_SIZE_SPI
/** Start a new transaction /** Start a new transaction.
* *
* @param data Transaction data * @param data Transaction data.
*/ */
void start_transaction(transaction_t *data); void start_transaction(transaction_t *data);
/** Dequeue a transaction /** Dequeue a transaction and start the transfer if there was one pending.
* */
*/
void dequeue_transaction(); void dequeue_transaction();
/* Queue of pending transfers */
static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer; static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer;
#endif #endif
#endif #endif //!defined(DOXYGEN_ONLY)
#endif //DEVICE_SPI_ASYNCH
#if !defined(DOXYGEN_ONLY)
protected: protected:
/* Internal SPI object identifying the resources */
spi_t _spi; spi_t _spi;
#if DEVICE_SPI_ASYNCH #if DEVICE_SPI_ASYNCH
/* Interrupt */
CThunk<SPI> _irq; CThunk<SPI> _irq;
/* Interrupt handler callback */
event_callback_t _callback; event_callback_t _callback;
/* Current preferred DMA mode @see dma_api.h */
DMAUsage _usage; DMAUsage _usage;
/* Current sate of the sleep manager */
bool _deep_sleep_locked; bool _deep_sleep_locked;
#endif #endif
/* Take over the physical SPI and apply our settings (thread safe) */
void aquire(void); void aquire(void);
/* Current user of the SPI */
static SPI *_owner; static SPI *_owner;
/* Used by lock and unlock for thread safety */
static SingletonPtr<PlatformMutex> _mutex; static SingletonPtr<PlatformMutex> _mutex;
/* Size of the SPI frame */
int _bits; int _bits;
/* Clock polairy and phase */
int _mode; int _mode;
/* Clock frequency */
int _hz; int _hz;
/* Default character used for NULL transfers */
char _write_fill; char _write_fill;
private: private:
/* Private acquire function without locking/unlocking /** Private acquire function without locking/unlocking.
* Implemented in order to avoid duplicate locking and boost performance * Implemented in order to avoid duplicate locking and boost performance.
*/ */
void _acquire(void); void _acquire(void);
#endif //!defined(DOXYGEN_ONLY)
}; };
} // namespace mbed } // namespace mbed