Orange Pi5 kernel

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