GPIOs API

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

group CosmicSDK GPIO API

Constants and APIs related to GPIO operations.

Functions

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

Sets the GPIO pins voltage.

Warning

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

Parameters:

• handle – Handle to the CosmicSDK instance

• voltage_mV – Voltage in millivolts to set the GPIO pins 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 GPIO pins (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_GpioUseExternalVoltage(CosmicSDK_Handle *handle, bool save)

Configures the GPIO pins 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 GPIO pins share the same voltage domain as I2C, SPI and UART. Calling this method will also affect those interfaces.

Parameters:

• handle – Handle to the CosmicSDK instance.

• save – If true, the external voltage configuration is stored in non-volatile memory and persists across power cycles. If false, applies only to the current session.

Return values:

• SUCCESS – Voltage domain successfully switched to external supply.

• FW_VOLTAGE_OUT_OF_RANGE – The requested voltage is outside the valid range.

• FW_VOLTAGE_ADJUSTMENT_FAILURE – The voltage could not be applied.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_GpioGetVoltage(CosmicSDK_Handle *handle, uint16_t *externalVoltage_mV)

Reads the measured GPIO voltage from the host adapter.

Warning

On Supernova and Pulsar host adapters, the GPIO pins share the same voltage domain as I2C, SPI and UART. Calling this method returns the same voltage values as CosmicSDK_I2cGetBusVoltage, CosmicSDK_SpiGetBusVoltage, and CosmicSDK_UartGetBusVoltage.

Parameters:

• handle – Handle to the CosmicSDK instance.

• externalVoltage_mV – [out] Receives the voltage (in millivolts) measured on the VTARG pin for the I2C/SPI/UART/GPIO voltage domain.

Return values:

• SUCCESS – Voltage measurements successfully retrieved.

• SDK_ERROR_WRONG_REQUEST – A NULL pointer was passed for externalVoltage_mV.

• SDK_ERROR_TIMEOUT – The operation timed out.

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

uint16_t CosmicSDK_GpioConfigurePin(CosmicSDK_Handle *handle, GpioPinNumber pinNumber, GpioFunctionality functionality, bool setInitialOutputLogicLevel, GpioLogicLevel initialOutputLogicLevel)

Configures a GPIO pin with the specified functionality.

This function configures a single GPIO pin as a digital input or output. It may be invoked at any point to modify the pin functionality.

Note

• This function must be called before any other GPIO operation on the pin.

• Calling any GPIO method before configuration will return FW_GPIO_NOT_CONFIGURED.

• When functionality is GPIO_DIGITAL_INPUT, initialOutputLogicLevel is ignored.

Parameters:

• handle – Handle to the CosmicSDK instance.

• pinNumber – The GPIO pin number to configure. See GpioPinNumber.

• functionality – The desired functionality for the GPIO pin. See GpioFunctionality.

• setInitialOutputLogicLevel – When true, the value provided in initialOutputLogicLevel will be applied to the GPIO pin during configuration. When false, the initial output logic level is left unchanged. This feature is reserved for future use.

• initialOutputLogicLevel – The initial output logic level for the GPIO pin. See GpioLogicLevel for valid values. This parameter is ignored unless setInitialOutputLogicLevel is true. This feature is reserved for future use.

Return values:

• SUCCESS – GPIO pin was successfully configured.

• FW_INVALID_PARAMETER – The pin number or functionality is 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_GpioDigitalWrite(CosmicSDK_Handle *handle, GpioPinNumber pinNumber, GpioLogicLevel logicLevel)

Writes a digital logic level to a GPIO pin.

Writes the provided logic level to a pin configured as a digital output.

Note

• The pin must be configured as GPIO_DIGITAL_OUTPUT using CosmicSDK_GpioConfigurePin.

• If the pin is not configured, this function returns FW_GPIO_NOT_CONFIGURED.

• If the pin is configured as a digital input, this function returns FW_GPIO_WRONG_CONFIGURATION.

Parameters:

• handle – Handle to the CosmicSDK instance.

• pinNumber – The GPIO pin number to write to. See GpioPinNumber.

• logicLevel – The logic level to write to the GPIO pin. See GpioLogicLevel.

Return values:

• SUCCESS – Logic level was successfully written.

• FW_GPIO_NOT_CONFIGURED – The GPIO pin has not been configured.

• FW_GPIO_WRONG_CONFIGURATION – The GPIO pin is not configured as a digital output.

• FW_INVALID_PARAMETER – The pin number is 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_GpioDigitalRead(CosmicSDK_Handle *handle, GpioPinNumber pinNumber, GpioLogicLevel *logicLevel)

Reads the digital logic level from a GPIO pin.

Reads the logic level from a pin configured as a digital input.

Note

• The pin must be configured as GPIO_DIGITAL_INPUT using CosmicSDK_GpioConfigurePin.

• If the pin is not configured, this function returns FW_GPIO_NOT_CONFIGURED.

• If the pin is configured as a digital output, this function returns FW_GPIO_WRONG_CONFIGURATION.

Parameters:

• handle – Handle to the CosmicSDK instance.

• pinNumber – The GPIO pin number to read from. See GpioPinNumber.

• logicLevel – On success, receives the logic level of the GPIO pin. See GpioLogicLevel.

Return values:

• SUCCESS – Logic level was successfully read.

• FW_GPIO_NOT_CONFIGURED – The GPIO pin has not been configured.

• FW_GPIO_WRONG_CONFIGURATION – The GPIO pin is not configured as a digital input.

• FW_INVALID_PARAMETER – The pin number is 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_GpioConfigureInterrupt(CosmicSDK_Handle *handle, GpioPinNumber pinNumber, GpioTriggerType trigger)

Configures and enables interrupts in a GPIO pin.

Configures the interrupt trigger for a GPIO pin and enables its callback.

Note

• The pin must be configured as GPIO_DIGITAL_INPUT using CosmicSDK_GpioConfigurePin.

• If the pin is not configured, this function returns FW_GPIO_NOT_CONFIGURED.

• If the pin is configured as a digital output, this function returns FW_GPIO_WRONG_CONFIGURATION.

• If the pin does not support interrupts, this function returns FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE.

Parameters:

• handle – Handle to the CosmicSDK instance.

• pinNumber – The GPIO pin number to configure interrupts for. See GpioPinNumber.

• trigger – The trigger type used for the interruption. See GpioTriggerType.

Return values:

• SUCCESS – GPIO interrupt was successfully configured and enabled.

• FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE – The selected GPIO pin does not support interrupts.

• FW_GPIO_NOT_CONFIGURED – The GPIO pin has not been configured.

• FW_GPIO_WRONG_CONFIGURATION – The GPIO pin is not configured as a digital input.

• FW_INVALID_PARAMETER – The pin number or trigger type is 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_GpioDisableInterrupt(CosmicSDK_Handle *handle, GpioPinNumber pinNumber)

Disables interrupts in a GPIO pin.

Disables interrupts for a GPIO pin configured as a digital input.

Note

• The pin must be configured as GPIO_DIGITAL_INPUT using CosmicSDK_GpioConfigurePin.

• If the pin is not configured, this function returns FW_GPIO_NOT_CONFIGURED.

• If the pin is configured as a digital output, this function returns FW_GPIO_WRONG_CONFIGURATION.

Parameters:

• handle – Handle to the CosmicSDK instance.

• pinNumber – The GPIO pin number to which the interrupt will be disabled. See GpioPinNumber.

Return values:

• SUCCESS – GPIO interrupt was successfully disabled.

• FW_GPIO_NOT_CONFIGURED – The GPIO pin has not been configured.

• FW_GPIO_WRONG_CONFIGURATION – The GPIO pin is not configured as a digital input.

• FW_INVALID_PARAMETER – The pin number is invalid or unsupported.

• SDK_ERROR_TIMEOUT – The operation timed out.

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