/* * Copyright 2022 Intel Corporation * Copyright 2023 Meta Platforms, Inc. and its affiliates * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ #define ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ /** * @brief I3C Common Command Codes * @defgroup i3c_ccc I3C Common Command Codes * @ingroup i3c_interface * @{ */ #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** Maximum CCC ID for broadcast */ #define I3C_CCC_BROADCAST_MAX_ID 0x7FU /** * Enable Events Command * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENEC(broadcast) ((broadcast) ? 0x00U : 0x80U) /** * Disable Events Command * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_DISEC(broadcast) ((broadcast) ? 0x01U : 0x81U) /** * Enter Activity State * * @param as Desired activity state * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENTAS(as, broadcast) (((broadcast) ? 0x02U : 0x82U) + (as)) /** * Enter Activity State 0 * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENTAS0(broadcast) I3C_CCC_ENTAS(0, broadcast) /** * Enter Activity State 1 * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENTAS1(broadcast) I3C_CCC_ENTAS(1, broadcast) /** * Enter Activity State 2 * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENTAS2(broadcast) I3C_CCC_ENTAS(2, broadcast) /** * Enter Activity State 3 * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENTAS3(broadcast) I3C_CCC_ENTAS(3, broadcast) /** Reset Dynamic Address Assignment (Broadcast) */ #define I3C_CCC_RSTDAA 0x06U /** Enter Dynamic Address Assignment (Broadcast) */ #define I3C_CCC_ENTDAA 0x07U /** Define List of Targets (Broadcast) */ #define I3C_CCC_DEFTGTS 0x08U /** * Set Max Write Length (Broadcast or Direct) * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_SETMWL(broadcast) ((broadcast) ? 0x09U : 0x89U) /** * Set Max Read Length (Broadcast or Direct) * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_SETMRL(broadcast) ((broadcast) ? 0x0AU : 0x8AU) /** Enter Test Mode (Broadcast) */ #define I3C_CCC_ENTTM 0x0BU /** Set Bus Context (Broadcast) */ #define I3C_CCC_SETBUSCON 0x0CU /** * Data Transfer Ending Procedure Control * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_ENDXFER(broadcast) ((broadcast) ? 0x12U : 0x92U) /** Enter HDR Mode (HDR-DDR) (Broadcast) */ #define I3C_CCC_ENTHDR(x) (0x20U + (x)) /** Enter HDR Mode 0 (HDR-DDR) (Broadcast) */ #define I3C_CCC_ENTHDR0 0x20U /** Enter HDR Mode 1 (HDR-TSP) (Broadcast) */ #define I3C_CCC_ENTHDR1 0x21U /** Enter HDR Mode 2 (HDR-TSL) (Broadcast) */ #define I3C_CCC_ENTHDR2 0x22U /** Enter HDR Mode 3 (HDR-BT) (Broadcast) */ #define I3C_CCC_ENTHDR3 0x23U /** Enter HDR Mode 4 (Broadcast) */ #define I3C_CCC_ENTHDR4 0x24U /** Enter HDR Mode 5 (Broadcast) */ #define I3C_CCC_ENTHDR5 0x25U /** Enter HDR Mode 6 (Broadcast) */ #define I3C_CCC_ENTHDR6 0x26U /** Enter HDR Mode 7 (Broadcast) */ #define I3C_CCC_ENTHDR7 0x27U /** * Exchange Timing Information (Broadcast or Direct) * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_SETXTIME(broadcast) ((broadcast) ? 0x28U : 0x98U) /** Set All Addresses to Static Addresses (Broadcast) */ #define I3C_CCC_SETAASA 0x29U /** * Target Reset Action * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_RSTACT(broadcast) ((broadcast) ? 0x2AU : 0x9AU) /** Define List of Group Address (Broadcast) */ #define I3C_CCC_DEFGRPA 0x2BU /** * Reset Group Address * * @param broadcast True if broadcast, false if direct. */ #define I3C_CCC_RSTGRPA(broadcast) ((broadcast) ? 0x2CU : 0x9CU) /** Multi-Lane Data Transfer Control (Broadcast) */ #define I3C_CCC_MLANE(broadcast) ((broadcast) ? 0x2DU : 0x9DU) /** * Vendor/Standard Extension * * @param broadcast True if broadcast, false if direct. * @param id Extension ID. */ #define I3C_CCC_VENDOR(broadcast, id) ((id) + ((broadcast) ? 0x61U : 0xE0U)) /** Set Dynamic Address from Static Address (Direct) */ #define I3C_CCC_SETDASA 0x87U /** Set New Dynamic Address (Direct) */ #define I3C_CCC_SETNEWDA 0x88U /** Get Max Write Length (Direct) */ #define I3C_CCC_GETMWL 0x8BU /** Get Max Read Length (Direct) */ #define I3C_CCC_GETMRL 0x8CU /** Get Provisioned ID (Direct) */ #define I3C_CCC_GETPID 0x8DU /** Get Bus Characteristics Register (Direct) */ #define I3C_CCC_GETBCR 0x8EU /** Get Device Characteristics Register (Direct) */ #define I3C_CCC_GETDCR 0x8FU /** Get Device Status (Direct) */ #define I3C_CCC_GETSTATUS 0x90U /** Get Accept Controller Role (Direct) */ #define I3C_CCC_GETACCCR 0x91U /** Set Bridge Targets (Direct) */ #define I3C_CCC_SETBRGTGT 0x93U /** Get Max Data Speed (Direct) */ #define I3C_CCC_GETMXDS 0x94U /** Get Optional Feature Capabilities (Direct) */ #define I3C_CCC_GETCAPS 0x95U /** Set Route (Direct) */ #define I3C_CCC_SETROUTE 0x96U /** Device to Device(s) Tunneling Control (Direct) */ #define I3C_CCC_D2DXFER 0x97U /** Get Exchange Timing Information (Direct) */ #define I3C_CCC_GETXTIME 0x99U /** Set Group Address (Direct) */ #define I3C_CCC_SETGRPA 0x9BU struct i3c_device_desc; /** * @brief Payload structure for Direct CCC to one target. */ struct i3c_ccc_target_payload { /** Target address */ uint8_t addr; /** @c 0 for Write, @c 1 for Read */ uint8_t rnw:1; /** * - For Write CCC, pointer to the byte array of data * to be sent, which may contain the Sub-Command Byte * and additional data. * - For Read CCC, pointer to the byte buffer for data * to be read into. */ uint8_t *data; /** Length in bytes for @p data. */ size_t data_len; /** * Total number of bytes transferred * * A Target can issue an EoD or the Controller can abort a transfer * before the length of the buffer. It is expected for the driver to * write to this after the transfer. */ size_t num_xfer; }; /** * @brief Payload structure for one CCC transaction. */ struct i3c_ccc_payload { struct { /** * The CCC ID (@c I3C_CCC_*). */ uint8_t id; /** * Pointer to byte array of data for this CCC. * * This is the bytes following the CCC command in CCC frame. * Set to @c NULL if no associated data. */ uint8_t *data; /** Length in bytes for optional data array. */ size_t data_len; /** * Total number of bytes transferred * * A Controller can abort a transfer before the length of the buffer. * It is expected for the driver to write to this after the transfer. */ size_t num_xfer; } ccc; struct { /** * Array of struct i3c_ccc_target_payload. * * Each element describes the target and associated * payloads for this CCC. * * Use with Direct CCC. */ struct i3c_ccc_target_payload *payloads; /** Number of targets */ size_t num_targets; } targets; }; /** * @brief Payload for ENEC/DISEC CCC (Target Events Command). */ struct i3c_ccc_events { /** * Event byte: * - Bit[0]: ENINT/DISINT: * - Target Interrupt Requests * - Bit[1]: ENCR/DISCR: * - Controller Role Requests * - Bit[3]: ENHJ/DISHJ: * - Hot-Join Event */ uint8_t events; } __packed; /** Enable Events (ENEC) - Target Interrupt Requests. */ #define I3C_CCC_ENEC_EVT_ENINTR BIT(0) /** Enable Events (ENEC) - Controller Role Requests. */ #define I3C_CCC_ENEC_EVT_ENCR BIT(1) /** Enable Events (ENEC) - Hot-Join Event. */ #define I3C_CCC_ENEC_EVT_ENHJ BIT(3) #define I3C_CCC_ENEC_EVT_ALL \ (I3C_CCC_ENEC_EVT_ENINTR | I3C_CCC_ENEC_EVT_ENCR | I3C_CCC_ENEC_EVT_ENHJ) /** Disable Events (DISEC) - Target Interrupt Requests. */ #define I3C_CCC_DISEC_EVT_DISINTR BIT(0) /** Disable Events (DISEC) - Controller Role Requests. */ #define I3C_CCC_DISEC_EVT_DISCR BIT(1) /** Disable Events (DISEC) - Hot-Join Event. */ #define I3C_CCC_DISEC_EVT_DISHJ BIT(3) #define I3C_CCC_DISEC_EVT_ALL \ (I3C_CCC_DISEC_EVT_DISINTR | I3C_CCC_DISEC_EVT_DISCR | I3C_CCC_DISEC_EVT_DISHJ) /* * Events for both enabling and disabling since * they have the same bits. */ /** Events - Target Interrupt Requests. */ #define I3C_CCC_EVT_INTR BIT(0) /** Events - Controller Role Requests. */ #define I3C_CCC_EVT_CR BIT(1) /** Events - Hot-Join Event. */ #define I3C_CCC_EVT_HJ BIT(3) /** Bitmask for all events. */ #define I3C_CCC_EVT_ALL \ (I3C_CCC_EVT_INTR | I3C_CCC_EVT_CR | I3C_CCC_EVT_HJ) /** * @brief Payload for SETMWL/GETMWL CCC (Set/Get Maximum Write Length). * * @note For drivers and help functions, the raw data coming * back from target device is in big endian. This needs to be * translated back to CPU endianness before passing back to * function caller. */ struct i3c_ccc_mwl { /** Maximum Write Length */ uint16_t len; } __packed; /** * @brief Payload for SETMRL/GETMRL CCC (Set/Get Maximum Read Length). * * @note For drivers and help functions, the raw data coming * back from target device is in big endian. This needs to be * translated back to CPU endianness before passing back to * function caller. */ struct i3c_ccc_mrl { /** Maximum Read Length */ uint16_t len; /** Optional IBI Payload Size */ uint8_t ibi_len; } __packed; /** * @brief The active controller part of payload for DEFTGTS CCC. * * This is used by DEFTGTS (Define List of Targets) CCC to describe * the active controller on the I3C bus. */ struct i3c_ccc_deftgts_active_controller { /** Dynamic Address of Active Controller */ uint8_t addr; /** Device Characteristic Register of Active Controller */ uint8_t dcr; /** Bus Characteristic Register of Active Controller */ uint8_t bcr; /** Static Address of Active Controller */ uint8_t static_addr; }; /** * @brief The target device part of payload for DEFTGTS CCC. * * This is used by DEFTGTS (Define List of Targets) CCC to describe * the existing target devices on the I3C bus. */ struct i3c_ccc_deftgts_target { /** Dynamic Address of a target device, or a group address */ uint8_t addr; union { /** * Device Characteristic Register of a I3C target device * or a group. */ uint8_t dcr; /** Legacy Virtual Register for legacy I2C device. */ uint8_t lvr; }; /** Bus Characteristic Register of a target device or a group */ uint8_t bcr; /** Static Address of a target device or a group */ uint8_t static_addr; }; /** * @brief Payload for DEFTGTS CCC (Define List of Targets). * * @note @p i3c_ccc_deftgts_target is an array of targets, where * the number of elements is dependent on the number of I3C targets * on the bus. Please have enough space for both read and write of * this CCC. */ struct i3c_ccc_deftgts { /** Data describing the active controller */ struct i3c_ccc_deftgts_active_controller active_controller; /** Data describing the target(s) on the bus */ struct i3c_ccc_deftgts_target targets[]; } __packed; /** * @brief Payload for a single device address. * * This is used for: * - SETDASA (Set Dynamic Address from Static Address) * - SETNEWDA (Set New Dynamic Address) * - SETGRPA (Set Group Address) * - GETACCCR (Get Accept Controller Role) * * Note that the target address is encoded within * struct i3c_ccc_target_payload instead of being encoded in * this payload. */ struct i3c_ccc_address { /** * - For SETDASA, Static Address to be assigned as * Dynamic Address. * - For SETNEWDA, new Dynamic Address to be assigned. * - For SETGRPA, new Group Address to be set. * - For GETACCCR, the correct address of Secondary * Controller. * * @note For SETDATA, SETNEWDA and SETGRAP, * the address is left-shift by 1, and bit[0] is always 0. * * @note Fpr SET GETACCCR, the address is left-shift by 1, * and bit[0] is the calculated odd parity bit. */ uint8_t addr; } __packed; /** * @brief Payload for GETPID CCC (Get Provisioned ID). */ struct i3c_ccc_getpid { /** * 48-bit Provisioned ID. * * @note Data is big-endian where first byte is MSB. */ uint8_t pid[6]; } __packed; /** * @brief Payload for GETBCR CCC (Get Bus Characteristics Register). */ struct i3c_ccc_getbcr { /** Bus Characteristics Register */ uint8_t bcr; } __packed; /** * @brief Payload for GETDCR CCC (Get Device Characteristics Register). */ struct i3c_ccc_getdcr { /** Device Characteristics Register */ uint8_t dcr; } __packed; /** * @brief Indicate which format of GETSTATUS to use. */ enum i3c_ccc_getstatus_fmt { /** GETSTATUS Format 1 */ GETSTATUS_FORMAT_1, /** GETSTATUS Format 2 */ GETSTATUS_FORMAT_2, }; /** * @brief Defining byte values for GETSTATUS Format 2. */ enum i3c_ccc_getstatus_defbyte { /** Target status. */ GETSTATUS_FORMAT_2_TGTSTAT = 0x00U, /** PRECR - Alternate status format describing Controller-capable device. */ GETSTATUS_FORMAT_2_PRECR = 0x91U, /** Invalid defining byte. */ GETSTATUS_FORMAT_2_INVALID = 0x100U }; /** * @brief Payload for GETSTATUS CCC (Get Device Status). */ union i3c_ccc_getstatus { struct { /** * Device Status * - Bit[15:8]: Reserved. * - Bit[7:6]: Activity Mode. * - Bit[5]: Protocol Error. * - Bit[4]: Reserved. * - Bit[3:0]: Number of Pending Interrupts. * * @note For drivers and help functions, the raw data coming * back from target device is in big endian. This needs to be * translated back to CPU endianness before passing back to * function caller. */ uint16_t status; } fmt1; union { /** * Defining Byte 0x00: TGTSTAT * * @see i3c_ccc_getstatus::fmt1::status */ uint16_t tgtstat; /** * Defining Byte 0x91: PRECR * - Bit[15:8]: Vendor Reserved * - Bit[7:2]: Reserved * - Bit[1]: Handoff Delay NACK * - Bit[0]: Deep Sleep Detected * * @note For drivers and help functions, the raw data coming * back from target device is in big endian. This needs to be * translated back to CPU endianness before passing back to * function caller. */ uint16_t precr; uint16_t raw_u16; } fmt2; } __packed; /** GETSTATUS Format 1 - Protocol Error bit. */ #define I3C_CCC_GETSTATUS_PROTOCOL_ERR BIT(5) /** GETSTATUS Format 1 - Activity Mode bit shift value. */ #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT 6 /** GETSTATUS Format 1 - Activity Mode bitmask. */ #define I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK \ (0x03U << I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT) /** * @brief GETSTATUS Format 1 - Activity Mode * * Obtain Activity Mode from GETSTATUS Format 1 value obtained via * GETSTATUS. * * @param status GETSTATUS Format 1 value */ #define I3C_CCC_GETSTATUS_ACTIVITY_MODE(status) \ (((status) & I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK) \ >> I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT) /** GETSTATUS Format 1 - Number of Pending Interrupts bit shift value. */ #define I3C_CCC_GETSTATUS_NUM_INT_SHIFT 0 /** GETSTATUS Format 1 - Number of Pending Interrupts bitmask. */ #define I3C_CCC_GETSTATUS_NUM_INT_MASK \ (0x0FU << I3C_CCC_GETSTATUS_NUM_INT_SHIFT) /** * @brief GETSTATUS Format 1 - Number of Pending Interrupts * * Obtain Number of Pending Interrupts from GETSTATUS Format 1 value * obtained via GETSTATUS. * * @param status GETSTATUS Format 1 value */ #define I3C_CCC_GETSTATUS_NUM_INT(status) \ (((status) & I3C_CCC_GETSTATUS_NUM_INT_MASK) \ >> I3C_CCC_GETSTATUS_NUM_INT_SHIFT) /** GETSTATUS Format 2 - PERCR - Deep Sleep Detected bit. */ #define I3C_CCC_GETSTATUS_PRECR_DEEP_SLEEP_DETECTED BIT(0) /** GETSTATUS Format 2 - PERCR - Handoff Delay NACK. */ #define I3C_CCC_GETSTATUS_PRECR_HANDOFF_DELAY_NACK BIT(1) /** * @brief One Bridged Target for SETBRGTGT payload. */ struct i3c_ccc_setbrgtgt_tgt { /** * Dynamic address of the bridged target. * * @note The address is left-shift by 1, and bit[0] * is always 0. */ uint8_t addr; /** * 16-bit ID for the bridged target. * * @note For drivers and help functions, the raw data coming * back from target device is in big endian. This needs to be * translated back to CPU endianness before passing back to * function caller. */ uint16_t id; } __packed; /** * @brief Payload for SETBRGTGT CCC (Set Bridge Targets). * * Note that the bridge target address is encoded within * struct i3c_ccc_target_payload instead of being encoded in * this payload. */ struct i3c_ccc_setbrgtgt { /** Number of bridged targets */ uint8_t count; /** Array of bridged targets */ struct i3c_ccc_setbrgtgt_tgt targets[]; } __packed; /** * @brief Payload for GETMXDS CCC (Get Max Data Speed). * * @note This is only for GETMXDS Format 1 and Format 2. */ union i3c_ccc_getmxds { struct { /** maxWr */ uint8_t maxwr; /** maxRd */ uint8_t maxrd; } fmt1; struct { /** maxWr */ uint8_t maxwr; /** maxRd */ uint8_t maxrd; /** * Maximum Read Turnaround Time in microsecond. * * This is in little-endian where first byte is LSB. */ uint8_t maxrdturn[3]; } fmt2; struct { /** * Defining Byte 0x00: WRRDTURN * * @see i3c_ccc_getmxds::fmt2 */ uint8_t wrrdturn; /** * Defining Byte 0x91: CRHDLY * - Bit[2]: Set Bus Actibity State * - Bit[1:0]: Controller Handoff Activity State */ uint8_t crhdly1; } fmt3; } __packed; /** Get Max Data Speed (GETMXDS) - Default Max Sustained Data Rate. */ #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_MAX 0 /** Get Max Data Speed (GETMXDS) - 8MHz Max Sustained Data Rate. */ #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_8MHZ 1 /** Get Max Data Speed (GETMXDS) - 6MHz Max Sustained Data Rate. */ #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_6MHZ 2 /** Get Max Data Speed (GETMXDS) - 4MHz Max Sustained Data Rate. */ #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_4MHZ 3 /** Get Max Data Speed (GETMXDS) - 2MHz Max Sustained Data Rate. */ #define I3C_CCC_GETMXDS_MAX_SDR_FSCL_2MHZ 4 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 8ns. */ #define I3C_CCC_GETMXDS_TSCO_8NS 0 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 9ns. */ #define I3C_CCC_GETMXDS_TSCO_9NS 1 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 10ns. */ #define I3C_CCC_GETMXDS_TSCO_10NS 2 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 11ns. */ #define I3C_CCC_GETMXDS_TSCO_11NS 3 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround <= 12ns. */ #define I3C_CCC_GETMXDS_TSCO_12NS 4 /** Get Max Data Speed (GETMXDS) - Clock to Data Turnaround > 12ns. */ #define I3C_CCC_GETMXDS_TSCO_GT_12NS 7 /** Get Max Data Speed (GETMXDS) - maxWr - Optional Defining Byte Support. */ #define I3C_CCC_GETMXDS_MAXWR_DEFINING_BYTE_SUPPORT BIT(3) /** Get Max Data Speed (GETMXDS) - Max Sustained Data Rate bit shift value. */ #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_SHIFT 0 /** Get Max Data Speed (GETMXDS) - Max Sustained Data Rate bitmask. */ #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK \ (0x07U << I3C_CCC_GET_MXDS_MAXWR_MAX_SDR_FSCL_SHIFT) /** * @brief Get Max Data Speed (GETMXDS) - maxWr - Max Sustained Data Rate * * Obtain Max Sustained Data Rate value from GETMXDS maxWr value * obtained via GETMXDS. * * @param maxwr GETMXDS maxWr value. */ #define I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL(maxwr) \ (((maxwr) & \ I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK) \ >> I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_SHIFT) /** Get Max Data Speed (GETMXDS) - maxRd - Write-to-Read Permits Stop Between. */ #define I3C_CCC_GETMXDS_MAXRD_W2R_PERMITS_STOP_BETWEEN BIT(6) /** Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround bit shift value. */ #define I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT 3 /** Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround bitmask. */ #define I3C_CCC_GETMXDS_MAXRD_TSCO_MASK \ (0x07U << I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT) /** * @brief Get Max Data Speed (GETMXDS) - maxRd - Clock to Data Turnaround * * Obtain Clock to Data Turnaround value from GETMXDS maxRd value * obtained via GETMXDS. * * @param maxrd GETMXDS maxRd value. */ #define I3C_CCC_GETMXDS_MAXRD_TSCO(maxrd) \ (((maxrd) & I3C_CCC_GETMXDS_MAXRD_TSCO_MASK) \ >> I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT) /** Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate bit shift value. */ #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_SHIFT 0 /** Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate bitmask. */ #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK \ (0x07U << I3C_CCC_GET_MXDS_MAXRD_MAX_SDR_FSCL_SHIFT) /** * @brief Get Max Data Speed (GETMXDS) - maxRd - Max Sustained Data Rate * * Obtain Max Sustained Data Rate value from GETMXDS maxRd value * obtained via GETMXDS. * * @param maxrd GETMXDS maxRd value. */ #define I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL(maxrd) \ (((maxrd) & \ I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK) \ >> I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_SHIFT) /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Set Bus Activity State bit shift value. */ #define I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE BIT(2) /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State bit shift value. */ #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_SHIFT 0 /** Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State bitmask. */ #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK \ (0x03U << I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_SHIFT) /** * @brief Get Max Data Speed (GETMXDS) - CRDHLY1 - Controller Handoff Activity State * * Obtain Controller Handoff Activity State value from GETMXDS value * obtained via GETMXDS. * * @param crhdly1 GETMXDS value. */ #define I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE(crhdly1) \ (((crhdly1) & \ I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_MASK) \ >> I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE_SHIFT) /** * @brief Payload for GETCAPS CCC (Get Optional Feature Capabilities). * * @note Only support GETCAPS Format 1. */ struct i3c_ccc_getcaps { /** * GETCAP[1-4] bytes. */ uint8_t getcaps[4]; } __packed; /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR-DDR mode bit. */ #define I3C_CCC_GETCAPS1_HDR_DDR BIT(0) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR-BT mode bit. */ #define I3C_CCC_GETCAPS1_HDR_BT BIT(3) /** * @brief Get Optional Feature Capabilities (GETCAPS) - HDR Mode * * Get the bit corresponding to HDR mode. * * @param x HDR mode */ #define I3C_CCC_GETCAPS1_HDR_MODE(x) BIT(x) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 0. */ #define I3C_CCC_GETCAPS1_HDR_MODE0 BIT(0) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 1. */ #define I3C_CCC_GETCAPS1_HDR_MODE1 BIT(1) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 2. */ #define I3C_CCC_GETCAPS1_HDR_MODE2 BIT(2) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 3. */ #define I3C_CCC_GETCAPS1_HDR_MODE3 BIT(3) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 4. */ #define I3C_CCC_GETCAPS1_HDR_MODE4 BIT(4) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 5. */ #define I3C_CCC_GETCAPS1_HDR_MODE5 BIT(5) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 6. */ #define I3C_CCC_GETCAPS1_HDR_MODE6 BIT(6) /** Get Optional Feature Capabilities (GETCAPS) Format 1 - HDR Mode 7. */ #define I3C_CCC_GETCAPS1_HDR_MODE7 BIT(7) /** Get Optional Feature Capabilities (GETCAPS) Format 2 - HDR-DDR Write Abort bit. */ #define I3C_CCC_GETCAPS2_HDRDDR_WRITE_ABORT BIT(6) /** Get Optional Feature Capabilities (GETCAPS) Format 2 - HDR-DDR Abort CRC bit. */ #define I3C_CCC_GETCAPS2_HDRDDR_ABORT_CRC BIT(7) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - * Group Address Capabilities bit shift value. */ #define I3C_CCC_GETCAPS2_GRPADDR_CAP_SHIFT 4 /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - * Group Address Capabilities bitmask. */ #define I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK \ (0x03U << I3C_CCC_GETCAPS2_GRPADDR_CAP_SHIFT) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - Group Address Capabilities. * * Obtain Group Address Capabilities value from GETCAPS Format 2 value * obtained via GETCAPS. * * @param getcaps2 GETCAPS2 value. */ #define I3C_CCC_GETCAPS2_GRPADDR_CAP(getcaps2) \ (((getcaps2) & \ I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK) \ >> I3C_CCC_GETCAPS_GRPADDR_CAP_SHIFT) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - * I3C 1.x Specification Version bit shift value. */ #define I3C_CCC_GETCAPS2_SPEC_VER_SHIFT 0 /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - * I3C 1.x Specification Version bitmask. */ #define I3C_CCC_GETCAPS2_SPEC_VER_MASK \ (0x0FU << I3C_CCC_GETCAPS2_SPEC_VER_SHIFT) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 2 - * I3C 1.x Specification Version. * * Obtain I3C 1.x Specification Version value from GETCAPS Format 2 value * obtained via GETCAPS. * * @param getcaps2 GETCAPS2 value. */ #define I3C_CCC_GETCAPS2_SPEC_VER(getcaps2) \ (((getcaps2) & \ I3C_CCC_GETCAPS2_SPEC_VER_MASK) \ >> I3C_CCC_GETCAPS_SPEC_VER_SHIFT) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * Multi-Lane Data Transfer Support bit. */ #define I3C_CCC_GETCAPS3_MLANE_SUPPORT BIT(0) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * Device to Device Transfer (D2DXFER) Support bit. */ #define I3C_CCC_GETCAPS3_D2DXFER_SUPPORT BIT(1) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * Device to Device Transfer (D2DXFER) IBI Capable bit. */ #define I3C_CCC_GETCAPS3_D2DXFER_IBI_CAPABLE BIT(2) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * Defining Byte Support in GETCAPS bit. */ #define I3C_CCC_GETCAPS3_GETCAPS_DEFINING_BYTE_SUPPORT BIT(3) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * Defining Byte Support in GETSTATUS bit. */ #define I3C_CCC_GETCAPS3_GETSTATUS_DEFINING_BYTE_SUPPORT BIT(4) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * HDR-BT CRC-32 Support bit. */ #define I3C_CCC_GETCAPS3_HDRBT_CRC32_SUPPORT BIT(5) /** * @brief Get Optional Feature Capabilities (GETCAPS) Format 3 - * IBI MDB Support for Pending Read Notification bit. */ #define I3C_CCC_GETCAPS3_IBI_MDR_PENDING_READ_NOTIFICATION BIT(6) /** * @brief Enum for I3C Reset Action (RSTACT) Defining Byte Values. */ enum i3c_ccc_rstact_defining_byte { /** No Reset on Target Reset Pattern. */ I3C_CCC_RSTACT_NO_RESET = 0x00U, /** Reset the I3C Peripheral Only. */ I3C_CCC_RSTACT_PERIPHERAL_ONLY = 0x01U, /** Reset the Whole Target. */ I3C_CCC_RSTACT_RESET_WHOLE_TARGET = 0x02U, /** Debug Network Adapter Reset. */ I3C_CCC_RSTACT_DEBUG_NETWORK_ADAPTER = 0x03U, /** Virtual Target Detect. */ I3C_CCC_RSTACT_VIRTUAL_TARGET_DETECT = 0x04U, }; /** * @brief Test if I3C CCC payload is for broadcast. * * This tests if the CCC payload is for broadcast. * * @param[in] payload Pointer to the CCC payload. * * @retval true if payload target is broadcast * @retval false if payload target is direct */ static inline bool i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload *payload) { return (payload->ccc.id <= I3C_CCC_BROADCAST_MAX_ID); } /** * @brief Get BCR from a target * * Helper function to get BCR (Bus Characteristic Register) from * target device. * * @param[in] target Pointer to the target device descriptor. * @param[out] bcr Pointer to the BCR payload structure. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getbcr(struct i3c_device_desc *target, struct i3c_ccc_getbcr *bcr); /** * @brief Get DCR from a target * * Helper function to get DCR (Device Characteristic Register) from * target device. * * @param[in] target Pointer to the target device descriptor. * @param[out] dcr Pointer to the DCR payload structure. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getdcr(struct i3c_device_desc *target, struct i3c_ccc_getdcr *dcr); /** * @brief Get PID from a target * * Helper function to get PID (Provisioned ID) from * target device. * * @param[in] target Pointer to the target device descriptor. * @param[out] pid Pointer to the PID payload structure. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getpid(struct i3c_device_desc *target, struct i3c_ccc_getpid *pid); /** * @brief Broadcast RSTACT to reset I3C Peripheral. * * Helper function to broadcast Target Reset Action (RSTACT) to * all connected targets to Reset the I3C Peripheral Only (0x01). * * @param[in] controller Pointer to the controller device driver instance. * @param[in] action What reset action to perform. * * @return @see i3c_do_ccc */ int i3c_ccc_do_rstact_all(const struct device *controller, enum i3c_ccc_rstact_defining_byte action); /** * @brief Broadcast RSTDAA to reset dynamic addresses for all targets. * * Helper function to reset dynamic addresses of all connected targets. * * @param[in] controller Pointer to the controller device driver instance. * * @return @see i3c_do_ccc */ int i3c_ccc_do_rstdaa_all(const struct device *controller); /** * @brief Set Dynamic Address from Static Address for a target * * Helper function to do SETDASA (Set Dynamic Address from Static Address) * for a particular target. * * Note this does not update @p target with the new dynamic address. * * @param[in] target Pointer to the target device descriptor where * the device is configured with a static address. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setdasa(const struct i3c_device_desc *target); /** * @brief Set New Dynamic Address for a target * * Helper function to do SETNEWDA(Set New Dynamic Address) for a particular target. * * Note this does not update @p target with the new dynamic address. * * @param[in] target Pointer to the target device descriptor where * the device is configured with a static address. * @param[in] new_da Pointer to the new_da struct. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setnewda(const struct i3c_device_desc *target, struct i3c_ccc_address new_da); /** * @brief Broadcast ENEC/DISEC to enable/disable target events. * * Helper function to broadcast Target Events Command to enable or * disable target events (ENEC/DISEC). * * @param[in] controller Pointer to the controller device driver instance. * @param[in] enable ENEC if true, DISEC if false. * @param[in] events Pointer to the event struct. * * @return @see i3c_do_ccc */ int i3c_ccc_do_events_all_set(const struct device *controller, bool enable, struct i3c_ccc_events *events); /** * @brief Direct CCC ENEC/DISEC to enable/disable target events. * * Helper function to send Target Events Command to enable or * disable target events (ENEC/DISEC) on a single target. * * @param[in] target Pointer to the target device descriptor. * @param[in] enable ENEC if true, DISEC if false. * @param[in] events Pointer to the event struct. * * @return @see i3c_do_ccc */ int i3c_ccc_do_events_set(struct i3c_device_desc *target, bool enable, struct i3c_ccc_events *events); /** * @brief Broadcast SETMWL to Set Maximum Write Length. * * Helper function to do SETMWL (Set Maximum Write Length) to * all connected targets. * * @param[in] controller Pointer to the controller device driver instance. * @param[in] mwl Pointer to SETMWL payload. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setmwl_all(const struct device *controller, const struct i3c_ccc_mwl *mwl); /** * @brief Single target SETMWL to Set Maximum Write Length. * * Helper function to do SETMWL (Set Maximum Write Length) to * one target. * * @param[in] target Pointer to the target device descriptor. * @param[in] mwl Pointer to SETMWL payload. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setmwl(const struct i3c_device_desc *target, const struct i3c_ccc_mwl *mwl); /** * @brief Single target GETMWL to Get Maximum Write Length. * * Helper function to do GETMWL (Get Maximum Write Length) of * one target. * * @param[in] target Pointer to the target device descriptor. * @param[out] mwl Pointer to GETMWL payload. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getmwl(const struct i3c_device_desc *target, struct i3c_ccc_mwl *mwl); /** * @brief Broadcast SETMRL to Set Maximum Read Length. * * Helper function to do SETMRL (Set Maximum Read Length) to * all connected targets. * * @param[in] controller Pointer to the controller device driver instance. * @param[in] mrl Pointer to SETMRL payload. * @param[in] has_ibi_size True if also sending the optional IBI payload * size. False if not sending. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setmrl_all(const struct device *controller, const struct i3c_ccc_mrl *mrl, bool has_ibi_size); /** * @brief Single target SETMRL to Set Maximum Read Length. * * Helper function to do SETMRL (Set Maximum Read Length) to * one target. * * Note this uses the BCR of the target to determine whether * to send the optional IBI payload size. * * @param[in] target Pointer to the target device descriptor. * @param[in] mrl Pointer to SETMRL payload. * * @return @see i3c_do_ccc */ int i3c_ccc_do_setmrl(const struct i3c_device_desc *target, const struct i3c_ccc_mrl *mrl); /** * @brief Single target GETMRL to Get Maximum Read Length. * * Helper function to do GETMRL (Get Maximum Read Length) of * one target. * * Note this uses the BCR of the target to determine whether * to send the optional IBI payload size. * * @param[in] target Pointer to the target device descriptor. * @param[out] mrl Pointer to GETMRL payload. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getmrl(const struct i3c_device_desc *target, struct i3c_ccc_mrl *mrl); /** * @brief Single target GETSTATUS to Get Target Status. * * Helper function to do GETSTATUS (Get Target Status) of * one target. * * Note this uses the BCR of the target to determine whether * to send the optional IBI payload size. * * @param[in] target Pointer to the target device descriptor. * @param[out] status Pointer to GETSTATUS payload. * @param[in] fmt Which GETSTATUS to use. * @param[in] defbyte Defining Byte if using format 2. * * @return @see i3c_do_ccc */ int i3c_ccc_do_getstatus(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status, enum i3c_ccc_getstatus_fmt fmt, enum i3c_ccc_getstatus_defbyte defbyte); /** * @brief Single target GETSTATUS to Get Target Status (Format 1). * * Helper function to do GETSTATUS (Get Target Status, format 1) of * one target. * * @param[in] target Pointer to the target device descriptor. * @param[out] status Pointer to GETSTATUS payload. * * @return @see i3c_do_ccc */ static inline int i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status) { return i3c_ccc_do_getstatus(target, status, GETSTATUS_FORMAT_1, GETSTATUS_FORMAT_2_INVALID); } /** * @brief Single target GETSTATUS to Get Target Status (Format 2). * * Helper function to do GETSTATUS (Get Target Status, format 2) of * one target. * * @param[in] target Pointer to the target device descriptor. * @param[out] status Pointer to GETSTATUS payload. * @param[in] defbyte Defining Byte for GETSTATUS format 2. * * @return @see i3c_do_ccc */ static inline int i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status, enum i3c_ccc_getstatus_defbyte defbyte) { return i3c_ccc_do_getstatus(target, status, GETSTATUS_FORMAT_2, defbyte); } #ifdef __cplusplus } #endif /** * @} */ #endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_CCC_H_ */