This section describes the programming interface of the DSPI master mode peripheral driver. The DSPI master mode peripheral driver transfers data to and from external devices on the DSPI bus in master mode. It supports transferring data buffers with a single function call.
DSPI Introduction
The driver is separated into two implementations: interrupt-driven and DMA-driven. The interrupt-driven driver uses interrupts to alert the CPU that the DSPI module needs to service the SPI data transmit and receive operations. The enhanced DMA (eDMA)-driven driver uses the eDMA module to transfer data between the buffers located in memory and the DSPI module transmit/receive buffers/FIFOs. In the subsequent sections the enhanced DMA-driven driver is referred to as the DMA-driven driver. The interrupt-driven and DMA-driven driver APIs are distinguished with the keyword "edma" in the source file name and by the keyword "Edma" in the API name. Each set of drivers have the same API functionality and are described in the following sections. Note that the DMA driven driver also uses interrupts to alert the CPU that the DMA has completed its transfer or that one final piece of data still needs to be received which is handled by the IRQ handler in the DMA driven driver. In both the interrupt and DMA drivers, the SPI module interrupts are enabled in the NVIC. In addition, the DMA driven-driver requests channels from the eDMA module. Also, these sections refer to either set of drivers as the "DSPI master driver" when discussing items that pertain to either driver. Note, when using the DMA driven DSPI driver, initialize the eDMA module. An example is shown in the Initialization section.
This is a step-by-step process to initialize and transfer the SPI data. For API specific examples, see the examples below. The example uses the interrupt-driven APIs and a blocking transfer to illustrate a high-level step-by-step usage. The usage of eDMA driver is similar to the interrupt-driven driver. Keep in mind that using interrupt and eDMA drivers in the same runtime application is not recommended because the SPI interrupt handler needs to be changed. The interrupt driver calls the DSPI_DRV_IRQHandler() function and the eDMA driver calls the DSPI_DRV_EdmaIRQHandler() function. See files fsl_dspi_irq.c and fsl_dspi_edma_irq.c for an example of these function calls.
s_dspiSinkBuffer, 32, 1000);
Note that it is not recommended to mix interrupt and DMA driven drivers in the same application. However, should the user decide to do so, separately set up and initialize another instance for DMA operations. The user can also de-initialize the current interrupt-driven DSPI instance and re-initialize it for DMA operations. Note, that, because the DMA driven driver also uses interrupts, the user must direct the IRQ handler from the vector table to the desired driver's IRQ handler. See files fsl_dspi_irq.c and fsl_dspi_edma_irq.c for examples on how to re-direct the IRQ handlers from the vector table to the interrupt-driven and DMA-driven driver IRQ handlers. Such files need to be included in the application project to direct the DSPI interrupt vectors to the proper IRQ handlers. The fsl_dspi_shared_function.c and fsl_dspi_edma_shared_function.c files direct the interrupts from the vector table to the appropriate master or slave driver interrupt handler by checking the DSPI mode via the HAL function DSPI_HAL_IsMaster(baseAddr). Note that the interrupt driver calls the DSPI_DRV_IRQHandler() function and the eDMA driver calls the DSPI_DRV_EdmaIRQHandler() function. See files fsl_dspi_irq.c and fsl_dspi_edma_irq.c for an example of these function calls.
When using the DSPI driver with the eDMA some DSPI instances do not support separate DMA requests for transmit and receive channels. In those cases with a single shared DMA request for transmit and receive DMA channels, the driver links one channel to the other to still take advantage of DMA transfers. However, the drawback to using an instance with shared DMA requests limits the maximum amount of data the driver can transfer. This limit depends on the bits/frame setting.
For DSPI instances with separate transmit and receive DMA requests, the maximum number of bytes that can be transferred is: 8-bit setting: 32767 bytes 16-bit setting: 65534 bytes
For DSPI instances with a shared transmit and receive DMA request, the maximum number of bytes that can be transferred is: 8-bit setting: 511 bytes 16-bit setting: 1022 bytes
See the microcontroller-specific documentation to see which DSPI instance have separate or shared transmit and receive DMA requests. Additionally, see the microcontroller-specific feature header file to see which DSPI instance have separate or shared transmit and receive DMA requests.
DSPI Run-time state structures
The DSPI master driver uses a run-time state structure to track the ongoing data transfers. The state structure for the interrupt-driven driver is called the dspi_master_state_t. The structure for the DMA driven driver is called the dspi_edma_master_state_t. This structure holds data that the DSPI master peripheral driver uses to communicate between the transfer function and the interrupt handler and other driver functions. The interrupt handler in the interrupt driven also uses this information to keep track of its progress. The user is only required to pass the memory for the run-time state structure. The DSPI master driver populates the members.
DSPI User configuration structures
The DSPI master driver uses instances of the user configuration structure for the DSPI master driver. The user configuration structure for the interrupt-driven driver is called the dspi_master_user_config_t. The user configuration structure for the DMA driven driver is called the dspi_edma_master_user_config_t. This structure allows the user to configure the most common settings of the DSPI peripheral with a single function call. The user configuration structure is passed into the master driver initialization function (DSPI_DRV_MasterInit or DSPI_DRV_EdmaMasterInit). The user configuration structure consists of whichCtar (generally set this to kDspiCtar0), option for continuous clock and peripheral chip select, the desired peripheral chip select to use, and the polarity of the peripheral chip select settings. An example of this is provided in the Initialization section.
DSPI Device structures
The DSPI master driver uses instances of the dspi_device_t or dspi_edma_device_t structure to represent the SPI bus configuration required to communicate to an external device that is connected to the bus.
The device structure can be passed into the DSPI_DRV_MasterConfigureBus or DSPI_DRV_EdmaMasterConfigureBus functions to manually configure the bus for a particular device. For example, if there is only one device connected to the bus, the user might configure it only once. Alternatively, the device structure can be passed to the data transfer functions where the bus is reconfigured before the transfer is started. The device structure consists of bitsPerSec (baud rate in Hz) and the dataBusConfig structure which consists of bits per frame, clock polarity and phase, and data shift direction (MSB or LSB).
DSPI Initialization
To initialize the DSPI master driver, call the DSPI_DRV_MasterInit() or the DSPI_DRV_EdmaMasterInit functions and pass the instance number of the DSPI peripheral, the memory allocation for the run-time state structure used by the master driver to keep track of data transfers, and the user configuration (dspi_master_user_config_t or dspi_edma_master_user_config_t). For the DMA driven driver, the memory allocation for the stcdSrc2CmdDataLast structure needs to be passed. Note that the pointer to this structure needs to be aligned to a 32-byte boundary.
First call the DSPI master initialization to initialize the DSPI module. Then, call the DSPI master configuration bus to configure the module for the specific device on the SPI bus. For the interrupt-driven case, while the DSPI_DRV_MasterInit() function initializes the DSPI peripheral, the DSPI_DRV_MasterConfigureBus() function configures the SPI bus parameters such as bits/frame, clock characteristics, data shift direction, baud rate, and desired chip select. The DMA-driven case follows the same logic, except that it uses the EDMA API names. Both examples are provided below. The interrupt driven example is provided first followed by the DMA example.
This is an example code to initialize and configure the DSPI master interrupt-driven driver including setting up the user configuration and device structures:
uint32_t masterInstance = 1;
uint32_t calculatedBaudRate;
This is an example code to initialize and configure the DSPI master DMA-driven driver including setting up the user configuration and device structures:
#pragma data_alignment=32
uint32_t masterInstance = 0;
uint32_t calculatedBaudRate;
The DSPI also offers an optional API to configure various bus timing delays. This function involves the DSPI module delay options to "fine tune" some of the signal timings and match the timing needs of a slower peripheral device. This is an optional function that can be called after the DSPI module is initialized for master mode. The bus timing delays that can be adjusted are listed here:
PCS to SCK Delay: Adjustable delay option between the assertion of the PCS signal to the first SCK edge.
After SCK Delay: Adjustable delay option between the last edge of SCK to the de-assertion of the PCS signal.
Delay after Transfer: Adjustable delay option between the de-assertion of the PCS signal for a frame to the assertion of the PCS signal for the next frame. Note that this is not adjustable for continuous clock mode because this delay is fixed at one SCK period.
This function takes in as a parameter the desired delay type and the delay value (in nanoseconds) and calculates the values needed for the prescaler and scaler. Returning the actual calculated delay as an exact delay match may not be possible. In this situation, the closest match is calculated without going below the desired delay value input. It is possible to input a very large delay value that exceeds the capability of the part, in which case the maximum supported delay is returned. In addition, the function returns an out-of-range status.
This is an example that shows how to use the set the bus timings delay function:
uint32_t delayInNanoSec = 200;
uint32_t calculatedDelay;
DSPI Transfers
The driver supports two different modes for transferring data: blocking and non-blocking (async). The blocking transfer function waits until the transfer is complete before returning. A timeout parameter is passed into the blocking function. A non-blocking (async) function returns immediately after starting the transfer. The user is required to get the transfer status during the transfer to ascertain when the transfer is complete. Additional functions provided to aid in non-blocking transfers are get transfer status and abort transfer. If there is a cache for memory, when using DMA to transfer data, ensure that the data is consistent. In other words, when reading the data from memory, application should ensure that the data to/from the memory device is current and is not not cached.
Blocking transfer function APIs (interrupt and DMA driven):
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
size_t transferByteCount,
uint32_t timeout);
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
size_t transferByteCount,
uint32_t timeout);
Non-blocking function APIs and associated functions (interrupt and DMA-driven):
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
size_t transferByteCount);
const uint8_t * sendBuffer,
uint8_t * receiveBuffer,
size_t transferByteCount);
Example of a blocking transfer (interrupt and DMA-driven). Note that the peripheral driver must be initialized first. See the Initialization Section for initialization information.
s_dspiSinkBuffer, 32, 1000);
s_dspiSinkBuffer, 32, 1000);
Example of a non-blocking transfer (interrupt and DMA-driven). Note that the peripheral driver must be initialized first. See the Initialization Section for initialization information.
DSPI De-initialization
To deinitialize and shut down the DSPI module, call this function:
|
| SPI_Type *const | g_dspiBase [SPI_INSTANCE_COUNT] |
| | Table of base pointers for SPI instances. More...
|
| |
| const IRQn_Type | g_dspiIrqId [SPI_INSTANCE_COUNT] |
| | Table to save DSPI IRQ enumeration numbers defined in the CMSIS header file. More...
|
| |
| SPI_Type *const | g_dspiBase [SPI_INSTANCE_COUNT] |
| | Table of base pointers for SPI instances. More...
|
| |
| const IRQn_Type | g_dspiIrqId [SPI_INSTANCE_COUNT] |
| | Table to save DSPI IRQ enumeration numbers defined in the CMSIS header file. More...
|
| |
| SPI_Type *const | g_dspiBase [SPI_INSTANCE_COUNT] |
| | Table of base pointers for SPI instances. More...
|
| |
| const IRQn_Type | g_dspiIrqId [SPI_INSTANCE_COUNT] |
| | Table to save DSPI IRQ enumeration numbers defined in the CMSIS header file. More...
|
| |
The user must populate the members to set up the DSPI master with DMA and properly communicate with the SPI device.
| uint32_t dspi_dma_device_t::bitsPerSec |
| struct dspi_dma_master_state_t |
This structure holds data used by the DSPI master Peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user passes the memory for this run-time state structure. The DSPI master driver populates the members.
| volatile bool dspi_dma_master_state_t::isTransferInProgress |
| volatile bool dspi_dma_master_state_t::isTransferBlocking |
| uint8_t* dspi_dma_master_state_t::rxBuffer |
| uint32_t dspi_dma_master_state_t::rxTransferByteCnt |
| struct dspi_dma_master_user_config_t |
Use an instance of this structure with the DSPI_DRV_DmaMasterInit() function. This allows the user to configure the most common settings of the DSPI peripheral with a single function call.
| struct dspi_edma_device_t |
The user must populate the members to set up the DSPI master with EDMA and properly communicate with the SPI device.
| uint32_t dspi_edma_device_t::bitsPerSec |
| struct dspi_edma_master_state_t |
This structure holds data used by the DSPI master Peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user passes the memory for this run-time state structure. The DSPI master driver populates the members.
| volatile bool dspi_edma_master_state_t::isTransferInProgress |
| volatile bool dspi_edma_master_state_t::isTransferBlocking |
| uint8_t* dspi_edma_master_state_t::rxBuffer |
| uint32_t dspi_edma_master_state_t::rxTransferByteCnt |
| struct dspi_edma_master_user_config_t |
Use an instance of this structure with the DSPI_DRV_EdmaMasterInit() function. This allows the user to configure the most common settings of the DSPI peripheral with a single function call.
The user must populate these members to set up the DSPI master and properly communicate with the SPI device.
| uint32_t dspi_device_t::bitsPerSec |
| struct dspi_master_state_t |
This structure holds data that is used by the DSPI master peripheral driver to communicate between the transfer function and the interrupt handler. The interrupt handler also uses this information to keep track of its progress. The user must pass the memory for this run-time state structure. The DSPI master driver populates the members.
| volatile bool dspi_master_state_t::isTransferInProgress |
| const uint8_t* dspi_master_state_t::sendBuffer |
| uint8_t* dspi_master_state_t::receiveBuffer |
| volatile size_t dspi_master_state_t::remainingSendByteCount |
| volatile size_t dspi_master_state_t::remainingReceiveByteCount |
| volatile bool dspi_master_state_t::isTransferBlocking |
| struct dspi_master_user_config_t |
Use an instance of this structure with the DSPI_DRV_MasterInit() function. This allows the user to configure the most common settings of the DSPI peripheral with a single function call.
This function uses a DMA-driven method for transferring data. This function initializes the run-time state structure to track the ongoing transfers, ungates the clock to the DSPI module, resets the DSPI module, initializes the module to user-defined settings and default settings, configures the IRQ state structure, enables the module-level interrupt to the core, and enables the DSPI module. The CTAR parameter is special in that it allows the user to have different SPI devices connected to the same DSPI module instance in addition to different peripheral chip selects. Each CTAR contains the bus attributes associated with that particular SPI device. For most use cases, where only one SPI device is connected per DSPI module instance, use CTAR0. This is an example to set up and call the DSPI_DRV_DmaMasterInit function by passing in these parameters:
uint32_t calculatedBaudRate;
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| dspiDmaState | The pointer to the DSPI DMA master driver state structure. The user passes the memory for the run-time state structure. The DSPI master driver populates the members. The run-time state structure keeps track of the transfer in progress. |
| userConfig | The dspi_dma_master_user_config_t user configuration structure. The user populates the members of this structure and passes the pointer of the structure into the function. |
| stcdSrc2CmdDataLast | This is a pointer to a structure of the stcdSrc2CmdDataLast type. It needs to be aligned to a 32-byte boundary. Some compilers allow you to use a #pragma directive to align a variable to a desired boundary. |
- Returns
- An error code or kStatus_DSPI_Success.
This function resets the DSPI peripheral, gates its clock, disables any used interrupts to the core, and releases any used DMA channels.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success indicating successful de-initialization
This function uses the DSPI module delay options to "fine tune" some of the signal timings and match the timing needs of a slower peripheral device. This is an optional function that can be called after the DSPI module has been initialized for master mode. The bus timing delays that can be adjusted are listed below:
PCS to SCK Delay: Adjustable delay option between the assertion of the PCS signal to the first SCK edge.
After SCK Delay: Adjustable delay option between the last edge of SCK to the de-assertion of the PCS signal.
Delay after Transfer: Adjustable delay option between the de-assertion of the PCS signal for a frame to the assertion of the PCS signal for the next frame. Note that this is not adjustable for continuous clock mode because this delay is fixed at one SCK period.
Each of the above delay parameters use both a pre-scalar and scalar value to calculate the needed delay. This function takes in as a parameter the desired delay type and the delay value (in nanoseconds), calculates the values needed for the prescaler and scaler. Returning the actual calculated delay as an exact delay match may not be possible. In this case, the closest match is calculated without going below the desired delay value input. It is possible to input a very large delay value that exceeds the capability of the part, in which case the maximum supported delay is returned. In addition, the function returns an out-of-range status.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| whichDelay | The desired delay to configure, must be of type dspi_delay_type_t |
| delayInNanoSec | The desired delay value in nano-seconds. |
| calculatedDelay | The calculated delay that best matches the desired delay (in nano-seconds). |
- Returns
- Either kStatus_DSPI_Success or kStatus_DSPI_OutOfRange if the desired delay exceeds the capability of the device.
The term "device" is used to indicate the SPI device for which the DSPI master is communicating. The user has two options to configure the device parameters: pass in the pointer to the device configuration structure to the desired transfer function (see DSPI_DRV_DmaMasterTransferBlocking or DSPI_DRV_DmaMasterTransfer) or pass it in to the DSPI_DRV_DmaMasterConfigureBus function. The user can pass in a device structure to the transfer function which contains the parameters for the bus (the transfer function then calls this function). However, the user has the option to call this function directly especially to get the calculated baud rate, at which point they may pass in NULL for the device structure in the transfer function (assuming they have called this configure bus function first). This is an example to set up the dspi_device_t structure to call the DSPI_DRV_DmaMasterConfigureBus function by passing in these parameters:
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration. The device parameters are the desired baud rate (in bits-per-sec), and the data format field which consists of bits-per-frame, clock polarity and phase, and data shift direction. |
| calculatedBaudRate | The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The baud rate never exceeds the desired baud rate. |
- Returns
- An error code or kStatus_DSPI_Success.
| dspi_status_t DSPI_DRV_DmaMasterTransferBlocking |
( |
uint32_t |
instance, |
|
|
const dspi_dma_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount, |
|
|
uint32_t |
timeout |
|
) |
| |
This function simultaneously sends and receives data on the SPI bus, because the SPI is naturally a full-duplex bus. The function does not return until the transfer is complete.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_DmaMasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter and bytes with a value of 0 (zero) is sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
| timeout | A timeout for the transfer in milliseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error returned. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress, or kStatus_DSPI_Timeout The transfer timed out and was aborted.
| dspi_status_t DSPI_DRV_DmaMasterTransfer |
( |
uint32_t |
instance, |
|
|
const dspi_dma_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount |
|
) |
| |
This function returns immediately. The user must check back whether the transfer is complete (using the DSPI_DRV_DmaMasterGetTransferStatus function). This function simultaneously sends and receives data on the SPI bus because the SPI is a full-duplex bus.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_DmaMasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress.
| dspi_status_t DSPI_DRV_DmaMasterGetTransferStatus |
( |
uint32_t |
instance, |
|
|
uint32_t * |
framesTransferred |
|
) |
| |
When performing an a-sync transfer, the user can call this function to ascertain the state of the current transfer: in progress (or busy) or complete (success). In addition, if the transfer is still in progress, the user can get the number of words that have been transferred up to now.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| framesTransferred | Pointer to value populated with the number of frames that have been sent during the active transfer. A frame is defined as the number of bits per frame. |
- Returns
- kStatus_DSPI_Success The transfer has completed successfully, or kStatus_DSPI_Busy The transfer is still in progress. framesTransferred is filled with the number of words that have been transferred so far.
| dspi_status_t DSPI_DRV_DmaMasterAbortTransfer |
( |
uint32_t |
instance | ) |
|
During an a-sync transfer, the user has the option to terminate the transfer early if the transfer is still in progress.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_NoTransferInProgress No transfer is currently in progress.
This function uses a DMA-driven method for transferring data. This function initializes the run-time state structure to track the ongoing transfers, ungates the clock to the DSPI module, resets the DSPI module, initializes the module to user-defined settings and default settings, configures the IRQ state structure, enables the module-level interrupt to the core, and enables the DSPI module. The CTAR parameter is special in that it allows the user to have different SPI devices connected to the same DSPI module instance in addition to different peripheral chip selects. Each CTAR contains the bus attributes associated with that particular SPI device. For most use cases, where only one SPI device is connected per DSPI module instance, use CTAR0. This is an example to set up and call the DSPI_DRV_EdmaMasterInit function by passing in these parameters:
uint32_t calculatedBaudRate;
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| dspiEdmaState | The pointer to the DSPI EDMA master driver state structure. The user passes the memory for the run-time state structure. The DSPI master driver populates the members. The run-time state structure keeps track of the transfer in progress. |
| userConfig | The dspi_edma_master_user_config_t user configuration structure. The user populates the members of this structure and passes the pointer of the structure into the function. |
| stcdSrc2CmdDataLast | This is a pointer to a structure of the stcdSrc2CmdDataLast type. It needs to be aligned to a 32-byte boundary. Some compilers allow you to use a #pragma directive to align a variable to a desired boundary. |
- Returns
- An error code or kStatus_DSPI_Success.
This function resets the DSPI peripheral, gates its clock, disables any used interrupts to the core, and releases any used DMA channels.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success indicating successful de-initialization
This function uses the DSPI module delay options to "fine tune" some of the signal timings and match the timing needs of a slower peripheral device. This is an optional function that can be called after the DSPI module has been initialized for master mode. The bus timing delays that can be adjusted are listed below:
PCS to SCK Delay: Adjustable delay option between the assertion of the PCS signal to the first SCK edge.
After SCK Delay: Adjustable delay option between the last edge of SCK to the de-assertion of the PCS signal.
Delay after Transfer: Adjustable delay option between the de-assertion of the PCS signal for a frame to the assertion of the PCS signal for the next frame. Note that this is not adjustable for continuous clock mode because this delay is fixed at one SCK period.
Each of the above delay parameters uses both a pre-scalar and scalar value to calculate the needed delay. This function takes the desired delay type as a parameter and the delay value (in nanoseconds), calculates the values needed for the prescaler and scaler. Returning the actual calculated delay as an exact delay match may not be possible. In this situation, the closest match is calculated without going below the desired delay value input. It is possible to input a very large delay value that exceeds the capability of the part, in which case the maximum supported delay is returned. In addition, the function returns an out-of-range status.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| whichDelay | The desired delay to configure, must be of type dspi_delay_type_t |
| delayInNanoSec | The desired delay value in nanoseconds. |
| calculatedDelay | The calculated delay that best matches the desired delay (in nanoseconds). |
- Returns
- Either kStatus_DSPI_Success or kStatus_DSPI_OutOfRange if the desired delay exceeds the capability of the device.
The term "device" describes the SPI device for which the DSPI master is communicating. The user has two options to configure the device parameters: pass in the pointer to the device configuration structure to the desired transfer function (see DSPI_DRV_EdmaMasterTransferBlocking or DSPI_DRV_EdmaMasterTransfer) or pass it in to the DSPI_DRV_EdmaMasterConfigureBus function. The user can pass in a device structure to the transfer function which contains the parameters for the bus (the transfer function then calls this function). However, the user has the option to call this function directly to get the calculated baud rate, at which point, the user may pass in NULL for the device structure in the transfer function (assuming they have called this configure bus function first). This is an example to set up the dspi_device_t structure to call the DSPI_DRV_EdmaMasterConfigureBus function by passing in these parameters:
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration. The device parameters are the desired baud rate (in bits-per-sec), and the data format field which consists of bits-per-frame, clock polarity and phase, and data shift direction. |
| calculatedBaudRate | The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The baud rate never exceeds the desired baud rate. |
- Returns
- An error code or kStatus_DSPI_Success.
| dspi_status_t DSPI_DRV_EdmaMasterTransferBlocking |
( |
uint32_t |
instance, |
|
|
const dspi_edma_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount, |
|
|
uint32_t |
timeout |
|
) |
| |
This function simultaneously sends and receives data on the SPI bus, because the SPI is naturally a full-duplex bus. The function does not return until the transfer is complete.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_EdmaMasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter and bytes with a value of 0 (zero) is sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
| timeout | A timeout for the transfer in milliseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error returned. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress, or kStatus_DSPI_Timeout The transfer timed out and was aborted.
| dspi_status_t DSPI_DRV_EdmaMasterTransfer |
( |
uint32_t |
instance, |
|
|
const dspi_edma_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount |
|
) |
| |
This function returns immediately. The user must check back whether the transfer is complete (using the DSPI_DRV_EdmaMasterGetTransferStatus function). This function simultaneously sends and receives data on the SPI bus because the SPI is a full-duplex bus.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_EdmaMasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress.
| dspi_status_t DSPI_DRV_EdmaMasterGetTransferStatus |
( |
uint32_t |
instance, |
|
|
uint32_t * |
framesTransferred |
|
) |
| |
When performing an a-sync transfer, the user can call this function to ascertain the state of the current transfer: in progress (or busy) or complete (success). In addition, if the transfer is still in progress, the user can get the number of words that have been transferred up to now.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| framesTransferred | Pointer to value populated with the number of frames that have been sent during the active transfer. A frame is defined as the number of bits per frame. |
- Returns
- kStatus_DSPI_Success The transfer has completed successfully, or kStatus_DSPI_Busy The transfer is still in progress. framesTransferred is filled with the number of words that have been transferred so far.
| dspi_status_t DSPI_DRV_EdmaMasterAbortTransfer |
( |
uint32_t |
instance | ) |
|
During an a-sync transfer, the user has the option to terminate the transfer early if the transfer is still in progress.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_NoTransferInProgress No transfer is currently in progress.
| void DSPI_DRV_EdmaMasterIRQHandler |
( |
uint32_t |
instance | ) |
|
This handler uses the buffers stored in the dspi_master_state_t structures to transfer data.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
This function uses a CPU interrupt driven method for transferring data. This function initializes the run-time state structure to track the ongoing transfers, un-gates the clock to the DSPI module, resets the DSPI module, initializes the module to user defined settings and default settings, configures the IRQ state structure, enables the module-level interrupt to the core, and enables the DSPI module. The CTAR parameter is special in that it allows the user to have different SPI devices connected to the same DSPI module instance in addition to different peripheral device selects. Each CTAR contains the bus attributes associated with that particular SPI device. For most use cases where only one SPI device is connected per DSPI module instance, use CTAR0. This is an example to set up the dspi_master_state_t and the dspi_master_user_config_t parameters and to call the DSPI_DRV_MasterInit function by passing in these parameters:
uint32_t calculatedBaudRate;
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| dspiState | The pointer to the DSPI master driver state structure. The user passes the memory for this run-time state structure. The DSPI master driver populates the members. This run-time state structure keeps track of the transfer in progress. |
| userConfig | The dspi_master_user_config_t user configuration structure. The user populates the members of this structure and passes the pointer of this structure to the function. |
- Returns
- An error code or kStatus_DSPI_Success.
This function resets the DSPI peripheral, gates its clock, and disables the interrupt to the core.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success indicating successful de-initialization
This function involves the DSPI module's delay options to "fine tune" some of the signal timings and match the timing needs of a slower peripheral device. This is an optional function that can be called after the DSPI module has been initialized for master mode. The bus timing delays that can be adjusted are listed below:
PCS to SCK Delay: Adjustable delay option between the assertion of the PCS signal to the first SCK edge.
After SCK Delay: Adjustable delay option between the last edge of SCK to the de-assertion of the PCS signal.
Delay after Transfer: Adjustable delay option between the de-assertion of the PCS signal for a frame to the assertion of the PCS signal for the next frame. Note that this is not adjustable for continuous clock mode because this delay is fixed at one SCK period.
Each of the above delay parameters use both a pre-scalar and scalar value to calculate the needed delay. This function takes in as a parameter the desired delay type and the delay value (in nanoseconds), calculates the values needed for the prescaler and scaler. Returning the actual calculated delay as an exact delay match may not be possible. In this case, the closest match is calculated without going below the desired delay value input. It is possible to input a very large delay value that exceeds the capability of the part, in which case the maximum supported delay is returned. In addition, the function returns an out-of-range status.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| whichDelay | The desired delay to configure, must be of type dspi_delay_type_t |
| delayInNanoSec | The desired delay value in nanoseconds. |
| calculatedDelay | The calculated delay that best matches the desired delay (in nanoseconds). |
- Returns
- Either kStatus_DSPI_Success or kStatus_DSPI_OutOfRange if the desired delay exceeds the capability of the device.
The term "device" is used to indicate the SPI device for which the DSPI master is communicating. The user has two options to configure the device parameters: either pass in the pointer to the device configuration structure to the desired transfer function (see DSPI_DRV_MasterTransferBlocking or DSPI_DRV_MasterTransfer) or pass it in to the DSPI_DRV_MasterConfigureBus function. The user can pass in a device structure to the transfer function which contains the parameters for the bus (the transfer function then calls this function). However, the user has the option to call this function directly especially to get the calculated baud rate, at which point they may pass in NULL for the device structure in the transfer function (assuming they have called this configure bus function first). This is an example to set up the dspi_device_t structure to call the DSPI_DRV_MasterConfigureBus function by passing in these parameters:
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration. The device parameters are the desired baud rate (in bits-per-sec), and the data format field which consists of bits-per-frame, clock polarity and phase, and data shift direction. |
| calculatedBaudRate | The calculated baud rate passed back to the user to determine if the calculated baud rate is close enough to meet the needs. The baud rate never exceeds the desired baud rate. |
- Returns
- An error code or kStatus_DSPI_Success.
| dspi_status_t DSPI_DRV_MasterTransferBlocking |
( |
uint32_t |
instance, |
|
|
const dspi_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount, |
|
|
uint32_t |
timeout |
|
) |
| |
This function simultaneously sends and receives data on the SPI bus, as SPI is naturally a full-duplex bus. The function does not return until the transfer is complete.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_MasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter and bytes with a value of 0 (zero) is sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
| timeout | A timeout for the transfer in milliseconds. If the transfer takes longer than this amount of time, the transfer is aborted and a kStatus_SPI_Timeout error returned. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress, or kStatus_DSPI_Timeout The transfer timed out and was aborted.
| dspi_status_t DSPI_DRV_MasterTransfer |
( |
uint32_t |
instance, |
|
|
const dspi_device_t * |
device, |
|
|
const uint8_t * |
sendBuffer, |
|
|
uint8_t * |
receiveBuffer, |
|
|
size_t |
transferByteCount |
|
) |
| |
This function returns immediately. The user needs to check whether the transfer is complete using the DSPI_DRV_MasterGetTransferStatus function. This function simultaneously sends and receives data on the SPI bus because the SPI is naturally a full-duplex bus.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| device | Pointer to the device information structure. This structure contains the settings for the SPI bus configuration in this transfer. You may pass NULL for this parameter, in which case the current bus configuration is used unmodified. The device can be configured separately by calling the DSPI_DRV_MasterConfigureBus function. |
| sendBuffer | The pointer to the data buffer of the data to send. You may pass NULL for this parameter, in which case bytes with a value of 0 (zero) are sent. |
| receiveBuffer | Pointer to the buffer where the received bytes are stored. If you pass NULL for this parameter, the received bytes are ignored. |
| transferByteCount | The number of bytes to send and receive. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_Busy Cannot perform transfer because a transfer is already in progress.
| dspi_status_t DSPI_DRV_MasterGetTransferStatus |
( |
uint32_t |
instance, |
|
|
uint32_t * |
framesTransferred |
|
) |
| |
When performing an a-sync transfer, the user can call this function to ascertain the state of the current transfer: in progress (or busy) or complete (success). In addition, if the transfer is still in progress, the user can get the number of words that have been transferred up to now.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| framesTransferred | Pointer to value that is filled in with the number of frames that have been sent in the active transfer. A frame is defined as the number of bits per frame. |
- Returns
- kStatus_DSPI_Success The transfer has completed successfully, or kStatus_DSPI_Busy The transfer is still in progress. framesTransferred is filled with the number of words that have been transferred so far.
During an a-sync transfer, the user has the option to terminate the transfer early if the transfer is still in progress.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
- Returns
- kStatus_DSPI_Success The transfer was successful, or kStatus_DSPI_NoTransferInProgress No transfer is currently in progress.
| void DSPI_DRV_MasterIRQHandler |
( |
uint32_t |
instance | ) |
|
This handler uses the buffers stored in the dspi_master_state_t structs to transfer data.
- Parameters
-
| instance | The instance number of the DSPI peripheral. |
| SPI_Type* const g_dspiBase[SPI_INSTANCE_COUNT] |
| const IRQn_Type g_dspiIrqId[SPI_INSTANCE_COUNT] |
| SPI_Type* const g_dspiBase[SPI_INSTANCE_COUNT] |
| const IRQn_Type g_dspiIrqId[SPI_INSTANCE_COUNT] |
| SPI_Type* const g_dspiBase[SPI_INSTANCE_COUNT] |
| const IRQn_Type g_dspiIrqId[SPI_INSTANCE_COUNT] |
