linux/i3c/ccc.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Copyright (C) 2018 Cadence Design Systems Inc.
0004  *
0005  * Author: Boris Brezillon <boris.brezillon@bootlin.com>
0006  */
0007
0008 #ifndef I3C_CCC_H
0009 #define I3C_CCC_H
0010
0011 #include <linux/bitops.h>
0012 #include <linux/i3c/device.h>
0013
0014 /* I3C CCC (Common Command Codes) related definitions */
0015 #define I3C_CCC_DIRECT          BIT(7)
0016
0017 #define I3C_CCC_ID(id, broadcast)   \
0018     ((id) | ((broadcast) ? 0 : I3C_CCC_DIRECT))
0019
0020 /* Commands valid in both broadcast and unicast modes */
0021 #define I3C_CCC_ENEC(broadcast)     I3C_CCC_ID(0x0, broadcast)
0022 #define I3C_CCC_DISEC(broadcast)    I3C_CCC_ID(0x1, broadcast)
0023 #define I3C_CCC_ENTAS(as, broadcast)    I3C_CCC_ID(0x2 + (as), broadcast)
0024 #define I3C_CCC_RSTDAA(broadcast)   I3C_CCC_ID(0x6, broadcast)
0025 #define I3C_CCC_SETMWL(broadcast)   I3C_CCC_ID(0x9, broadcast)
0026 #define I3C_CCC_SETMRL(broadcast)   I3C_CCC_ID(0xa, broadcast)
0027 #define I3C_CCC_SETXTIME(broadcast) ((broadcast) ? 0x28 : 0x98)
0028 #define I3C_CCC_VENDOR(id, broadcast)   ((id) + ((broadcast) ? 0x61 : 0xe0))
0029
0030 /* Broadcast-only commands */
0031 #define I3C_CCC_ENTDAA          I3C_CCC_ID(0x7, true)
0032 #define I3C_CCC_DEFSLVS         I3C_CCC_ID(0x8, true)
0033 #define I3C_CCC_ENTTM           I3C_CCC_ID(0xb, true)
0034 #define I3C_CCC_ENTHDR(x)       I3C_CCC_ID(0x20 + (x), true)
0035
0036 /* Unicast-only commands */
0037 #define I3C_CCC_SETDASA         I3C_CCC_ID(0x7, false)
0038 #define I3C_CCC_SETNEWDA        I3C_CCC_ID(0x8, false)
0039 #define I3C_CCC_GETMWL          I3C_CCC_ID(0xb, false)
0040 #define I3C_CCC_GETMRL          I3C_CCC_ID(0xc, false)
0041 #define I3C_CCC_GETPID          I3C_CCC_ID(0xd, false)
0042 #define I3C_CCC_GETBCR          I3C_CCC_ID(0xe, false)
0043 #define I3C_CCC_GETDCR          I3C_CCC_ID(0xf, false)
0044 #define I3C_CCC_GETSTATUS       I3C_CCC_ID(0x10, false)
0045 #define I3C_CCC_GETACCMST       I3C_CCC_ID(0x11, false)
0046 #define I3C_CCC_SETBRGTGT       I3C_CCC_ID(0x13, false)
0047 #define I3C_CCC_GETMXDS         I3C_CCC_ID(0x14, false)
0048 #define I3C_CCC_GETHDRCAP       I3C_CCC_ID(0x15, false)
0049 #define I3C_CCC_GETXTIME        I3C_CCC_ID(0x19, false)
0050
0051 #define I3C_CCC_EVENT_SIR       BIT(0)
0052 #define I3C_CCC_EVENT_MR        BIT(1)
0053 #define I3C_CCC_EVENT_HJ        BIT(3)
0054
0055 /**
0056  * struct i3c_ccc_events - payload passed to ENEC/DISEC CCC
0057  *
0058  * @events: bitmask of I3C_CCC_EVENT_xxx events.
0059  *
0060  * Depending on the CCC command, the specific events coming from all devices
0061  * (broadcast version) or a specific device (unicast version) will be
0062  * enabled (ENEC) or disabled (DISEC).
0063  */
0064 struct i3c_ccc_events {
0065     u8 events;
0066 };
0067
0068 /**
0069  * struct i3c_ccc_mwl - payload passed to SETMWL/GETMWL CCC
0070  *
0071  * @len: maximum write length in bytes
0072  *
0073  * The maximum write length is only applicable to SDR private messages or
0074  * extended Write CCCs (like SETXTIME).
0075  */
0076 struct i3c_ccc_mwl {
0077     __be16 len;
0078 };
0079
0080 /**
0081  * struct i3c_ccc_mrl - payload passed to SETMRL/GETMRL CCC
0082  *
0083  * @len: maximum read length in bytes
0084  * @ibi_len: maximum IBI payload length
0085  *
0086  * The maximum read length is only applicable to SDR private messages or
0087  * extended Read CCCs (like GETXTIME).
0088  * The IBI length is only valid if the I3C slave is IBI capable
0089  * (%I3C_BCR_IBI_REQ_CAP is set).
0090  */
0091 struct i3c_ccc_mrl {
0092     __be16 read_len;
0093     u8 ibi_len;
0094 } __packed;
0095
0096 /**
0097  * struct i3c_ccc_dev_desc - I3C/I2C device descriptor used for DEFSLVS
0098  *
0099  * @dyn_addr: dynamic address assigned to the I3C slave or 0 if the entry is
0100  *        describing an I2C slave.
0101  * @dcr: DCR value (not applicable to entries describing I2C devices)
0102  * @lvr: LVR value (not applicable to entries describing I3C devices)
0103  * @bcr: BCR value or 0 if this entry is describing an I2C slave
0104  * @static_addr: static address or 0 if the device does not have a static
0105  *       address
0106  *
0107  * The DEFSLVS command should be passed an array of i3c_ccc_dev_desc
0108  * descriptors (one entry per I3C/I2C dev controlled by the master).
0109  */
0110 struct i3c_ccc_dev_desc {
0111     u8 dyn_addr;
0112     union {
0113         u8 dcr;
0114         u8 lvr;
0115     };
0116     u8 bcr;
0117     u8 static_addr;
0118 };
0119
0120 /**
0121  * struct i3c_ccc_defslvs - payload passed to DEFSLVS CCC
0122  *
0123  * @count: number of dev descriptors
0124  * @master: descriptor describing the current master
0125  * @slaves: array of descriptors describing slaves controlled by the
0126  *      current master
0127  *
0128  * Information passed to the broadcast DEFSLVS to propagate device
0129  * information to all masters currently acting as slaves on the bus.
0130  * This is only meaningful if you have more than one master.
0131  */
0132 struct i3c_ccc_defslvs {
0133     u8 count;
0134     struct i3c_ccc_dev_desc master;
0135     struct i3c_ccc_dev_desc slaves[];
0136 } __packed;
0137
0138 /**
0139  * enum i3c_ccc_test_mode - enum listing all available test modes
0140  *
0141  * @I3C_CCC_EXIT_TEST_MODE: exit test mode
0142  * @I3C_CCC_VENDOR_TEST_MODE: enter vendor test mode
0143  */
0144 enum i3c_ccc_test_mode {
0145     I3C_CCC_EXIT_TEST_MODE,
0146     I3C_CCC_VENDOR_TEST_MODE,
0147 };
0148
0149 /**
0150  * struct i3c_ccc_enttm - payload passed to ENTTM CCC
0151  *
0152  * @mode: one of the &enum i3c_ccc_test_mode modes
0153  *
0154  * Information passed to the ENTTM CCC to instruct an I3C device to enter a
0155  * specific test mode.
0156  */
0157 struct i3c_ccc_enttm {
0158     u8 mode;
0159 };
0160
0161 /**
0162  * struct i3c_ccc_setda - payload passed to SETNEWDA and SETDASA CCCs
0163  *
0164  * @addr: dynamic address to assign to an I3C device
0165  *
0166  * Information passed to the SETNEWDA and SETDASA CCCs to assign/change the
0167  * dynamic address of an I3C device.
0168  */
0169 struct i3c_ccc_setda {
0170     u8 addr;
0171 };
0172
0173 /**
0174  * struct i3c_ccc_getpid - payload passed to GETPID CCC
0175  *
0176  * @pid: 48 bits PID in big endian
0177  */
0178 struct i3c_ccc_getpid {
0179     u8 pid[6];
0180 };
0181
0182 /**
0183  * struct i3c_ccc_getbcr - payload passed to GETBCR CCC
0184  *
0185  * @bcr: BCR (Bus Characteristic Register) value
0186  */
0187 struct i3c_ccc_getbcr {
0188     u8 bcr;
0189 };
0190
0191 /**
0192  * struct i3c_ccc_getdcr - payload passed to GETDCR CCC
0193  *
0194  * @dcr: DCR (Device Characteristic Register) value
0195  */
0196 struct i3c_ccc_getdcr {
0197     u8 dcr;
0198 };
0199
0200 #define I3C_CCC_STATUS_PENDING_INT(status)  ((status) & GENMASK(3, 0))
0201 #define I3C_CCC_STATUS_PROTOCOL_ERROR       BIT(5)
0202 #define I3C_CCC_STATUS_ACTIVITY_MODE(status)    \
0203     (((status) & GENMASK(7, 6)) >> 6)
0204
0205 /**
0206  * struct i3c_ccc_getstatus - payload passed to GETSTATUS CCC
0207  *
0208  * @status: status of the I3C slave (see I3C_CCC_STATUS_xxx macros for more
0209  *      information).
0210  */
0211 struct i3c_ccc_getstatus {
0212     __be16 status;
0213 };
0214
0215 /**
0216  * struct i3c_ccc_getaccmst - payload passed to GETACCMST CCC
0217  *
0218  * @newmaster: address of the master taking bus ownership
0219  */
0220 struct i3c_ccc_getaccmst {
0221     u8 newmaster;
0222 };
0223
0224 /**
0225  * struct i3c_ccc_bridged_slave_desc - bridged slave descriptor
0226  *
0227  * @addr: dynamic address of the bridged device
0228  * @id: ID of the slave device behind the bridge
0229  */
0230 struct i3c_ccc_bridged_slave_desc {
0231     u8 addr;
0232     __be16 id;
0233 } __packed;
0234
0235 /**
0236  * struct i3c_ccc_setbrgtgt - payload passed to SETBRGTGT CCC
0237  *
0238  * @count: number of bridged slaves
0239  * @bslaves: bridged slave descriptors
0240  */
0241 struct i3c_ccc_setbrgtgt {
0242     u8 count;
0243     struct i3c_ccc_bridged_slave_desc bslaves[];
0244 } __packed;
0245
0246 /**
0247  * enum i3c_sdr_max_data_rate - max data rate values for private SDR transfers
0248  */
0249 enum i3c_sdr_max_data_rate {
0250     I3C_SDR0_FSCL_MAX,
0251     I3C_SDR1_FSCL_8MHZ,
0252     I3C_SDR2_FSCL_6MHZ,
0253     I3C_SDR3_FSCL_4MHZ,
0254     I3C_SDR4_FSCL_2MHZ,
0255 };
0256
0257 /**
0258  * enum i3c_tsco - clock to data turn-around
0259  */
0260 enum i3c_tsco {
0261     I3C_TSCO_8NS,
0262     I3C_TSCO_9NS,
0263     I3C_TSCO_10NS,
0264     I3C_TSCO_11NS,
0265     I3C_TSCO_12NS,
0266 };
0267
0268 #define I3C_CCC_MAX_SDR_FSCL_MASK   GENMASK(2, 0)
0269 #define I3C_CCC_MAX_SDR_FSCL(x)     ((x) & I3C_CCC_MAX_SDR_FSCL_MASK)
0270
0271 /**
0272  * struct i3c_ccc_getmxds - payload passed to GETMXDS CCC
0273  *
0274  * @maxwr: write limitations
0275  * @maxrd: read limitations
0276  * @maxrdturn: maximum read turn-around expressed micro-seconds and
0277  *         little-endian formatted
0278  */
0279 struct i3c_ccc_getmxds {
0280     u8 maxwr;
0281     u8 maxrd;
0282     u8 maxrdturn[3];
0283 } __packed;
0284
0285 #define I3C_CCC_HDR_MODE(mode)      BIT(mode)
0286
0287 /**
0288  * struct i3c_ccc_gethdrcap - payload passed to GETHDRCAP CCC
0289  *
0290  * @modes: bitmap of supported HDR modes
0291  */
0292 struct i3c_ccc_gethdrcap {
0293     u8 modes;
0294 } __packed;
0295
0296 /**
0297  * enum i3c_ccc_setxtime_subcmd - SETXTIME sub-commands
0298  */
0299 enum i3c_ccc_setxtime_subcmd {
0300     I3C_CCC_SETXTIME_ST = 0x7f,
0301     I3C_CCC_SETXTIME_DT = 0xbf,
0302     I3C_CCC_SETXTIME_ENTER_ASYNC_MODE0 = 0xdf,
0303     I3C_CCC_SETXTIME_ENTER_ASYNC_MODE1 = 0xef,
0304     I3C_CCC_SETXTIME_ENTER_ASYNC_MODE2 = 0xf7,
0305     I3C_CCC_SETXTIME_ENTER_ASYNC_MODE3 = 0xfb,
0306     I3C_CCC_SETXTIME_ASYNC_TRIGGER = 0xfd,
0307     I3C_CCC_SETXTIME_TPH = 0x3f,
0308     I3C_CCC_SETXTIME_TU = 0x9f,
0309     I3C_CCC_SETXTIME_ODR = 0x8f,
0310 };
0311
0312 /**
0313  * struct i3c_ccc_setxtime - payload passed to SETXTIME CCC
0314  *
0315  * @subcmd: one of the sub-commands ddefined in &enum i3c_ccc_setxtime_subcmd
0316  * @data: sub-command payload. Amount of data is determined by
0317  *    &i3c_ccc_setxtime->subcmd
0318  */
0319 struct i3c_ccc_setxtime {
0320     u8 subcmd;
0321     u8 data[];
0322 } __packed;
0323
0324 #define I3C_CCC_GETXTIME_SYNC_MODE  BIT(0)
0325 #define I3C_CCC_GETXTIME_ASYNC_MODE(x)  BIT((x) + 1)
0326 #define I3C_CCC_GETXTIME_OVERFLOW   BIT(7)
0327
0328 /**
0329  * struct i3c_ccc_getxtime - payload retrieved from GETXTIME CCC
0330  *
0331  * @supported_modes: bitmap describing supported XTIME modes
0332  * @state: current status (enabled mode and overflow status)
0333  * @frequency: slave's internal oscillator frequency in 500KHz steps
0334  * @inaccuracy: slave's internal oscillator inaccuracy in 0.1% steps
0335  */
0336 struct i3c_ccc_getxtime {
0337     u8 supported_modes;
0338     u8 state;
0339     u8 frequency;
0340     u8 inaccuracy;
0341 } __packed;
0342
0343 /**
0344  * struct i3c_ccc_cmd_payload - CCC payload
0345  *
0346  * @len: payload length
0347  * @data: payload data. This buffer must be DMA-able
0348  */
0349 struct i3c_ccc_cmd_payload {
0350     u16 len;
0351     void *data;
0352 };
0353
0354 /**
0355  * struct i3c_ccc_cmd_dest - CCC command destination
0356  *
0357  * @addr: can be an I3C device address or the broadcast address if this is a
0358  *    broadcast CCC
0359  * @payload: payload to be sent to this device or broadcasted
0360  */
0361 struct i3c_ccc_cmd_dest {
0362     u8 addr;
0363     struct i3c_ccc_cmd_payload payload;
0364 };
0365
0366 /**
0367  * struct i3c_ccc_cmd - CCC command
0368  *
0369  * @rnw: true if the CCC should retrieve data from the device. Only valid for
0370  *   unicast commands
0371  * @id: CCC command id
0372  * @ndests: number of destinations. Should always be one for broadcast commands
0373  * @dests: array of destinations and associated payload for this CCC. Most of
0374  *     the time, only one destination is provided
0375  * @err: I3C error code
0376  */
0377 struct i3c_ccc_cmd {
0378     u8 rnw;
0379     u8 id;
0380     unsigned int ndests;
0381     struct i3c_ccc_cmd_dest *dests;
0382     enum i3c_error_code err;
0383 };
0384
0385 #endif /* I3C_CCC_H */