0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ============
0004 I3C protocol
0005 ============
0006
0007 Disclaimer
0008 ==========
0009
0010 This chapter will focus on aspects that matter to software developers. For
0011 everything hardware related (like how things are transmitted on the bus, how
0012 collisions are prevented, ...) please have a look at the I3C specification.
0013
0014 This document is just a brief introduction to the I3C protocol and the concepts
0015 it brings to the table. If you need more information, please refer to the MIPI
0016 I3C specification (can be downloaded here
0017 https://resources.mipi.org/mipi-i3c-v1-download).
0018
0019 Introduction
0020 ============
0021
0022 The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed
0023 to overcome I2C limitations (limited speed, external signals needed for
0024 interrupts, no automatic detection of the devices connected to the bus, ...)
0025 while remaining power-efficient.
0026
0027 I3C Bus
0028 =======
0029
0030 An I3C bus is made of several I3C devices and possibly some I2C devices as
0031 well, but let's focus on I3C devices for now.
0032
0033 An I3C device on the I3C bus can have one of the following roles:
0034
0035 * Master: the device is driving the bus. It's the one in charge of initiating
0036 transactions or deciding who is allowed to talk on the bus (slave generated
0037 events are possible in I3C, see below).
0038 * Slave: the device acts as a slave, and is not able to send frames to another
0039 slave on the bus. The device can still send events to the master on
0040 its own initiative if the master allowed it.
0041
0042 I3C is a multi-master protocol, so there might be several masters on a bus,
0043 though only one device can act as a master at a given time. In order to gain
0044 bus ownership, a master has to follow a specific procedure.
0045
0046 Each device on the I3C bus has to be assigned a dynamic address to be able to
0047 communicate. Until this is done, the device should only respond to a limited
0048 set of commands. If it has a static address (also called legacy I2C address),
0049 the device can reply to I2C transfers.
0050
0051 In addition to these per-device addresses, the protocol defines a broadcast
0052 address in order to address all devices on the bus.
0053
0054 Once a dynamic address has been assigned to a device, this address will be used
0055 for any direct communication with the device. Note that even after being
0056 assigned a dynamic address, the device should still process broadcast messages.
0057
0058 I3C Device discovery
0059 ====================
0060
0061 The I3C protocol defines a mechanism to automatically discover devices present
0062 on the bus, their capabilities and the functionalities they provide. In this
0063 regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI.
0064
0065 The discovery mechanism is called DAA (Dynamic Address Assignment), because it
0066 not only discovers devices but also assigns them a dynamic address.
0067
0068 During DAA, each I3C device reports 3 important things:
0069
0070 * BCR: Bus Characteristic Register. This 8-bit register describes the device bus
0071 related capabilities
0072 * DCR: Device Characteristic Register. This 8-bit register describes the
0073 functionalities provided by the device
0074 * Provisional ID: A 48-bit unique identifier. On a given bus there should be no
0075 Provisional ID collision, otherwise the discovery mechanism may fail.
0076
0077 I3C slave events
0078 ================
0079
0080 The I3C protocol allows slaves to generate events on their own, and thus allows
0081 them to take temporary control of the bus.
0082
0083 This mechanism is called IBI for In Band Interrupts, and as stated in the name,
0084 it allows devices to generate interrupts without requiring an external signal.
0085
0086 During DAA, each device on the bus has been assigned an address, and this
0087 address will serve as a priority identifier to determine who wins if 2 different
0088 devices are generating an interrupt at the same moment on the bus (the lower the
0089 dynamic address the higher the priority).
0090
0091 Masters are allowed to inhibit interrupts if they want to. This inhibition
0092 request can be broadcast (applies to all devices) or sent to a specific
0093 device.
0094
0095 I3C Hot-Join
0096 ============
0097
0098 The Hot-Join mechanism is similar to USB hotplug. This mechanism allows
0099 slaves to join the bus after it has been initialized by the master.
0100
0101 This covers the following use cases:
0102
0103 * the device is not powered when the bus is probed
0104 * the device is hotplugged on the bus through an extension board
0105
0106 This mechanism is relying on slave events to inform the master that a new
0107 device joined the bus and is waiting for a dynamic address.
0108
0109 The master is then free to address the request as it wishes: ignore it or
0110 assign a dynamic address to the slave.
0111
0112 I3C transfer types
0113 ==================
0114
0115 If you omit SMBus (which is just a standardization on how to access registers
0116 exposed by I2C devices), I2C has only one transfer type.
0117
0118 I3C defines 3 different classes of transfer in addition to I2C transfers which
0119 are here for backward compatibility with I2C devices.
0120
0121 I3C CCC commands
0122 ----------------
0123
0124 CCC (Common Command Code) commands are meant to be used for anything that is
0125 related to bus management and all features that are common to a set of devices.
0126
0127 CCC commands contain an 8-bit CCC ID describing the command that is executed.
0128 The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a
0129 unicast one (bit7 = 1).
0130
0131 The command ID can be followed by a payload. Depending on the command, this
0132 payload is either sent by the master sending the command (write CCC command),
0133 or sent by the slave receiving the command (read CCC command). Of course, read
0134 accesses only apply to unicast commands.
0135 Note that, when sending a CCC command to a specific device, the device address
0136 is passed in the first byte of the payload.
0137
0138 The payload length is not explicitly passed on the bus, and should be extracted
0139 from the CCC ID.
0140
0141 Note that vendors can use a dedicated range of CCC IDs for their own commands
0142 (0x61-0x7f and 0xe0-0xef).
0143
0144 I3C Private SDR transfers
0145 -------------------------
0146
0147 Private SDR (Single Data Rate) transfers should be used for anything that is
0148 device specific and does not require high transfer speed.
0149
0150 It is the equivalent of I2C transfers but in the I3C world. Each transfer is
0151 passed the device address (dynamic address assigned during DAA), a payload
0152 and a direction.
0153
0154 The only difference with I2C is that the transfer is much faster (typical clock
0155 frequency is 12.5MHz).
0156
0157 I3C HDR commands
0158 ----------------
0159
0160 HDR commands should be used for anything that is device specific and requires
0161 high transfer speed.
0162
0163 The first thing attached to an HDR command is the HDR mode. There are currently
0164 3 different modes defined by the I3C specification (refer to the specification
0165 for more details):
0166
0167 * HDR-DDR: Double Data Rate mode
0168 * HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices
0169 * HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices
0170
0171 When sending an HDR command, the whole bus has to enter HDR mode, which is done
0172 using a broadcast CCC command.
0173 Once the bus has entered a specific HDR mode, the master sends the HDR command.
0174 An HDR command is made of:
0175
0176 * one 16-bits command word in big endian
0177 * N 16-bits data words in big endian
0178
0179 Those words may be wrapped with specific preambles/post-ambles which depend on
0180 the chosen HDR mode and are detailed here (see the specification for more
0181 details).
0182
0183 The 16-bits command word is made of:
0184
0185 * bit[15]: direction bit, read is 1, write is 0
0186 * bit[14:8]: command code. Identifies the command being executed, the amount of
0187 data words and their meaning
0188 * bit[7:1]: I3C address of the device this command is addressed to
0189 * bit[0]: reserved/parity-bit
0190
0191 Backward compatibility with I2C devices
0192 =======================================
0193
0194 The I3C protocol has been designed to be backward compatible with I2C devices.
0195 This backward compatibility allows one to connect a mix of I2C and I3C devices
0196 on the same bus, though, in order to be really efficient, I2C devices should
0197 be equipped with 50 ns spike filters.
0198
0199 I2C devices can't be discovered like I3C ones and have to be statically
0200 declared. In order to let the master know what these devices are capable of
0201 (both in terms of bus related limitations and functionalities), the software
0202 has to provide some information, which is done through the LVR (Legacy I2C
0203 Virtual Register).
