ADuCM302x Device Drivers API Reference Manual
Release 3.1.2.0
|
Serial Peripheral Interface (SPI) Driver. More...
Modules | |
Static Configuration | |
Data Structures | |
struct | ADI_SPI_TRANSCEIVER |
Macros | |
#define | ADI_SPI_MEMORY_SIZE (40u + ADI_SEM_SIZE) |
Typedefs | |
typedef struct __ADI_SPI_DEV_DATA_TYPE * | ADI_SPI_HANDLE |
typedef const struct __ADI_SPI_DEV_DATA_TYPE * | ADI_SPI_CONST_HANDLE |
Functions | |
ADI_SPI_RESULT | adi_spi_Open (uint32_t nDeviceNum, void *pDevMemory, uint32_t nMemorySize, ADI_SPI_HANDLE *const phDevice) |
Initialize and allocate an SPI device for use in Master Mode. More... | |
ADI_SPI_RESULT | adi_spi_Close (ADI_SPI_HANDLE const hDevice) |
Uninitialize and deallocate an SPI device. More... | |
ADI_SPI_RESULT | adi_spi_MasterReadWrite (ADI_SPI_HANDLE const hDevice, const ADI_SPI_TRANSCEIVER *const pXfr) |
Submit data buffers for SPI Master-Mode transaction in "Blocking mode".This function returns only after the data transfer is complete. More... | |
ADI_SPI_RESULT | adi_spi_SetMasterMode (ADI_SPI_CONST_HANDLE const hDevice, const bool bFlag) |
Set SPI Master-Mode operation. More... | |
ADI_SPI_RESULT | adi_spi_SlaveReadWrite (ADI_SPI_HANDLE const hDevice, const ADI_SPI_TRANSCEIVER *const pXfr) |
Submit data buffers for SPI Slave-Mode transaction in "Blocking mode".This function returns only after the data transfer is complete. More... | |
ADI_SPI_RESULT | adi_spi_MasterSubmitBuffer (ADI_SPI_HANDLE const hDevice, const ADI_SPI_TRANSCEIVER *const pXfr) |
Submit data buffers for SPI Master-Mode transaction. More... | |
ADI_SPI_RESULT | adi_spi_SlaveSubmitBuffer (ADI_SPI_HANDLE const hDevice, const ADI_SPI_TRANSCEIVER *const pXfr) |
Submit data buffers for SPI Slave-Mode transaction. More... | |
ADI_SPI_RESULT | adi_spi_RegisterCallback (ADI_SPI_HANDLE const hDevice, ADI_CALLBACK const pfCallback, void *const pCBParam) |
Register or unregister the callback. More... | |
ADI_SPI_RESULT | adi_spi_GetBuffer (ADI_SPI_HANDLE const hDevice, uint32_t *const pHWErrors) |
Block until the SPI transaction is complete. More... | |
ADI_SPI_RESULT | adi_spi_SetClockPhase (ADI_SPI_HANDLE const hDevice, const bool bFlag) |
Set the clock phase. More... | |
ADI_SPI_RESULT | adi_spi_SetClockPolarity (ADI_SPI_HANDLE const hDevice, const bool bFlag) |
Set the clock polarity. More... | |
ADI_SPI_RESULT | adi_spi_isBufferAvailable (ADI_SPI_CONST_HANDLE const hDevice, bool *const bComplete) |
Get the SPI transaction completion status. More... | |
ADI_SPI_RESULT | adi_spi_SetContinuousMode (ADI_SPI_CONST_HANDLE const hDevice, const bool bFlag) |
Set the continuous transfer mode. More... | |
ADI_SPI_RESULT | adi_spi_SetLoopback (ADI_SPI_CONST_HANDLE const hDevice, const bool bFlag) |
Set the internal loopback mode. More... | |
ADI_SPI_RESULT | adi_spi_SetIrqmode (ADI_SPI_CONST_HANDLE const hDevice, const uint8_t nMode) |
Set the IRQ mode. More... | |
ADI_SPI_RESULT | adi_spi_SetReceiveOverflow (ADI_SPI_CONST_HANDLE const hDevice, const bool bFlag) |
Set the SPI receive FIFO overflow mode. More... | |
ADI_SPI_RESULT | adi_spi_SetTransmitUnderflow (ADI_SPI_CONST_HANDLE const hDevice, const bool bFlag) |
Set the SPI transmit FIFO underflow mode. More... | |
ADI_SPI_RESULT | adi_spi_SetBitrate (ADI_SPI_CONST_HANDLE const hDevice, const uint32_t Hertz) |
Set the SPI serial clock frequency. More... | |
ADI_SPI_RESULT | adi_spi_SetChipSelect (ADI_SPI_HANDLE const hDevice, const ADI_SPI_CHIP_SELECT eChipSelect) |
Set the chip select. More... | |
ADI_SPI_RESULT | adi_spi_GetBitrate (ADI_SPI_CONST_HANDLE const hDevice, uint32_t *const pnBitrate) |
Get the SPI serial clock frequency. More... | |
Serial Peripheral Interface (SPI) Driver.
The SPI driver manages all instances of the SPI peripheral.
#define ADI_SPI_MEMORY_SIZE (40u + ADI_SEM_SIZE) |
typedef struct __ADI_SPI_DEV_DATA_TYPE* ADI_SPI_HANDLE |
typedef const struct __ADI_SPI_DEV_DATA_TYPE* ADI_SPI_CONST_HANDLE |
enum ADI_SPI_RESULT |
SPI Device Error Codes. ADI_SPI_SUCCESS is always zero The return value of all SPI APIs returning ADI_SPI_RESULT should always be tested at the application level for success or failure.
enum ADI_SPI_HW_ERRORS |
Enumeration of events notified in the application provided callback. More than one event can be recorded at a time so the enumerator symbols have to be assigned values of 2^N
enum ADI_SPI_CHIP_SELECT |
SPI Device Chip Select Enumeration. Allows designation of an external SPI slave device chip select pin to be driven by the SPI controller. Multiple external slave SPI devices may be present on a shared SPI bus, and the chip select pin allows each of them to be assigned dedicated selects. Use the adi_spi_SetChipSelect() API to configure the active chip select. Note that SPI0 is an internal channel dedicated to the UHF controller and hence, has a dedicated SPI0 chip select pin that is not available externally.
ADI_SPI_RESULT adi_spi_Open | ( | uint32_t | nDeviceNum, |
void * | pDevMemory, | ||
uint32_t | nMemorySize, | ||
ADI_SPI_HANDLE *const | phDevice | ||
) |
Initialize and allocate an SPI device for use in Master Mode.
[in] | nDeviceNum | Zero-based device index designating which device to initialize. |
[in] | pDevMemory | Pointer to a buffer of size ADI_SPI_MEMORY_SIZE required by the driver for the operation of specified SPI device. |
[in] | nMemorySize | Size of the buffer to which "pMemory" points. |
[out] | phDevice | The caller's device handle pointer for storing the initialized device instance data pointer. |
ADI_SPI_RESULT adi_spi_Close | ( | ADI_SPI_HANDLE const | hDevice | ) |
Uninitialize and deallocate an SPI device.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
Uninitialize and release an allocated SPI device,and memory associated with it for other use.
ADI_SPI_RESULT adi_spi_MasterReadWrite | ( | ADI_SPI_HANDLE const | hDevice, |
const ADI_SPI_TRANSCEIVER *const | pXfr | ||
) |
Submit data buffers for SPI Master-Mode transaction in "Blocking mode".This function
returns only after the data transfer is complete.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pXfr | Pointer to transfer data struct ADI_SPI_TRANSCEIVER. |
Request a blocking mode transmit and receive of multiple data bytes
over the SPI serial channel.
Buffer allocations are made by the calling code (the application).
The transmit buffer is sent and the receive buffer is written according
to the size and increment information contained by the pXft transfer
data structure parameter.
ADI_SPI_RESULT adi_spi_SetMasterMode | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set SPI Master-Mode operation.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to select either Master-Mode or Slave-Mode operation. - true Enable Master-Mode. Default. - false Enable Slave-Mode. |
Controls SPI Master/Slave mode of operation, set for Master-Mode, clear for Slave-Mode.
ADI_SPI_RESULT adi_spi_SlaveReadWrite | ( | ADI_SPI_HANDLE const | hDevice, |
const ADI_SPI_TRANSCEIVER *const | pXfr | ||
) |
Submit data buffers for SPI Slave-Mode transaction in "Blocking mode".This function
returns only after the data transfer is complete.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pXfr | Pointer to transfer data struct ADI_SPI_TRANSCEIVER. |
Request a blocking mode transmit and receive of multiple data bytes
over the SPI serial channel.
Buffer allocations are made by the calling code (the application).
The transmit buffer is sent and the receive buffer is written according
to the size and increment information contained by the pXft transfer
data structure parameter.
ADI_SPI_RESULT adi_spi_MasterSubmitBuffer | ( | ADI_SPI_HANDLE const | hDevice, |
const ADI_SPI_TRANSCEIVER *const | pXfr | ||
) |
Submit data buffers for SPI Master-Mode transaction.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pXfr | Pointer to transfer data struct. |
Request a non-blocking mode transmit and receive of multiple data bytes
over the SPI serial channel.
Buffer allocations are made by the calling code (the application).
The transmit buffer is sent and the receive buffer is written according
to the size and increment information contained by the pXft transfer
data structure parameter.
Definition at line 874 of file adi_spi.c.
Referenced by adi_spi_MasterReadWrite().
ADI_SPI_RESULT adi_spi_SlaveSubmitBuffer | ( | ADI_SPI_HANDLE const | hDevice, |
const ADI_SPI_TRANSCEIVER *const | pXfr | ||
) |
Submit data buffers for SPI Slave-Mode transaction.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pXfr | Pointer to transfer data struct. |
Request a non-blocking transmit and receive of multiple data bytes
over the SPI serial channel. Honours current blocking and DMA modes.
Buffer allocations are made by the calling code (the application).
The transmit buffer is sent and the receive buffer is written according
to the size and increment information contained by the pXft transfer
data structure parameter.
The application must make a call to adi_spi_GetBuffer() to retrieve the buffer
Definition at line 1322 of file adi_spi.c.
Referenced by adi_spi_SlaveReadWrite().
ADI_SPI_RESULT adi_spi_RegisterCallback | ( | ADI_SPI_HANDLE const | hDevice, |
ADI_CALLBACK const | pfCallback, | ||
void *const | pCBParam | ||
) |
Register or unregister the callback.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pfCallback | Pointer to the callback function. Can be passed as NULL to unregister the previously registered callback. |
[in] | pCBParam | Callback parameter which will be passed back to the application when the callback is called. |
ADI_SPI_RESULT adi_spi_GetBuffer | ( | ADI_SPI_HANDLE const | hDevice, |
uint32_t *const | pHWErrors | ||
) |
Block until the SPI transaction is complete.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[out] | pHWErrors | Pointer to hardware error return variable. |
ADI_SPI_RESULT adi_spi_SetClockPhase | ( | ADI_SPI_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the clock phase.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to manage the phase of the serial data clock. - true Sample data on trailing-edge of each serial bit. - false Sample data on leading-edge of each serial bit. |
Sets the SPI clock polarity phase bit (CPHA). Used in conjunction with clock polarity (CPOL) to program
the exact timing of serial data capture and transmit. Both clock phase and polarity must be considered in
selecting the data transfer mode best suited to the Master/Slave device pair, typically dependant on the
manufacturer and timing requirements of the external SPI device.
Both Master and Slave devices must use the same settings for clock phase and polarity.
If the phase of the clock is zero (CPHA=0), receive data are latched on the rising-clock-edge with
CPOL=0 (idle-low) polarity, and on the falling-clock-edge with CPOL=1 (idle high) ploarity.
If CPHA=1, the effective clock edges are reversed; CPOL=0 latches receive data on the falling-clock-edge
and CPOL=1 latches receive data on the rising-clock-edge.
Data are transmitted on the opposite clock edge as the receive, i.e., receive and transmit are out of phase.
ADI_SPI_RESULT adi_spi_SetClockPolarity | ( | ADI_SPI_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the clock polarity.
[in] | hDevice | Device handle obtained from adi_spi_Open() |
[in] | bFlag | Flag to manage the idle state of the serial data clock between samples. - true Clock is idled high. - false Clock is idled low. |
Sets the SPI clock polarity control bit (CPOL). Used in conjunction with clock phase (CPHA) to program
the exact timing of serial data capture and transmit. Both clock phase and polarity must be considered in
selecting the data transfer mode best suited to the Master/Slave device pair, typically dependant on the
manufacturer and timing requirements of the external SPI device.
Both Master and Slave devices must use the same settings for clock phase and polarity.
If the phase of the clock is zero (CPHA=0), receive data are latched on the rising-clock-edge with
CPOL=0 (idle-low) polarity, and on the falling-clock-edge with CPOL=1 (idle high) ploarity.
If CPHA=1, the effective clock edges are reversed; CPOL=0 latches receive data on the falling-clock-edge
and CPOL=1 latches receive data on the rising-clock-edge.
Data are transmitted on the opposite clock edge as the receive, i.e., receive and transmit are out of phase.
ADI_SPI_RESULT adi_spi_isBufferAvailable | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
bool *const | bComplete | ||
) |
Get the SPI transaction completion status.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[out] | bComplete | Pointer to boolean variable that indicates - true DMA transmit sequence is complete. - false DMA transmit sequence is incomplete. |
ADI_SPI_RESULT adi_spi_SetContinuousMode | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the continuous transfer mode.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to manage SPI continuous transfer mode.
|
Setting this mode causes the SPI controller to drive the Chip Select signal continuously until the transaction is complete. Clearing it causes Chip Select to cycle between bytes.
ADI_SPI_RESULT adi_spi_SetLoopback | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the internal loopback mode.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to manage internal SPI loopback mode.
|
Set or clear the internal SPI loopback mode. Primarily used for testing.
ADI_SPI_RESULT adi_spi_SetIrqmode | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const uint8_t | nMode | ||
) |
Set the IRQ mode.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | nMode | IRQ mode value to set. Valid values are 0 - 7 Tx interrupt occurs when (nMode+1) byte has been transferred. Rx interrupt occurs when (nMode+1) or more bytes have been received into the FIFO. |
These bits configure when the Tx/Rx interrupts occur in a transfer. For DMA Rxtransfer, these bits should be 0. Valid values are 0-7 Tx interrupt occurs when (nMode+1) byte(s) has been transferred. Rx interrupt occurs when (nMode+1) or more bytes have been received into the FIFO.
ADI_SPI_RESULT adi_spi_SetReceiveOverflow | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the SPI receive FIFO overflow mode.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to manage receive FIFO overflow behaviour. - true Discard old data on receive FIFO overflow. - false Discard new data on receive FIFO overflow. |
Controls what to do with excess incoming data when the receive FIFO becomes full. Either the new data or the old data is discarded. Set the receive FIFO overflow mode to replace data in the RX register (top of receive FIFO) with the incoming new data. Clear it to discard incoming new data and preserve old unread data.
ADI_SPI_RESULT adi_spi_SetTransmitUnderflow | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const bool | bFlag | ||
) |
Set the SPI transmit FIFO underflow mode.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | bFlag | Flag to manage transmit FIFO underflow behaviour. - true Send zeroes on transmit FIFO underflow. - false Resend last data on transmit FIFO underflow. |
Controls what to transmit when lacking valid data because the transmit FIFO is empty.
Either zeros or the last valid data are transmitted. Set transmit FIFO underflow mode to send zeros.
Clear it to resend the last transmitted data.
ADI_SPI_RESULT adi_spi_SetBitrate | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
const uint32_t | Hertz | ||
) |
Set the SPI serial clock frequency.
[in] | hDevice | Device handle obtained from adi_spi_Open() |
[in] | Hertz | Target frequency (in Hz) for SPI bitrate. |
Compute and set the internal SPI clock rate divider register to produce
the desired serial clock frequency. Resulting frequency is subject to arithmetic rounding errors.
Use adi_spi_GetBitrate() to obtain the exact frequency produced, including rounding errors.
ADI_SPI_RESULT adi_spi_SetChipSelect | ( | ADI_SPI_HANDLE const | hDevice, |
const ADI_SPI_CHIP_SELECT | eChipSelect | ||
) |
Set the chip select.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | eChipSelect | An enum value representing the requested Chip Select. |
Sets the desired chip select to use for activating an external slave device.
ADI_SPI_RESULT adi_spi_GetBitrate | ( | ADI_SPI_CONST_HANDLE const | hDevice, |
uint32_t *const | pnBitrate | ||
) |
Get the SPI serial clock frequency.
[in] | hDevice | Device handle obtained from adi_spi_Open() |
[out] | pnBitrate | Pointer to the location where Bitrate need to be written. |
Get the current serial clock frequency. The returned value is exact but
may not exactly match the value set with adi_spi_SetBitrate() due to
computational round-off errors resulting from fixed register size and
finite-precision arithmetic.