/**
 * @file definitions.h
 *
 * @brief This file contains the definition of all the constants and enums used in the Cosmic SDK.
 * By constants we mean the command codes, result codes, and other definitions that are used
 * throughout the SDK, for instance, as parameters for the methods.
 *
 * All constants are defined in a way that they can be used in both C and C++ code. Additionally,
 * the constants are grouped by protocol or interface, and each group has its own set of commands
 * and results. The commands and results are also grouped by role, which can be either controller,
 * target, or generic. The commands can be either request-response type or notification type.
 *
 * @author Binho
 */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

/**********************************************************************************************
 * NOTIFICATION ID Definitions
 **********************************************************************************************/
/**
 * @brief Notification ID. While all the commands request and responses use a 2-byte transaction ID,
 * the value 0 is reserved for notifications. For this reason, the command requests and responses
 * must use a transaction ID from 1 to 65535 (0x0001 to 0xFFFF), while the notifications
 * use a transaction ID of 0 (0x0000).
 *
 * Notifications are used to send information from the target to the controller asynchronously,
 * without a previous request.
 *
 */
#define NOTIFICATION_ID 0x00

/**********************************************************************************************
 * COMMANDS/RESULTS GROUPS Definitions
 **********************************************************************************************/

/**
 * @brief The macros below define the groups of commands and results. The commands adn results
 * are grouped by protocol or interface, which are identified by the macros below.
 *
 */
/** @cond INTERNAL_MACROS */
#define GROUP_GLOBAL   0
#define GROUP_SYS      1
#define GROUP_I2C      2
#define GROUP_SPI      3
#define GROUP_UART     4
#define GROUP_GPIO     5
#define GROUP_I3C      6
#define GROUP_ONE_WIRE 7
#define GROUP_CAN      8
#define GROUP_RS485    9
/** @endcond */

/**********************************************************************************************
 * COMMAND CODES Definitions
 **********************************************************************************************/

/**
 * @brief Additionally to the group, the commands and results are associated to a role. Some
 * commands/results are only available for the controller role, others are available for target
 * role, and some are generic commands that are role-independent.
 * @cond INTERNAL_MACROS
 */
#define ROLE_GENERIC    0
#define ROLE_CONTROLLER 1
#define ROLE_TARGET     2
/** @endcond */

/**
 * @brief The macros below define the category of the code. The codes can correspond to a
 * request-response type or a notification type.
 * @cond INTERNAL_MACROS
 */
#define TYPE_REQUEST_RESPONSE 0
#define TYPE_NOTIFICATION     1
/** @endcond */

/**
 * @brief The macros below define the command masks for each component. The command code
 * is a 16-bit value composed of three parts:
 * - Group: 6 bits (bits 10-15)
 * - Role: 2 bits (bits 8-9)
 * - Type: 1 bit (bit 7)
 * - Value: 7 bits (bits 0-6)
 * @cond INTERNAL_MACROS
 */
#define COMMAND_GROUP_MASK 0xFC00
#define COMMAND_ROLE_MASK  0x0300
#define COMMAND_TYPE_MASK  0x0080

#define COMMAND_GROUP_SHIFT 10
#define COMMAND_ROLE_SHIFT  8
#define COMMAND_TYPE_SHIFT  7
/** @endcond */

/**
 * @brief The macro below is used to create a command code from its components.
 * The command code is a 16-bit value composed of:
 * - Group: 6 bits (bits 10-15)
 * - Role: 2 bits (bits 8-9)
 * - Type: 1 bit (bit 7)
 * - Value: 7 bits (bits 0-6)
 */
#define MAKE_COMMAND_CODE(GROUP, ROLE, TYPE, VALUE) ((GROUP << COMMAND_GROUP_SHIFT) | (ROLE << COMMAND_ROLE_SHIFT) | (TYPE << COMMAND_TYPE_SHIFT) | VALUE)

/**
 * @brief The macros below are used to extract the group, role, and type from a command code.
 * Allows to breakdown the command into its components.
 * @cond INTERNAL_MACROS
 */
#define GET_GROUP(VALUE) ((VALUE & COMMAND_GROUP_MASK) >> COMMAND_GROUP_SHIFT)
#define GET_ROLE(VALUE)  ((VALUE & COMMAND_ROLE_MASK) >> COMMAND_ROLE_SHIFT)
#define GET_TYPE(VALUE)  ((VALUE & COMMAND_TYPE_MASK) >> COMMAND_TYPE_SHIFT)
/** @endcond */

/**********************************************************************************************
 * COMMANDS CODE DEFINITION
 **********************************************************************************************/

/**
 * @brief System command code definitions
 */
#define CMD_SYS_RESET_DEVICE                           MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1)  /**< Hex.: 0x0401, Dec.: 1025. Reserved for future implementation in the SDK. */
#define CMD_SYS_ENTER_BOOT_MODE                        MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 2)  /**< Hex.: 0x0402, Dec.: 1026. */
#define CMD_SYS_ENTER_ISP_MODE                         MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 3)  /**< Hex.: 0x0403, Dec.: 1027. Reserved for future implementation in the SDK. */
#define CMD_SYS_SET_I3C_VOLTAGE                        MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 4)  /**< Hex.: 0x0404, Dec.: 1028. Reserved for future implementation in the SDK. */
#define CMD_SYS_SET_I2C_SPI_UART_GPIO_VOLTAGE          MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 5)  /**< Hex.: 0x0405, Dec.: 1029. */
#define CMD_SYS_SET_1WIRE_VOLTAGE                      MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 6)  /**< Hex.: 0x0406, Dec.: 1030. Reserved for future implementation in both SDK and FW. */
#define CMD_SYS_GET_USB_STRING                         MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 7)  /**< Hex.: 0x0407, Dec.: 1031. */
#define CMD_SYS_GET_I3C_CONNECTOR_STATUS               MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 8)  /**< Hex.: 0x0408, Dec.: 1032. Reserved for future implementation in the SDK. */
#define CMD_SYS_GET_ANALOG_MEASUREMENTS                MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 9)  /**< Hex.: 0x0409, Dec.: 1033. Reserved for future implementation in the SDK. */
#define CMD_SYS_USE_EXTERNAL_I3C_VOLTAGE               MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 10) /**< Hex.: 0x040A, Dec.: 1034. Reserved for future implementation in the SDK. */
#define CMD_SYS_USE_EXTERNAL_I2C_SPI_UART_GPIO_VOLTAGE MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 11) /**< Hex.: 0x040B, Dec.: 1035. Reserved for future implementation in the SDK. */
#define CMD_SYS_GET_DEVICE_INFO                        MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 12) /**< Hex.: 0x040C, Dec.: 1036. Reserved for future implementation in the SDK. */
#define CMD_SYS_I3C_CONNECTOR_EVENT_NOTIFICATION       MAKE_COMMAND_CODE(GROUP_SYS, ROLE_GENERIC, TYPE_NOTIFICATION, 1)      /**< Hex.: 0x0481, Dec.: 1153. Reserved for future implementation in the SDK. */

/**
 * @brief I2C command code definitions
 */
#define CMD_I2C_DEINIT                    MAKE_COMMAND_CODE(GROUP_I2C, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1)    /**< Hex.: 0x0801, Dec.: 2049. Reserved for future implementation in both SDK and FW. */
#define CMD_I2C_SET_PULLUP_RESISTORS      MAKE_COMMAND_CODE(GROUP_I2C, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 2)    /**< Hex.: 0x0802, Dec.: 2050. */
#define CMD_I2C_CONTROLLER_INIT           MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 1) /**< Hex.: 0x0901, Dec.: 2305. */
#define CMD_I2C_CONTROLLER_SET_PARAMETERS MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 2) /**< Hex.: 0x0902, Dec.: 2306. */
#define CMD_I2C_CONTROLLER_GET_PARAMETERS MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 3) /**< Hex.: 0x0903, Dec.: 2307. Reserved for future implementation in both SDK and FW. */
#define CMD_I2C_CONTROLLER_WRITE          MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 4) /**< Hex.: 0x0904, Dec.: 2308. */
#define CMD_I2C_CONTROLLER_READ           MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 5) /**< Hex.: 0x0905, Dec.: 2309. */
#define CMD_I2C_CONTROLLER_SCAN_BUS       MAKE_COMMAND_CODE(GROUP_I2C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 6) /**< Hex.: 0x0906, Dec.: 2310. */

/**
 * @brief SPI command code definitions
 */
#define CMD_SPI_DEINIT                    MAKE_COMMAND_CODE(GROUP_SPI, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1)    /**< Hex.: 0x0C01, Dec.: 3073. Reserved for future implementation in both SDK and FW. */
#define CMD_SPI_CONTROLLER_INIT           MAKE_COMMAND_CODE(GROUP_SPI, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 1) /**< Hex.: 0x0D01, Dec.: 3329. */
#define CMD_SPI_CONTROLLER_SET_PARAMETERS MAKE_COMMAND_CODE(GROUP_SPI, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 2) /**< Hex.: 0x0D02, Dec.: 3330. */
#define CMD_SPI_CONTROLLER_GET_PARAMETERS MAKE_COMMAND_CODE(GROUP_SPI, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 3) /**< Hex.: 0x0D03, Dec.: 3331. Reserved for future implementation in both SDK and FW. */
#define CMD_SPI_CONTROLLER_TRANSFER       MAKE_COMMAND_CODE(GROUP_SPI, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 4) /**< Hex.: 0x0D04, Dec.: 3332. */

/**
 * @brief I3C command code definitions
 */
#define CMD_I3C_DEINIT                              MAKE_COMMAND_CODE(GROUP_I3C, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1)     /**< Hex.: 0x1801, Dec.: 6145. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_SET_PULLUP_RESISTORS                MAKE_COMMAND_CODE(GROUP_I3C, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 2)     /**< Hex.: 0x1802, Dec.: 6146. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_CONTROLLER_INIT                     MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 1)  /**< Hex.: 0x1901, Dec.: 6401. */
#define CMD_I3C_CONTROLLER_SET_PARAMETERS           MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 2)  /**< Hex.: 0x1902, Dec.: 6402. */
#define CMD_I3C_CONTROLLER_GET_PARAMETERS           MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 3)  /**< Hex.: 0x1903, Dec.: 6403. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_CONTROLLER_INIT_BUS                 MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 4)  /**< Hex.: 0x1904, Dec.: 6404. */
#define CMD_I3C_CONTROLLER_RESET_BUS                MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 5)  /**< Hex.: 0x1905, Dec.: 6405. */
#define CMD_I3C_CONTROLLER_GET_TARGET_DEVICES_TABLE MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 6)  /**< Hex.: 0x1906, Dec.: 6406. */
#define CMD_I3C_CONTROLLER_SET_TARGET_DEVICE_CONFIG MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 7)  /**< Hex.: 0x1907, Dec.: 6407. */
#define CMD_I3C_CONTROLLER_PRIVATE_TRANSFER         MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 8)  /**< Hex.: 0x1908, Dec.: 6408. */
#define CMD_I3C_CONTROLLER_CCC_TRANSFER             MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 9)  /**< Hex.: 0x1909, Dec.: 6409. */
#define CMD_I3C_CONTROLLER_TRIGGER_PATTERN          MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_REQUEST_RESPONSE, 10) /**< Hex.: 0x190A, Dec.: 6410. */
#define CMD_I3C_CONTROLLER_IBI_REQUEST_NOTIFICATION MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_NOTIFICATION, 1)      /**< Hex.: 0x1981, Dec.: 6529. */
#define CMD_I3C_CONTROLLER_HJ_REQUEST_NOTIFICATION  MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_NOTIFICATION, 2)      /**< Hex.: 0x1982, Dec.: 6530. */
#define CMD_I3C_CONTROLLER_CR_REQUEST_NOTIFICATION  MAKE_COMMAND_CODE(GROUP_I3C, ROLE_CONTROLLER, TYPE_NOTIFICATION, 3)      /**< Hex.: 0x1983, Dec.: 6531. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_TARGET_INIT                         MAKE_COMMAND_CODE(GROUP_I3C, ROLE_TARGET, TYPE_REQUEST_RESPONSE, 1)      /**< Hex.: 0x1A01, Dec.: 6657. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_TARGET_SET_PARAMETERS               MAKE_COMMAND_CODE(GROUP_I3C, ROLE_TARGET, TYPE_REQUEST_RESPONSE, 2)      /**< Hex.: 0x1A02, Dec.: 6658. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_TARGET_WRITE_MEMORY                 MAKE_COMMAND_CODE(GROUP_I3C, ROLE_TARGET, TYPE_REQUEST_RESPONSE, 3)      /**< Hex.: 0x1A03, Dec.: 6659. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_TARGET_READ_MEMORY                  MAKE_COMMAND_CODE(GROUP_I3C, ROLE_TARGET, TYPE_REQUEST_RESPONSE, 4)      /**< Hex.: 0x1A04, Dec.: 6660. Reserved for future implementation in both SDK and FW. */
#define CMD_I3C_TARGET_BUS_EVENT_NOTIFICATION       MAKE_COMMAND_CODE(GROUP_I3C, ROLE_TARGET, TYPE_NOTIFICATION, 1)          /**< Hex.: 0x1A81, Dec.: 6785. Reserved for future implementation in both SDK and FW. */

/**
 * @brief GPIO command code definitions
 */
#define CMD_GPIO_CONFIGURE_PIN          MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1) /**< Hex.: 0x1401, Dec.: 5121. */
#define CMD_GPIO_DIGITAL_WRITE          MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 2) /**< Hex.: 0x1402, Dec.: 5122. */
#define CMD_GPIO_DIGITAL_READ           MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 3) /**< Hex.: 0x1403, Dec.: 5123. */
#define CMD_GPIO_CONFIGURE_INTERRUPT    MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 4) /**< Hex.: 0x1404, Dec.: 5124. */
#define CMD_GPIO_DISABLE_INTERRUPT      MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 5) /**< Hex.: 0x1405, Dec.: 5125. */
#define CMD_GPIO_INTERRUPT_NOTIFICATION MAKE_COMMAND_CODE(GROUP_GPIO, ROLE_GENERIC, TYPE_NOTIFICATION, 1)     /**< Hex.: 0x1481, Dec.: 5249. */

/**
 * @brief UART command code definitions
 */
#define CMD_UART_DEINIT         MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 1) /**< Hex.: 0x1401, Dec.: 5121. Reserved for future implementation in both SDK and FW. */
#define CMD_UART_INIT           MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 2) /**< Hex.: 0x1401, Dec.: 5121. */
#define CMD_UART_SET_PARAMETERS MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 3) /**< Hex.: 0x1401, Dec.: 5121. */
#define CMD_UART_GET_PARAMETERS MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 4) /**< Hex.: 0x1401, Dec.: 5121. Reserved for future implementation in both SDK and FW. */
#define CMD_UART_SEND           MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_REQUEST_RESPONSE, 5) /**< Hex.: 0x1401, Dec.: 5121. */
#define CMD_UART_NOTIFICATION   MAKE_COMMAND_CODE(GROUP_UART, ROLE_GENERIC, TYPE_NOTIFICATION, 1)     /**< Hex.: 0x1401, Dec.: 5121. */

/**********************************************************************************************
 * RESULT CODES Definitions
 **********************************************************************************************/

/**
 * @brief Bitmask to extract firmware-specific result code (lower 13 bits).
 *
 * Result codes are 16-bit values. The lower 13 bits represent the result
 * generated by the firmware. Use this mask to isolate that portion.
 */
#define FW_RESULT_MASK 0x1FFF

/**
 * @brief Bitmask to extract SDK-level flags or status (upper 3 bits).
 *
 * The upper 3 bits of a result code are reserved for SDK-level
 * categorization (e.g., severity, internal flags). This mask helps
 * isolate those bits.
 */
#define SDK_RESULT_MASK 0xE000

/**
 * @name Generic FW Result Codes
 * @ingroup ResultCodes_Generic
 * @{
 */
#define SUCCESS                              0x0000 /**< Hex.: 0x0000, Dec.: 0. The requested action ended successfully. */
#define FW_UNSUPPORTED_COMMAND               0x0001 /**< Hex.: 0x0001, Dec.: 1. The requested command is not supported by the firmware. */
#define FW_INVALID_COMMAND                   0x0002 /**< Hex.: 0x0002, Dec.: 2. The command is not valid for the current state or context. */
#define FW_FULL_RECEPTION_QUEUE              0x0003 /**< Hex.: 0x0003, Dec.: 3. The reception queue is full. Reserved for future use. */
#define FW_INVALID_PARAMETER                 0x0004 /**< Hex.: 0x0004, Dec.: 4. At least one of the parameters of the command is not valid. */
#define FW_FEATURE_NOT_SUPPORTED_BY_HARDWARE 0x0005 /**< Hex.: 0x0005, Dec.: 5. The requested feature is not supported by the hardware. */
#define FW_INTERFACE_NOT_INITIALIZED         0x0006 /**< Hex.: 0x0006, Dec.: 6. The interface is not initialized. Run the corresponding initialization command first. */
#define FW_INTERFACE_ALREADY_INITIALIZED     0x0007 /**< Hex.: 0x0007, Dec.: 7. The interface is already initialized. Run the corresponding set parameters command to modify the current configuration. */
#define FW_BUS_NOT_SUPPORTED                 0x0008 /**< Hex.: 0x0008, Dec.: 8. The addressed interface/protocol bus is not supported by the hardware or firmware. */
#define FW_BUS_TIMEOUT                       0x0009 /**< Hex.: 0x0009, Dec.: 9. Communication with a downstream device in the corresponding interface bus timed out. */
#define FW_RX_FIFO_FULL                      0x000A /**< Hex.: 0x000A, Dec.: 10. The reception FIFO is full. Apply for target roles such as I3C Target.*/
#define FW_TX_FIFO_EMPTY                     0x000B /**< Hex.: 0x000B, Dec.: 11. The transmission FIFO is empty. Apply for target roles such as I3C Target.*/
#define FW_UNHANDLED_ERROR                   0x000C /**< Hex.: 0x000C, Dec.: 12. An error occurred that is not handled by the firmware. */
/** @} */

/**
 * @name System Result Codes
 * @ingroup ResultCodes_System
 * @{
 */
#define FW_VOLTAGE_OUT_OF_RANGE           0x0101 /**< Hex.: 0x0101, Dec.: 257. The voltage is out of the supported range. */
#define FW_EXTERNAL_VOLTAGE_DETECTED      0x0102 /**< Hex.: 0x0102, Dec.: 258. An external voltage was detected on the when trying to set the voltage and enabling VTARG pin. */
#define FW_VOLTAGE_ADJUSTMENT_FAILURE     0x0103 /**< Hex.: 0x0103, Dec.: 259. The voltage adjustment failed. */
#define FW_I3C_PORTS_NOT_POWERED          0x0104 /**< Hex.: 0x0104, Dec.: 260. No external voltage measured on either of the I3C ports when trying to use an external voltage supply. Only one of the two ports must be powered at a time. */
#define FW_BOTH_I3C_PORTS_POWERED         0x0105 /**< Hex.: 0x0105, Dec.: 261. Both I3C ports are powered when trying to use an external voltage supply. Only one of the two ports must be powered at a time. */
#define FW_VOLTAGE_OUT_OF_RANGE_ON_I3C_LV 0x0106 /**< Hex.: 0x0106, Dec.: 262. The voltage is out of range on the I3C low voltage port. Range goes from 800 mV to 1199 mV. */
#define FW_VOLTAGE_OUT_OF_RANGE_ON_I3C_HV 0x0107 /**< Hex.: 0x0107, Dec.: 263. The voltage is out of range on the I3C high voltage port. Range goes from 1200 mV to 3000 mV. */
/** @} */

/**
 * @name I2C Result Codes
 * @ingroup ResultCodes_I2C
 * @{
 */
#define FW_I2C_PULLUP_RESISTOR_SETTING_FAILURE 0x0201 /**< Hex.: 0x0201, Dec.: 513. The pull-up resistor setting failed. */
#define FW_I2C_ARBITRATION_LOST                0x0202 /**< Hex.: 0x0202, Dec.: 514. The arbitration was lost during an I2C transfer. */
#define FW_I2C_NACK_ADDRESS                    0x0203 /**< Hex.: 0x0203, Dec.: 515. The address was not acknowledged by the target device. */
#define FW_I2C_NACK_BYTE                       0x0204 /**< Hex.: 0x0204, Dec.: 516. The last data byte was not acknowledged by the target device. */
#define FW_I2C_BIT_ERROR                       0x0205 /**< Hex.: 0x0205, Dec.: 517. A bit error occurred during an I2C transfer. */
#define FW_I2C_START_STOP_ERROR                0x0206 /**< Hex.: 0x0206, Dec.: 518. The start or stop condition was not properly generated during an I2C transfer. */
#define FW_I2C_BUSY                            0x0207 /**< Hex.: 0x0207, Dec.: 519. The I2C bus is busy and the a new transfer request cannot be started. */
#define FW_I2C_TIMEOUT_CONTINUE_TRANSFER       0x0208 /**< Hex.: 0x0208, Dec.: 520. The timeout occurred while continuing an I2C transfer. */
#define FW_I2C_TIMEOUT_WAITING_BUS_EVENT       0x0209 /**< Hex.: 0x0209, Dec.: 521. The timeout occurred while waiting for a bus event. */
#define FW_I2C_TIMEOUT_SCL_LOW                 0x020A /**< Hex.: 0x020A, Dec.: 522. The SCL line was low for too long during an I2C transfer. */
#define FW_I2C_DMA_REQUEST_FAIL                0x020B /**< Hex.: 0x020B, Dec.: 523. The DMA request failed. */
#define FW_I2C_INVALID_PARAMETER               0x020C /**< Hex.: 0x020C, Dec.: 524. The parameter is invalid for the I2C operation. */
#define FW_I2C_NO_TRANSFER_IN_PROGRESS         0x020D /**< Hex.: 0x020D, Dec.: 525. No transfer is in progress. */
#define FW_I2C_UNEXPECTED_STATE                0x020E /**< Hex.: 0x020E, Dec.: 526. The I2C state is unexpected. */
#define FW_I2C_BUS_WITH_NO_TARGETS_CONNECTED   0x020F /**< Hex.: 0x020F, Dec.: 527. The I2C bus has no targets connected. Returned when the I2C SCAN BUS command does not discover any static address. */
/** @} */

/**
 * @name GPIO Result Codes
 * @ingroup ResultCodes_GPIO
 * @{
 */
#define FW_GPIO_NOT_CONFIGURED      0x0501 /**< Hex.: 0x0501, Dec.: 1281. The GPIO is not configured. */
#define FW_GPIO_WRONG_CONFIGURATION 0x0502 /**< Hex.: 0x0502, Dec.: 1282. The GPIO configuration is wrong. This result is returned when the GPIO is configured as a digital output and the user attempts to enable interrupts on it. */
/** @} */

/**
 * @name I3C Result Codes
 * @ingroup ResultCodes_I3C
 * @{
 */
#define FW_FULL_TARGET_DEVICES_TABLE                0x0601 /**< Hex.: 0x0601, Dec.: 1537. The target devices table is full. This might be reported when a new Hot-Join is requested and the table is already full. The maximum number of target devices the firmware supports is 11. */
#define FW_NOT_ENOUGH_SPACE_IN_TARGET_DEVICES_TABLE 0x0602 /**< Hex.: 0x0602, Dec.: 1538. The number of devices discovered during the ENTDAA or sent by the host application using ENTDAA, SETDASA, or SETAASA surpass the maximum number of targets. This means more than 11 targets.  */
#define FW_TARGET_DEVICES_TABLE_OVERFLOW            0x0603 /**< Hex.: 0x0603, Dec.: 1539. The target devices table overflowed during the ENTDAA CCC. */
#define FW_TARGET_ADDRESS_NOT_FOUND_IN_THE_TABLE    0x0604 /**< Hex.: 0x0604, Dec.: 1540. The target address was not found in the table when trying to change its configuration. */
#define FW_REPEATED_TARGET_ADDRESS                  0x0605 /**< Hex.: 0x0605, Dec.: 1541. The target address is already in the table. This might be returned when attempting to issue a SETDASA or SETAASA CCCs. */
#define FW_INVALID_TARGET_ADDRESS                   0x0606 /**< Hex.: 0x0606, Dec.: 1542. The host application attempts to use an invalid target address, this is an address that is not within of the space of valid I3C address based on the MIPI I3C spec. */
#define FW_I3C_BUS_INIT_NACK_RSTDAA                 0x0607 /**< Hex.: 0x0607, Dec.: 1543. No target acknowledged the Broadcast Address 0x7E issued in the header of the RSTDAA CCC during the `I3C INIT BUS` command. */
#define FW_I3C_BUS_INIT_NACK_SETDASA                0x0608 /**< Hex.: 0x0608, Dec.: 1544. At least one target did not acknowledge the Broadcast Address 0x7E issued in the header of the SETDASA command during the `I3C INIT BUS` command. */
#define FW_I3C_BUS_INIT_NACK_SETAASA                0x0609 /**< Hex.: 0x0609, Dec.: 1545. No target acknowledged the Broadcast Address 0x7E issued in the header of the SETAASA command during the `I3C INIT BUS` command. */
#define FW_I3C_BUS_INIT_NACK_ENTDAA                 0x060A /**< Hex.: 0x060A, Dec.: 1546. No target acknowledged the Broadcast Address 0x7E issued in the header of the ENTDAA command during the `I3C INIT BUS` command. */
#define FW_I3C_NACK_ADDRESS                         0x060B /**< Hex.: 0x060B, Dec.: 1547. The target device did not acknowledge its dynamic address, or its static address if it is an I2C target, during an I3C transfer. */
#define FW_I3C_I2C_NACK_BYTE                        0x060C /**< Hex.: 0x060C, Dec.: 1548. An I2C target did not acknowledge a byte during an I2C transfer over the I3C bus. */
#define FW_I3C_TRANSFER_ABORTED_BY_CONTROLLER       0x060D /**< Hex.: 0x060D, Dec.: 1549. Reserved for future use. */
#define FW_I3C_TRANSFER_MWL_REACHED                 0x060E /**< Hex.: 0x060E, Dec.: 1550. Reserved for future use. */
#define FW_I3C_TRANSFER_MRL_REACHED                 0x060F /**< Hex.: 0x060F, Dec.: 1551. Reserved for future use. */
#define FW_I3C_TRANSFER_PARITY_ERROR                0x0610 /**< Hex.: 0x0610, Dec.: 1552. Reserved for future use. */
#define FW_IBI_REQUEST_ACCEPTED                     0x0611 /**< Hex.: 0x0611, Dec.: 1553. The Supernova accepted an IBI request if an IBI without payload. */
#define FW_IBI_REQUEST_ACCEPTED_WITH_PAYLOAD        0x0612 /**< Hex.: 0x0612, Dec.: 1554. The Supernova accepted an IBI request and additional payload was received. */
#define FW_IBI_REQUEST_REJECTED                     0x0613 /**< Hex.: 0x0613, Dec.: 1555. The Supernova rejected an IBI request. */
#define FW_HJ_REQUEST_ACCEPTED                      0x0614 /**< Hex.: 0x0614, Dec.: 1556. The Supernova accepted a HJ request. */
#define FW_HJ_REQUEST_REJECTED                      0x0615 /**< Hex.: 0x0615, Dec.: 1557. The Supernova rejected a HJ request. */
#define FW_REGISTER_ADDRESS_OUT_OF_RANGE            0x0616 /**< Hex.: 0x0616, Dec.: 1558. Reserved for future use. */
#define FW_SURPASSED_MEMORY_SIZE                    0x0617 /**< Hex.: 0x0617, Dec.: 1559. Reserved for future use. */
/** @} */

/**
 * @name SDK Result Codes
 * @ingroup ResultCodes_SDK
 * @{
 */
#define SDK_ERROR_TIMEOUT             0x2000 /**< Hex.: 0x2000, Dec.: 8192. The USB host adapter device did not respond within the expected timeout period. */
#define SDK_ERROR_DISCONNECT          0x4000 /**< Hex.: 0x4000, Dec.: 16384. The USB host adapter device was disconnected. */
#define SDK_ERROR_UNEXPECTED_RESPONSE 0x6000 /**< Hex.: 0x6000, Dec.: 24576. The device returned an unexpected response. */
#define SDK_ERROR_WRONG_REQUEST       0x8000 /**< Hex.: 0x8000, Dec.: 32768. The request was malformed. */
#define SDK_ERROR_WRONG_RESPONSE      0xA000 /**< Hex.: 0xA000, Dec.: 40960. The response was malformed. */
/** @} */

/**********************************************************************************************
 * System Definitions
 **********************************************************************************************/

/**
 * @name Get USB string methods Sub-command Codes
 * @ingroup Constants_System
 * @brief Selectors used with @ref CMD_SYS_GET_USB_STRING.
 * @{
 */
#define GET_MANUFACTURER_STR 0x01 /**< Request the USB manufacturer string descriptor. */
#define GET_PRODUCT_STR      0x02 /**< Request the USB product string descriptor. */
#define GET_USB_SN_STR       0x03 /**< Request the USB serial-number string descriptor. */
#define GET_FW_VERSION       0x04 /**< Request the firmware version string. */
#define GET_HW_VERSION       0x05 /**< Request the hardware version string. */
/** @} */

/**********************************************************************************************
 * I2C Definitions
 **********************************************************************************************/

/**
 * @name I2C General Constants
 * @ingroup Constants_I2C
 * @{
 */
#define MAX_I2C_TRANSFER_LENGTH 1024 /**< Maximum I2C payload length in bytes per transfer request. */
/** @} */

/**
 * @name I2C Bus Selection
 * @ingroup Constants_I2C
 * @{
 */
#define I2C_BUS_A 0x00 /**< Select I2C bus/channel A. For Pulsar, accessible through the I2C-dedicated Qwiic connector. For Supernova, it is accessible though both the I2C-dedicated Qwiic connector and the 2x15 pin connector. */
#define I2C_BUS_B 0x01 /**< Select I2C bus/channel B. This bus id applies only for the Pulsar. This bus is accessible through the 2x15 pin connector and the external breakout board. */
/** @} */

/**
 * @name I2C Pull-up Resistor Options
 * @ingroup Constants_I2C
 * @brief Encoded pull-up resistor selections used by @ref CMD_I2C_SET_PULLUP_RESISTORS.
 * @{
 */
#define I2C_PULLUP_150Ohm  0x00 /**< Configure 150 Ohm pull-up resistance. */
#define I2C_PULLUP_220Ohm  0x01 /**< Configure 220 Ohm pull-up resistance. */
#define I2C_PULLUP_330Ohm  0x02 /**< Configure 330 Ohm pull-up resistance. */
#define I2C_PULLUP_470Ohm  0x03 /**< Configure 470 Ohm pull-up resistance. */
#define I2C_PULLUP_680Ohm  0x04 /**< Configure 680 Ohm pull-up resistance. */
#define I2C_PULLUP_1kOhm   0x05 /**< Configure 1.0 kOhm pull-up resistance. */
#define I2C_PULLUP_1_5kOhm 0x06 /**< Configure 1.5 kOhm pull-up resistance. */
#define I2C_PULLUP_2_2kOhm 0x07 /**< Configure 2.2 kOhm pull-up resistance. */
#define I2C_PULLUP_3_3kOhm 0x08 /**< Configure 3.3 kOhm pull-up resistance. */
#define I2C_PULLUP_4kOhm   0x09 /**< Configure 4.0 kOhm pull-up resistance. */
#define I2C_PULLUP_4_7kOhm 0x0A /**< Configure 4.7 kOhm pull-up resistance. */
#define I2C_PULLUP_10kOhm  0x0B /**< Configure 10 kOhm pull-up resistance. */
#define I2C_PULLUP_DISABLE 0x0C /**< Disable internal pull-up resistors. */
/** @} */

/**********************************************************************************************
 * I3C Definitions
 **********************************************************************************************/

#define I3C_BROADCAST_ADDRESS 0x7E /**< Hex.: 0x7E, Dec.: 126. The I3C Broadcast Address is a reserved address used for specific control and management \
                                    * operations on the I3C bus, */

/**
 * @enum I3cPushPullRate
 * @brief This enum represents the available Push-Pull transfer rates and duty cycles for I3C SDR communication.
 * @ingroup Constants_I3C
 */
typedef enum {
  PUSH_PULL_2_5_MHz_DC_10,      /**< 2.5 MHz with 10% duty cycle */
  PUSH_PULL_2_5_MHz_DC_15,      /**< 2.5 MHz with 15% duty cycle */
  PUSH_PULL_2_5_MHz_DC_20,      /**< 2.5 MHz with 20% duty cycle */
  PUSH_PULL_2_5_MHz_DC_25,      /**< 2.5 MHz with 25% duty cycle */
  PUSH_PULL_3_125_MHz_DC_12_5,  /**< 3.125 MHz with 12.5% duty cycle */
  PUSH_PULL_3_125_MHz_DC_18_75, /**< 3.125 MHz with 18.75% duty cycle */
  PUSH_PULL_3_125_MHz_DC_25,    /**< 3.125 MHz with 25% duty cycle */
  PUSH_PULL_3_125_MHz_DC_31_25, /**< 3.125 MHz with 31.25% duty cycle */
  PUSH_PULL_5_MHz_DC_20,        /**< 5 MHz with 20% duty cycle */
  PUSH_PULL_5_MHz_DC_30,        /**< 5 MHz with 30% duty cycle */
  PUSH_PULL_5_MHz_DC_40,        /**< 5 MHz with 40% duty cycle */
  PUSH_PULL_5_MHz_DC_50,        /**< 5 MHz with 50% duty cycle */
  PUSH_PULL_6_25_MHz_DC_25,     /**< 6.25 MHz with 25% duty cycle */
  PUSH_PULL_6_25_MHz_DC_37_5,   /**< 6.25 MHz with 37.5% duty cycle */
  PUSH_PULL_6_25_MHz_DC_50,     /**< 6.25 MHz with 50% duty cycle */
  PUSH_PULL_7_5_MHz_DC_30,      /**< 7.5 MHz with 30% duty cycle */
  PUSH_PULL_7_5_MHz_DC_45,      /**< 7.5 MHz with 45% duty cycle */
  PUSH_PULL_10_MHz_DC_40,       /**< 10 MHz with 40% duty cycle */
  PUSH_PULL_12_5_MHz_DC_50      /**< 12.5 MHz with 50% duty cycle */
} I3cPushPullRate;

/**
 * @enum I3cOpenDrainTransferRate
 * @brief This enum represents the available Open-Drain transfer rates for I3C communication.
 * @ingroup Constants_I3C
 */
typedef enum {
  OPEN_DRAIN_100_KHz, /**< 100 kHz open-drain transfer rate */
  OPEN_DRAIN_400_KHz, /**< 400 kHz open-drain transfer rate */
  OPEN_DRAIN_1_MHz,   /**< 1 MHz open-drain transfer rate */
  OPEN_DRAIN_2_MHz,   /**< 2 MHz open-drain transfer rate */
  OPEN_DRAIN_4_17_MHz /**< 4.17 MHz open-drain transfer rate */
} I3cOpenDrainTransferRate;

/**
 * @enum I2cTransferRate
 * @brief This enum represents the available legacy I2C transfer modes.
 * @ingroup Constants_I3C
 */
typedef enum {
  STANDARD_MODE,   /**< Standard mode (100 kHz) */
  FAST_MODE,       /**< Fast mode (400 kHz) */
  FAST_MODE_PLUS,  /**< Fast mode Plus (1 MHz) */
  HIGH_SPEED_MODE, /**< High-speed mode (3.4 MHz) */
  ULTRA_FAST_MODE  /**< Ultra-fast mode (5 MHz) */
} I2cTransferRate;

/**
 * @enum I3cDriveStrength
 * @brief This enum represents the drive strength configuration for the I3C bus.
 * @ingroup Constants_I3C
 */
typedef enum {
  STANDARD, /**< Standard drive strength (default configuration) */
  FAST      /**< Increased drive strength for higher speed or heavier bus loads */
} I3cDriveStrength;

/**
 * @union I3cTargetConfiguration
 * @brief Represents configurable behavior and capabilities of an I3C target device.
 * @ingroup Structures_I3C
 *
 * @details
 * This union allows accessing the device configuration either as a raw byte
 * or as individual bit fields.
 *
 * Each bit enables or describes specific target capabilities or behavior
 * related to Dynamic Address Assignment (DAA), In-Band Interrupt (IBI),
 * and Controller Role (CR) support.
 */
typedef union {
  uint8_t byte; /**< Raw configuration byte representation */

  struct {
    uint8_t targetType : 1;         /**< 0 = I3C target, 1 = Legacy I2C target */
    bool IBIRequest : 1;            /**< Target supports generating In-Band Interrupt (IBI) */
    bool CRRequest : 1;             /**< Target supports Controller Role request. Reserved for future. */
    bool daaUseSETDASA : 1;         /**< Use SETDASA during Dynamic Address Assignment */
    bool daaUseSETAASA : 1;         /**< Use SETAASA during Dynamic Address Assignment */
    bool daaUseENTDAA : 1;          /**< Use ENTDAA during Dynamic Address Assignment */
    bool ibiTimestampEnable : 1;    /**< Enables timestamping for received IBIs. Reserved for future. */
    bool pendingReadCapability : 1; /**< Target supports pending read notification. Reserved for future. */
  } bits;                           /**< Bit-field representation of the target configuration byte. */

} I3cTargetConfiguration;

/**
 * @union I3cBCR
 * @brief Represents the I3C Bus Characteristics Register (BCR).
 * @ingroup Structures_I3C
 *
 * @details
 * The Bus Characteristics Register (BCR) defines the fundamental
 * protocol capabilities of an I3C target as specified by the
 * MIPI I3C specification.
 *
 * This union allows accessing the BCR either as a raw byte or
 * through individual capability fields.
 */
typedef union {
  uint8_t byte; /**< Raw BCR register value */

  struct {
    uint8_t maxDataSpeedLimit : 1;    /**< Indicates presence of maximum data speed limitation */
    uint8_t ibiRequestCapable : 1;    /**< Target is capable of issuing IBI */
    uint8_t ibiPayload : 1;           /**< Target supports IBI with payload */
    uint8_t offlineCapable : 1;       /**< Target supports offline mode */
    uint8_t virtualTargetSupport : 1; /**< Target supports Virtual Target feature */
    uint8_t advancedCapabilities : 1; /**< Target supports advanced capability extensions */
    uint8_t deviceRole : 2;           /**< Device role (Target / Secondary Controller / etc.) */
  } bits;                             /**< Bit-field representation of the BCR register value. */

} I3cBCR;

/**
 * @struct I3cTargetInfo
 * @brief Contains complete information about an I3C target device.
 * @ingroup Structures_I3C
 *
 * @details
 * This structure represents a target entry stored in the internal
 * device table after device discovery or Dynamic Address Assignment.
 *
 * It includes identification data, capability registers, protocol
 * limits, and runtime configuration.
 */
typedef struct {
  uint8_t staticAddress;                /**< Static address (if applicable). 0 if none. */
  uint8_t dynamicAddress;               /**< Assigned dynamic address on the I3C bus. */
  uint8_t pid[6];                       /**< 48-bit Provisional ID (PID), MSB first. */
  I3cBCR bcr;                           /**< Bus Characteristics Register. */
  uint8_t dcr;                          /**< Device Characteristics Register. */
  uint16_t mwl;                         /**< Maximum Write Length supported by the target. Reserved for future use. */
  uint16_t mrl;                         /**< Maximum Read Length supported by the target. Reserved for future use. */
  uint8_t maxIbiPayloadLength;          /**< Maximum payload length for IBI. Reserved for future use. */
  I3cTargetConfiguration configuration; /**< Current configuration flags. */
} I3cTargetInfo;

/**
 * @enum I3cTransferMode
 * @brief This enum represents the supported I3C transfer modes.
 * @ingroup Constants_I3C
 */
typedef enum {
  SDR,     /**< Standard Data Rate mode (default I3C mode) */
  HDR_DDR, /**< High Data Rate Double Data Rate mode */
  I2C      /**< Legacy I2C-compatible mode */
} I3cTransferMode;

/**
 * @enum I3cTransferDirection
 * @brief This enum represents the transfer direction.
 * @ingroup Constants_I3C
 */
typedef enum {
  WRITE, /**< Write transfer (controller to target) */
  READ   /**< Read transfer (target to controller) */
} I3cTransferDirection;

/**
 * @enum I3cTransferFlags
 * @brief This enum represents optional flags that modify the behavior of an I3C transfer.
 * @ingroup Constants_I3C
 */
typedef enum {
  I3C_XFER_NONE          = 0,       /**< Standard transfer: START + Target Address + ... + STOP */
  I3C_XFER_NONSTOP       = 1u << 0, /**< No STOP condition is emitted at the end of the transfer */
  I3C_XFER_START_WITH_7E = 1u << 1  /**< Transfer starts with broadcast address 0x7E before addressing the target */
} I3cTransferFlags;

/**
 * @enum I3cTargetResetDefByte
 * @brief This enum represents the defining byte values for the RSTACT CCC.
 * @ingroup Constants_I3C
 */
typedef enum {
  NO_RESET                         = 0x00, /**< No reset action */
  RESET_I3C_PERIPHERAL             = 0x01, /**< Reset only the I3C peripheral logic */
  RESET_WHOLE_TARGET               = 0x02, /**< Reset the entire target device */
  RESET_DEBUG_NETWORK              = 0x03, /**< Reset the debug network */
  VIRTUAL_TARGET_DETECT            = 0x04, /**< Trigger virtual target detection */
  RETURN_TIME_RESET_PERIPHERAL     = 0x81, /**< Return reset time for I3C peripheral reset */
  RETURN_TIME_RESET_WHOLE_TARGET   = 0x82, /**< Return reset time for full target reset */
  RETURN_TIME_DEBUG_NETWORK_RESET  = 0x83, /**< Return reset time for debug network reset */
  RETURN_VIRTUAL_TARGET_INDICATION = 0x84  /**< Return virtual target indication */
} I3cTargetResetDefByte;

/**
 * @enum I3CEvent
 * @brief This enum represents the Target Event bits used with the methods for the ENEC and DISEC CCCs.
 * @ingroup Constants_I3C
 */
typedef enum {
  IBI = 0x01, /**< In-Band Interrupt */
  CR  = 0x02, /**< Controller Role Request */
  HJ  = 0x08  /**< Hot-Join Request */
} I3CEvent;

/**
 * @enum I3cCccType
 * @brief This enum represents the type of CCC based on the presence of a defining byte.
 * @ingroup Constants_I3C
 */
typedef enum {
  CCC_WITHOUT_DEFINING_BYTE, /**< CCC without defining byte */
  CCC_WITH_DEFINING_BYTE     /**< CCC including a defining byte */
} I3cCccType;

/**
 * @enum I3cPattern
 * @brief This enum represents the supported I3C bus patterns.
 * @ingroup Constants_I3C
 */
typedef enum {
  I3C_TARGET_RESET_PATTERN, /**< Target Reset Pattern */
  I3C_HDR_EXIT_PATTERN      /**< HDR Exit Pattern */
} I3cPattern;

/**
 * @enum CCC
 * @brief Common Command Codes (CCC) defined by the MIPI I3C v1.2 specification.
 *
 * @details
 * This table includes Broadcast CCCs (B_*, 0x00-0x7F) and Direct CCCs
 * (D_*, 0x80-0xFF). For paired commands, the Direct opcode is typically the
 * Broadcast opcode + 0x80.
 * @ingroup Constants_I3C
 */
typedef enum {
  B_ENEC      = 0x00, /**< Broadcast ENEC: Enable events on all targets. */
  B_DISEC     = 0x01, /**< Broadcast DISEC: Disable events on all targets. */
  B_ENTAS0    = 0x02, /**< Broadcast ENTAS0: Enter Activity State 0. */
  B_ENTAS1    = 0x03, /**< Broadcast ENTAS1: Enter Activity State 1. */
  B_ENTAS2    = 0x04, /**< Broadcast ENTAS2: Enter Activity State 2. */
  B_ENTAS3    = 0x05, /**< Broadcast ENTAS3: Enter Activity State 3. */
  B_RSTDAA    = 0x06, /**< Broadcast RSTDAA: Reset dynamic addresses. */
  B_ENTDAA    = 0x07, /**< Broadcast ENTDAA: Enter Dynamic Address Assignment. */
  B_DEFTGTS   = 0x08, /**< Broadcast DEFTGTS: Define list of targets. */
  B_SETMWL    = 0x09, /**< Broadcast SETMWL: Set Maximum Write Length. */
  B_SETMRL    = 0x0A, /**< Broadcast SETMRL: Set Maximum Read Length. */
  B_ENTTM     = 0x0B, /**< Broadcast ENTTM: Enter test mode. */
  B_SETBUSCON = 0x0C, /**< Broadcast SETBUSCON: Set bus context. */
  MIPI_RS_0D  = 0x0D, /**< 0x0D – 0x11 - MIPI Reserved */
  MIPI_RS_0E  = 0x0E,
  MIPI_RS_0F  = 0x0F,
  MIPI_RS_10  = 0x10,
  MIPI_RS_11  = 0x11,
  B_ENDXFER   = 0x12, /**< Broadcast ENDXFER: End an ongoing transfer. */
  MIPI_RS_13  = 0x13, /**< 0x13 – 0x1E - MIPI Reserved */
  MIPI_RS_14  = 0x14,
  MIPI_RS_15  = 0x15,
  MIPI_RS_16  = 0x16,
  MIPI_RS_17  = 0x17,
  MIPI_RS_18  = 0x18,
  MIPI_RS_19  = 0x19,
  MIPI_RS_1A  = 0x1A,
  MIPI_RS_1B  = 0x1B,
  MIPI_RS_1C  = 0x1C,
  MIPI_RS_1D  = 0x1D,
  MIPI_RS_1E  = 0x1E,
  RES_1F      = 0x1F, /**< 0x1F Reserved */
  B_ENTHDR0   = 0x20, /**< Broadcast ENTHDR0: Enter HDR mode 0. */
  B_ENTHDR1   = 0x21, /**< Broadcast ENTHDR1: Enter HDR mode 1. */
  B_ENTHDR2   = 0x22, /**< Broadcast ENTHDR2: Enter HDR mode 2. */
  B_ENTHDR3   = 0x23, /**< Broadcast ENTHDR3: Enter HDR mode 3. */
  B_ENTHDR4   = 0x24, /**< Broadcast ENTHDR4: Enter HDR mode 4. */
  B_ENTHDR5   = 0x25, /**< Broadcast ENTHDR5: Enter HDR mode 5. */
  B_ENTHDR6   = 0x26, /**< Broadcast ENTHDR6: Enter HDR mode 6. */
  B_ENTHDR7   = 0x27, /**< Broadcast ENTHDR7: Enter HDR mode 7. */
  B_SETXTIME  = 0x28, /**< Broadcast SETXTIME: Set exchange timing information. */
  B_SETAASA   = 0x29, /**< Broadcast SETAASA: Assign dynamic addresses from static addresses. */
  B_RSTACT    = 0x2A, /**< Broadcast RSTACT: Configure target reset action. */
  B_DEFGRPA   = 0x2B, /**< Broadcast DEFGRPA: Define group address assignments. */
  B_RSTGRPA   = 0x2C, /**< Broadcast RSTGRPA: Reset group address assignments. */
  B_MLANE     = 0x2D, /**< Broadcast MLANE: Configure multi-lane operation. */
  MIPI_WG_2E  = 0x2E, /**< 0x2E – 0x48 - MIPI I3C WG Reserved */
  MIPI_WG_2F  = 0x2F,
  MIPI_WG_30  = 0x30,
  MIPI_WG_31  = 0x31,
  MIPI_WG_32  = 0x32,
  MIPI_WG_33  = 0x33,
  MIPI_WG_34  = 0x34,
  MIPI_WG_35  = 0x35,
  MIPI_WG_36  = 0x36,
  MIPI_WG_37  = 0x37,
  MIPI_WG_38  = 0x38,
  MIPI_WG_39  = 0x39,
  MIPI_WG_3A  = 0x3A,
  MIPI_WG_3B  = 0x3B,
  MIPI_WG_3C  = 0x3C,
  MIPI_WG_3D  = 0x3D,
  MIPI_WG_3E  = 0x3E,
  MIPI_WG_3F  = 0x3F,
  MIPI_WG_40  = 0x40,
  MIPI_WG_41  = 0x41,
  MIPI_WG_42  = 0x42,
  MIPI_WG_43  = 0x43,
  MIPI_WG_44  = 0x44,
  MIPI_WG_45  = 0x45,
  MIPI_WG_46  = 0x46,
  MIPI_WG_47  = 0x47,
  MIPI_WG_48  = 0x48,
  MIPI_CAM_49 = 0x49, /**< 0x49 – 0x4C - MIPI Camera WG Reserved – Broadcast CCCs */
  MIPI_CAM_4A = 0x4A,
  MIPI_CAM_4B = 0x4B,
  MIPI_CAM_4C = 0x4C,
  MIPI_RS_4D  = 0x4D, /**< 0x4D – 0x57 - MIPI Reserved – Broadcast CCCs */
  MIPI_RS_4E  = 0x4E,
  MIPI_RS_4F  = 0x4F,
  MIPI_RS_50  = 0x50,
  MIPI_RS_51  = 0x51,
  MIPI_RS_52  = 0x52,
  MIPI_RS_53  = 0x53,
  MIPI_RS_54  = 0x54,
  MIPI_RS_55  = 0x55,
  MIPI_RS_56  = 0x56,
  MIPI_RS_57  = 0x57,
  MIPI_DWG_58 = 0x58, /**< 0x58 – 0x5B - MIPI Debug WG Reserved – Broadcast CCCs */
  MIPI_DWG_59 = 0x59,
  MIPI_DWG_5A = 0x5A,
  MIPI_DWG_5B = 0x5B,
  MIPIRIOWG5C = 0x5C, /**< 0x5C – 0x60 - MIPI RIO WG Reserved – Broadcast CCCs */
  MIPIRIOWG5D = 0x5D,
  MIPIRIOWG5E = 0x5E,
  MIPIRIOWG5F = 0x5F,
  MIPIRIOWG60 = 0x60,
  B_VENCCC_61 = 0x61, /**< 0x61 – 0x7F - Vendor / Standards Extension – Broadcast CCCs */
  B_VENCCC_62 = 0x62,
  B_VENCCC_63 = 0x63,
  B_VENCCC_64 = 0x64,
  B_VENCCC_65 = 0x65,
  B_VENCCC_66 = 0x66,
  B_VENCCC_67 = 0x67,
  B_VENCCC_68 = 0x68,
  B_VENCCC_69 = 0x69,
  B_VENCCC_6A = 0x6A,
  B_VENCCC_6B = 0x6B,
  B_VENCCC_6C = 0x6C,
  B_VENCCC_6D = 0x6D,
  B_VENCCC_6E = 0x6E,
  B_VENCCC_6F = 0x6F,
  B_VENCCC_70 = 0x70,
  B_VENCCC_71 = 0x71,
  B_VENCCC_72 = 0x72,
  B_VENCCC_73 = 0x73,
  B_VENCCC_74 = 0x74,
  B_VENCCC_75 = 0x75,
  B_VENCCC_76 = 0x76,
  B_VENCCC_77 = 0x77,
  B_VENCCC_78 = 0x78,
  B_VENCCC_79 = 0x79,
  B_VENCCC_7A = 0x7A,
  B_VENCCC_7B = 0x7B,
  B_VENCCC_7C = 0x7C,
  B_VENCCC_7D = 0x7D,
  B_VENCCC_7E = 0x7E,
  B_VENCCC_7F = 0x7F,
  D_ENEC      = 0x80, /**< Direct ENEC: Enable events on a specific target. */
  D_DISEC     = 0x81, /**< Direct DISEC: Disable events on a specific target. */
  D_ENTAS0    = 0x82, /**< Direct ENTAS0: Enter Activity State 0. */
  D_ENTAS1    = 0x83, /**< Direct ENTAS1: Enter Activity State 1. */
  D_ENTAS2    = 0x84, /**< Direct ENTAS2: Enter Activity State 2. */
  D_ENTAS3    = 0x85, /**< Direct ENTAS3: Enter Activity State 3. */
  D_RSTDAA    = 0x86, /**< 0x86 - DEPRECATED: RSTDAA Direct. Reset Dynamic Address Assignment */
  D_SETDASA   = 0x87, /**< Direct SETDASA: Set dynamic address from static address. */
  D_SETNEWDA  = 0x88, /**< Direct SETNEWDA: Set a new dynamic address. */
  D_SETMWL    = 0x89, /**< Direct SETMWL: Set Maximum Write Length. */
  D_SETMRL    = 0x8A, /**< Direct SETMRL: Set Maximum Read Length. */
  D_GETMWL    = 0x8B, /**< Direct GETMWL: Get Maximum Write Length. */
  D_GETMRL    = 0x8C, /**< Direct GETMRL: Get Maximum Read Length. */
  D_GETPID    = 0x8D, /**< Direct GETPID: Get Provisioned ID. */
  D_GETBCR    = 0x8E, /**< Direct GETBCR: Get Bus Characteristics Register. */
  D_GETDCR    = 0x8F, /**< Direct GETDCR: Get Device Characteristics Register. */
  D_GETSTATUS = 0x90, /**< Direct GETSTATUS: Get target status. */
  D_GETACCCR  = 0x91, /**< Direct GETACCCR: Get Accept Controller Role. */
  D_ENDXFER   = 0x92, /**< Direct ENDXFER: End an ongoing transfer. */
  D_SETBRGTGT = 0x93, /**< Direct SETBRGTGT: Set bridge target parameters. */
  D_GETMXDS   = 0x94, /**< Direct GETMXDS: Get maximum data speed settings. */
  D_GETCAPS   = 0x95, /**< Direct GETCAPS: Get optional feature capabilities. */
  D_SETROUTE  = 0x96, /**< Direct SETROUTE: Configure routing information. */
  D_D2DXFER   = 0x97, /**< Direct D2DXFER: Device-to-device tunneling control (not in I3C Basic). */
  D_SETXTIME  = 0x98, /**< Direct SETXTIME: Set exchange timing information. */
  D_GETXTIME  = 0x99, /**< Direct GETXTIME: Get exchange timing information. */
  D_RSTACT    = 0x9A, /**< Direct RSTACT: Configure target reset action. */
  D_SETGRPA   = 0x9B, /**< Direct SETGRPA: Set target group address assignment. */
  D_RSTGRPA   = 0x9C, /**< Direct RSTGRPA: Reset target group address assignment. */
  D_MLANE     = 0x9D, /**< Direct MLANE: Configure multi-lane operation. */
  MIPI_WG_9E  = 0x9E, /**< 0x9E – 0xBF - MIPI I3C WG Reserved – Direct CCCs */
  MIPI_WG_9F  = 0x9F,
  MIPI_WG_A0  = 0xA0,
  MIPI_WG_A1  = 0xA1,
  MIPI_WG_A2  = 0xA2,
  MIPI_WG_A3  = 0xA3,
  MIPI_WG_A4  = 0xA4,
  MIPI_WG_A5  = 0xA5,
  MIPI_WG_A6  = 0xA6,
  MIPI_WG_A7  = 0xA7,
  MIPI_WG_A8  = 0xA8,
  MIPI_WG_A9  = 0xA9,
  MIPI_WG_AA  = 0xAA,
  MIPI_WG_AB  = 0xAB,
  MIPI_WG_AC  = 0xAC,
  MIPI_WG_AD  = 0xAD,
  MIPI_WG_AE  = 0xAE,
  MIPI_WG_AF  = 0xAF,
  MIPI_WG_B0  = 0xB0,
  MIPI_WG_B1  = 0xB1,
  MIPI_WG_B2  = 0xB2,
  MIPI_WG_B3  = 0xB3,
  MIPI_WG_B4  = 0xB4,
  MIPI_WG_B5  = 0xB5,
  MIPI_WG_B6  = 0xB6,
  MIPI_WG_B7  = 0xB7,
  MIPI_WG_B8  = 0xB8,
  MIPI_WG_B9  = 0xB9,
  MIPI_WG_BA  = 0xBA,
  MIPI_WG_BB  = 0xBB,
  MIPI_WG_BC  = 0xBC,
  MIPI_WG_BD  = 0xBD,
  MIPI_WG_BE  = 0xBE,
  MIPI_WG_BF  = 0xBF,
  MIPI_CAM_C0 = 0xC0, /**< 0xC0 – 0xC3 - MIPI Camera WG Reserved – Direct CCCs */
  MIPI_CAM_C1 = 0xC1,
  MIPI_CAM_C2 = 0xC2,
  MIPI_CAM_C3 = 0xC3,
  MIPI_RS_C4  = 0xC4, /**< 0xC4 – 0xD6 - MIPI Reserved – Direct CCCs */
  MIPI_RS_C5  = 0xC5,
  MIPI_RS_C6  = 0xC6,
  MIPI_RS_C7  = 0xC7,
  MIPI_RS_C8  = 0xC8,
  MIPI_RS_C9  = 0xC9,
  MIPI_RS_CA  = 0xCA,
  MIPI_RS_CB  = 0xCB,
  MIPI_RS_CC  = 0xCC,
  MIPI_RS_CD  = 0xCD,
  MIPI_RS_CE  = 0xCE,
  MIPI_RS_CF  = 0xCF,
  MIPI_RS_D0  = 0xD0,
  MIPI_RS_D1  = 0xD1,
  MIPI_RS_D2  = 0xD2,
  MIPI_RS_D3  = 0xD3,
  MIPI_RS_D4  = 0xD4,
  MIPI_RS_D5  = 0xD5,
  MIPI_RS_D6  = 0xD6,
  MIPI_DWG_D7 = 0xD7, /**< 0xD7 – 0xDA - MIPI Debug WG Reserved – Direct CCCs */
  MIPI_DWG_D8 = 0xD8,
  MIPI_DWG_D9 = 0xD9,
  MIPI_DWG_DA = 0xDA,
  MIPIRIOWGDB = 0xDB, /**< 0xDB – 0xDF - MIPI RIO WG Reserved – Direct CCCs */
  MIPIRIOWGDC = 0xDC,
  MIPIRIOWGDD = 0xDD,
  MIPIRIOWGDE = 0xDE,
  MIPIRIOWGDF = 0xDF,
  D_VENCCC_E0 = 0xE0, /**< 0xE0 – 0xFE - Vendor / Standards Extension – Direct CCCs */
  D_VENCCC_E1 = 0xE1,
  D_VENCCC_E2 = 0xE2,
  D_VENCCC_E3 = 0xE3,
  D_VENCCC_E4 = 0xE4,
  D_VENCCC_E5 = 0xE5,
  D_VENCCC_E6 = 0xE6,
  D_VENCCC_E7 = 0xE7,
  D_VENCCC_E8 = 0xE8,
  D_VENCCC_E9 = 0xE9,
  D_VENCCC_EA = 0xEA,
  D_VENCCC_EB = 0xEB,
  D_VENCCC_EC = 0xEC,
  D_VENCCC_ED = 0xED,
  D_VENCCC_EE = 0xEE,
  D_VENCCC_EF = 0xEF,
  D_VENCCC_F0 = 0xF0,
  D_VENCCC_F1 = 0xF1,
  D_VENCCC_F2 = 0xF2,
  D_VENCCC_F3 = 0xF3,
  D_VENCCC_F4 = 0xF4,
  D_VENCCC_F5 = 0xF5,
  D_VENCCC_F6 = 0xF6,
  D_VENCCC_F7 = 0xF7,
  D_VENCCC_F8 = 0xF8,
  D_VENCCC_F9 = 0xF9,
  D_VENCCC_FA = 0xFA,
  D_VENCCC_FB = 0xFB,
  D_VENCCC_FC = 0xFC,
  D_VENCCC_FD = 0xFD,
  D_VENCCC_FE = 0xFE,
  MIPI_WG_FF  = 0xFF /**< 0xFF - MIPI I3C WG Reserved */
} CCC;

/**********************************************************************************************
 * UART Definitions
 **********************************************************************************************/

/**
 * @enum UartBaudRate
 * @brief This enum represents the UART baudrate options.
 * @ingroup Constants_UART
 */
typedef enum {
  UART_BAUD_600    = 0x00, /**< 600 bps */
  UART_BAUD_1200   = 0x01, /**< 1200 bps */
  UART_BAUD_2400   = 0x02, /**< 2400 bps */
  UART_BAUD_4800   = 0x03, /**< 4800 bps */
  UART_BAUD_9600   = 0x04, /**< 9600 bps */
  UART_BAUD_14400  = 0x05, /**< 14400 bps */
  UART_BAUD_19200  = 0x06, /**< 19200 bps */
  UART_BAUD_38400  = 0x07, /**< 38400 bps */
  UART_BAUD_56000  = 0x08, /**< 56000 bps */
  UART_BAUD_57600  = 0x09, /**< 57600 bps */
  UART_BAUD_115200 = 0x0A  /**< 115200 bps */
} UartBaudRate;

/**
 * @enum UartParity
 * @brief This enum represents the UART parity options.
 * @ingroup Constants_UART
 */
typedef enum {
  UART_PARITY_NONE = 0x00, /**< No parity */
  UART_PARITY_EVEN = 0x01, /**< Even parity */
  UART_PARITY_ODD  = 0x02  /**< Odd parity */
} UartParity;

/**
 * @enum UartDataSize
 * @brief This enum represents the UART data character size options.
 * @ingroup Constants_UART
 */
typedef enum {
  UART_DATA_SIZE_7 = 0x00, /**< 7-bit data size */
  UART_DATA_SIZE_8 = 0x01  /**< 8-bit data size */
} UartDataSize;

/**
 * @enum UartStopBit
 * @brief This enum represents the UART stop bit options.
 * @ingroup Constants_UART
 */
typedef enum {
  UART_STOP_BIT_1 = 0x00, /**< 1 stop bit */
  UART_STOP_BIT_2 = 0x01  /**< 2 stop bits */
} UartStopBit;

/**
 * @enum UartHwHandshake
 * @brief This enum represents the UART hardware handshake (RTS/CTS) configuration.
 * @ingroup Constants_UART
 */
typedef enum {
  UART_HW_HANDSHAKE_DIS = 0x00, /**< Disable UART hardware handshake RTS/CTS. */
  UART_HW_HANDSHAKE_EN  = 0x01  /**< Enable UART hardware handshake RTS/CTS. */
} UartHwHandshake;

/**********************************************************************************************
 * GPIO Definitions
 **********************************************************************************************/

/**
 * @enum GpioPinNumber
 * @brief GPIO pin identifiers available on the host adapter.
 * @ingroup Constants_GPIO
 */
typedef enum {
  GPIO_1 = 0x00, /**< GPIO pin 1 */
  GPIO_2 = 0x01, /**< GPIO pin 2 */
  GPIO_3 = 0x02, /**< GPIO pin 3 */
  GPIO_4 = 0x03, /**< GPIO pin 4 */
  GPIO_5 = 0x04, /**< GPIO pin 5 */
  GPIO_6 = 0x05  /**< GPIO pin 6 */
} GpioPinNumber;

/**
 * @enum GpioLogicLevel
 * @brief Digital logic levels used for GPIO input/output operations.
 * @ingroup Constants_GPIO
 */
typedef enum {
  GPIO_LOW  = 0x00, /**< Logic low level (0) */
  GPIO_HIGH = 0x01  /**< Logic high level (1) */
} GpioLogicLevel;

/**
 * @enum GpioFunctionality
 * @brief GPIO operating modes supported by the host adapter.
 * @ingroup Constants_GPIO
 */
typedef enum {
  GPIO_DIGITAL_INPUT  = 0x00, /**< Configure pin as digital input */
  GPIO_DIGITAL_OUTPUT = 0x01  /**< Configure pin as digital output */
} GpioFunctionality;

/**
 * @enum GpioTriggerType
 * @brief Trigger modes for GPIO interrupt generation.
 * @ingroup Constants_GPIO
 */
typedef enum {
  GPIO_TRIGGER_RISING_EDGE  = 0x01, /**< Interrupt on rising edge */
  GPIO_TRIGGER_FALLING_EDGE = 0x02, /**< Interrupt on falling edge */
  GPIO_TRIGGER_BOTH_EDGES   = 0x03  /**< Interrupt on both edges */
} GpioTriggerType;

/**********************************************************************************************
 * SPI Definitions
 **********************************************************************************************/

/**
 * @enum SpiBitOrder
 * @brief This enum represents the SPI bit transmission order.
 * @ingroup Constants_SPI
 */
typedef enum {
  SPI_BIT_ORDER_MSB = 0x00, /**< Most Significant Bit first */
  SPI_BIT_ORDER_LSB = 0x01  /**< Least Significant Bit first */
} SpiBitOrder;

/**
 * @enum SpiMode
 * @brief This enum represents the SPI clock polarity and phase modes.
 * @ingroup Constants_SPI
 */
typedef enum {
  SPI_MODE_0 = 0x00, /**< CPOL = 0, CPHA = 0 */
  SPI_MODE_1 = 0x01, /**< CPOL = 0, CPHA = 1 */
  SPI_MODE_2 = 0x02, /**< CPOL = 1, CPHA = 0 */
  SPI_MODE_3 = 0x03  /**< CPOL = 1, CPHA = 1 */
} SpiMode;

/**
 * @enum SpiDataWidth
 * @brief This enum represents the SPI data word size.
 * @ingroup Constants_SPI
 */
typedef enum {
  SPI_DATA_WIDTH_8_BITS  = 0x00, /**< 8-bit data width */
  SPI_DATA_WIDTH_16_BITS = 0x01  /**< 16-bit data width */
} SpiDataWidth;

/**
 * @enum SpiChipSelect
 * @brief This enum represents the available SPI chip select lines.
 * @ingroup Constants_SPI
 */
typedef enum {
  SPI_CHIP_SELECT_0 = 0x00, /**< Chip select line 0 */
  SPI_CHIP_SELECT_1 = 0x01, /**< Chip select line 1 */
  SPI_CHIP_SELECT_2 = 0x02, /**< Chip select line 2 */
  SPI_CHIP_SELECT_3 = 0x03  /**< Chip select line 3 */
} SpiChipSelect;

/**
 * @enum SpiChipSelectPolarity
 * @brief This enum represents the SPI chip select active polarity.
 * @ingroup Constants_SPI
 */
typedef enum {
  SPI_CS_ACTIVE_LOW  = 0x00, /**< Chip select is active low */
  SPI_CS_ACTIVE_HIGH = 0x01  /**< Chip select is active high */
} SpiChipSelectPolarity;

#ifdef __cplusplus
}
#endif
