tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: driver-api: Add I3C documentation
Add the I3C documentation describing the protocol, the master driver API
and the device driver API.
Signed-off-by: Boris Brezillon <boris.brezillon@bootlin.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Arnd Bergmann <arnd@arndb.de>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
+233
+9
Documentation/driver-api/i3c/device-driver-api.rst
+9
Documentation/driver-api/i3c/device-driver-api.rst
+11
Documentation/driver-api/i3c/index.rst
+11
Documentation/driver-api/i3c/index.rst
+9
Documentation/driver-api/i3c/master-driver-api.rst
+9
Documentation/driver-api/i3c/master-driver-api.rst
+203
Documentation/driver-api/i3c/protocol.rst
+203
Documentation/driver-api/i3c/protocol.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
============
4
+
I3C protocol
5
+
============
6
+
7
+
Disclaimer
8
+
==========
9
+
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
12
+
collisions are prevented, ...) please have a look at the I3C specification.
13
+
14
+
This document is just a brief introduction to the I3C protocol and the concepts
15
+
it brings to the table. If you need more information, please refer to the MIPI
16
+
I3C specification (can be downloaded here
17
+
http://resources.mipi.org/mipi-i3c-v1-download).
18
+
19
+
Introduction
20
+
============
21
+
22
+
The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed
23
+
to overcome I2C limitations (limited speed, external signals needed for
24
+
interrupts, no automatic detection of the devices connected to the bus, ...)
25
+
while remaining power-efficient.
26
+
27
+
I3C Bus
28
+
=======
29
+
30
+
An I3C bus is made of several I3C devices and possibly some I2C devices as
31
+
well, but let's focus on I3C devices for now.
32
+
33
+
An 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
+
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
44
+
bus ownership, a master has to follow a specific procedure.
45
+
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
48
+
set of commands. If it has a static address (also called legacy I2C address),
49
+
the device can reply to I2C transfers.
50
+
51
+
In addition to these per-device addresses, the protocol defines a broadcast
52
+
address in order to address all devices on the bus.
53
+
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.
57
+
58
+
I3C Device discovery
59
+
====================
60
+
61
+
The I3C protocol defines a mechanism to automatically discover devices present
62
+
on the bus, their capabilities and the functionalities they provide. In this
63
+
regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI.
64
+
65
+
The discovery mechanism is called DAA (Dynamic Address Assignment), because it
66
+
not only discovers devices but also assigns them a dynamic address.
67
+
68
+
During 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
+
77
+
I3C slave events
78
+
================
79
+
80
+
The I3C protocol allows slaves to generate events on their own, and thus allows
81
+
them to take temporary control of the bus.
82
+
83
+
This mechanism is called IBI for In Band Interrupts, and as stated in the name,
84
+
it allows devices to generate interrupts without requiring an external signal.
85
+
86
+
During DAA, each device on the bus has been assigned an address, and this
87
+
address will serve as a priority identifier to determine who wins if 2 different
88
+
devices are generating an interrupt at the same moment on the bus (the lower the
89
+
dynamic address the higher the priority).
90
+
91
+
Masters are allowed to inhibit interrupts if they want to. This inhibition
92
+
request can be broadcast (applies to all devices) or sent to a specific
93
+
device.
94
+
95
+
I3C Hot-Join
96
+
============
97
+
98
+
The Hot-Join mechanism is similar to USB hotplug. This mechanism allows
99
+
slaves to join the bus after it has been initialized by the master.
100
+
101
+
This 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
+
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.
108
+
109
+
The master is then free to address the request as it wishes: ignore it or
110
+
assign a dynamic address to the slave.
111
+
112
+
I3C transfer types
113
+
==================
114
+
115
+
If you omit SMBus (which is just a standardization on how to access registers
116
+
exposed by I2C devices), I2C has only one transfer type.
117
+
118
+
I3C defines 3 different classes of transfer in addition to I2C transfers which
119
+
are here for backward compatibility with I2C devices.
120
+
121
+
I3C CCC commands
122
+
----------------
123
+
124
+
CCC (Common Command Code) commands are meant to be used for anything that is
125
+
related to bus management and all features that are common to a set of devices.
126
+
127
+
CCC commands contain an 8-bit CCC ID describing the command that is executed.
128
+
The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a
129
+
unicast one (bit7 = 1).
130
+
131
+
The command ID can be followed by a payload. Depending on the command, this
132
+
payload is either sent by the master sending the command (write CCC command),
133
+
or sent by the slave receiving the command (read CCC command). Of course, read
134
+
accesses only apply to unicast commands.
135
+
Note that, when sending a CCC command to a specific device, the device address
136
+
is passed in the first byte of the payload.
137
+
138
+
The payload length is not explicitly passed on the bus, and should be extracted
139
+
from the CCC ID.
140
+
141
+
Note that vendors can use a dedicated range of CCC IDs for their own commands
142
+
(0x61-0x7f and 0xe0-0xef).
143
+
144
+
I3C Private SDR transfers
145
+
-------------------------
146
+
147
+
Private SDR (Single Data Rate) transfers should be used for anything that is
148
+
device specific and does not require high transfer speed.
149
+
150
+
It is the equivalent of I2C transfers but in the I3C world. Each transfer is
151
+
passed the device address (dynamic address assigned during DAA), a payload
152
+
and a direction.
153
+
154
+
The only difference with I2C is that the transfer is much faster (typical clock
155
+
frequency is 12.5MHz).
156
+
157
+
I3C HDR commands
158
+
----------------
159
+
160
+
HDR commands should be used for anything that is device specific and requires
161
+
high transfer speed.
162
+
163
+
The first thing attached to an HDR command is the HDR mode. There are currently
164
+
3 different modes defined by the I3C specification (refer to the specification
165
+
for 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
+
171
+
When sending an HDR command, the whole bus has to enter HDR mode, which is done
172
+
using a broadcast CCC command.
173
+
Once the bus has entered a specific HDR mode, the master sends the HDR command.
174
+
An 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
+
179
+
Those words may be wrapped with specific preambles/post-ambles which depend on
180
+
the chosen HDR mode and are detailed here (see the specification for more
181
+
details).
182
+
183
+
The 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
+
191
+
Backward compatibility with I2C devices
192
+
=======================================
193
+
194
+
The I3C protocol has been designed to be backward compatible with I2C devices.
195
+
This backward compatibility allows one to connect a mix of I2C and I3C devices
196
+
on the same bus, though, in order to be really efficient, I2C devices should
197
+
be equipped with 50 ns spike filters.
198
+
199
+
I2C devices can't be discovered like I3C ones and have to be statically
200
+
declared. 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
202
+
has to provide some information, which is done through the LVR (Legacy I2C
203
+
Virtual Register).