SPI API

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

group CosmicSDK SPI API

Constants and APIs related to SPI operations.

Functions

uint16_t spiSetBusVoltage(uint16_t id, uint16_t voltage_mV, bool persist = false)

Set the operating voltage of the SPI bus.

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:

  • id – uint16_t Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • voltage_mV – uint16_t 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:

uint16_t Result of the request.

uint16_t spiUseExternalVoltage(uint16_t id, bool save = false)

Configures the SPI bus to use an externally supplied voltage.

Notify the host adapter that I2C/SPI/UART/GPIO bus voltage comes from an external supply.

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 will also affect the voltage domain of I2C, UART and GPIO interfaces.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • save – If true, stores the measured external voltage as the rail’s power-on setpoint: after a power cycle the adapter drives the rail itself at that voltage. It does not store “external”. If false, applies only to the current session.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

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

uint16_t spiDeinit(uint16_t id)

Deinitialize the SPI interface, releasing whichever role it holds.

Tears the interface down whether it was brought up as a controller or as a target, and leaves it uninitialized so it can be brought up again as either role.

Note

  • The command reaches the firmware from v4.5.0 onwards; older firmware answers FW_UNSUPPORTED_COMMAND in the response.

Parameters:

id – Transaction id, echoed in the response.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

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

uint16_t spiControllerInit(uint16_t id, 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:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 – The command was successfully sent to the host adapter.

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

uint16_t spiSetParameters(uint16_t id, 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

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • 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 – The command was successfully sent to the host adapter.

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

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

Performs a SPI transfer.

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

Note

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

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

  • 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 – The command was successfully sent to the host adapter.

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

uint16_t spiWriteBulk(uint16_t id, const std::vector<uint8_t> &data)

Writes a block of bytes to the downstream SPI device over the vendor bulk endpoint.

Sends the command, then streams data on the vendor OUT endpoint immediately afterwards, because the firmware holds that endpoint open for it from the moment the command is dispatched. This call blocks the calling thread only for the duration of the bulk transfer itself (not for the firmware’s reply); the firmware’s actual result code for the write arrives later through the registered onResponse callback. Any bytes clocked back from the downstream device (MISO) while writing are discarded; use spiReadBulk when the response matters.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • data – Bytes to clock out; must be non-empty and within SPI_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command and payload were successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – data is empty or larger than SPI_BULK_MAX_PAYLOAD.

  • SDK_ERROR_TIMEOUT – Streaming data over the bulk endpoint timed out.

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

uint16_t spiReadBulk(uint16_t id, const std::vector<uint8_t> &commandBytes, uint16_t readLength)

Sends a short command and starts reading a large block back over the vendor bulk endpoint.

Chip select is held across both phases: commandBytes is sent inside the request, then chip select stays asserted while readLength bytes are clocked in and streamed back over the vendor bulk IN endpoint. Only that data phase is returned, so the caller does not have to skip its own command bytes. The reply announces the length first, so the caller must wait for the onResponse callback and then collect the payload with receivePayload once the announced length is known.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • commandBytes – Command and address bytes (e.g. a read opcode plus an address), sent in the request itself. May be empty if the downstream device needs no command phase.

  • readLength – Data bytes to read; must be non-zero and within SPI_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – readLength is zero or larger than SPI_BULK_MAX_PAYLOAD.

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

uint16_t spiTransferBulk(uint16_t id, const std::vector<uint8_t> &inData, uint16_t transferLength)

Full-duplex transfer whose received bytes return over the vendor bulk endpoint.

The asynchronous half of CosmicSDK::spiTransferBulk. Encodes the same parameter block spiTransfer does – payload length, then transfer length, then the outgoing bytes – under CMD_SPI_CONTROLLER_TRANSFER_BULK, which differs from CMD_SPI_CONTROLLER_TRANSFER only in where the received bytes come back. Nothing is written to the endpoint here; the reply announces how many bytes are waiting and the caller collects them with receivePayload.

Parameters:

  • id – Transaction id correlating the response.

  • inData – Bytes to clock out, carried inside the request. At most MAX_SPI_TRANSFER_LENGTH.

  • transferLength – Bytes to clock and read back. Non-zero, at most SPI_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The request was dispatched.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable.

  • SDK_ERROR_WRONG_REQUEST – transferLength is out of range, or inData is too long.

  • SDK_ERROR_DISCONNECT – The request could not be written.

uint16_t spiTargetInit(uint16_t id, SpiMode mode, SpiBitOrder bitOrder, SpiChipSelect chipSelect, SpiChipSelectPolarity chipSelectPol, SpiTargetModel model, SpiTargetEngine engine)

Enters SPI target (slave) mode.

Arms the device as an SPI target backed by an arena drawn from the shared bulk-staging pool. An external controller clocks bytes against that arena while the firmware services the chip-select-framed transactions autonomously. The model selects how the clocked byte stream is interpreted; engine selects the MEMORY-model service path (ignored by FLASH/REGISTER_MAP).

Note

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • mode – SPI mode 0..3 (CPOL/CPHA); must match the controller. See SpiMode.

  • bitOrder – MSB-first or LSB-first. See SpiBitOrder.

  • chipSelect – Which SSEL line the target answers on; reported in notifications. See SpiChipSelect.

  • chipSelectPol – Chip-select active polarity. See SpiChipSelectPolarity.

  • model – Emulation model presented on the bus. See SpiTargetModel.

  • engine – MEMORY service engine. See SpiTargetEngine.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

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

uint16_t spiTargetSetParameters(uint16_t id, SpiMode mode, SpiBitOrder bitOrder, SpiChipSelect chipSelect, SpiChipSelectPolarity chipSelectPol, SpiTargetModel model, SpiTargetEngine engine)

Reconfigures the active SPI target in place.

Re-arms the target with a new mode, chip select, or model without discarding the arena contents. Shares the exact request/response shape as spiTargetInit and is the idempotent way to re-run configuration.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • mode – SPI mode 0..3 (CPOL/CPHA); must match the controller. See SpiMode.

  • bitOrder – MSB-first or LSB-first. See SpiBitOrder.

  • chipSelect – Which SSEL line the target answers on; reported in notifications. See SpiChipSelect.

  • chipSelectPol – Chip-select active polarity. See SpiChipSelectPolarity.

  • model – Emulation model presented on the bus. See SpiTargetModel.

  • engine – MEMORY service engine. See SpiTargetEngine.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

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

uint16_t spiTargetSetFlashConfig(uint16_t id, uint8_t addressBytes, uint16_t pageSize, uint32_t writeCycle_us, uint8_t idLength, const uint8_t flashId[8], uint8_t flags)

Configures the FLASH emulation model (SPI target).

Valid only while the active model is SPI_TARGET_MODEL_FLASH. Sets the address width, the page-program wrap granularity, the program busy timing, and the JEDEC id reported by RDID.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • addressBytes – Address width in bytes: 2 or 3.

  • pageSize – Page-program wrap granularity. Must be a power of two.

  • writeCycle_us – Program time in microseconds; a program stays WIP-busy for this long.

  • idLength – Number of valid JEDEC id bytes in flashId (0..8).

  • flashId – JEDEC id bytes reported by RDID (0x9F). Always eight bytes on the wire; only the first idLength are used.

  • flags – Config flags. Bit 0 = require WEL before program; other bits reserved (send 0).

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

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

uint16_t spiTargetWriteMemory(uint16_t id, uint16_t memoryAddress, const std::vector<uint8_t> &data)

Preloads the SPI target arena over the vendor bulk endpoint.

Sends the command, then streams data on the vendor OUT endpoint immediately afterwards, because the firmware holds that endpoint open for it from the moment the command is dispatched. This call blocks the calling thread only for the duration of the bulk transfer itself (not for the firmware’s reply); the firmware’s actual result code for the write arrives later through the registered onResponse callback.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • memoryAddress – Arena offset to start writing at.

  • data – Bytes to store; must be non-empty and within SPI_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command and payload were successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – data is empty or larger than SPI_BULK_MAX_PAYLOAD.

  • SDK_ERROR_TIMEOUT – Streaming data over the bulk endpoint timed out.

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

uint16_t spiTargetReadMemory(uint16_t id, uint16_t memoryAddress, uint16_t length)

Starts an SPI target arena read over the vendor bulk endpoint.

Only the data phase comes back on the vendor bulk endpoint; the reply announces the length first, so the caller must wait for the onResponse callback and then collect the payload with receivePayload once the announced length is known.

Parameters:

  • id – Command Id to identify the request. Values from 1 to 65535 are valid. 0 is reserved for notifications.

  • memoryAddress – Arena offset to start reading from.

  • length – Bytes to read; must be non-zero and within SPI_BULK_MAX_PAYLOAD.

Return values:

  • SUCCESS – The command was successfully sent to the host adapter.

  • SDK_ERROR_BULK_UNAVAILABLE – The vendor bulk transport is not usable (not claimed, or unsupported by the firmware).

  • SDK_ERROR_WRONG_REQUEST – length is zero or larger than SPI_BULK_MAX_PAYLOAD.

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