1.. SPDX-License-Identifier: GPL-2.0
2
3============
4I3C protocol
5============
6
7Disclaimer
8==========
9
10This chapter will focus on aspects that matter to software developers. For
11everything hardware related (like how things are transmitted on the bus, how
12collisions are prevented, ...) please have a look at the I3C specification.
13
14This document is just a brief introduction to the I3C protocol and the concepts
15it brings to the table. If you need more information, please refer to the MIPI
16I3C specification (can be downloaded here
17https://resources.mipi.org/mipi-i3c-v1-download).
18
19Introduction
20============
21
22The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed
23to overcome I2C limitations (limited speed, external signals needed for
24interrupts, no automatic detection of the devices connected to the bus, ...)
25while remaining power-efficient.
26
27I3C Bus
28=======
29
30An I3C bus is made of several I3C devices and possibly some I2C devices as
31well, but let's focus on I3C devices for now.
32
33An I3C device on the I3C bus can have one of the following roles:
34
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
37  events are possible in I3C, see below).
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
40  its own initiative if the master allowed it.
41
42I3C is a multi-master protocol, so there might be several masters on a bus,
43though only one device can act as a master at a given time. In order to gain
44bus ownership, a master has to follow a specific procedure.
45
46Each device on the I3C bus has to be assigned a dynamic address to be able to
47communicate. Until this is done, the device should only respond to a limited
48set of commands. If it has a static address (also called legacy I2C address),
49the device can reply to I2C transfers.
50
51In addition to these per-device addresses, the protocol defines a broadcast
52address in order to address all devices on the bus.
53
54Once a dynamic address has been assigned to a device, this address will be used
55for any direct communication with the device. Note that even after being
56assigned a dynamic address, the device should still process broadcast messages.
57
58I3C Device discovery
59====================
60
61The I3C protocol defines a mechanism to automatically discover devices present
62on the bus, their capabilities and the functionalities they provide. In this
63regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI.
64
65The discovery mechanism is called DAA (Dynamic Address Assignment), because it
66not only discovers devices but also assigns them a dynamic address.
67
68During DAA, each I3C device reports 3 important things:
69
70* BCR: Bus Characteristic Register. This 8-bit register describes the device bus
71  related capabilities
72* DCR: Device Characteristic Register. This 8-bit register describes the
73  functionalities provided by the device
74* Provisional ID: A 48-bit unique identifier. On a given bus there should be no
75  Provisional ID collision, otherwise the discovery mechanism may fail.
76
77I3C slave events
78================
79
80The I3C protocol allows slaves to generate events on their own, and thus allows
81them to take temporary control of the bus.
82
83This mechanism is called IBI for In Band Interrupts, and as stated in the name,
84it allows devices to generate interrupts without requiring an external signal.
85
86During DAA, each device on the bus has been assigned an address, and this
87address will serve as a priority identifier to determine who wins if 2 different
88devices are generating an interrupt at the same moment on the bus (the lower the
89dynamic address the higher the priority).
90
91Masters are allowed to inhibit interrupts if they want to. This inhibition
92request can be broadcast (applies to all devices) or sent to a specific
93device.
94
95I3C Hot-Join
96============
97
98The Hot-Join mechanism is similar to USB hotplug. This mechanism allows
99slaves to join the bus after it has been initialized by the master.
100
101This covers the following use cases:
102
103* the device is not powered when the bus is probed
104* the device is hotplugged on the bus through an extension board
105
106This mechanism is relying on slave events to inform the master that a new
107device joined the bus and is waiting for a dynamic address.
108
109The master is then free to address the request as it wishes: ignore it or
110assign a dynamic address to the slave.
111
112I3C transfer types
113==================
114
115If you omit SMBus (which is just a standardization on how to access registers
116exposed by I2C devices), I2C has only one transfer type.
117
118I3C defines 3 different classes of transfer in addition to I2C transfers which
119are here for backward compatibility with I2C devices.
120
121I3C CCC commands
122----------------
123
124CCC (Common Command Code) commands are meant to be used for anything that is
125related to bus management and all features that are common to a set of devices.
126
127CCC commands contain an 8-bit CCC ID describing the command that is executed.
128The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a
129unicast one (bit7 = 1).
130
131The command ID can be followed by a payload. Depending on the command, this
132payload is either sent by the master sending the command (write CCC command),
133or sent by the slave receiving the command (read CCC command). Of course, read
134accesses only apply to unicast commands.
135Note that, when sending a CCC command to a specific device, the device address
136is passed in the first byte of the payload.
137
138The payload length is not explicitly passed on the bus, and should be extracted
139from the CCC ID.
140
141Note that vendors can use a dedicated range of CCC IDs for their own commands
142(0x61-0x7f and 0xe0-0xef).
143
144I3C Private SDR transfers
145-------------------------
146
147Private SDR (Single Data Rate) transfers should be used for anything that is
148device specific and does not require high transfer speed.
149
150It is the equivalent of I2C transfers but in the I3C world. Each transfer is
151passed the device address (dynamic address assigned during DAA), a payload
152and a direction.
153
154The only difference with I2C is that the transfer is much faster (typical clock
155frequency is 12.5MHz).
156
157I3C HDR commands
158----------------
159
160HDR commands should be used for anything that is device specific and requires
161high transfer speed.
162
163The first thing attached to an HDR command is the HDR mode. There are currently
1643 different modes defined by the I3C specification (refer to the specification
165for more details):
166
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
170
171When sending an HDR command, the whole bus has to enter HDR mode, which is done
172using a broadcast CCC command.
173Once the bus has entered a specific HDR mode, the master sends the HDR command.
174An HDR command is made of:
175
176* one 16-bits command word in big endian
177* N 16-bits data words in big endian
178
179Those words may be wrapped with specific preambles/post-ambles which depend on
180the chosen HDR mode and are detailed here (see the specification for more
181details).
182
183The 16-bits command word is made of:
184
185* bit[15]: direction bit, read is 1, write is 0
186* bit[14:8]: command code. Identifies the command being executed, the amount of
187  data words and their meaning
188* bit[7:1]: I3C address of the device this command is addressed to
189* bit[0]: reserved/parity-bit
190
191Backward compatibility with I2C devices
192=======================================
193
194The I3C protocol has been designed to be backward compatible with I2C devices.
195This backward compatibility allows one to connect a mix of I2C and I3C devices
196on the same bus, though, in order to be really efficient, I2C devices should
197be equipped with 50 ns spike filters.
198
199I2C devices can't be discovered like I3C ones and have to be statically
200declared. In order to let the master know what these devices are capable of
201(both in terms of bus related limitations and functionalities), the software
202has to provide some information, which is done through the LVR (Legacy I2C
203Virtual Register).
204