driver-api/i3c/protocol.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 This chapter will focus on aspects that matter to software developers. For
11 everything hardware related (like how things are transmitted on the bus, how
17 https://resources.mipi.org/mipi-i3c-v1-download).
22 The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed
25 while remaining power-efficient.
31 well, but let's focus on I3C devices for now.
33 An I3C device on the I3C bus can have one of the following roles:
35 * Master: the device is driving the bus. It's the one in charge of initiating
36   transactions or deciding who is allowed to talk on the bus (slave generated
38 * Slave: the device acts as a slave, and is not able to send frames to another
39   slave on the bus. The device can still send events to the master on
42 I3C is a multi-master protocol, so there might be several masters on a bus,
43 though only one device can act as a master at a given time. In order to gain
46 Each device on the I3C bus has to be assigned a dynamic address to be able to
47 communicate. Until this is done, the device should only respond to a limited
49 the device can reply to I2C transfers.
51 In addition to these per-device addresses, the protocol defines a broadcast
52 address in order to address all devices on the bus.
54 Once a dynamic address has been assigned to a device, this address will be used
55 for any direct communication with the device. Note that even after being
56 assigned a dynamic address, the device should still process broadcast messages.
58 I3C Device discovery
62 on the bus, their capabilities and the functionalities they provide. In this
68 During DAA, each I3C device reports 3 important things:
70 * BCR: Bus Characteristic Register. This 8-bit register describes the device bus
72 * DCR: Device Characteristic Register. This 8-bit register describes the
73   functionalities provided by the device
74 * Provisioned ID: A 48-bit unique identifier. On a given bus there should be no
80 The I3C protocol allows slaves to generate events on their own, and thus allows
86 During DAA, each device on the bus has been assigned an address, and this
88 devices are generating an interrupt at the same moment on the bus (the lower the
93 device.
95 I3C Hot-Join
98 The Hot-Join mechanism is similar to USB hotplug. This mechanism allows
103 * the device is not powered when the bus is probed
104 * the device is hotplugged on the bus through an extension board
106 This mechanism is relying on slave events to inform the master that a new
107 device joined the bus and is waiting for a dynamic address.
115 If you omit SMBus (which is just a standardization on how to access registers
122 ----------------
127 CCC commands contain an 8-bit CCC ID describing the command that is executed.
131 The command ID can be followed by a payload. Depending on the command, this
135 Note that, when sending a CCC command to a specific device, the device address
138 The payload length is not explicitly passed on the bus, and should be extracted
142 (0x61-0x7f and 0xe0-0xef).
145 -------------------------
148 device specific and does not require high transfer speed.
151 passed the device address (dynamic address assigned during DAA), a payload
158 ----------------
160 HDR commands should be used for anything that is device specific and requires
167 * HDR-DDR: Double Data Rate mode
168 * HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices
169 * HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices
176 * one 16-bits command word in big endian
177 * N 16-bits data words in big endian
179 Those words may be wrapped with specific preambles/post-ambles which depend on
183 The 16-bits command word is made of:
188 * bit[7:1]: I3C address of the device this command is addressed to
189 * bit[0]: reserved/parity-bit
196 on the same bus, though, in order to be really efficient, I2C devices should