# 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

    - 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 CosmicSDK_SpiSetParameters instead of reinitializing the interface.

    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

    - This function must only be called after a successful call to CosmicSDK_SpiControllerInit.

    - Calling this function before UART initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.

    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

    - The SPI interface must be successfully initialized with CosmicSDK_SpiControllerInit before calling this function.

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

    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.