SPI API

This page aggregates all C++ SPI-related public methods of the class CosmicSDK.

group CosmicSDK SPI API

Constants and APIs related to SPI operations.

Functions

uint16_t spiSetBusVoltage(uint16_t voltage_mV, bool persist = false)

Sets the SPI bus voltage.

Warning

On Supernova and Pulsar host adapters, the SPI interface shares the same voltage domain as I2C, UART and GPIOs. As a result, calling this method to set the SPI voltage will also affect the voltage of I2C, UART and GPIO interfaces. This must be taken into account when more than one interfaces are used simultaneously.

Parameters:

• voltage_mV – Voltage in millivolts to set the SPI bus to. The valid values are 0 mV, and any value in the range 1200 to 3300 mV. The value 0mV deactivates the VTARG pin and turn offs the downstream devices.

• persist – bool If true, the voltage setting will be persistent across power cycles. This ensures that any DUT connected to the SPI bus (e.g. via Pulsar or Supernova) will receive power immediately upon startup, without waiting for the host to issue the voltage set command. If false, the setting will only apply to the current session.

Returns:

The status code of the operation

uint16_t spiControllerInit(SpiBitOrder bitOrder, SpiMode mode, SpiDataWidth dataWidth, SpiChipSelect chipSelect, SpiChipSelectPolarity chipSelectPol, uint32_t frequency)

Initializes the SPI controller.

This function initializes the SPI peripheral and must be called successfully before any other SPI-related API is used.

Note

• This function must be called exactly once.

• Calling any SPI API before initialization will result in FW_INTERFACE_NOT_INITIALIZED.

• Calling this function more than once will result in FW_INTERFACE_ALREADY_INITIALIZED.

• To modify the SPI configuration after initialization, use spiSetParameters instead of reinitializing the interface.

Parameters:

• bitOrder – Bit transmission order (MSB-first or LSB-first). See SpiBitOrder for supported values.

• mode – SPI clock mode (CPOL/CPHA configuration). See SpiMode for supported values.

• dataWidth – Width of a single SPI data frame, in bits. See SpiDataWidth for supported values.

• chipSelect – Chip select line to be used by the controller. See SpiChipSelect for supported values.

• chipSelectPol – Polarity of the chip select signal (active high or low). See SpiChipSelectPolarity for supported values.

• frequency – SPI clock frequency in Hertz. Valid range: 10000 (10 kHz) to 50000000 (50 MHz). The maximum frequency may vary depending on the USB host device model and hardware revision.

Return values:

• SUCCESS – SPI interphase was successfully initialized.

• FW_INTERFACE_ALREADY_INITIALIZED – The SPI interface has already been initialized.

• FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

• SDK_ERROR_TIMEOUT – The operation timed out.

• SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t spiSetParameters(SpiBitOrder bitOrder, SpiMode mode, SpiDataWidth dataWidth, SpiChipSelect chipSelect, SpiChipSelectPolarity chipSelectPol, uint32_t frequency)

Sets the SPI bus parameters.

This function updates the SPI bus parameters after the SPI interface has been successfully initialized using spiControllerInit. It allows runtime reconfiguration of the SPI without requiring a full deinitialization or reinitialization of the peripheral.

Note

• This function must only be called after a successful call to spiControllerInit.

• Calling this function before UART initialization will result in FW_INTERFACE_NOT_INITIALIZED.

Parameters:

• bitOrder – Bit transmission order (MSB-first or LSB-first). See SpiBitOrder for supported values.

• mode – SPI clock mode (CPOL/CPHA configuration). See SpiMode for supported values.

• dataWidth – Width of a single SPI data frame, in bits. See SpiDataWidth for supported values.

• chipSelect – Chip select line to be used by the controller. See SpiChipSelect for supported values.

• chipSelectPol – Polarity of the chip select signal (active high or low). See SpiChipSelectPolarity for supported values.

• frequency – SPI clock frequency in Hertz. Valid range: 10000 (10 kHz) to 50000000 (50 MHz). The maximum frequency may vary depending on the USB host device model and hardware revision.

Return values:

• SUCCESS – SPI parameters were successfully updated.

• FW_INTERFACE_NOT_INITIALIZED – The SPI interface has not been initialized.

• FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

• SDK_ERROR_TIMEOUT – The operation timed out.

• SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

uint16_t spiTransfer(std::vector<uint8_t> &inData, std::vector<uint8_t> &outData, uint16_t transferLength)

Performs an SPI transfer.

Requests the host adapter to send data using the currently active SPI configuration (see spiControllerInit and spiSetParameters).

Note

• The SPI interface must be successfully initialized with spiControllerInit before calling this function.

• If the UART interface is not initialized, this function returns FW_INTERFACE_NOT_INITIALIZED.

Parameters:

• inData – Buffer containing the data to be transmitted over SPI MOSI pin.

• outData – Buffer where the received data through SPI MISO pin will be stored.

• transferLength – Total length of the transfer in terms of frames or data units. Typically, the frame size is 8 bits, or in other words, 1 byte. It is worth mentioning that the transferLength can be equal or greater than the length of the inData buffer.

Return values:

• SUCCESS – SPI message was successfully sent.

• FW_INTERFACE_NOT_INITIALIZED – The UART interface has not been initialized.

• FW_INVALID_PARAMETER – The transferLength is greater than te maximum SPI data length supported by the host device.

• FW_UNHANDLED_ERROR – An unhandled error occurred while transferring SPI data.

• SDK_ERROR_TIMEOUT – The operation timed out.

• SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.