diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-bus-i3c | 146 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt | 43 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/i3c/i3c.txt | 138 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt | 41 | ||||
| -rw-r--r-- | Documentation/driver-api/i3c/device-driver-api.rst | 9 | ||||
| -rw-r--r-- | Documentation/driver-api/i3c/index.rst | 11 | ||||
| -rw-r--r-- | Documentation/driver-api/i3c/master-driver-api.rst | 9 | ||||
| -rw-r--r-- | Documentation/driver-api/i3c/protocol.rst | 203 | ||||
| -rw-r--r-- | Documentation/driver-api/index.rst | 1 |
9 files changed, 601 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c new file mode 100644 index 000000000000..2f332ec36f82 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i3c @@ -0,0 +1,146 @@ +What: /sys/bus/i3c/devices/i3c-<bus-id> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + An I3C bus. This directory will contain one sub-directory per + I3C device present on the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/current_master +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the master that owns the bus (<bus-id>-<master-pid>) at + the time this file is read. Note that bus ownership can change + overtime, so there's no guarantee that when the read() call + returns, the value returned is still valid. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/mode +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + I3C bus mode. Can be "pure", "mixed-fast" or "mixed-slow". See + the I3C specification for a detailed description of what each + of these modes implies. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/i3c_scl_frequency +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + The frequency (expressed in Hz) of the SCL signal when + operating in I3C SDR mode. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/i2c_scl_frequency +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + The frequency (expressed in Hz) of the SCL signal when + operating in I2C mode. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/dynamic_address +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Dynamic address assigned to the master controller. This + address may change if the bus is re-initialized. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/bcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + BCR stands for Bus Characteristics Register and express the + device capabilities in term of speed, maximum read/write + length, etc. See the I3C specification for more details. + This entry describes the BCR of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/dcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + DCR stands for Device Characteristics Register and express the + device capabilities in term of exposed features. See the I3C + specification for more details. + This entry describes the DCR of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/pid +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + PID stands for Provisional ID and is used to uniquely identify + a device on a bus. This PID contains information about the + vendor, the part and an instance ID so that several devices of + the same type can be connected on the same bus. + See the I3C specification for more details. + This entry describes the PID of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/hdrcap +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the HDR (High Data Rate) capabilities of a device. + Returns a list of supported HDR mode, each element is separated + by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". + See the I3C specification for more details about these HDR + modes. + This entry describes the HDRCAP of the master controller + driving the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + An I3C device present on I3C bus identified by <bus-id>. Note + that all devices are represented including the master driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dynamic_address +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Dynamic address assigned to device <bus-id>-<device-pid>. This + address may change if the bus is re-initialized. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/bcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + BCR stands for Bus Characteristics Register and express the + device capabilities in term of speed, maximum read/write + length, etc. See the I3C specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + DCR stands for Device Characteristics Register and express the + device capabilities in term of exposed features. See the I3C + specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/pid +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + PID stands for Provisional ID and is used to uniquely identify + a device on a bus. This PID contains information about the + vendor, the part and an instance ID so that several devices of + the same type can be connected on the same bus. + See the I3C specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/hdrcap +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the HDR (High Data Rate) capabilities of a device. + Returns a list of supported HDR mode, each element is separated + by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". + See the I3C specification for more details about these HDR + modes. + +What: /sys/bus/i3c/devices/<bus-id>-<device-pid> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + These directories are just symbolic links to + /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>. diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt new file mode 100644 index 000000000000..69da2115abdc --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt @@ -0,0 +1,43 @@ +Bindings for cadence I3C master block +===================================== + +Required properties: +-------------------- +- compatible: shall be "cdns,i3c-master" +- clocks: shall reference the pclk and sysclk +- clock-names: shall contain "pclk" and "sysclk" +- interrupts: the interrupt line connected to this I3C master +- reg: I3C master registers + +Mandatory properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- #address-cells: shall be set to 1 +- #size-cells: shall be set to 0 + +Optional properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- i2c-scl-hz +- i3c-scl-hz + +I3C device connected on the bus follow the generic description (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details). + +Example: + + i3c-master@0d040000 { + compatible = "cdns,i3c-master"; + clocks = <&coreclock>, <&i3csysclock>; + clock-names = "pclk", "sysclk"; + interrupts = <3 0>; + reg = <0x0d040000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + i2c-scl-hz = <100000>; + + nunchuk: nunchuk@52 { + compatible = "nintendo,nunchuk"; + reg = <0x52 0x80000010 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/i3c/i3c.txt b/Documentation/devicetree/bindings/i3c/i3c.txt new file mode 100644 index 000000000000..ab729a0a86ae --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/i3c.txt @@ -0,0 +1,138 @@ +Generic device tree bindings for I3C busses +=========================================== + +This document describes generic bindings that should be used to describe I3C +busses in a device tree. + +Required properties +------------------- + +- #address-cells - should be <3>. Read more about addresses below. +- #size-cells - should be <0>. +- compatible - name of the I3C master controller driving the I3C bus + +For other required properties e.g. to describe register sets, +clocks, etc. check the binding documentation of the specific driver. +The node describing an I3C bus should be named i3c-master. + +Optional properties +------------------- + +These properties may not be supported by all I3C master drivers. Each I3C +master bindings should specify which of them are supported. + +- i3c-scl-hz: frequency of the SCL signal used for I3C transfers. + When undefined the core sets it to 12.5MHz. + +- i2c-scl-hz: frequency of the SCL signal used for I2C transfers. + When undefined, the core looks at LVR (Legacy Virtual Register) + values of I2C devices described in the device tree to determine + the maximum I2C frequency. + +I2C devices +=========== + +Each I2C device connected to the bus should be described in a subnode. All +properties described in Documentation/devicetree/bindings/i2c/i2c.txt are +valid here, but several new properties have been added. + +New constraint on existing properties: +-------------------------------------- +- reg: contains 3 cells + + first cell : still encoding the I2C address + + + second cell: shall be 0 + + + third cell: shall encode the I3C LVR (Legacy Virtual Register) + bit[31:8]: unused/ignored + bit[7:5]: I2C device index. Possible values + * 0: I2C device has a 50 ns spike filter + * 1: I2C device does not have a 50 ns spike filter but supports high + frequency on SCL + * 2: I2C device does not have a 50 ns spike filter and is not tolerant + to high frequencies + * 3-7: reserved + + bit[4]: tell whether the device operates in FM (Fast Mode) or FM+ mode + * 0: FM+ mode + * 1: FM mode + + bit[3:0]: device type + * 0-15: reserved + +The I2C node unit-address should always match the first cell of the reg +property: <device-type>@<i2c-address>. + +I3C devices +=========== + +All I3C devices are supposed to support DAA (Dynamic Address Assignment), and +are thus discoverable. So, by default, I3C devices do not have to be described +in the device tree. +This being said, one might want to attach extra resources to these devices, +and those resources may have to be described in the device tree, which in turn +means we have to describe I3C devices. + +Another use case for describing an I3C device in the device tree is when this +I3C device has a static I2C address and we want to assign it a specific I3C +dynamic address before the DAA takes place (so that other devices on the bus +can't take this dynamic address). + +The I3C device should be names <device-type>@<static-i2c-address>,<i3c-pid>, +where device-type is describing the type of device connected on the bus +(gpio-controller, sensor, ...). + +Required properties +------------------- +- reg: contains 3 cells + + first cell : encodes the static I2C address. Should be 0 if the device does + not have one (0 is not a valid I2C address). + + + second and third cells: should encode the ProvisionalID. The second cell + contains the manufacturer ID left-shifted by 1. + The third cell contains ORing of the part ID + left-shifted by 16, the instance ID left-shifted + by 12 and the extra information. This encoding is + following the PID definition provided by the I3C + specification. + +Optional properties +------------------- +- assigned-address: dynamic address to be assigned to this device. This + property is only valid if the I3C device has a static + address (first cell of the reg property != 0). + + +Example: + + i3c-master@d040000 { + compatible = "cdns,i3c-master"; + clocks = <&coreclock>, <&i3csysclock>; + clock-names = "pclk", "sysclk"; + interrupts = <3 0>; + reg = <0x0d040000 0x1000>; + #address-cells = <3>; + #size-cells = <0>; + i2c-scl-hz = <100000>; + + /* I2C device. */ + nunchuk: nunchuk@52 { + compatible = "nintendo,nunchuk"; + reg = <0x52 0x0 0x10>; + }; + + /* I3C device with a static I2C address. */ + thermal_sensor: sensor@68,39200144004 { + reg = <0x68 0x392 0x144004>; + assigned-address = <0xa>; + }; + + /* + * I3C device without a static I2C address but requiring + * resources described in the DT. + */ + sensor@0,39200154004 { + reg = <0x0 0x392 0x154004>; + clocks = <&clock_provider 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt new file mode 100644 index 000000000000..5020eb71eb8d --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt @@ -0,0 +1,41 @@ +Bindings for Synopsys DesignWare I3C master block +================================================= + +Required properties: +-------------------- +- compatible: shall be "snps,dw-i3c-master-1.00a" +- clocks: shall reference the core_clk +- interrupts: the interrupt line connected to this I3C master +- reg: Offset and length of I3C master registers + +Mandatory properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- #address-cells: shall be set to 3 +- #size-cells: shall be set to 0 + +Optional properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- i2c-scl-hz +- i3c-scl-hz + +I3C device connected on the bus follow the generic description (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details). + +Example: + + i3c-master@2000 { + compatible = "snps,dw-i3c-master-1.00a"; + #address-cells = <3>; + #size-cells = <0>; + reg = <0x02000 0x1000>; + interrupts = <0>; + clocks = <&i3cclk>; + + eeprom@57{ + compatible = "atmel,24c01"; + reg = <0x57 0x0 0x10>; + pagesize = <0x8>; + }; + }; diff --git a/Documentation/driver-api/i3c/device-driver-api.rst b/Documentation/driver-api/i3c/device-driver-api.rst new file mode 100644 index 000000000000..85bc3381cd3e --- /dev/null +++ b/Documentation/driver-api/i3c/device-driver-api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +I3C device driver API +===================== + +.. kernel-doc:: include/linux/i3c/device.h + +.. kernel-doc:: drivers/i3c/device.c diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst new file mode 100644 index 000000000000..783d6dad054b --- /dev/null +++ b/Documentation/driver-api/i3c/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +I3C subsystem +============= + +.. toctree:: + + protocol + device-driver-api + master-driver-api diff --git a/Documentation/driver-api/i3c/master-driver-api.rst b/Documentation/driver-api/i3c/master-driver-api.rst new file mode 100644 index 000000000000..332552b28358 --- /dev/null +++ b/Documentation/driver-api/i3c/master-driver-api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +I3C master controller driver API +================================ + +.. kernel-doc:: drivers/i3c/master.c + +.. kernel-doc:: include/linux/i3c/master.h diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst new file mode 100644 index 000000000000..dae3b6d32c6b --- /dev/null +++ b/Documentation/driver-api/i3c/protocol.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +I3C protocol +============ + +Disclaimer +========== + +This chapter will focus on aspects that matter to software developers. For +everything hardware related (like how things are transmitted on the bus, how +collisions are prevented, ...) please have a look at the I3C specification. + +This document is just a brief introduction to the I3C protocol and the concepts +it brings to the table. If you need more information, please refer to the MIPI +I3C specification (can be downloaded here +http://resources.mipi.org/mipi-i3c-v1-download). + +Introduction +============ + +The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed +to overcome I2C limitations (limited speed, external signals needed for +interrupts, no automatic detection of the devices connected to the bus, ...) +while remaining power-efficient. + +I3C Bus +======= + +An I3C bus is made of several I3C devices and possibly some I2C devices as +well, but let's focus on I3C devices for now. + +An I3C device on the I3C bus can have one of the following roles: + +* Master: the device is driving the bus. It's the one in charge of initiating + transactions or deciding who is allowed to talk on the bus (slave generated + events are possible in I3C, see below). +* Slave: the device acts as a slave, and is not able to send frames to another + slave on the bus. The device can still send events to the master on + its own initiative if the master allowed it. + +I3C is a multi-master protocol, so there might be several masters on a bus, +though only one device can act as a master at a given time. In order to gain +bus ownership, a master has to follow a specific procedure. + +Each device on the I3C bus has to be assigned a dynamic address to be able to +communicate. Until this is done, the device should only respond to a limited +set of commands. If it has a static address (also called legacy I2C address), +the device can reply to I2C transfers. + +In addition to these per-device addresses, the protocol defines a broadcast +address in order to address all devices on the bus. + +Once a dynamic address has been assigned to a device, this address will be used +for any direct communication with the device. Note that even after being +assigned a dynamic address, the device should still process broadcast messages. + +I3C Device discovery +==================== + +The I3C protocol defines a mechanism to automatically discover devices present +on the bus, their capabilities and the functionalities they provide. In this +regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI. + +The discovery mechanism is called DAA (Dynamic Address Assignment), because it +not only discovers devices but also assigns them a dynamic address. + +During DAA, each I3C device reports 3 important things: + +* BCR: Bus Characteristic Register. This 8-bit register describes the device bus + related capabilities +* DCR: Device Characteristic Register. This 8-bit register describes the + functionalities provided by the device +* Provisional ID: A 48-bit unique identifier. On a given bus there should be no + Provisional ID collision, otherwise the discovery mechanism may fail. + +I3C slave events +================ + +The I3C protocol allows slaves to generate events on their own, and thus allows +them to take temporary control of the bus. + +This mechanism is called IBI for In Band Interrupts, and as stated in the name, +it allows devices to generate interrupts without requiring an external signal. + +During DAA, each device on the bus has been assigned an address, and this +address will serve as a priority identifier to determine who wins if 2 different +devices are generating an interrupt at the same moment on the bus (the lower the +dynamic address the higher the priority). + +Masters are allowed to inhibit interrupts if they want to. This inhibition +request can be broadcast (applies to all devices) or sent to a specific +device. + +I3C Hot-Join +============ + +The Hot-Join mechanism is similar to USB hotplug. This mechanism allows +slaves to join the bus after it has been initialized by the master. + +This covers the following use cases: + +* the device is not powered when the bus is probed +* the device is hotplugged on the bus through an extension board + +This mechanism is relying on slave events to inform the master that a new +device joined the bus and is waiting for a dynamic address. + +The master is then free to address the request as it wishes: ignore it or +assign a dynamic address to the slave. + +I3C transfer types +================== + +If you omit SMBus (which is just a standardization on how to access registers +exposed by I2C devices), I2C has only one transfer type. + +I3C defines 3 different classes of transfer in addition to I2C transfers which +are here for backward compatibility with I2C devices. + +I3C CCC commands +---------------- + +CCC (Common Command Code) commands are meant to be used for anything that is +related to bus management and all features that are common to a set of devices. + +CCC commands contain an 8-bit CCC ID describing the command that is executed. +The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a +unicast one (bit7 = 1). + +The command ID can be followed by a payload. Depending on the command, this +payload is either sent by the master sending the command (write CCC command), +or sent by the slave receiving the command (read CCC command). Of course, read +accesses only apply to unicast commands. +Note that, when sending a CCC command to a specific device, the device address +is passed in the first byte of the payload. + +The payload length is not explicitly passed on the bus, and should be extracted +from the CCC ID. + +Note that vendors can use a dedicated range of CCC IDs for their own commands +(0x61-0x7f and 0xe0-0xef). + +I3C Private SDR transfers +------------------------- + +Private SDR (Single Data Rate) transfers should be used for anything that is +device specific and does not require high transfer speed. + +It is the equivalent of I2C transfers but in the I3C world. Each transfer is +passed the device address (dynamic address assigned during DAA), a payload +and a direction. + +The only difference with I2C is that the transfer is much faster (typical clock +frequency is 12.5MHz). + +I3C HDR commands +---------------- + +HDR commands should be used for anything that is device specific and requires +high transfer speed. + +The first thing attached to an HDR command is the HDR mode. There are currently +3 different modes defined by the I3C specification (refer to the specification +for more details): + +* HDR-DDR: Double Data Rate mode +* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices +* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices + +When sending an HDR command, the whole bus has to enter HDR mode, which is done +using a broadcast CCC command. +Once the bus has entered a specific HDR mode, the master sends the HDR command. +An HDR command is made of: + +* one 16-bits command word in big endian +* N 16-bits data words in big endian + +Those words may be wrapped with specific preambles/post-ambles which depend on +the chosen HDR mode and are detailed here (see the specification for more +details). + +The 16-bits command word is made of: + +* bit[15]: direction bit, read is 1, write is 0 +* bit[14:8]: command code. Identifies the command being executed, the amount of + data words and their meaning +* bit[7:1]: I3C address of the device this command is addressed to +* bit[0]: reserved/parity-bit + +Backward compatibility with I2C devices +======================================= + +The I3C protocol has been designed to be backward compatible with I2C devices. +This backward compatibility allows one to connect a mix of I2C and I3C devices +on the same bus, though, in order to be really efficient, I2C devices should +be equipped with 50 ns spike filters. + +I2C devices can't be discovered like I3C ones and have to be statically +declared. In order to let the master know what these devices are capable of +(both in terms of bus related limitations and functionalities), the software +has to provide some information, which is done through the LVR (Legacy I2C +Virtual Register). diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 909f991b4c0d..ab38ced66a44 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -33,6 +33,7 @@ available subsections can be seen below. pci/index spi i2c + i3c/index hsi edac scsi |