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).