Commit b3cc2bfe authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'i3c/for-4.21' of git://git.kernel.org/pub/scm/linux/kernel/git/i3c/linux 

Pull initial i3c support from Boris Brezillon:
 "Add initial support for I3C along with two I3C master controller
  drivers"

* tag 'i3c/for-4.21' of git://git.kernel.org/pub/scm/linux/kernel/git/i3c/linux:
  i3c: master: cdns: fix I2C transfers in Cadence I3C master driver
  ic3: off by one in mode_show()
  i3c: fix an error code in i3c_master_add_i3c_dev_locked()
  i3c: master: dw: fix mask operation by using the correct operator
  MAINTAINERS: Add myself as the dw-i3c-master module maintainer
  dt-binding: i3c: Document Synopsys DesignWare I3C
  i3c: master: Add driver for Synopsys DesignWare IP
  i3c: master: Remove set but not used variable 'old_i3c_scl_lim'
  dt-bindings: i3c: Document Cadence I3C master bindings
  i3c: master: Add driver for Cadence IP
  MAINTAINERS: Add myself as the I3C subsystem maintainer
  dt-bindings: i3c: Document core bindings
  i3c: Add sysfs ABI spec
  docs: driver-api: Add I3C documentation
  i3c: Add core I3C infrastructure
parents 4971f090 25ac3da6

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

Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt

0 → 100644
+43 −0
Original line number Diff line number Diff line 
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>;

		};

	};

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/devicetree/bindings/i3c/snps,dw-i3c-master.txt

0 → 100644
+41 −0
Original line number Diff line number Diff line 
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>;

		};

	};

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

CRA Git | Maintained and supported by SUSTech CRA and CCSE