/**
 * @file CosmicSDK_API_c.h
 *
 * @brief Header file that declares the CosmicSDK C API. This API provides a C-compatible
 * interface to interact with Binho host adapters using the Cosmic SDK from a C environment.
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include "CosmicNotifications.h"
#include "CosmicSDKExport.h"
#include "definitions.h"

/** \addtogroup CosmicSDK_C
 *  @{
 */

/**
 * @brief Structure to hold device information from C API
 */
struct C_DeviceInfo {
  char* manufacturer;        /**< Null-terminated manufacturer string. */
  size_t manufacturerLength; /**< Manufacturer string length, excluding null terminator. */
  char* productName;         /**< Null-terminated product name string. */
  size_t productNameLength;  /**< Product name string length, excluding null terminator. */
  char* serialNumber;        /**< Null-terminated device serial number string. */
  size_t serialNumberLength; /**< Serial number string length, excluding null terminator. */
  char* fwVersion;           /**< Null-terminated firmware version string. */
  size_t fwVersionLength;    /**< Firmware version string length, excluding null terminator. */
  char* hwVersion;           /**< Null-terminated hardware version string. */
  size_t hwVersionLength;    /**< Hardware version string length, excluding null terminator. */
};
typedef struct C_DeviceInfo C_DeviceInfo;

/**
 * @brief Opaque handle for CosmicSDK instance
 */
typedef struct CosmicSDK_Handle CosmicSDK_Handle;

/**
 * @brief Creates a new CosmicSDK instance
 * @param timeout_ms Timeout in milliseconds for operations.
 * @return Handle to the created instance
 */
COSMICSDK_API CosmicSDK_Handle* CosmicSDK_Create(int timeout_ms);

/**
 * @brief Destroys a CosmicSDK instance and frees associated resources
 * @param handle Handle to the instance to destroy
 */
COSMICSDK_API void CosmicSDK_Destroy(CosmicSDK_Handle* handle);

/**
 * @brief Registers a notification callback for asynchronous I3C events.
 *
 * @param handle  Handle to the CosmicSDK instance
 * @param callback Function pointer invoked with a @ref Notification.
 */
COSMICSDK_API void CosmicSDK_onNotification(CosmicSDK_Handle* handle, void (*callback)(const Notification*));

/**
 * @brief Attempts to parse a Hot-Join notification.
 * If @p c_notification contains a valid Hot-Join payload, the fields are
 * decoded into @p HJInfo and the function returns `true`.
 *
 * @param c_notification Pointer to a generic notification.
 * @param HJInfo Output structure for parsed Hot-Join information.
 * @return `true` if parsing succeeded, otherwise `false`.
 */
COSMICSDK_API bool CosmicSDK_notificationAsI3cHotJoin(const Notification* c_notification, I3cHotJoinNotification* HJInfo);

/**
 * @brief Attempts to parse an In-Band Interrupt (IBI) notification.
 * If @p c_notification contains a valid IBI payload, the fields are decoded
 * into @p IBIInfo and the function returns `true`.
 *
 * @param c_notification Pointer to a generic notification.
 * @param IBIInfo Output structure for parsed IBI information.
 * @return `true` if parsing succeeded, otherwise `false`.
 */
COSMICSDK_API bool CosmicSDK_notificationAsI3cIbi(const Notification* c_notification, I3cIbiNotification* IBIInfo);


/*****************************************************
 * @section Version Query
 ****************************************************/

/**
 * @brief Gets the CosmicSDK library version string
 *
 * @details
 * Returns a pointer to a null-terminated string containing the version number
 * of the linked CosmicSDK library. This allows the verification at startup
 * that the linked library matches what they were built against.
 *
 * @note
 * The returned string is statically allocated and must not be freed.
 * The pointer remains valid for the lifetime of the application.
 *
 * @return A null-terminated version string in the format "MAJOR.MINOR.PATCH",
 *         e.g. "1.2.3"
 */
COSMICSDK_API const char* CosmicSDK_GetVersion(void);

/*****************************************************
 * @section System Interface
 ****************************************************/

/**
 * @brief Attempts to parse an GPIO Interrupt notification.
 * If @p c_notification contains a valid GPIO payload, the fields are decoded
 * into @p GpioInfo and the function returns `true`.
 *
 * @param c_notification Pointer to a generic notification.
 * @param GpioInfo Output structure for parsed GPIO information.
 * @return `true` if parsing succeeded, otherwise `false`.
 */
COSMICSDK_API bool CosmicSDK_notificationAsGpio(const Notification* c_notification, GpioInterruptNotification* GpioInfo);

/**
 * @brief Attempts to parse a UART notification.
 * If @p c_notification contains a valid UART payload, the fields are decoded
 * into @p uartInfo and the function returns `true`.
 *
 * @param c_notification Pointer to a generic notification.
 * @param uartInfo Output structure for parsed UART information.
 * @return `true` if parsing succeeded, otherwise `false`.
 */
COSMICSDK_API bool CosmicSDK_notificationAsUartRx(const Notification* c_notification, UartRxNotification* uartInfo);

/**
 * @brief Opens connection to the device
 * @param handle Handle to the CosmicSDK instance
 * @param devicePath Optional path to the device. Pass NULL to use default device.
 * @return true if connection successful, false otherwise
 */
COSMICSDK_API bool CosmicSDK_Connect(CosmicSDK_Handle* handle, const char* devicePath);

/**
 * @brief Opens connection to the device using its serial number
 * @param handle Handle to the CosmicSDK instance
 * @param serialNumber Serial number of the device to connect to
 * @return true if connection successful, false otherwise
 */
COSMICSDK_API bool CosmicSDK_ConnectWithSerialNumber(CosmicSDK_Handle* handle, const char* serialNumber);

/**
 * @brief Closes connection to the device
 * @param handle Handle to the CosmicSDK instance
 */
COSMICSDK_API void CosmicSDK_Disconnect(CosmicSDK_Handle* handle);

/**
 * @brief Gets the connected device information, like Manufacturer,
 * Product Name, FW and HW versions and Serial Number
 * @param handle Handle to the CosmicSDK instance
 * @param deviceInfoOut DeviceInfo object to write the connected devices data
 * @return SUCCESS on success, error code otherwise
 */
COSMICSDK_API uint16_t CosmicSDK_GetDeviceInfo(CosmicSDK_Handle* handle,
                                               C_DeviceInfo* deviceInfoOut);

/**
 * @brief Puts the device into boot mode. Once the device process the request, it immediately jumps into the bootloader. After the user has flashed the device with a firmware, a new connection needs to be done to continue using the device.
 * @param handle Handle to the CosmicSDK instance
 * @return SUCCESS or SDK_ERROR_DISCONNECT if the device is not connected
 */
COSMICSDK_API uint16_t CosmicSDK_EnterBootMode(CosmicSDK_Handle* handle);

/*****************************************************
 * @section I2C Interface
 ****************************************************/

/**
 * @brief Sets the I2C bus voltage.
 * @warning On Supernova and Pulsar host adapters, the I2C interface shares the same voltage domain as SPI, UART and GPIOs.
 * As a result, calling this method to set the I2C voltage will also affect the voltage of SPI, UART and GPIO interfaces.
 * This must be taken into account when more than one interfaces are used simultaneously.
 * @ingroup CosmicSDK_C_I2C
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param voltage_mV
 *        Voltage in millivolts to set the I2C 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.
 *
 * @param persist
 *        If true, the voltage setting will be persistent across power cycles. This ensures that any DUT
 *        connected to the I2C 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.
 *
 * @retval SUCCESS
 *         Voltage successfully configured.
 * @retval FW_VOLTAGE_OUT_OF_RANGE
 *         If the requested voltage is outside the valid range.
 * @retval FW_VOLTAGE_ADJUSTMENT_FAILURE
 *         If the voltage could not be applied.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cSetBusVoltage(CosmicSDK_Handle* handle, uint16_t voltage_mV, bool persist);

/**
 * @brief Initializes the I2C controller.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * This function initializes the I2C peripheral and must be called successfully before any other
 * I2C-related API is used.
 *
 * @note
 * - This function must be called exactly once.
 * - Calling any I2C 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 I2C configuration after initialization, use @ref CosmicSDK_I2cSetParameters instead of
 * reinitializing the interface.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param frequency_Hz
 *        The I2C bus frequency in Hz (e.g., 400000 for 400kHz).
 *
 * @param pullUpResistor
 *        The pull-up resistor value. Valid values are defined in definitions.h (e.g., I2C_PULLUP_330Ohm).
 *
 * @retval SUCCESS
 *         I2C interphase was successfully initialized.
 * @retval FW_INTERFACE_ALREADY_INITIALIZED
 *         The I2C interface has already been initialized.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The @p bus value is not valid.
 * @retval FW_INVALID_PARAMETER
 *         The @p pullUpResistor value is not valid.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cControllerInit(CosmicSDK_Handle* handle, uint8_t bus,
                                                   uint32_t frequency_Hz, uint8_t pullUpResistor);

/**
 * @brief Sets the I2C bus parameters.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * This function updates the I2C bus parameters after the I2C interface has been successfully
 * initialized using @ref CosmicSDK_I2cControllerInit. It allows runtime reconfiguration of the I2C without
 * requiring a full deinitialization or reinitialization of the peripheral.
 *
 * @note
 * - This function must only be called after a successful call to @ref CosmicSDK_I2cControllerInit.
 * - Calling this function before UART initialization will result in
 * `FW_INTERFACE_NOT_INITIALIZED`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param frequency_Hz
 *        The I2C bus frequency in Hz (e.g., 400000 for 400kHz).
 *
 * @param pullUpResistor
 *        The pull-up resistor value. Valid values are defined in definitions.h  (e.g., I2C_PULLUP_330Ohm).
 *
 * @retval SUCCESS
 *         I2C parameters were successfully updated.
 * @retval FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE
 *         The device is Supernova and the hardware revision is previous to 'C'.
 * @retval FW_I2C_PULLUP_RESISTOR_SETTING_FAILURE
 *         The firmware failed to set the Pull Up Resistor.
 * @retval FW_INVALID_PARAMETER
 *         The @p pullUpResistor value is not valid.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I2C interface has not been initialized.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The specified @p bus is not valid or not supported by the hardware.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cSetParameters(CosmicSDK_Handle* handle, uint8_t bus,
                                                  uint32_t frequency_Hz, uint8_t pullUpResistor);

/**
 * @brief Sets the I2C pull-up resistors.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * Configures the internal pull-up resistors connected to the selected I2C bus.
 * The specified @p value determines the effective pull-up strength according
 * to the hardware capabilities and predefined settings.
 *
 * @note
 * - This function must only be called after a successful call to @ref CosmicSDK_I2cControllerInit.
 * - On some hardware revisions, this feature may not be available.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param value
 *        The value of the pull-up resistors to be set. Valid values are defined in definitions.h (e.g., I2C_PULLUP_NONE, I2C_PULLUP_330Ohm, I2C_PULLUP_1kOhm).
 *
 * @retval SUCCESS
 *         I2C Pull Up Resistors were successfully updated.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The specified @p bus is not valid or not supported by the hardware.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I2C interface has not been initialized.
 * @retval FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE
 *         The device is Supernova and the hardware revision is previous to 'C'.
 * @retval FW_I2C_PULLUP_RESISTOR_SETTING_FAILURE
 *         The firmware failed to set the Pull Up Resistor.
 * @retval FW_INVALID_PARAMETER
 *         The @p value is not valid.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cSetPullUpResistors(CosmicSDK_Handle* handle, uint8_t bus, uint8_t value);

/**
 * @brief Writes data to an I2C device at an optional subAddress.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * Writes data to an I2C target , optionally including an internal subaddress on the target device.
 *
 * @note
 * - This function is valid only when the host is initialized as an I2C controller with @ref
 * CosmicSDK_I2cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param address
 *        The I2C address of the device.
 *
 * @param subAddress
 *        The optional sub-address to write to.
 *
 * @param subAddressLength
 *        Length of sub-address array (0-4 bytes).
 *
 * @param inData
 *        The data to be written to the device.
 *
 * @param dataLength
 *        Length of data to write.
 *
 * @param nonStop
 *        If true, the operation will not stop after writing.
 *
 * @retval SUCCESS
 *         The write transaction completed successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I2C interface has not been initialized.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The specified @p bus is not valid or not supported by the hardware.
 * @retval FW_I2C_BUSY
 *         The I2C bus is currently busy and the transfer could not be started.
 * @retval FW_I2C_NACK_ADDRESS
 *         The target device did not acknowledge its address.
 * @retval FW_I2C_NACK_BYTE
 *         A data byte was not acknowledged by the target device.
 * @retval FW_I2C_INVALID_PARAMETER
 *         One or more input parameters are invalid (e.g., empty data buffer
 *         when required, invalid address, or unsupported configuration).
 * @retval FW_I2C_BIT_ERROR
 *         A bit-level error occurred during the transfer (unexpected bus state).
 * @retval FW_I2C_ARBITRATION_LOST
 *         Arbitration was lost during the transfer in multi-master mode.
 * @retval FW_I2C_NO_TRANSFER_IN_PROGRESS
 *         An operation requiring an active transfer was requested but no
 *         transfer was in progress.
 * @retval FW_I2C_DMA_REQUEST_FAIL
 *         The DMA request could not be serviced.
 * @retval FW_I2C_START_STOP_ERROR
 *         An error occurred while generating a START or STOP condition.
 * @retval FW_I2C_UNEXPECTED_STATE
 *         The I2C peripheral entered an unexpected internal state.
 * @retval FW_I2C_TIMEOUT_CONTINUE_TRANSFER
 *         Timeout occurred while attempting to continue an ongoing transfer.
 * @retval FW_I2C_TIMEOUT_WAITING_BUS_EVENT
 *         Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).
 * @retval FW_I2C_TIMEOUT_SCL_LOW
 *         Timeout detected due to SCL being held low (possible clock stretching
 *         or bus lock condition).
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength parameter is greater than four or
 *         - the @p subAddressLength parameter is greater than zero but @p subAddress is NULL
 *           pointer or
 *         - the @p dataLength parameter is greater than zero but @p subAddress is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cWrite(CosmicSDK_Handle* handle, uint8_t bus, uint8_t address,
                                          const uint8_t* subAddress, uint8_t subAddressLength,
                                          const uint8_t* inData, uint32_t dataLength, bool nonStop);

/**
 * @brief Reads data from an I2C device at an optional subAddress.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * Reads data from an I2C target, optionally a subaddress may be written first to select a register
 * or memory location prior to performing the read.
 *
 * @note
 * - This function is valid only when the host is initialized as an I2C controller with @ref
 * CosmicSDK_I2cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param address
 *        The I2C address of the device.
 *
 * @param subAddress
 *        The optional sub-address to read from.
 *
 * @param subAddressLength
 *        Length of sub-address array (0-4 bytes).
 *
 * @param readLength
 *        The length of data to be read.
 *
 * @param outData
 *        The buffer to store the read data.
 *
 * @param nonStop
 *        If true, the operation will not stop after reading.
 *
 * @retval SUCCESS
 *         The read transaction completed successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I2C interface has not been initialized.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The specified @p bus is not valid or not supported by the hardware.
 * @retval FW_I2C_BUSY
 *         The I2C bus is currently busy and the transfer could not be started.
 * @retval FW_I2C_NACK_ADDRESS
 *         The target device did not acknowledge its address.
 * @retval FW_I2C_NACK_BYTE
 *         A data byte was not acknowledged by the target device.
 * @retval FW_I2C_INVALID_PARAMETER
 *         One or more input parameters are invalid (e.g., empty data buffer
 *         when required, invalid address, or unsupported configuration).
 * @retval FW_I2C_BIT_ERROR
 *         A bit-level error occurred during the transfer (unexpected bus state).
 * @retval FW_I2C_ARBITRATION_LOST
 *         Arbitration was lost during the transfer in multi-master mode.
 * @retval FW_I2C_NO_TRANSFER_IN_PROGRESS
 *         An operation requiring an active transfer was requested but no
 *         transfer was in progress.
 * @retval FW_I2C_DMA_REQUEST_FAIL
 *         The DMA request could not be serviced.
 * @retval FW_I2C_START_STOP_ERROR
 *         An error occurred while generating a START or STOP condition.
 * @retval FW_I2C_UNEXPECTED_STATE
 *         The I2C peripheral entered an unexpected internal state.
 * @retval FW_I2C_TIMEOUT_CONTINUE_TRANSFER
 *         Timeout occurred while attempting to continue an ongoing transfer.
 * @retval FW_I2C_TIMEOUT_WAITING_BUS_EVENT
 *         Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).
 * @retval FW_I2C_TIMEOUT_SCL_LOW
 *         Timeout detected due to SCL being held low (possible clock stretching
 *         or bus lock condition).
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength parameter is greater than four or
 *         - the @p subAddressLength parameter is greater than zero but @p subAddress is NULL
 *           pointer or
 *         - the @p outData parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cRead(CosmicSDK_Handle* handle, uint8_t bus, uint8_t address,
                                         const uint8_t* subAddress, uint8_t subAddressLength,
                                         uint16_t readLength, uint8_t* outData, bool nonStop);

/**
 * @brief Request to the the host device to perform an I2C scan of the I2C bus and return the list of discovered static addresses.
 * @ingroup CosmicSDK_C_I2C
 *
 * @details
 * Initiates an address scan on the selected I2C bus to detect connected target devices. The scan probes
 * valid address ranges and collects the addresses of devices that acknowledge their address.
 *
 * Discovered addresses are returned in @p deviceAddresses following
 * this order:
 * - All detected 7-bit addresses first (1 byte per address).
 * - All detected 10-bit addresses afterwards (2 bytes per address,
 *   high byte first).
 *
 * The total number of detected 7-bit and 10-bit devices is returned
 * separately via @p count7BitAddresses and @p count10BitAddresses.
 *
 * @note
 * - This function is valid only when the host is initialized as an I2C controller with @ref
 * CosmicSDK_I2cControllerInit.
 * 
 * @warning
 * Depending on the bus characteristics, such as frequency, voltage, number of targets connected, and the length of the wires used in the 
 * hardware setup, the performance of the I2C SCAN BUS may be affected, and as a result, it might return a wrong list of detected addresses, 
 * an ``SDK_ERROR_TIMEOUT`` error, and the firmware might indeed get stuck, especially in the Pulsar. In order to avoid this scenario, consider 
 * the following recommendations to run a smooth scan bus procedure:
 *   - Set the clock frequency to low values, such as 100KHz and 400 KHz.
 *   - Disable the pull-up resistors, or set their value to high values - weak pull-ups.
 *      - In the case of the Pulsar, suggested values are: ``I2C_PULLUP_DISABLE`` , ``I2C_PULLUP_4kOhm``, or ``I2C_PULLUP_2_2kOhm``
 *      - In the case of the Supernova, suggested values are: ``I2C_PULLUP_DISABLE`` , ``I2C_PULLUP_10kOhm``, or ``I2C_PULLUP_4_7kOhm``
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param deviceAddresses
 *        Buffer to store all the device addresses found by the scan bus.
 *        The addresses are stored in the following way:
 *        - 7-bit addresses first.
 *        - 10-bit addresses at the end.
 *        - Each 10-bit address uses two bytes of the buffer (high byte first).
 *
 * @param deviceAddressesLength
 *        Capacity of @p deviceAddresses.
 *
 * @param count7BitAddresses
 *        Variable to store the number of 7-bit addresses discovered.
 *
 * @param count10BitAddresses
 *        Variable to store the number of 10-bit addresses discovered.
 *
 * @param bus
 *        I2C bus number (e.g., 0 for I2C_BUS_A). Valid values are defined in definitions.h (e.g., I2C_BUS_A, I2C_BUS_B).
 *
 * @param include10BitAddresses
 *        Indicates if the scan must include 10-bit addresses.
 *
 * @retval SUCCESS
 *         The Scan Bus completed successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I2C interface has not been initialized.
 * @retval FW_BUS_NOT_SUPPORTED
 *         The specified @p bus is not valid or not supported by the hardware.
 * @retval FW_I2C_BUS_WITH_NO_TARGETS_CONNECTED
 *         No target device detected.
 * @retval FW_I2C_BUSY
 *         The I2C bus is currently busy and the transfer could not be started.
 * @retval FW_I2C_NACK_ADDRESS
 *         The target device did not acknowledge its address.
 * @retval FW_I2C_NACK_BYTE
 *         A data byte was not acknowledged by the target device.
 * @retval FW_I2C_INVALID_PARAMETER
 *         One or more input parameters are invalid (e.g., empty data buffer
 *         when required, invalid address, or unsupported configuration).
 * @retval FW_I2C_BIT_ERROR
 *         A bit-level error occurred during the transfer (unexpected bus state).
 * @retval FW_I2C_ARBITRATION_LOST
 *         Arbitration was lost during the transfer in multi-master mode.
 * @retval FW_I2C_NO_TRANSFER_IN_PROGRESS
 *         An operation requiring an active transfer was requested but no
 *         transfer was in progress.
 * @retval FW_I2C_DMA_REQUEST_FAIL
 *         The DMA request could not be serviced.
 * @retval FW_I2C_START_STOP_ERROR
 *         An error occurred while generating a START or STOP condition.
 * @retval FW_I2C_UNEXPECTED_STATE
 *         The I2C peripheral entered an unexpected internal state.
 * @retval FW_I2C_TIMEOUT_CONTINUE_TRANSFER
 *         Timeout occurred while attempting to continue an ongoing transfer.
 * @retval FW_I2C_TIMEOUT_WAITING_BUS_EVENT
 *         Timeout while waiting for a bus event (e.g., TXE, RXNE, BTF).
 * @retval FW_I2C_TIMEOUT_SCL_LOW
 *         Timeout detected due to SCL being held low (possible clock stretching
 *         or bus lock condition).
 * @retval SDK_ERROR_WRONG_RESPONSE
 *         The response received from the device does not match the expected format or size.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p bus is different form `I2C_BUS_A` or `I2C_BUS_B` or
 *         - the @p deviceAddresses parameter and/or the @p count7BitAddresses parameter and/or @p count10BitAddresses parameter are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I2cScanBus(CosmicSDK_Handle* handle, uint8_t* deviceAddresses, uint8_t deviceAddressesLength, uint8_t* count7BitAddresses, uint8_t* count10BitAddresses, uint8_t bus, bool include10BitAddresses);

/*****************************************************
 * @section I3C Interface
 ****************************************************/

/**
 * @brief Set the I3C bus supply voltage (VTARG).
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Configures the output voltage applied to the I3C bus through the Supernova VTARG pin.
 *
 * Setting the voltage to 0 mV disables the VTARG output and powers off the downstream devices
 * connected to the I3C bus.
 *
 * This function controls the physical bus supply and does not perform any I3C protocol transaction.
 *
 * @note
 * - Ensure the selected voltage is compatible with all connected devices.
 * - Disabling VTARG (0 mV) may reset or power down all downstream targets.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param voltage_mV
 *        Voltage in millivolts to set the I3C bus to.
 *        Valid values are 0 mV or any value between 800 mV and 3300 mV.
 *
 * @retval SUCCESS
 *         The bus voltage was successfully configured.
 * @retval FW_VOLTAGE_OUT_OF_RANGE
 *         The requested voltage value is outside the supported range.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cSetBusVoltage(CosmicSDK_Handle* handle, uint16_t voltage_mV);

/**
 * @brief Initializes the I3C controller
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * This function initializes the I3C peripheral and must be called successfully before any other
 * I3C-related API is used.
 *
 * @note
 * - This function must be called exactly once.
 * - Calling any I3C 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 I3C configuration after initialization, use @ref CosmicSDK_I3cSetParameters
 * instead of reinitializing the interface.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param pushPullFrequency
 *        The I3C SCL frequency in the push-pull phase.
 *        See @ref I3cPushPullRate for supported values.
 *
 * @param openDrainFrequency
 *        The I3C SCL frequency in the open-drain phase.
 *        See @ref I3cOpenDrainTransferRate for supported values.
 *
 * @param i2cOpenDrainFrequency
 *        The I2C SCL open drain frequency.
 *        See @ref I2cTransferRate for supported values.
 *
 * @param driveStrength
 *        The drive strength configuration for the I3C pads.
 *        See @ref I3cDriveStrength for supported values.
 *
 * @retval SUCCESS
 *         I3C interphase was successfully initialized.
 * @retval FW_INTERFACE_ALREADY_INITIALIZED
 *         The I3C interface has already been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cControllerInit(CosmicSDK_Handle* handle,
                                                   I3cPushPullRate pushPullFrequency,
                                                   I3cOpenDrainTransferRate openDrainFrequency,
                                                   I2cTransferRate i2cOpenDrainFrequency,
                                                   I3cDriveStrength driveStrength);

/**
 * @brief Sets the I3C bus parameters.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * This function updates the I3C bus parameters after the I3C interface has been successfully
 * initialized using @ref CosmicSDK_I3cControllerInit. It allows runtime reconfiguration of the I3C
 * without requiring a full deinitialization or reinitialization of the peripheral.
 *
 * @note
 * - This function must only be called after a successful call to @ref CosmicSDK_I3cControllerInit.
 * - Calling this function before UART initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param pushPullFrequency
 *        The I3C SCL frequency in the push-pull phase.
 *        See @ref I3cPushPullRate for supported values.
 *
 * @param openDrainFrequency
 *        The I3C SCL frequency in the open-drain phase.
 *        See @ref I3cOpenDrainTransferRate for supported values.
 *
 * @param i2cOpenDrainFrequency
 *        The I2C SCL open drain frequency.
 *        See @ref I2cTransferRate for supported values.
 *
 * @param driveStrength
 *        The drive strength configuration for the I3C pads.
 *        See @ref I3cDriveStrength for supported values.
 *
 * @retval SUCCESS
 *         I3C parameters were successfully updated.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cSetParameters(CosmicSDK_Handle* handle,
                                                  I3cPushPullRate pushPullFrequency,
                                                  I3cOpenDrainTransferRate openDrainFrequency,
                                                  I2cTransferRate i2cOpenDrainFrequency,
                                                  I3cDriveStrength driveStrength);

/**
 * @brief Initializes the I3C bus.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * By default, the Supernova acting as the controller issues the RSTDAA followed by the ENTDAA CCCs
 * to discover I3C targets on the bus and automatically assign dynamic addresses.
 *
 * Optionally, a table of target devices can be provided to control the bus initialization process.
 * When the @p targets parameter is provided, the controller uses this information to:
 *  - Assign a specific dynamic address to a known I3C target.
 *  - Register legacy I2C devices on the bus, which do not respond to the ENTDAA CCC.
 *
 * This allows mixed I3C/I2C buses to be initialized correctly and enables deterministic dynamic
 * address assignment for selected targets.
 *
 * If @p targets is empty, the controller relies solely on the standard I3C discovery mechanism
 * (RSTDAA + ENTDAA) and only I3C targets responding to ENTDAA will be detected.
 *
 * @note
 * - This function must be called exactly once.
 * - Calling any I3C 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 I3C configuration after initialization, use @ref CosmicSDK_I3cSetParameters
 * instead of reinitializing the interface.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param targets
 *        An array containing information about the target devices connected to the I3C bus.
 *        See @ref I3cTargetInfo for valid table entry format.
 *
 * @param numberOfTargets
 *        The quantity of devices on the targets array.
 *
 * @retval SUCCESS
 *         I3C bus was successfully initialized.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE
 *         The number of targets to be initialized surpassed the maximum allowed number of targets
 * (11).
 * @retval FW_INVALID_TARGET_ADDRESS
 *         The address of one of the target devices is a reserved address.
 * @retval FW_I3C_BUS_INIT_NACK_RSTDAA
 *         One or more targets did not acknowledge the RSTDAA CCC during bus initialization.
 * @retval FW_I3C_BUS_INIT_NACK_SETDASA
 *         A target did not acknowledge the SETDASA CCC when assigning a dynamic address.
 * @retval FW_I3C_BUS_INIT_NACK_SETAASA
 *         A target did not acknowledge the SETAASA CCC when assigning a dynamic address.
 * @retval FW_I3C_BUS_INIT_NACK_ENTDAA
 *         One or more targets did not acknowledge or complete the ENTDAA CCC.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus during initialization.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cInitBus(CosmicSDK_Handle* handle, I3cTargetInfo* targets,
                                            uint8_t numberOfTargets);

/**
 * @brief Resets the I3C bus.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Issue the RSTDAA CCC and clear the target device table.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @retval SUCCESS
 *         I3C bus was successfully resetted.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus during the reset.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cResetBus(CosmicSDK_Handle* handle);

/**
 * @brief Get the target device table stored internally in the Supernova.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Retrieves the current I3C target device table maintained internally by the Supernova firmware.
 *
 * The table contains information about the targets discovered or configured on the I3C bus, such as
 * dynamic address, static address (if available), PID (if retrieved), and other relevant
 * attributes.
 *
 * This function does not perform any bus transaction. It only queries the internal device table
 * maintained by the firmware.
 *
 * @note
 * - The returned table reflects the current internal state of the Supernova.
 * - The content of the table depends on previous operations such as ENTDAA, SETDASA, SETAASA,
 * GETPID, etc.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param targets
 *        The list of targets on the I3C bus
 *        See @ref I3cTargetInfo for table entry format.
 *
 * @param maxTargets
 *        Maximum number of target entries that can be stored in the targets array.
 *
 * @param targetsQuantity
 *        The effective number of target on the bus, copied into the targets array argument.
 *
 * @retval SUCCESS
 *         I3C device table successfully returned.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         @p target and/or @p targetsQuantity are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cGetDeviceTable(CosmicSDK_Handle* handle, I3cTargetInfo* targets,
                                                   uint8_t maxTargets, uint8_t* targetsQuantity);

/**
 * @brief Changes de configuration of an I3C target given by a dictionary containing the new target
 * configuration.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Updates the configuration of a target device stored in the Supernova's internal I3C device table.
 *
 * @note
 * - The target must exist in the internal device table prior to calling this function.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        Target address whose configuration will be set.
 *
 * @param targetConfiguration
 *        A dictionary containing the new configuration.
 *
 * @retval SUCCESS
 *         I3C target device configuration updated.
 * @retval FW_TARGET_ADDRESS_NOT_FOUND_IN_THE_TABLE
 *         The Supernova's stored target device table does not have the requested target address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cSetTargetDeviceConfiguration(
    CosmicSDK_Handle* handle, uint8_t address, I3cTargetConfiguration targetConfiguration);

/**
 * @brief Performs an I3C write using Legacy I2C mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Writes data to an I2C target using a Legacy I2C Private Transfer over the I3C bus. This function
 * issues a standard I2C write transaction (Legacy I2C mode), optionally including an internal
 * subaddress on the target device. The transfer may also begin with a broadcast address (0x7E) if
 * required by the higher-level protocol being implemented.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The static address of the I2C target.
 *
 * @param subAddress
 *        The optional sub-address to write to.
 *
 * @param subAddressLength
 *        The sub-address length.
 *
 * @param inData
 *        The data to be written to the device.
 *
 * @param dataLength
 *        The data length.
 *
 * @param flags
 *        Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can
 *        be combined using bitwise OR. See @ref I3cTransferFlags for supported values.
 *
 * @retval SUCCESS
 *         I3C data was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_I2C_NACK_BYTE
 * 		     The I2C target NACKed the write data, terminating the message.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength parameter is greater than four or
 *         - the @p subAddressLength parameter is greater than zero but @p subAddress is NULL
 *           pointer or
 *         - the @p dataLength parameter is greater than zero but @p subAddress is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cLegacyI2CWrite(CosmicSDK_Handle* handle, uint8_t address,
                                                   const uint8_t* subAddress,
                                                   uint8_t subAddressLength, const uint8_t* inData,
                                                   uint16_t dataLength, I3cTransferFlags flags);

/**
 * @brief Performs an I3C read using Legacy I2C mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Reads data from an I2C target using a Legacy I2C Private Transfer over the I3C bus. This function
 * performs a standard I2C read operation (Legacy I2C mode). Optionally, a subaddress may be written
 * first to select a register or memory location prior to performing the read.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The static address of the I2C target.
 *
 * @param subAddress
 *        The optional sub-address to write to.
 *
 * @param subAddressLength
 *        The sub-address length.
 *
 * @param readLength
 *        The length of data to be read.
 *
 * @param outData
 *        The buffer to store the read data.
 *
 * @param flags
 *        Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can
 *        be combined using bitwise OR. See @ref I3cTransferFlags for supported values.
 *
 * @retval SUCCESS
 *         I3C data was successfully read.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_I2C_NACK_BYTE
 * 		     The I2C target NACKed the data.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength parameter is greater than four or
 *         - the @p subAddressLength parameter is greater than zero but @p subAddress is NULL
 *           pointer or
 *         - the @p outData parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cLegacyI2CRead(CosmicSDK_Handle* handle, uint8_t address,
                                                  const uint8_t* subAddress,
                                                  uint8_t subAddressLength, uint16_t readLength,
                                                  uint8_t* outData, I3cTransferFlags flags);

/**
 * @brief Performs an I3C write in SDR mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Writes data to an I3C device or to a group of I3C targets through an I3C Private Transfer in SDR
 * mode. Optionally, the internal subaddress of the target memory where the data is written to can
 * be set, especially when writing to a single target.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the I3C target, or the group address.
 *
 * @param subAddress
 *        The optional sub-address to write to.
 *
 * @param subAddressLength
 *        The sub-address length.
 *
 * @param inData
 *        The data to be written to the device.
 *
 * @param dataLength
 *        The data length
 *
 * @param flags
 *        Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can
 *        be combined using bitwise OR. See @ref I3cTransferFlags for supported values.
 *
 * @retval SUCCESS
 *         I3C data was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength is greater than four or
 *         - the @p subAddressLength is greater than zero but @p subAddress is NULL pointer or
 *         - the @p dataLength is greater than zero but @p inData is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cSdrWrite(CosmicSDK_Handle* handle, uint8_t address,
                                             const uint8_t* subAddress, uint8_t subAddressLength,
                                             const uint8_t* inData, uint16_t dataLength,
                                             I3cTransferFlags flags);

/**
 * @brief Performs an I3C read in SDR mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Reads data from an I3C target through an I3C Private Read transfer in SDR mode. Optionally, the
 * internal subaddress of the target where the data is read from can be also set.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the I3C target.
 *
 * @param subAddress
 *        The optional sub-address to write to.
 *
 * @param subAddressLength
 *        The sub-address length.
 *
 * @param readLength
 *        The length of data to be read.
 *
 * @param outData
 *        The buffer to store the read data.
 *
 * @param outDataLength
 *        The actual length of the data read.
 *
 * @param flags
 *        Bitmask of transfer options controlling the behavior of the I3C/I2C transaction. Flags can
 *        be combined using bitwise OR. See @ref I3cTransferFlags for supported values.
 *
 * @retval SUCCESS
 *         I3C data was successfully read.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         - The @p subAddressLength parameter is greater than four or
 *         - the @p subAddressLength parameter is greater than zero but @p subAddress is NULL
 *           pointer or
 *         - the @p outData parameter and/or @p outDataLength parameter are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cSdrRead(CosmicSDK_Handle* handle, uint8_t address,
                                            const uint8_t* subAddress, uint8_t subAddressLength,
                                            uint16_t readLength, uint8_t* outData,
                                            uint16_t* outDataLength, I3cTransferFlags flags);

/**
 * @brief Performs an I3C write in HDR-DDR mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Writes data to an I3C target using an HDR-DDR Private Transfer. If the bus is currently operating
 * in SDR mode, this function will automatically issue the ENTHDR0 CCC before starting the HDR-DDR
 * transfer.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the I3C target.
 *
 * @param command
 *        The HDR-DDR command byte. Must be in the range [0x00, 0x7F].
 *
 * @param inData
 *        The data payload to be written. The payload length must be a multiple of 2.
 *
 * @param dataLength
 *        Length of the data buffer.
 *
 * @retval SUCCESS
 *         I3C data was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p dataLength parameter is greater than zero but @p subAddress is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cHdrDdrWrite(CosmicSDK_Handle* handle, uint8_t address,
                                                uint8_t command, const uint8_t* inData,
                                                uint16_t dataLength);

/**
 * @brief Performs an I3C read in HDR-DDR mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Reads data from an I3C target using an HDR-DDR Private Read Transfer. If the bus is currently
 * operating in SDR mode, this function will automatically issue the ENTHDR0 CCC before starting the
 * HDR-DDR transfer.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the I3C target.
 *
 * @param command
 *        The HDR-DDR command byte. Must be in the range [0x80, 0xFF].
 *
 * @param readLength
 *        The length of the data to read. Must be a multiple of 2.
 *
 * @param outData
 *        The buffer where the received data will be stored.
 *
 * @param outDataLength
 *        The actual length of the data read.
 *
 * @retval SUCCESS
 *         I3C data was successfully read.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p outData parameter and/or @p outDataLength parameter are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cHdrDdrRead(CosmicSDK_Handle* handle, uint8_t address,
                                               uint8_t command, uint16_t readLength,
                                               uint16_t* outDataLength, uint8_t* outData);

/**
 * @brief Emit the Target Reset Pattern to trigger the default or configured reset action on the I3C
 * targets.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Emits the I3C Target Reset Pattern on the bus.
 *
 * All targets that recognize the Target Reset Pattern and support reset functionality will perform
 * the corresponding reset action.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The reset action executed depends on the most recent RSTACT configuration, or the default reset
 * behavior if none was configured.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @retval SUCCESS
 *         I3C Target Reset Pattern emmitted successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cTargetResetPattern(CosmicSDK_Handle* handle);

/**
 * @brief Issue the HDR Exit Pattern to leave the current HDR mode and exit back to SDR mode.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Emits the I3C HDR Exit Pattern on the bus.
 *
 * This pattern terminates the current High Data Rate (HDR) mode and forces all participating
 * devices to return to Standard Data Rate (SDR) mode, as defined by the I3C specification.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - It must be issued while the bus is operating in HDR mode.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @retval SUCCESS
 *         I3C Exit Pattern issued successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cHdrExitPattern(CosmicSDK_Handle* handle);

/**
 * @brief Emit the RSTDAA CCC and reset all dynamic addresses assigned on the bus.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the RSTDAA (Reset Dynamic Address Assignment) Common Command Code (CCC) in broadcast mode.
 *
 * Unlike the @ref CosmicSDK_I3cResetBus method, the target device table is not cleared. After
 * successful completion, the SDK updates the internal target device table by clearing only the
 * stored dynamic addresses of all entries. The device information remains present in the table,
 * allowing a new Dynamic Address Assignment (DAA) procedure to be performed without losing device
 * metadata.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - After issuing RSTDAA, a new Dynamic Address Assignment (DAA) procedure must be executed before
 * communicating with targets using dynamic addresses.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @retval SUCCESS
 *         RSTDAA was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccRSTDAA(CosmicSDK_Handle* handle);

/**
 * @brief Enter Dynamic Address Assignment procedure (ENTDAA)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the ENTDAA (Enter Dynamic Address Assignment) Common Command Code (CCC) in broadcast mode
 * to initiate the Dynamic Address Assignment (DAA) procedure.
 *
 * All unaddressed I3C targets participate in the arbitration process and are sequentially assigned
 * a unique dynamic address by the controller.
 *
 * During the procedure, each discovered target is identified and added to the internal target
 * device table together with its assigned dynamic address and associated device information.
 *
 * The procedure continues until no additional targets respond or the maximum number of supported
 * targets is reached.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @retval SUCCESS
 *         The Dynamic Address Assignment procedure completed successfully.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_TARGET_DEVICES_TABLE_OVERFLOW
 *         The number of targets answered to the ENTDAA is greater than the maximum allowed number
 *         of targets (11).
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccENTDAA(CosmicSDK_Handle* handle);

/**
 * @brief Assign a Dynamic Address to a target using its Static Address (SETDASA CCC).
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETDASA (Set Dynamic Address from Static Address) Common Command Code (CCC) in direct
 * mode to the target identified by its static address.
 *
 * The target device at @p staticAddress is instructed to adopt the specified @p dynamicAddress.
 * Upon successful completion and acknowledgment by the target, the SDK adds a new entry to the
 * internal target device table containing the assigned dynamic address and associated device
 * information.
 *
 * Prior to issuing the CCC, the SDK validates that:
 * - The requested dynamic address is not reserved.
 * - The dynamic address is not already in use by another target.
 * - There is available space in the internal target device table.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param staticAddress
 *        Static address of the target device.
 *
 * @param dynamicAddress
 *        Dynamic address to assign to the target.
 *
 * @retval SUCCESS
 *         The dynamic address was successfully assigned and the device was added to the target
 *         device table.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE
 *         The number of targets on the table is already the maximum allowed number of targets (11).
 * @retval FW_INVALID_TARGET_ADDRESS
 *         The dynamic address to be assigned is a reserved address.
 * @retval FW_REPEATED_TARGET_ADDRESS
 *         The dynamic address to be set is already used by a target on the bus.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETDASA(CosmicSDK_Handle* handle, uint8_t staticAddress,
                                               uint8_t dynamicAddress);

/**
 * @brief Set static address as dynamic address (SETAASA CCC).
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETAASA (Set All Addresses to Static Address) Common Command Code (CCC) in broadcast
 * mode.
 *
 * Targets that support the SETAASA CCC adopt their own static address as their dynamic address.
 *
 * The @p staticAddresses parameter specifies the static addresses of the targets expected to
 * process this command. After successful completion, the SDK adds a new entry to the internal
 * target device table for each responding device, using its static address as its dynamic address.
 *
 * Prior to issuing the CCC, the SDK validates that:
 * - None of the provided addresses are reserved.
 * - There is sufficient space in the internal target device table to accommodate all new devices.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - Only targets that support the SETAASA CCC will respond and adopt their static address as
 * dynamic.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param staticAddresses
 *        Array of static addresses of those I3C targets that support SETAASA CCC.
 *        If the SETAASA CCC ends successfully, new devices are added to the target device table.
 *
 * @param count
 *        Number of static addresses in the array.
 *
 * @retval SUCCESS
 *         The CCC was successfully sent and the responding targets were
 *         added to the device table using their static address as dynamic address.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE
 *         The number of targets on the table plus the number of targets on @p staticAddresses is
 *         greater than the maximum allowed number of targets (11).
 * @retval FW_INVALID_TARGET_ADDRESS
 *         One or more addresses are reserved addresses.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETAASA(CosmicSDK_Handle* handle,
                                               const uint8_t* staticAddresses, size_t count);

/**
 * @brief Set a new Dynamic Address for a target by issuing the SETNEWDA CCC.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETNEWDA (Set New Dynamic Address) Common Command Code (CCC) in direct mode to the
 * specified target.
 *
 * The target identified by @p oldDynamicAddress is instructed to change its dynamic address to @p
 * newDynamicAddress.
 *
 * If the command completes successfully and is acknowledged by the target, the SDK updates the
 * internal target device table by replacing the stored dynamic address with the new value.
 *
 * Validation of @p newDynamicAddress is performed before issuing the CCC to ensure that it is not a
 * reserved address and that it is not already assigned to another target on the bus.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param oldDynamicAddress
 *        The dynamic address of the target.
 *
 * @param newDynamicAddress
 *        The new dynamic address for the target.
 *
 * @retval SUCCESS
 *         The dynamic address was successfully updated on the target and in the device table.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_INVALID_TARGET_ADDRESS
 *         The dynamic address to be assigned is a reserved address.
 * @retval FW_REPEATED_TARGET_ADDRESS
 *         The dynamic address to be set is already used by a target on the bus.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETNEWDA(CosmicSDK_Handle* handle, uint8_t oldDynamicAddress,
                                                uint8_t newDynamicAddress);

/**
 * @brief Gets the PID of one target.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETPID Common Command Code (CCC) in direct read mode to the specified I3C target.
 *
 * If the transfer completes successfully, the the corresponding entry in the internal target device
 * table is updated with the retrieved PID value.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param pid
 *        Vector where the retrieved Provisional ID will be stored.
 *
 * @retval SUCCESS
 *         Target PID was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p pid parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETPID(CosmicSDK_Handle* handle, uint8_t address,
                                              uint8_t* pid);

/**
 * @brief Get the Bus Characteristic Register (BCR) value of the target.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETBCR (Get Bus Characteristic Register) Common Command Code (CCC) in direct mode to
 * the specified I3C target.
 *
 * The controller reads the BCR value from the addressed target and stores the result in @p bcr. If
 * the operation completes successfully, the internal target device table is updated with the
 * retrieved BCR value to keep the software representation synchronized with the device state.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The output parameter @p bcr is updated only if the function returns @ref SUCCESS.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param bcr
 *        The Bus Characteristic Register of the target.
 *
 * @retval SUCCESS
 *         Target BCR was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p dcr parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETBCR(CosmicSDK_Handle* handle, uint8_t address,
                                              uint8_t* bcr);

/**
 * @brief Get the Device Characteristic Register (DCR) value of the target.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETDCR (Get Device Characteristic Register) Common Command Code (CCC) in direct mode to
 * the specified I3C target.
 *
 * The controller reads the DCR value from the addressed target and stores the result in @p dcr. If
 * the operation completes successfully, the internal target device table is updated with the
 * retrieved DCR value to keep the software representation synchronized with the device state.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The output parameter @p dcr is updated only if the function returns @ref SUCCESS.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param dcr
 *        The Device Characteristic Register of the target.
 *
 * @retval SUCCESS
 *         Target DCR was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p dcr parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETDCR(CosmicSDK_Handle* handle, uint8_t address,
                                              uint8_t* dcr);

/**
 * @brief Gets the STATUS from a target device on the I3C bus.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETSTATUS Common Command Code (CCC) in direct read mode to the specified I3C target.
 *
 * Two formats of the GETSTATUS CCC are supported:
 * - Format 1: If @p defByte is not provided, the command is issued without a defining byte and the
 * target returns its default STATUS data.
 * - Format 2: If @p defByte is provided, it is transmitted as the defining byte, and the target
 * returns the STATUS data corresponding to that definition.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param targetAddress
 *        The dynamic address of the target device from which to get the STATUS.
 *
 * @param status
 *        Vector where the retrieved STATUS will be stored.
 *
 * @param lenOut
 *        Number of bytes returned.
 *
 * @param hasDefByte
 *        If true, defByte is used and Format 2 of the CCC is sent.
 *
 * @param defByte
 *        The defining byte for the GETSTATUS Format 2 version of the CCC.
 *        If not provided, the default value is None and it is assumed the Format 1 of the CCC.
 *
 * @retval SUCCESS
 *         Target STATUS was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p status parameter and/or the @p lenOut parameter are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETSTATUS(CosmicSDK_Handle* handle, uint8_t targetAddress,
                                                 uint8_t* status, uint8_t* lenOut, bool hasDefByte,
                                                 uint8_t defByte);

/**
 * @brief Get the Optional Feature Capabilities (CAPS) from a target device on the I3C bus.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETCAPS (Get Optional Feature Capabilities) Common Command Code (CCC) in direct read
 * mode to the specified I3C target.
 *
 * Two formats of the GETCAPS CCC are supported:
 * - Format 1: If @p defByte is not provided, the command is issued without a defining byte and the
 * target returns its default CAPS data.
 * - Format 2: If @p defByte is provided, it is transmitted as the defining byte, and the target
 * returns the CAPS data corresponding to that definition.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param targetAddress
 *        The address of the target device from which to get the CAPS.
 *
 * @param caps
 *        Vector where the retrieved Optional Feature Capabilities (CAPS) will be stored.
 *
 * @param lenOut
 *        Number of bytes returned.
 *
 * @param hasDefByte
 *        If true, defByte is used and Format 2 of the CCC is sent.
 *
 * @param defByte
 *        The defining byte for the GETCAPS Format 2 version of the CCC.
 *        If not provided, the default value is None and it is assumed the Format 1 of the CCC.
 *
 * @retval SUCCESS
 *         Target CAPS was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p caps parameter and/or the @p lenOut parameter are NULL pointers.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETCAPS(CosmicSDK_Handle* handle, uint8_t targetAddress,
                                               uint8_t* caps, uint8_t* lenOut, bool hasDefByte,
                                               uint8_t defByte);

/**
 * @brief Emits the RSTACT Broadcast CCC to configure the next Target Reset action on all I3C
 * targets.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the RSTACT (Reset Action) Common Command Code (CCC) in broadcast mode.
 *
 * The RSTACT CCC and the Target Reset Pattern are emitted within the same frame. All targets that
 * support the specified reset action execute it upon receiving the command and the associated reset
 * pattern.
 *
 * This operation affects all I3C targets on the bus that support RSTACT.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - Devices that do not support the specified reset action may ignore the command.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param defByte
 *        The defining byte specifying the reset action to be performed.
 *        See @ref I3cTargetResetDefByte for supported values.
 *
 * @retval SUCCESS
 *         RSTACT Broadcast was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccRSTACTBroadcast(CosmicSDK_Handle* handle,
                                                       I3cTargetResetDefByte defByte);

/**
 * @brief Sends the Direct Write or Direct Read RSTACT CCC.
 *
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the RSTACT (Reset Action) Common Command Code (CCC) in direct mode to the specified target.
 *
 * The behavior depends on the selected @p direction:
 *
 * - Write transfer:
 *   The @p defByte specifies the reset action to be configured for the addressed target. The Target
 * Reset Pattern is emitted within the same frame, causing the target to execute the specified reset
 * action.
 *
 * - Read transfer:
 *   The command retrieves the reset recovery timing information from the addressed target, as
 * defined by the I3C specification. The retrieved value is stored in @p outValue if provided.
 *
 * Only the addressed target processes this command. Other devices on the bus are not affected.
 *
 * @note
 * - This function is valid only when the host is configured as an I3C controller.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param targetAddress
 *        The dynamic address of the target device.
 *
 * @param defByte
 *        The defining byte specifying the reset action to be performed.
 *        See @ref I3cTargetResetDefByte for supported values.
 *
 * @param direction
 *        Indicates whether the command is a read or write transfer.
 *        See @ref I3cTransferDirection for supported values.
 *
 * @param outValue
 *        Pointer where the retrieved reset recovery timing value will be stored when @p direction
 *        is read. Ignored for write transfers.
 *
 * @retval SUCCESS
 *         RSTACT Direct was successfully sent and acknowledged by the addressed target.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval SDK_ERROR_WRONG_REQUEST
 *         The @p direction is `READ` but @p outValue is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccRSTACTDirect(CosmicSDK_Handle* handle, uint8_t targetAddress,
                                                    I3cTargetResetDefByte defByte,
                                                    I3cTransferDirection direction, uint8_t* outValue);

/**
 * @brief Enable events for all targets (broadcast)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the ENEC (Enable Events Command) Common Command Code (CCC) in broadcast mode to all I3C
 * targets on the bus.
 *
 * Targets that do not support a specific event or the ENEC CCC may ignore the corresponding bits.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param events
 *        Bitmask of I3C events to be enabled. Possible events are defined on @ref I3CEvent.
 *        Multiple events may be combined using bitwise OR.
 *
 * @retval SUCCESS
 *         ENEC Broadcast was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccENECBroadcast(CosmicSDK_Handle* handle,
                                                     const uint8_t events);

/**
 * @brief Enable specific events on a single target (direct)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the ENEC (Enable Events Command) Common Command Code (CCC) in direct mode to the specified
 * I3C target.
 *
 * Only the addressed target processes this command. Other devices on the bus are not affected.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param events
 *        Bitmask of I3C events to be enabled. Possible events are defined on @ref I3CEvent.
 *        Multiple events may be combined using bitwise OR.
 *
 * @retval SUCCESS
 *         ENEC Direct was successfully sent and acknowledged by the addressed target.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccENECDirect(CosmicSDK_Handle* handle, uint8_t address,
                                                  const uint8_t events);

/**
 * @brief Disable events for all targets (broadcast)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the DISEC (Disable Events) Common Command Code (CCC) in broadcast mode to all I3C targets
 * on the bus.
 *
 * All targets capable of processing broadcast CCCs will receive and apply the command. Devices that
 * do not support a given event may ignore the corresponding bit.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param events
 *        Bitmask of I3C events to be disabled. Possible events are defined on @ref I3CEvent.
 *        Multiple events may be combined using bitwise OR.
 *
 * @retval SUCCESS
 *         DISEC Broadcast was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccDISECBroadcast(CosmicSDK_Handle* handle,
                                                      const uint8_t events);

/**
 * @brief Disable specific events on a single target (direct).
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the DISEC (Disable Events) Common Command Code (CCC) in direct mode to a single I3C target
 * identified by its dynamic address.
 *
 * Only the addressed target processes this command. Unlike the broadcast variant, other devices on
 * the bus are not affected.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param events
 *        Bitmask of I3C events to be disabled. Possible events are defined on @ref I3CEvent.
 *        Multiple events may be combined using bitwise OR.
 *
 * @retval SUCCESS
 *         DISEC Direct was successfully sent and acknowledged by the addressed target.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccDISECDirect(CosmicSDK_Handle* handle, uint8_t address,
                                                   const uint8_t events);

/**
 * @brief Get the Maximum Write Length (MWL) supported by the target
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETMWL (Get Maximum Write Length) Common Command Code (CCC) in direct mode to the
 * specified I3C target.
 *
 * The controller reads the Maximum Write Length value supported by the addressed target and stores
 * the result in @p maxWriteLength.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The output parameter @p maxWriteLength is updated only if the function returns @ref SUCCESS.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param maxWriteLength
 *        The Maximum Write Length of the target.
 *
 * @retval SUCCESS
 *         Target MWL was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval CosmicSDK_I3cCccGETMWL
 *         The @p maxWriteLength parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETMWL(CosmicSDK_Handle* handle, uint8_t address,
                                              uint16_t* maxWriteLength);

/**
 * @brief Set the Maximum Write Length (MWL) for all targets (broadcast CCC)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETMWL (Set Maximum Write Length) Common Command Code (CCC) in broadcast mode to all
 * I3C targets on the bus.
 *
 * All targets capable of processing broadcast CCCs will receive and apply the command.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The configured value applies to all targets that support the SETMWL CCC.
 * - Devices that do not support this CCC may ignore the command.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param mwl
 *        The Maximum Write Length.
 *
 * @retval SUCCESS
 *         MLW Broadcast was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETMWLBroadcast(CosmicSDK_Handle* handle, uint16_t mwl);

/**
 * @brief Set the Maximum Write Length (MWL) for a specific target (direct CCC)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETMWL (Set Maximum Write Length) Common Command Code (CCC)
 * in direct mode to the specified I3C target.
 *
 * Only the addressed target processes this command. Other devices on the
 * bus are not affected.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - A return value of @ref SUCCESS indicates that the CCC was transmitted successfully and
 * acknowledged by the addressed target.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param mwl
 *        The Maximum Write Length for the target.
 *
 * @retval SUCCESS
 *         MWL Direct was successfully sent and acknowledged by the addressed target.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETMWLDirect(CosmicSDK_Handle* handle, uint8_t address,
                                                    uint16_t mwl);

/**
 * @brief Get the Maximum Read Length (MRL) supported by the target.
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the GETMRL (Get Maximum Read Length) Common Command Code (CCC) in direct mode to the
 * specified I3C target.
 *
 * If the target supports In-Band Interrupt (IBI) payloads, it appends an additional byte to the
 * response indicating the maximum supported IBI payload length. In that case, @p ibiLength is set
 * with the returned value. If the response contains only two bytes, the target does not support IBI
 * payloads and @p ibiLength is reset.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The output parameters @p maxReadLength and @p ibiLength are updated only if the function
 * returns @ref SUCCESS.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param maxReadLength
 *        The Maximum Read Length of the target.
 *
 * @param ibiLength
 *        (optional) Set to the maximum IBI payload length if supported by the target, or reset if
 *        the target does not support IBI payloads.
 *
 * @param ibiLengthReturned
 *        Flag indicating if the target responded with IBI Length information. If the target does
 *        not support IBI, a NULL pointer could be passed.
 *
 * @retval SUCCESS
 *         Target MRL was successfully gotten.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 * @retval CosmicSDK_I3cCccGETMWL
 *         The @p maxReadLength parameter is NULL pointer.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccGETMRL(CosmicSDK_Handle* handle, uint8_t address,
                                              uint16_t* maxReadLength, uint8_t* ibiLength,
                                              bool* ibiLengthReturned);

/**
 * @brief Set the Maximum Read Length (MRL) for all targets (broadcast CCC)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETMRL (Set Maximum Read Length) Common Command Code (CCC) in broadcast mode to all I3C
 * targets on the bus.
 *
 * If @p ibiLength is provided, the CCC includes the optional IBI payload length field and
 * configures the maximum IBI payload size supported by the targets. If @p ibiLength is not set, the
 * CCC is sent without the IBI payload length field and the existing IBI payload configuration
 * remains unchanged.
 *
 * All targets capable of processing broadcast CCCs will receive and apply the command according to
 * the I3C specification.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The IBI payload length field is included in the CCC only when @p ibiLength
 *   contains a value.
 * - Devices that do not support the optional IBI length field may ignore it.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param mrl
 *        The Maximum Read Length.
 *
 * @param hasIbiLength
 *        If true, send the CCC with an IBI payload length.
 *
 * @param ibiLength
 *        (optional) When set, configures the maximum IBI payload size for the target; when not set,
 *        no IBI payload length is configured.
 *
 * @retval SUCCESS
 *         MRL Broadcast was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     None target acknowledged the broadcast address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETMRLBroadcast(CosmicSDK_Handle* handle, uint16_t mrl,
                                                       bool hasIbiLength, uint8_t ibiLength);

/**
 * @brief Set the Maximum Read Length (MRL) for a specific target (direct CCC)
 * @ingroup CosmicSDK_C_I3C
 *
 * @details
 * Sends the SETMRL (Set Maximum Read Length) Common Command Code (CCC) in direct mode to the
 * specified I3C target.
 *
 * If @p ibiLength is provided, the CCC includes the optional IBI payload length field and
 * configures the maximum IBI payload size supported by the target. If @p ibiLength is not set, the
 * CCC is sent without the IBI payload length field and the target IBI payload configuration remains
 * unchanged.
 *
 * Only the addressed target processes this command. Other devices on the bus are not affected.
 *
 * @note
 * - This function is valid only when the host is initialized as an I3C controller with @ref
 * CosmicSDK_I3cControllerInit.
 * - The IBI payload length field is included in the CCC only when @p ibiLength contains a value.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param address
 *        The dynamic address of the target device.
 *
 * @param mrl
 *        The Maximum Read Length for the target.
 *
 * @param hasIbiLength
 *        If true, send the CCC with an IBI payload length.
 *
 * @param ibiLength
 *        (optional) When set, configures the maximum IBI payload size for the target; when not set,
 *        no IBI payload length is configured.
 *
 * @retval SUCCESS
 *         MRL Direct was successfully sent and acknowledged by the addressed target.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The I3C interface has not been initialized.
 * @retval FW_INVALID_COMMAND
 *         The host device was initialized as a target device instead of a controller device.
 * @retval FW_BUS_TIMEOUT
 *         A timeout occurred while waiting for a response on the I3C bus.
 * @retval FW_I3C_NACK_ADDRESS
 * 		     The target NACKed the address.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_I3cCccSETMRLDirect(CosmicSDK_Handle* handle, uint8_t address,
                                                    uint16_t mrl, bool hasIbiLength,
                                                    uint8_t ibiLength);

/*****************************************************
 * @section UART Interface
 ****************************************************/

/**
 * @brief Sets the UART bus voltage
 * @warning On Supernova and Pulsar host adapters, the UART interface shares the same voltage domain as I2C, SPI and GPIOs.
 * As a result, calling this method to set the UART voltage will also affect the voltage of I2C, SPI and GPIO interfaces.
 * This must be taken into account when more than one interfaces are used simultaneously.
 * @ingroup CosmicSDK_C_UART
 *
 * @param handle Handle to the CosmicSDK instance
 * @param voltage_mV Voltage in millivolts to set the UART interface 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.
 * @param persist bool If true, the voltage setting will be persistent across power cycles. This ensures that any DUT
 * connected to the UART interface (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.
 * @return SUCCESS on success, error code otherwise
 */
COSMICSDK_API uint16_t CosmicSDK_UartSetBusVoltage(CosmicSDK_Handle* handle, uint16_t voltage_mV, bool persist);

/**
 * @brief Initialize the UART interface.
 * @ingroup CosmicSDK_C_UART
 *
 * @details
 * This function initializes the UART peripheral and must be called
 * successfully before any other UART-related API is used.
 *
 * @note
 * - This function must be called exactly once.
 * - Calling any UART 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 UART configuration after initialization, use
 * @ref CosmicSDK_UartSetParameters instead of reinitializing the interface.
 *
 * @param handle
 *        Handle to the CosmicSDK instance
 *
 * @param baudrate
 *        UART baud rate used for both transmission (TX) and reception (RX).
 *        See @ref UartBaudRate for supported values.
 *
 * @param hardwareHandshake
 *        Enables or disables hardware flow control (RTS/CTS), if supported
 *        by the underlying hardware.
 *        See @ref UartHwHandshake for supported values.
 *
 * @param parityMode
 *        UART parity configuration.
 *        See @ref UartParity for supported values.
 *
 * @param dataSize
 *        Number of data bits per UART frame.
 *        See @ref UartDataSize for supported values.
 *
 * @param stopBit
 *        Number of stop bits per UART frame.
 *        See @ref UartStopBit for supported values.
 *
 * @retval SUCCESS
 *         UART interphase was successfully initialized.
 * @retval FW_INTERFACE_ALREADY_INITIALIZED
 *         The UART interface has already been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_UartInit(CosmicSDK_Handle* handle, UartBaudRate baudrate, UartHwHandshake hardwareHandshake, UartParity parityMode, UartDataSize dataSize, UartStopBit stopBit);

/**
 * @brief Configure UART peripheral communication parameters.
 * @ingroup CosmicSDK_C_UART
 *
 * @details
 * This function updates the UART communication parameters after the UART
 * interface has been successfully initialized using @ref CosmicSDK_UartInit.
 * It allows runtime reconfiguration of the UART without requiring a full
 * deinitialization or reinitialization of the peripheral.
 *
 * @note
 * - This function must only be called after a successful call to
 *   @ref CosmicSDK_UartInit.
 * - Calling this function before UART initialization will result in
 *   FW_INTERFACE_NOT_INITIALIZED.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param baudrate
 *        UART baud rate used for both transmission (TX) and reception (RX).
 *        See @ref UartBaudRate for supported values.
 *
 * @param hardwareHandshake
 *        Enables or disables hardware flow control (RTS/CTS), if supported
 *        by the underlying hardware.
 *        See @ref UartHwHandshake for supported values.
 *
 * @param parityMode
 *        UART parity configuration.
 *        See @ref UartParity for supported values.
 *
 * @param dataSize
 *        Number of data bits per UART frame.
 *        See @ref UartDataSize for supported values.
 *
 * @param stopBit
 *        Number of stop bits per UART frame.
 *        See @ref UartStopBit for supported values.
 *
 * @retval SUCCESS
 *         UART parameters were successfully updated.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The UART interface has not been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_UartSetParameters(CosmicSDK_Handle* handle, UartBaudRate baudrate, UartHwHandshake hardwareHandshake, UartParity parityMode, UartDataSize dataSize, UartStopBit stopBit);

/**
 * @brief Transmit a UART message through the host adapter device.
 * @ingroup CosmicSDK_C_UART
 *
 * @details
 * Requests the host adapter to send data using the currently active
 * UART configuration (see @ref CosmicSDK_UartInit and @ref CosmicSDK_UartSetParameters).
 *
 * @note
 * - The UART interface must be successfully initialized with @ref CosmicSDK_UartInit
 *   before calling this function.
 * - If the UART interface is not initialized, this function returns
 *   `FW_INTERFACE_NOT_INITIALIZED`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param inData
 *        Pointer to the buffer containing the bytes to transmit.
 *
 * @param dataLength
 *        Number of bytes to transmit from @p data.
 *
 * @retval SUCCESS
 *         UART message were successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The UART interface has not been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_UartSendMessage(CosmicSDK_Handle* handle, uint8_t* inData, uint16_t dataLength);

/*****************************************************
 * @section GPIO Interface
 ****************************************************/

/**
 * @brief 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.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @param handle Handle to the CosmicSDK instance
 * @param 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.
 * @param 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.
 * @return SUCCESS on success, error code otherwise
 */
COSMICSDK_API uint16_t CosmicSDK_GpioSetVoltage(CosmicSDK_Handle* handle, uint16_t voltage_mV, bool persist);

/**
 * @brief Configures a GPIO pin with the specified functionality.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @details
 * 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 @p functionality is `GPIO_DIGITAL_INPUT`, @p initialOutputLogicLevel is ignored.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 * @param pinNumber
 *        The GPIO pin number to configure. See @ref GpioPinNumber.
 * @param functionality
 *        The desired functionality for the GPIO pin. See @ref GpioFunctionality.
 * @param setInitialOutputLogicLevel
 *        When true, the value provided in @p 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.
 * @param initialOutputLogicLevel
 *        The initial output logic level for the GPIO pin.
 *        See @ref GpioLogicLevel for valid values.
 *        This parameter is ignored unless @p setInitialOutputLogicLevel is true.
 *        This feature is reserved for future use.
 *
 * @retval SUCCESS
 *         GPIO pin was successfully configured.
 * @retval FW_INVALID_PARAMETER
 *         The pin number or functionality is invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_GpioConfigurePin(CosmicSDK_Handle* handle, GpioPinNumber pinNumber, GpioFunctionality functionality, bool setInitialOutputLogicLevel, GpioLogicLevel initialOutputLogicLevel);

/**
 * @brief Writes a digital logic level to a GPIO pin.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @details
 * Writes the provided logic level to a pin configured as a digital output.
 *
 * @note
 * - The pin must be configured as `GPIO_DIGITAL_OUTPUT` using
 *   @ref 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`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 * @param pinNumber
 *        The GPIO pin number to write to. See @ref GpioPinNumber.
 * @param logicLevel
 *        The logic level to write to the GPIO pin. See @ref GpioLogicLevel.
 *
 * @retval SUCCESS
 *         Logic level was successfully written.
 * @retval FW_GPIO_NOT_CONFIGURED
 *         The GPIO pin has not been configured.
 * @retval FW_GPIO_WRONG_CONFIGURATION
 *         The GPIO pin is not configured as a digital output.
 * @retval FW_INVALID_PARAMETER
 *         The pin number is invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_GpioDigitalWrite(CosmicSDK_Handle* handle, GpioPinNumber pinNumber, GpioLogicLevel logicLevel);

/**
 * @brief Reads the digital logic level from a GPIO pin.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @details
 * Reads the logic level from a pin configured as a digital input.
 *
 * @note
 * - The pin must be configured as `GPIO_DIGITAL_INPUT` using
 *   @ref 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`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 * @param pinNumber
 *        The GPIO pin number to read from. See @ref GpioPinNumber.
 * @param logicLevel
 *        On success, receives the logic level of the GPIO pin. See @ref GpioLogicLevel.
 *
 * @retval SUCCESS
 *         Logic level was successfully read.
 * @retval FW_GPIO_NOT_CONFIGURED
 *         The GPIO pin has not been configured.
 * @retval FW_GPIO_WRONG_CONFIGURATION
 *         The GPIO pin is not configured as a digital input.
 * @retval FW_INVALID_PARAMETER
 *         The pin number is invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_GpioDigitalRead(CosmicSDK_Handle* handle, GpioPinNumber pinNumber, GpioLogicLevel* logicLevel);

/**
 * @brief Configures and enables interrupts in a GPIO pin.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @details
 * Configures the interrupt trigger for a GPIO pin and enables its callback.
 *
 * @note
 * - The pin must be configured as `GPIO_DIGITAL_INPUT` using
 *   @ref 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`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 * @param pinNumber
 *        The GPIO pin number to configure interrupts for. See @ref GpioPinNumber.
 * @param trigger
 *        The trigger type used for the interruption. See @ref GpioTriggerType.
 *
 * @retval SUCCESS
 *         GPIO interrupt was successfully configured and enabled.
 * @retval FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE
 *         The selected GPIO pin does not support interrupts.
 * @retval FW_GPIO_NOT_CONFIGURED
 *         The GPIO pin has not been configured.
 * @retval FW_GPIO_WRONG_CONFIGURATION
 *         The GPIO pin is not configured as a digital input.
 * @retval FW_INVALID_PARAMETER
 *         The pin number or trigger type is invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_GpioConfigureInterrupt(CosmicSDK_Handle* handle, GpioPinNumber pinNumber, GpioTriggerType trigger);

/**
 * @brief Disables interrupts in a GPIO pin.
 * @ingroup CosmicSDK_C_GPIO
 *
 * @details
 * Disables interrupts for a GPIO pin configured as a digital input.
 *
 * @note
 * - The pin must be configured as `GPIO_DIGITAL_INPUT` using
 *   @ref 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`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 * @param pinNumber
 *        The GPIO pin number to which the interrupt will be disabled. See @ref GpioPinNumber.
 *
 * @retval SUCCESS
 *         GPIO interrupt was successfully disabled.
 * @retval FW_GPIO_NOT_CONFIGURED
 *         The GPIO pin has not been configured.
 * @retval FW_GPIO_WRONG_CONFIGURATION
 *         The GPIO pin is not configured as a digital input.
 * @retval FW_INVALID_PARAMETER
 *         The pin number is invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_GpioDisableInterrupt(CosmicSDK_Handle* handle, GpioPinNumber pinNumber);

/*****************************************************
 * @section SPI Interface
 ****************************************************/

/**
 * @brief 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.
 * @ingroup CosmicSDK_C_SPI
 *
 * @param handle Handle to the CosmicSDK instance
 * @param 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.
 * @param 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.
 * @return SUCCESS on success, error code otherwise
 */
COSMICSDK_API uint16_t CosmicSDK_SpiSetBusVoltage(CosmicSDK_Handle* handle, uint16_t voltage_mV, bool persist);

/**
 * @brief Initializes the SPI controller.
 * @ingroup CosmicSDK_C_SPI
 *
 * @details
 * 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
 * @ref CosmicSDK_SpiSetParameters instead of reinitializing the interface.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bitOrder
 *        Bit transmission order (MSB-first or LSB-first).
 *        See @ref SpiBitOrder for supported values.
 *
 * @param mode
 *        SPI clock mode (CPOL/CPHA configuration).
 *        See @ref SpiMode for supported values.
 *
 * @param dataWidth
 *        Width of a single SPI data frame, in bits.
 *        See @ref SpiDataWidth for supported values.
 *
 * @param chipSelect
 *        Chip select line to be used by the controller.
 *        See @ref SpiChipSelect for supported values.
 *
 * @param chipSelectPol
 *        Polarity of the chip select signal (active high or low).
 *        See @ref SpiChipSelectPolarity for supported values.
 *
 * @param 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.
 *
 * @retval SUCCESS
 *         SPI interphase was successfully initialized.
 * @retval FW_INTERFACE_ALREADY_INITIALIZED
 *         The SPI interface has already been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_SpiControllerInit(CosmicSDK_Handle* handle, SpiBitOrder bitOrder,
                                                   SpiMode mode, SpiDataWidth dataWidth,
                                                   SpiChipSelect chipSelect,
                                                   SpiChipSelectPolarity chipSelectPol, uint32_t frequency);

/**
 * @brief Sets the SPI bus parameters.
 * @ingroup CosmicSDK_C_SPI
 *
 * @details
 * This function updates the SPI bus parameters after the SPI interface has been
 * successfully initialized using @ref 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 @ref CosmicSDK_SpiControllerInit.
 * - Calling this function before UART initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param bitOrder
 *        Bit transmission order (MSB-first or LSB-first).
 *        See @ref SpiBitOrder for supported values.
 *
 * @param mode
 *        SPI clock mode (CPOL/CPHA configuration).
 *        See @ref SpiMode for supported values.
 *
 * @param dataWidth
 *        Width of a single SPI data frame, in bits.
 *        See @ref SpiDataWidth for supported values.
 *
 * @param chipSelect
 *        Chip select line to be used by the controller.
 *        See @ref SpiChipSelect for supported values.
 *
 * @param chipSelectPol
 *        Polarity of the chip select signal (active high or low).
 *        See @ref SpiChipSelectPolarity for supported values.
 *
 * @param 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.
 *
 * @retval SUCCESS
 *         SPI parameters were successfully updated.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The SPI interface has not been initialized.
 * @retval FW_INVALID_PARAMETER
 *         One or more configuration parameters are invalid or unsupported.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_SpiSetParameters(CosmicSDK_Handle* handle, SpiBitOrder bitOrder,
                                                  SpiMode mode, SpiDataWidth dataWidth,
                                                  SpiChipSelect chipSelect,
                                                  SpiChipSelectPolarity chipSelectPol, uint32_t frequency);

/**
 * @brief Performs a SPI transfer
 * @ingroup CosmicSDK_C_SPI
 *
 * @details
 * Requests the host adapter to send data using the currently active
 * SPI configuration (see @ref CosmicSDK_SpiControllerInit and @ref CosmicSDK_SpiSetParameters).
 *
 * @note
 * - The SPI interface must be successfully initialized with @ref CosmicSDK_SpiControllerInit
 *   before calling this function.
 * - If the UART interface is not initialized, this function returns `FW_INTERFACE_NOT_INITIALIZED`.
 *
 * @param handle
 *        Handle to the CosmicSDK instance.
 *
 * @param inData
 *        Buffer containing the data to be transmitted over SPI MOSI pin.
 *
 * @param inDataLength
 *        Length of the buffer pointed by @p inData.
 *
 * @param outData
 *        Buffer where the received data through SPI MISO pin will be stored.
 *
 * @param 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 @p transferLength can be equal or
 *        greater than the length of the @p inData buffer.
 *
 * @retval SUCCESS
 *         SPI message was successfully sent.
 * @retval FW_INTERFACE_NOT_INITIALIZED
 *         The UART interface has not been initialized.
 * @retval FW_INVALID_PARAMETER
 *         The @p transferLength is greater than te maximum SPI data length supported
 *         by the host device.
 * @retval FW_UNHANDLED_ERROR
 *         An unhandled error occurred while transferring SPI data.
 * @retval SDK_ERROR_TIMEOUT
 *         The operation timed out.
 * @retval SDK_ERROR_DISCONNECT
 *         The device was disconnected or became unavailable during the operation.
 */
COSMICSDK_API uint16_t CosmicSDK_SpiTransfer(CosmicSDK_Handle* handle, uint8_t* inData, uint16_t inDataLength, uint8_t* outData, uint16_t transferLength);

#ifdef __cplusplus
}
#endif

/** @} */ /* end of CosmicSDK_C */
