Loading Documentation/ABI/testing/sysfs-bus-i3c 0 → 100644 +146 −0 Original line number Diff line number Diff line What: /sys/bus/i3c/devices/i3c-<bus-id> KernelVersion: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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>. Documentation/devicetree/bindings/i3c/i3c.txt 0 → 100644 +138 −0 Original line number Diff line number Diff line 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>; }; }; Documentation/driver-api/i3c/device-driver-api.rst 0 → 100644 +9 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ===================== I3C device driver API ===================== .. kernel-doc:: include/linux/i3c/device.h .. kernel-doc:: drivers/i3c/device.c Documentation/driver-api/i3c/index.rst 0 → 100644 +11 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ============= I3C subsystem ============= .. toctree:: protocol device-driver-api master-driver-api Documentation/driver-api/i3c/master-driver-api.rst 0 → 100644 +9 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ================================ I3C master controller driver API ================================ .. kernel-doc:: drivers/i3c/master.c .. kernel-doc:: include/linux/i3c/master.h Loading
Documentation/ABI/testing/sysfs-bus-i3c 0 → 100644 +146 −0 Original line number Diff line number Diff line What: /sys/bus/i3c/devices/i3c-<bus-id> KernelVersion: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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: 4.20 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>.
Documentation/devicetree/bindings/i3c/i3c.txt 0 → 100644 +138 −0 Original line number Diff line number Diff line 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>; }; };
Documentation/driver-api/i3c/device-driver-api.rst 0 → 100644 +9 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ===================== I3C device driver API ===================== .. kernel-doc:: include/linux/i3c/device.h .. kernel-doc:: drivers/i3c/device.c
Documentation/driver-api/i3c/index.rst 0 → 100644 +11 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ============= I3C subsystem ============= .. toctree:: protocol device-driver-api master-driver-api
Documentation/driver-api/i3c/master-driver-api.rst 0 → 100644 +9 −0 Original line number Diff line number Diff line .. SPDX-License-Identifier: GPL-2.0 ================================ I3C master controller driver API ================================ .. kernel-doc:: drivers/i3c/master.c .. kernel-doc:: include/linux/i3c/master.h
