Skip to content

Doc: spi documentation fixes #8516

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 27, 2018
Merged

Doc: spi documentation fixes #8516

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
482f2b6
spi doxygen fixes
paul-szczepanek-arm Oct 23, 2018
263f067
imperative
paul-szczepanek-arm Oct 23, 2018
68628c1
fix syntax err from misplaced ifdef
paul-szczepanek-arm Oct 24, 2018
d4b6fdc
SPI capitalisation
paul-szczepanek-arm Oct 24, 2018
efdcdd5
active voice
paul-szczepanek-arm Oct 24, 2018
889a98e
Update SPI.h
paul-szczepanek-arm Oct 25, 2018
fa09fff
Fix interleaved ifdefs with DEVICE_SPI_ASYNCH + DOXYGEN_ONLY
geky Oct 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 133 additions & 97 deletions drivers/SPI.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,39 +36,44 @@
namespace mbed {
/** \addtogroup drivers */

/** A SPI Master, used for communicating with SPI slave devices
/** A SPI Master, used for communicating with SPI slave devices.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An SPI

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's pronounced "spy". I think 'an' vs 'a' is decided by pronunciation. So it's "an honour" and I can't think of a counter example.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah. Right, in that case, carry on.

I'm quite pleased it IS a 'spymaster' after all!

*
* 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
* can be controlled using DigitalOut pins
* can be controlled using DigitalOut pins.
*
* @note Synchronization level: Thread safe
*
* Example:
* Example of how to send a byte to a SPI slave and record the response:
* @code
* // Send a byte to a SPI slave, and record the response
*
* #include "mbed.h"
*
* // hardware ssel (where applicable)
* //SPI device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
* SPI device(SPI_MOSI, SPI_MISO, SPI_SCLK)
*
* // software ssel
* SPI device(p5, p6, p7); // mosi, miso, sclk
* DigitalOut cs(p8); // ssel
* DigitalOut chip_select(SPI_CS);
*
* int main() {
* // hardware ssel (where applicable)
* //int response = device.write(0xFF);
*
* device.lock();
* // software ssel
* cs = 0;
* chip_select = 0;
*
* int response = device.write(0xFF);
* cs = 1;
*
* 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
* @ingroup drivers
Expand All @@ -77,22 +82,22 @@ class SPI : private NonCopyable<SPI> {

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 miso SPI Master In, Slave Out pin
* @param sclk SPI Clock pin
* @param ssel SPI chip select pin
* @param mosi SPI Master Out, Slave In pin.
* @param miso SPI Master In, Slave Out pin.
* @param sclk SPI Clock pin.
* @param ssel SPI Chip Select pin.
*/
SPI(PinName mosi, PinName miso, PinName sclk, PinName ssel = NC);
virtual ~SPI();

/** Configure the data transmission format
/** Configure the data transmission format.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do these need \brief commands/tags/whatever they're called?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. @brief is implied.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

*
* @param bits Number of bits per SPI frame (4 - 16)
* @param mode Clock polarity and phase mode (0 - 3)
* @param bits Number of bits per SPI frame (4 - 16).
* @param mode Clock polarity and phase mode (0 - 3).
*
* @code
* mode | POL PHA
Expand All @@ -105,69 +110,71 @@ class SPI : private NonCopyable<SPI> {
*/
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);

/** 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
* Response from the SPI slave
* @return Response from the SPI slave.
*/
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
* tx_length and rx_length. The bytes written will be padded with the
* value 0xff.
*
* @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 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
* @returns
* @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 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.
* @return
* The number of bytes written and read from the device. This is
* maximum of tx_length and 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);

/** Release exclusive access to this SPI bus
/** Release exclusive access to this SPI bus.
*/
virtual void unlock(void);

/** Set default write data
/** Set default write data.
* SPI requires the master to send some data during a read operation.
* Different devices may require different default byte values.
* 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);

#if DEVICE_SPI_ASYNCH

/** 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,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @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,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param callback The event callback function
* @param event The logical OR of events to modify. Look at spi hal header file for SPI events.
* @return Zero if the transfer has started, or -1 if SPI peripheral is busy
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param callback The event callback function.
* @param event The event mask of events to modify. @see spi_api.h for SPI events.
*
* @return Operation result.
* @retval 0 If the transfer has started.
* @retval -1 If SPI peripheral is busy.
*/
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)
Expand All @@ -179,75 +186,85 @@ class SPI : private NonCopyable<SPI> {
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();

/** Clear the transaction buffer
/** Clear the queue of transfers.
*/
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();

/** Configure DMA usage suggestion for non-blocking transfers
/** Configure DMA usage suggestion for non-blocking transfers.
*
* @param usage The usage DMA hint for peripheral
* @return Zero if the usage was set, -1 if a transaction is on-going
*/
* @param usage The usage DMA hint for peripheral.
*
* @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);

protected:
/** SPI IRQ handler
*
*/
/** SPI interrupt handler.
*/
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,
* 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,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR 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
*/
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width in bits.
* @param callback The event callback function.
* @param event The event mask of events to modify.
*
* @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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is actually a bug in the implementation, it doesn't forward the error code, will file an issue

*/
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,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @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,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR of events to modify
* @return Zero if a transfer was added to the queue, or -1 if the queue is full
*/
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width in bits.
* @param callback The event callback function.
* @param event The event mask of events to modify.
*
* @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);

/** 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,
* the default SPI value is sent
* @param tx_length The length of TX buffer in bytes
* the default SPI value is sent.
* @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,
* received data are ignored
* @param rx_length The length of RX buffer in bytes
* @param bit_width The buffers element width
* @param callback The event callback function
* @param event The logical OR of events to modify
*/
* received data are ignored.
* @param rx_length The length of RX buffer in bytes.
* @param bit_width The buffers element width.
* @param callback The event callback function.
* @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);

#if !defined(DOXYGEN_ONLY)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like this is causing the travis failure. @0xc0170 @cmonr does anyone know if DOXYGEN_ONLY is set for all travis jobs?


private:
/** Lock deep sleep only if it is not yet locked */
void lock_deep_sleep();
Expand All @@ -258,44 +275,63 @@ class SPI : private NonCopyable<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);

/** Dequeue a transaction
*
*/
/** Dequeue a transaction and start the transfer if there was one pending.
*/
void dequeue_transaction();

/* Queue of pending transfers */
static CircularBuffer<Transaction<SPI>, TRANSACTION_QUEUE_SIZE_SPI> _transaction_buffer;
#endif

#endif
#endif //!defined(DOXYGEN_ONLY)

#endif //DEVICE_SPI_ASYNCH

#if !defined(DOXYGEN_ONLY)

protected:
/* Internal SPI object identifying the resources */
spi_t _spi;

#if DEVICE_SPI_ASYNCH
/* Interrupt */
CThunk<SPI> _irq;
/* Interrupt handler callback */
event_callback_t _callback;
/* Current preferred DMA mode @see dma_api.h */
DMAUsage _usage;
/* Current sate of the sleep manager */
bool _deep_sleep_locked;
#endif

/* Take over the physical SPI and apply our settings (thread safe) */
void aquire(void);
/* Current user of the SPI */
static SPI *_owner;
/* Used by lock and unlock for thread safety */
static SingletonPtr<PlatformMutex> _mutex;
/* Size of the SPI frame */
int _bits;
/* Clock polairy and phase */
int _mode;
/* Clock frequency */
int _hz;
/* Default character used for NULL transfers */
char _write_fill;

private:
/* Private acquire function without locking/unlocking
* Implemented in order to avoid duplicate locking and boost performance
/** Private acquire function without locking/unlocking.
* Implemented in order to avoid duplicate locking and boost performance.
*/
void _acquire(void);

#endif //!defined(DOXYGEN_ONLY)
};

} // namespace mbed
Expand Down