MSPM0G1X0X_G3X0X TI-Driver Library
1.20.01.06
|
Modules | |
SPIMSPM0_STATUS | |
SPIMSPM0_CMD | |
Data Structures | |
struct | SPIMSPM0_HWAttrs |
SPIMSPM0 Hardware attributes. More... | |
struct | SPIMSPM0_Object |
SPIMSPM0 Object. More... | |
Enumerations | |
enum | SPIMSPM0_FrameSize { SPIMSPM0_8bit = 0, SPIMSPM0_16bit = 1 } |
SPIMSPM0 data frame size is used to determine how to configure the DMA data transfers. This field is to be only used internally. More... | |
enum | SPIMSPM0_ReturnPartial { SPIMSPM0_retPartDisabled = 0, SPIMSPM0_retPartEnabledIntNotSet = 1, SPIMSPM0_retPartEnabledIntSet = 2 } |
SPIMSPM0 return partial field indicates the status of the return partial mode and the associated pin interrupt. This field is for internal use only. More... | |
Variables | |
const SPI_FxnTable | SPIMSPM0_fxnTable |
SPI function table pointer. | |
The SPI header file should be included in an application as follows:
Refer to SPI.h for a complete description of APIs.
Note that the user also needs to include the DMAMSPM0.h driver since the SPI uses DMA in order to improve throughput.
The general SPI API should be used in application code, i.e. SPI_open() should be used instead of SPIMSPM0_open(). The configuration file will define the device specific config, and casting in the general API will ensure that the correct device specific functions are called. This is also reflected in the example code.
Before using SPI on MSPM0 devices:
The following is true for peripheral operation:
The following apply for controller operation:
After SPI operation has ended:
The callback function is always called in a SWI context.
If an RX overrun occurs during peripheral operation:
Timeout can occur in SPI_MODE_BLOCKING, there's no timeout in SPI_MODE_CALLBACK. When in SPI_MODE_CALLBACK, the transfer must be cancelled by calling SPI_transferCancel().
If a timeout happens in either SPI_PERIPHERAL or SPI_CONTROLLER mode, the receive buffer will contain the bytes received up until the timeout occurred. The SPI transaction status will be set to SPI_TRANSFER_FAILED. The SPI transaction count will be set to the number of bytes sent/received before timeout. The remaining bytes will be flushed from the TX FIFO so that the subsequent transfer can be executed correctly. Note that specifying a timeout prevents the driver from performing a polling transfer when in peripheral mode.
The power management framework will try to put the device into the most power efficient mode whenever possible. Please see the technical reference manual for further details on each power mode.
The SPIMSPM0.h driver is setting a power constraint during transfers to keep the device out of standby. When the transfer has finished, the power constraint is released. The following statements are valid:
This SPI controller supports a hardware chip select pin. Refer to the user manual on how this hardware chip select pin behaves in regards to the SPI frame format.
Chip select type | SPI_CONTROLLER mode | SPI_PERIPHERAL mode |
---|---|---|
Hardware chip select | No action is needed by the application to select the peripheral. | See the device documentation on it's chip select requirements. |
Software chip select | The application is responsible to ensure that correct SPI peripheral is selected before performing a SPI_transfer(). | See the device documentation on it's chip select requirements. |
In a scenario where the SPI module is operating in controller mode with multiple SPI peripherals, the chip select pin can be reallocated at runtime to select the appropriate peripheral device. See Controller Mode With Multiple Peripherals" use case below. This is only relevant when chip select is a hardware chip select. Otherwise the application can control the chip select pins directly using the GPIO driver.
SPI data frames can be any size from 4-bits to 16-bits. If the dataSize in SPI_Params is greater that 8-bits, then the SPIMSPM0 driver implementation will assume that the SPI_Transaction txBuf and rxBuf point to an array of 16-bit uint16_t elements.
dataSize | buffer element size |
---|---|
4-8 bits | uint8_t |
9-16 bits | uint16_t |
The DMA module generates IRQs on the SPI interrupt vector. This driver automatically installs a DMA aware Hwi (interrupt) to service the assigned DMA channels.
The DMA controller only supports data transfers of up to 1024 data frames. A transfer with more than 1024 frames will be transmitted/received in multiple 1024 sized portions until all data has been transmitted/received. A data frame can be 4 to 16 bits in length.
A uint16_t scratch buffer is used to allow SPI_transfers where txBuf or rxBuf are NULL. Rather than requiring txBuf or rxBuf to have a dummy buffer of size of the transfer count, a single-word DMA accessible uint16_t scratch buffer is used. When rxBuf is NULL, the DMA will transfer all the received SPI data into the scratch buffer as a "bit-bucket". When txBuf is NULL, the scratch buffer is initialized to defaultTxBufValue so the DMA will send some known value. Each SPI driver instance uses its own scratch buffer.
Before SPI_transfer, txBuf should be filled with the outgoing SPI data. These data are sent out during the transfer, while the incoming data are received into rxBuf. To save memory space, txBuf and rxBuf can be assigned to the same buffer location. At the beginning of the transfer, this buffer holds outgoing data. At the end of the transfer, the outgoing data are overwritten and the buffer holds the received SPI data.
When used in blocking mode small SPI transfers are can be done by polling the peripheral & sending data frame-by-frame. A controller device can perform the transfer immediately and return, but a peripheral will block until it receives the number of frames specified in the SPI_Transfer() call. The minDmaTransferSize field in the hardware attributes is the threshold; if the transaction count is below the threshold a polling transfer is performed; otherwise a DMA transfer is done. This is intended to reduce the overhead of setting up a DMA transfer to only send a few data frames.
Notes:
Generic API function | API function | Description |
---|---|---|
SPI_init() | SPIMSPM0_init() | Initialize SPI driver |
SPI_open() | SPIMSPM0_open() | Initialize SPI HW and set system dependencies |
SPI_close() | SPIMSPM0_close() | Disable SPI and DMA HW and release system dependencies |
SPI_control() | SPIMSPM0_control() | Configure an already opened SPI handle |
SPI_transfer() | SPIMSPM0_transfer() | Start transfer from SPI |
SPI_transferCancel() | SPIMSPM0_transferCancel() | Cancel ongoing transfer from SPI |
Receive 100 bytes over SPI in SPI_MODE_BLOCKING.
This use case will perform a transfer in SPI_MODE_BLOCKING until the wanted amount of bytes is transferred or until chip select is deasserted by the SPI controller. This SPI_transfer() call can be used when unknown amount of bytes shall be transferred. Note: The partial return is also possible in SPI_MODE_CALLBACK mode. Note: Polling transfers are not available when using return partial mode.
This use case will configure the SPI driver to transfer continuously in SPI_MODE_CALLBACK, 16 bytes at the time and echoing received data after every 16 bytes.
This use case will configure a SPI controller to send the data in txBuf while receiving data to rxBuf in BLOCKING_MODE.
This use case will configure a SPI controller to send data to one peripheral and then to another in BLOCKING_MODE. It is assumed that SysConfig is configured so that the two chip select pins have a default setting of a high output and that the SPIMSPM0_HWAttrs used points to one of them since the SPI driver will revert to this default setting when switching the chip select pin.
Below is an example of queueing three transactions
This example shows a peripheral device queueing two transactions that will complete one after the other. From the controller's perspective there will be one long transfer.
External hardware connected on the SPI, i.e. SPI controller/peripheral, might have configured a pull on one or more of the SPI lines. Dependent on the hardware, it might conflict with the pull used for the device SPI. To avoid increased leakage and ensure the lowest possible power consumption when the SPI is inactive, the application must configure a matching pull on the SPI IOs. An example of how this can be done is shown below.
This example demonstrates using a GPIO callback on Chip Select to wake up the device to allow low power modes while waiting for a chip select edge.
In sysconfig or the board file, the CSN GPIO should be configured as input/pull up with an interrupt on falling edge. Otherwise, SPI_close() will reset the pin to the wrong settings and you may see line glitches.
*Note: The SPI controller must allow enough time between deasserting the chip select and the start of the transaction for the SPI peripheral to wake up and open up the SPI driver.
enum SPIMSPM0_FrameSize |
SPIMSPM0 data frame size is used to determine how to configure the DMA data transfers. This field is to be only used internally.
Enumerator | |
---|---|
SPIMSPM0_8bit | Frame size 8bit |
SPIMSPM0_16bit | Frame size 8bit |
SPIMSPM0 return partial field indicates the status of the return partial mode and the associated pin interrupt. This field is for internal use only.