protocol.rst (8172B)
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).