SPI API

This page aggregates all SPI-related functions for the C API.

group CosmicSDK SPI API

Constants and APIs related to SPI operations.

Functions

uint16_t CosmicSDK_SpiSetBusVoltage(CosmicSDK_Handle *handle, uint16_t voltage_mV, bool persist)

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 interface is used simultaneously.

Parameters:

  • handle – Handle to the CosmicSDK instance

  • 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:

SUCCESS on success, error code otherwise

uint16_t CosmicSDK_SpiControllerInit(CosmicSDK_Handle *handle, 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

Parameters:

  • handle – Handle to the CosmicSDK instance.

  • 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 CosmicSDK_SpiSetParameters(CosmicSDK_Handle *handle, 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 CosmicSDK_SpiControllerInit. It allows runtime reconfiguration of the SPI without requiring a full deinitialization or reinitialization of the peripheral.

Note

Parameters:

  • handle – Handle to the CosmicSDK instance.

  • 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 CosmicSDK_SpiTransfer(CosmicSDK_Handle *handle, uint8_t *inData, uint16_t inDataLength, uint8_t *outData, uint16_t transferLength)

Performs a SPI transfer.

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

Note

Parameters:

  • handle – Handle to the CosmicSDK instance.

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

  • inDataLength – Length of the buffer pointed by inData.

  • 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.