[5/5] Documentation: i3c: Add I3C slave mode controller and function

Message ID 20231018215809.3477437-6-Frank.Li@nxp.com
State New
Headers
Series I3C slave mode support |

Commit Message

Frank Li Oct. 18, 2023, 9:58 p.m. UTC
  Add I3C slave mode and tty over i3c func driver document.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
 Documentation/driver-api/i3c/index.rst        |   1 +
 .../driver-api/i3c/slave/i3c-slave-cfs.rst    | 109 ++++++++++
 .../driver-api/i3c/slave/i3c-slave.rst        | 189 ++++++++++++++++++
 .../driver-api/i3c/slave/i3c-tty-function.rst | 103 ++++++++++
 .../driver-api/i3c/slave/i3c-tty-howto.rst    | 109 ++++++++++
 Documentation/driver-api/i3c/slave/index.rst  |  13 ++
 6 files changed, 524 insertions(+)
 create mode 100644 Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
 create mode 100644 Documentation/driver-api/i3c/slave/i3c-slave.rst
 create mode 100644 Documentation/driver-api/i3c/slave/i3c-tty-function.rst
 create mode 100644 Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
 create mode 100644 Documentation/driver-api/i3c/slave/index.rst
  

Comments

Frank Li Oct. 18, 2023, 10:07 p.m. UTC | #1
On Wed, Oct 18, 2023 at 05:58:09PM -0400, Frank Li wrote:
> Add I3C slave mode and tty over i3c func driver document.
> 
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
>  Documentation/driver-api/i3c/index.rst        |   1 +
>  .../driver-api/i3c/slave/i3c-slave-cfs.rst    | 109 ++++++++++
>  .../driver-api/i3c/slave/i3c-slave.rst        | 189 ++++++++++++++++++
>  .../driver-api/i3c/slave/i3c-tty-function.rst | 103 ++++++++++
>  .../driver-api/i3c/slave/i3c-tty-howto.rst    | 109 ++++++++++
>  Documentation/driver-api/i3c/slave/index.rst  |  13 ++
>  6 files changed, 524 insertions(+)
>  create mode 100644 Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
>  create mode 100644 Documentation/driver-api/i3c/slave/i3c-slave.rst
>  create mode 100644 Documentation/driver-api/i3c/slave/i3c-tty-function.rst

Please omit i3c-tty-function.rst. This one accidently add to here.
I will remove it at next version.

>  create mode 100644 Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
>  create mode 100644 Documentation/driver-api/i3c/slave/index.rst
> 
> diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst
> index 783d6dad054b6..63fc51fc8bd58 100644
> --- a/Documentation/driver-api/i3c/index.rst
> +++ b/Documentation/driver-api/i3c/index.rst
> @@ -9,3 +9,4 @@ I3C subsystem
>     protocol
>     device-driver-api
>     master-driver-api
> +   slave/index
> diff --git a/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst b/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
> new file mode 100644
> index 0000000000000..d78fcbc4e5587
> --- /dev/null
> +++ b/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
> @@ -0,0 +1,109 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======================================
> +Configuring I3C Slave Using CONFIGFS
> +=======================================
> +
> +:Author: Frank Li <Frank.Li@nxp.com>
> +
> +The I3C Slave Core exposes configfs entry (i3c_slave) to configure the I3C
> +slave function and to bind the slave function
> +with the slave controller. (For introducing other mechanisms to
> +configure the I3C Slave Function refer to [1]).
> +
> +Mounting configfs
> +=================
> +
> +The I3C Slave Core layer creates i3c_slave directory in the mounted configfs
> +directory. configfs can be mounted using the following command::
> +
> +	mount -t configfs none /sys/kernel/config
> +
> +Directory Structure
> +===================
> +
> +The i3c_slave configfs has two directories at its root: controllers and
> +functions. Every Controller device present in the system will have an entry in
> +the *controllers* directory and every Function driver present in the system
> +will have an entry in the *functions* directory.
> +::
> +
> +	/sys/kernel/config/i3c_slave/
> +		.. controllers/
> +		.. functions/
> +
> +Creating Function Device
> +===================
> +
> +Every registered Function driver will be listed in controllers directory. The
> +entries corresponding to Function driver will be created by the Function core.
> +::
> +
> +	/sys/kernel/config/i3c_slave/functions/
> +		.. <Function Driver1>/
> +			... <Function Device 11>/
> +			... <Function Device 21>/
> +			... <Function Device 31>/
> +		.. <Function Driver2>/
> +			... <Function Device 12>/
> +			... <Function Device 22>/
> +
> +In order to create a <Function device> of the type probed by <Function Driver>,
> +the user has to create a directory inside <Function DriverN>.
> +
> +Every <Function device> directory consists of the following entries that can be
> +used to configure the standard configuration header of the slave function.
> +(These entries are created by the framework when any new <Function Device> is
> +created)
> +::
> +
> +		.. <Function Driver1>/
> +			... <Function Device 11>/
> +				... vendor_id
> +				... part_id
> +				... bcr
> +				... dcr
> +				... ext_id
> +				... instance_id
> +				... max_read_len
> +				... max_write_len
> +				... vendor_info
> +
> +Controller Device
> +==========
> +
> +Every registered Controller device will be listed in controllers directory. The
> +entries corresponding to Controller device will be created by the Controller
> +core.
> +::
> +
> +	/sys/kernel/config/i3c_slave/controllers/
> +		.. <Controller Device1>/
> +			... <Symlink Function Device11>/
> +		.. <Controller Device2>/
> +			... <Symlink Function Device21>/
> +
> +The <Controller Device> directory will have a list of symbolic links to
> +<Function Device>. These symbolic links should be created by the user to
> +represent the functions present in the slave device. Only <Function Device>
> +that represents a physical function can be linked to a Controller device.
> +
> +::
> +
> +			 | controllers/
> +				| <Directory: Controller name>/
> +					| <Symbolic Link: Function>
> +			 | functions/
> +				| <Directory: Function driver>/
> +					| <Directory: Function device>/
> +						| vendor_id
> +						| part_id
> +						| bcr
> +						| dcr
> +						| ext_id
> +						| instance_id
> +						| max_read_len
> +						| max_write_len
> +						| vendor_info
> +
> +[1] Documentation/I3C/slave/pci-slave.rst
> diff --git a/Documentation/driver-api/i3c/slave/i3c-slave.rst b/Documentation/driver-api/i3c/slave/i3c-slave.rst
> new file mode 100644
> index 0000000000000..363421241b594
> --- /dev/null
> +++ b/Documentation/driver-api/i3c/slave/i3c-slave.rst
> @@ -0,0 +1,189 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +:Author: Frank Li <Frank.Li@nxp.com>
> +
> +This document is a guide to use the I3C Slave Framework in order to create
> +slave controller driver, slave function driver, and using configfs
> +interface to bind the function driver to the controller driver.
> +
> +Introduction
> +============
> +
> +Linux has a comprehensive I3C subsystem to support I3C controllers that
> +operates in master mode. The subsystem has capability to scan I3C bus,assign
> +i3c device address, load I3C driver (based on Manufacturer ID, part ID),
> +support other services like hot-join, In-Band Interrupt(IBI).
> +
> +However the I3C controller IP integrated in some SoCs is capable of operating
> +either in Master mode or Slave mode. I3C Slave Framework will add slave mode
> +support in Linux. This will help to run Linux in an slave system which can
> +have a wide variety of use cases from testing or validation, co-processor
> +accelerator, etc.
> +
> +I3C Slave Core
> +=================
> +
> +The I3C Slave Core layer comprises 3 components: the Slave Controller
> +library, the Slave Function library, and the configfs layer to bind the
> +slave function with the slave controller.
> +
> +I3C Slave Controller Library
> +------------------------------------
> +
> +The Controller library provides APIs to be used by the controller that can
> +operate in slave mode. It also provides APIs to be used by function
> +driver/library in order to implement a particular slave function.
> +
> +APIs for the I3C Slave controller Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This section lists the APIs that the I3C Slave core provides to be used
> +by the I3C controller driver.
> +
> +* devm_i3c_slave_ctrl_create()/i3c_slave_ctrl_create()
> +
> +   The I3C controller driver should implement the following ops:
> +
> +	* set_config: ops to set i3c configuration
> +	* enable: ops to enable controller
> +	* disable: ops to disable controller
> +	* raise_ibi: ops to raise IBI to master controller
> +	* alloc_request: ops to alloc a transfer request
> +	* free_request: ops to free a transfer request
> +	* queue: ops to queue a request to transfer queue
> +	* dequeue: ops to dequeue a request from transfer queue
> +	* cancel_all_reqs: ops to cancel all request from transfer queue
> +        * fifo_status: ops to get fifo status
> +        * fifo_flush: ops to flush hardware fifo
> +	* get_features: ops to get controller supported features
> +
> +   The I3C controller driver can then create a new Controller device by
> +   invoking devm_i3c_slave_ctrl_create()/i3c_slave_ctrl_create().
> +
> +* devm_i3c_slave_ctrl_destroy()/i3c_slave_ctrl_destroy()
> +
> +   The I3C controller driver can destroy the Controller device created by
> +   either devm_i3c_slave_ctrl_create() or i3c_slave_ctrl_create() using
> +   devm_i3c_slave_ctrl_destroy() or i3c_slave_ctrl_destroy().
> +
> +I3C Slave Controller APIs for the I3C Slave Function Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This section lists the APIs that the I3C Slave core provides to be used
> +by the I3C slave function driver.
> +
> +* i3c_slave_ctrl_set_config()
> +
> +   The I3C slave function driver should use i3c_slave_ctrl_set_config() to
> +   write i3c configuration to the slave controller.
> +
> +* i3c_slave_ctrl_enable()/i3c_slave_ctrl_disable()
> +
> +   The I3C slave function driver should use i3c_slave_ctrl_enable()/
> +   i3c_slave_ctrl_disable() to enable/disable i3c slave controller.
> +
> +* i3c_slave_ctrl_alloc_request()/i3c_slave_ctrl_free_request()
> +
> +   The I3C slave function driver should usei3c_slave_ctrl_alloc_request() /
> +   i3c_slave_ctrl_free_request() to alloc/free a i3c request.
> +
> +* i3c_slave_ctrl_raise_ibi()
> +
> +   The I3C slave function driver should use i3c_slave_ctrl_raise_ibi() to
> +   raise IBI.
> +
> +* i3c_slave_ctrl_queue()/i3c_slave_ctrl_dequeue()
> +
> +   The I3C slave function driver should use i3c_slave_ctrl_queue()/
> +   i3c_slave_ctrl_dequeue(), to queue/dequeue I3C transfer to/from transfer
> +   queue.
> +
> +* i3c_slave_ctrl_get_features()
> +
> +   The I3C slave function driver should use i3c_slave_ctrl_get_features()
> +   to get I3C slave controller supported features.
> +
> +Other I3C Slave Controller APIs
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +There are other APIs provided by the Controller library. These are used for
> +binding the I3C Slave Function device with Controlller device. i3c-cfs.c can
> +be used as reference for using these APIs.
> +
> +* i3c_slave_ctrl_get()
> +
> +   Get a reference to the I3C slave controller based on the device name of
> +   the controller.
> +
> +* i3c_slave_ctrl_put()
> +
> +   Release the reference to the I3C slave controller obtained using
> +   i3c_slave_ctrl_get()
> +
> +* i3c_slave_ctrl_add_func()
> +
> +   Add a I3C slave function to a I3C slave controller.
> +
> +* i3c_slave_ctrl_remove_func()
> +
> +   Remove the I3C slave function from I3C slave controller.
> +
> +I3C Slave Function Library
> +----------------------------------
> +
> +The I3C Slave Function library provides APIs to be used by the function driver
> +and the Controller library to provide slave mode functionality.
> +
> +I3C Slave Function APIs for the I3C Slave Function Driver
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This section lists the APIs that the I3C Slave core provides to be used
> +by the I3C slave function driver.
> +
> +* i3c_slave_func_register_driver()
> +
> +   The I3C Slave Function driver should implement the following ops:
> +	 * bind: ops to perform when a Controller device has been bound to
> +	   Function device
> +	 * unbind: ops to perform when a binding has been lost between a
> +	   Controller device and Function device
> +
> +  The I3C Function driver can then register the I3C Function driver by using
> +  i3c_slave_func_register_driver().
> +
> +* i3c_slave_func_unregister_driver()
> +
> +  The I3C Function driver can unregister the I3C Function driver by using
> +  i3c_epf_unregister_driver().
> +
> +APIs for the I3C Slave Controller Library
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +This section lists the APIs that the I3C Slave core provides to be used
> +by the I3C slave controller library.
> +
> +Other I3C Slave APIs
> +~~~~~~~~~~~~~~~~~~~~
> +
> +There are other APIs provided by the Function library. These are used to
> +notify the function driver when the Function device is bound to the EPC device.
> +i3c-cfs.c can be used as reference for using these APIs.
> +
> +* i3c_slave_func_create()
> +
> +   Create a new I3C Function device by passing the name of the I3C EPF device.
> +   This name will be used to bind the Function device to a Function driver.
> +
> +* i3c_slave_func_destroy()
> +
> +   Destroy the created I3C Function device.
> +
> +* i3c_slave_func_bind()
> +
> +   i3c_slave_func_bind() should be invoked when the EPF device has been bound
> +   to a Controller device.
> +
> +* i3c_slave_func_unbind()
> +
> +   i3c_slave_func_unbind() should be invoked when the binding between EPC
> +   device and function device is lost.
> diff --git a/Documentation/driver-api/i3c/slave/i3c-tty-function.rst b/Documentation/driver-api/i3c/slave/i3c-tty-function.rst
> new file mode 100644
> index 0000000000000..3c8521d7aa31a
> --- /dev/null
> +++ b/Documentation/driver-api/i3c/slave/i3c-tty-function.rst
> @@ -0,0 +1,103 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=================
> +PCI Test Function
> +=================
> +
> +:Author: Kishon Vijay Abraham I <kishon@ti.com>
> +
> +Traditionally PCI RC has always been validated by using standard
> +PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
> +However with the addition of EP-core in linux kernel, it is possible
> +to configure a PCI controller that can operate in EP mode to work as
> +a test device.
> +
> +The PCI endpoint test device is a virtual device (defined in software)
> +used to test the endpoint functionality and serve as a sample driver
> +for other PCI endpoint devices (to use the EP framework).
> +
> +The PCI endpoint test device has the following registers:
> +
> +	1) PCI_ENDPOINT_TEST_MAGIC
> +	2) PCI_ENDPOINT_TEST_COMMAND
> +	3) PCI_ENDPOINT_TEST_STATUS
> +	4) PCI_ENDPOINT_TEST_SRC_ADDR
> +	5) PCI_ENDPOINT_TEST_DST_ADDR
> +	6) PCI_ENDPOINT_TEST_SIZE
> +	7) PCI_ENDPOINT_TEST_CHECKSUM
> +	8) PCI_ENDPOINT_TEST_IRQ_TYPE
> +	9) PCI_ENDPOINT_TEST_IRQ_NUMBER
> +
> +* PCI_ENDPOINT_TEST_MAGIC
> +
> +This register will be used to test BAR0. A known pattern will be written
> +and read back from MAGIC register to verify BAR0.
> +
> +* PCI_ENDPOINT_TEST_COMMAND
> +
> +This register will be used by the host driver to indicate the function
> +that the endpoint device must perform.
> +
> +========	================================================================
> +Bitfield	Description
> +========	================================================================
> +Bit 0		raise legacy IRQ
> +Bit 1		raise MSI IRQ
> +Bit 2		raise MSI-X IRQ
> +Bit 3		read command (read data from RC buffer)
> +Bit 4		write command (write data to RC buffer)
> +Bit 5		copy command (copy data from one RC buffer to another RC buffer)
> +========	================================================================
> +
> +* PCI_ENDPOINT_TEST_STATUS
> +
> +This register reflects the status of the PCI endpoint device.
> +
> +========	==============================
> +Bitfield	Description
> +========	==============================
> +Bit 0		read success
> +Bit 1		read fail
> +Bit 2		write success
> +Bit 3		write fail
> +Bit 4		copy success
> +Bit 5		copy fail
> +Bit 6		IRQ raised
> +Bit 7		source address is invalid
> +Bit 8		destination address is invalid
> +========	==============================
> +
> +* PCI_ENDPOINT_TEST_SRC_ADDR
> +
> +This register contains the source address (RC buffer address) for the
> +COPY/READ command.
> +
> +* PCI_ENDPOINT_TEST_DST_ADDR
> +
> +This register contains the destination address (RC buffer address) for
> +the COPY/WRITE command.
> +
> +* PCI_ENDPOINT_TEST_IRQ_TYPE
> +
> +This register contains the interrupt type (Legacy/MSI) triggered
> +for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
> +
> +Possible types:
> +
> +======	==
> +Legacy	0
> +MSI	1
> +MSI-X	2
> +======	==
> +
> +* PCI_ENDPOINT_TEST_IRQ_NUMBER
> +
> +This register contains the triggered ID interrupt.
> +
> +Admissible values:
> +
> +======	===========
> +Legacy	0
> +MSI	[1 .. 32]
> +MSI-X	[1 .. 2048]
> +======	===========
> diff --git a/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst b/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
> new file mode 100644
> index 0000000000000..11c8900fd16f3
> --- /dev/null
> +++ b/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
> @@ -0,0 +1,109 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===================
> +I3C TTY User Guide
> +===================
> +
> +:Author: Frank Li <Frank.Li@nxp.com>
> +
> +This document is a guide to help users use i3c-slave-tty function driver
> +and i3ctty master driver for testing I3C. The list of steps to be followed in the
> +master side and slave side is given below.
> +
> +Endpoint Device
> +===============
> +
> +Endpoint Controller Devices
> +---------------------------
> +
> +To find the list of slave controller devices in the system::
> +
> +	# ls  /sys/class/i3c_slave/
> +	  44330000.i3c-slave
> +
> +If CONFIG_I3C_SLAVE_CONFIGFS is enabled::
> +
> +	# ls /sys/kernel/config/i3c_slave/controllers/
> +	  44330000.i3c-slave
> +
> +
> +Endpoint Function Drivers
> +-------------------------
> +
> +To find the list of slave function drivers in the system::
> +
> +	# ls /sys/bus/i3c_slave_func/drivers
> +	  tty
> +
> +If CONFIG_I3C_SLAVE_CONFIGFS is enabled::
> +
> +	# ls /sys/kernel/config/i3c_slave/functions
> +	  tty
> +
> +
> +Creating i3c-slave-tty Device
> +----------------------------
> +
> +I3C slave function device can be created using the configfs. To create
> +i3c-slave-tty device, the following commands can be used::
> +
> +	# mount -t configfs none /sys/kernel/config
> +	# cd /sys/kernel/config/i3c_slave/
> +	# mkdir functions/tty/func1
> +
> +The "mkdir func1" above creates the i3c-slave-tty function device that will
> +be probed by i3c tty driver.
> +
> +The I3C slave framework populates the directory with the following
> +configurable fields::
> +
> +	# ls functions/tty/func1
> +	bcr  dcr  ext_id  instance_id  max_read_len  max_write_len
> +	part_id  vendor_id  vendor_info
> +
> +The I3C slave function driver populates these entries with default values
> +when the device is bound to the driver. The i3c-slave-tty driver populates
> +vendorid with 0xffff and interrupt_pin with 0x0001::
> +
> +	# cat functions/tty/func1/vendor_id
> +	  0x0
> +
> +Configuring i3c-slave-tty Device
> +-------------------------------
> +
> +The user can configure the i3c-slave-tty device using configfs entry. In order
> +to change the vendorid, the following commands can be used::
> +
> +	# echo 0x011b > functions/tty/func1/vendor_id
> +	# echo 0x1000 > functions/tty/func1/part_id
> +	# echo 0x6 > functions/tty/t/bcr
> +
> +Binding i3c-slave-tty Device to slave Controller
> +------------------------------------------------
> +
> +In order for the slave function device to be useful, it has to be bound to
> +a I3C slave controller driver. Use the configfs to bind the function
> +device to one of the controller driver present in the system::
> +
> +	# ln -s functions/pci_epf_test/func1 controllers/44330000.i3c-slave/
> +
> +I3C Master Device
> +================
> +
> +Check I3C tty device is probed
> +
> +	# ls /sys/bus/i3c/devices/0-23610000000
> +	0-23610000000:0  bcr  dcr  driver  dynamic_address  hdrcap
> +	modalias  pid  power  subsystem  tty  uevent
> +
> +Using Slave TTY function Device
> +-----------------------------------
> +
> +Host side:
> +	cat /dev/ttyI3C0
> +Slave side
> +	echo abc >/dev/ttyI3C0
> +
> +You will see "abc" show at console.
> +
> +You can use other tty tool to test I3C slave tty device.
> diff --git a/Documentation/driver-api/i3c/slave/index.rst b/Documentation/driver-api/i3c/slave/index.rst
> new file mode 100644
> index 0000000000000..69727ccf985db
> --- /dev/null
> +++ b/Documentation/driver-api/i3c/slave/index.rst
> @@ -0,0 +1,13 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================
> +I3C Slave Framework
> +======================
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   i3c-slave
> +   i3c-slave-cfs
> +   i3c-tty-howto
> +
> -- 
> 2.34.1
>
  

Patch

diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst
index 783d6dad054b6..63fc51fc8bd58 100644
--- a/Documentation/driver-api/i3c/index.rst
+++ b/Documentation/driver-api/i3c/index.rst
@@ -9,3 +9,4 @@  I3C subsystem
    protocol
    device-driver-api
    master-driver-api
+   slave/index
diff --git a/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst b/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
new file mode 100644
index 0000000000000..d78fcbc4e5587
--- /dev/null
+++ b/Documentation/driver-api/i3c/slave/i3c-slave-cfs.rst
@@ -0,0 +1,109 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Configuring I3C Slave Using CONFIGFS
+=======================================
+
+:Author: Frank Li <Frank.Li@nxp.com>
+
+The I3C Slave Core exposes configfs entry (i3c_slave) to configure the I3C
+slave function and to bind the slave function
+with the slave controller. (For introducing other mechanisms to
+configure the I3C Slave Function refer to [1]).
+
+Mounting configfs
+=================
+
+The I3C Slave Core layer creates i3c_slave directory in the mounted configfs
+directory. configfs can be mounted using the following command::
+
+	mount -t configfs none /sys/kernel/config
+
+Directory Structure
+===================
+
+The i3c_slave configfs has two directories at its root: controllers and
+functions. Every Controller device present in the system will have an entry in
+the *controllers* directory and every Function driver present in the system
+will have an entry in the *functions* directory.
+::
+
+	/sys/kernel/config/i3c_slave/
+		.. controllers/
+		.. functions/
+
+Creating Function Device
+===================
+
+Every registered Function driver will be listed in controllers directory. The
+entries corresponding to Function driver will be created by the Function core.
+::
+
+	/sys/kernel/config/i3c_slave/functions/
+		.. <Function Driver1>/
+			... <Function Device 11>/
+			... <Function Device 21>/
+			... <Function Device 31>/
+		.. <Function Driver2>/
+			... <Function Device 12>/
+			... <Function Device 22>/
+
+In order to create a <Function device> of the type probed by <Function Driver>,
+the user has to create a directory inside <Function DriverN>.
+
+Every <Function device> directory consists of the following entries that can be
+used to configure the standard configuration header of the slave function.
+(These entries are created by the framework when any new <Function Device> is
+created)
+::
+
+		.. <Function Driver1>/
+			... <Function Device 11>/
+				... vendor_id
+				... part_id
+				... bcr
+				... dcr
+				... ext_id
+				... instance_id
+				... max_read_len
+				... max_write_len
+				... vendor_info
+
+Controller Device
+==========
+
+Every registered Controller device will be listed in controllers directory. The
+entries corresponding to Controller device will be created by the Controller
+core.
+::
+
+	/sys/kernel/config/i3c_slave/controllers/
+		.. <Controller Device1>/
+			... <Symlink Function Device11>/
+		.. <Controller Device2>/
+			... <Symlink Function Device21>/
+
+The <Controller Device> directory will have a list of symbolic links to
+<Function Device>. These symbolic links should be created by the user to
+represent the functions present in the slave device. Only <Function Device>
+that represents a physical function can be linked to a Controller device.
+
+::
+
+			 | controllers/
+				| <Directory: Controller name>/
+					| <Symbolic Link: Function>
+			 | functions/
+				| <Directory: Function driver>/
+					| <Directory: Function device>/
+						| vendor_id
+						| part_id
+						| bcr
+						| dcr
+						| ext_id
+						| instance_id
+						| max_read_len
+						| max_write_len
+						| vendor_info
+
+[1] Documentation/I3C/slave/pci-slave.rst
diff --git a/Documentation/driver-api/i3c/slave/i3c-slave.rst b/Documentation/driver-api/i3c/slave/i3c-slave.rst
new file mode 100644
index 0000000000000..363421241b594
--- /dev/null
+++ b/Documentation/driver-api/i3c/slave/i3c-slave.rst
@@ -0,0 +1,189 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+:Author: Frank Li <Frank.Li@nxp.com>
+
+This document is a guide to use the I3C Slave Framework in order to create
+slave controller driver, slave function driver, and using configfs
+interface to bind the function driver to the controller driver.
+
+Introduction
+============
+
+Linux has a comprehensive I3C subsystem to support I3C controllers that
+operates in master mode. The subsystem has capability to scan I3C bus,assign
+i3c device address, load I3C driver (based on Manufacturer ID, part ID),
+support other services like hot-join, In-Band Interrupt(IBI).
+
+However the I3C controller IP integrated in some SoCs is capable of operating
+either in Master mode or Slave mode. I3C Slave Framework will add slave mode
+support in Linux. This will help to run Linux in an slave system which can
+have a wide variety of use cases from testing or validation, co-processor
+accelerator, etc.
+
+I3C Slave Core
+=================
+
+The I3C Slave Core layer comprises 3 components: the Slave Controller
+library, the Slave Function library, and the configfs layer to bind the
+slave function with the slave controller.
+
+I3C Slave Controller Library
+------------------------------------
+
+The Controller library provides APIs to be used by the controller that can
+operate in slave mode. It also provides APIs to be used by function
+driver/library in order to implement a particular slave function.
+
+APIs for the I3C Slave controller Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the I3C Slave core provides to be used
+by the I3C controller driver.
+
+* devm_i3c_slave_ctrl_create()/i3c_slave_ctrl_create()
+
+   The I3C controller driver should implement the following ops:
+
+	* set_config: ops to set i3c configuration
+	* enable: ops to enable controller
+	* disable: ops to disable controller
+	* raise_ibi: ops to raise IBI to master controller
+	* alloc_request: ops to alloc a transfer request
+	* free_request: ops to free a transfer request
+	* queue: ops to queue a request to transfer queue
+	* dequeue: ops to dequeue a request from transfer queue
+	* cancel_all_reqs: ops to cancel all request from transfer queue
+        * fifo_status: ops to get fifo status
+        * fifo_flush: ops to flush hardware fifo
+	* get_features: ops to get controller supported features
+
+   The I3C controller driver can then create a new Controller device by
+   invoking devm_i3c_slave_ctrl_create()/i3c_slave_ctrl_create().
+
+* devm_i3c_slave_ctrl_destroy()/i3c_slave_ctrl_destroy()
+
+   The I3C controller driver can destroy the Controller device created by
+   either devm_i3c_slave_ctrl_create() or i3c_slave_ctrl_create() using
+   devm_i3c_slave_ctrl_destroy() or i3c_slave_ctrl_destroy().
+
+I3C Slave Controller APIs for the I3C Slave Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the I3C Slave core provides to be used
+by the I3C slave function driver.
+
+* i3c_slave_ctrl_set_config()
+
+   The I3C slave function driver should use i3c_slave_ctrl_set_config() to
+   write i3c configuration to the slave controller.
+
+* i3c_slave_ctrl_enable()/i3c_slave_ctrl_disable()
+
+   The I3C slave function driver should use i3c_slave_ctrl_enable()/
+   i3c_slave_ctrl_disable() to enable/disable i3c slave controller.
+
+* i3c_slave_ctrl_alloc_request()/i3c_slave_ctrl_free_request()
+
+   The I3C slave function driver should usei3c_slave_ctrl_alloc_request() /
+   i3c_slave_ctrl_free_request() to alloc/free a i3c request.
+
+* i3c_slave_ctrl_raise_ibi()
+
+   The I3C slave function driver should use i3c_slave_ctrl_raise_ibi() to
+   raise IBI.
+
+* i3c_slave_ctrl_queue()/i3c_slave_ctrl_dequeue()
+
+   The I3C slave function driver should use i3c_slave_ctrl_queue()/
+   i3c_slave_ctrl_dequeue(), to queue/dequeue I3C transfer to/from transfer
+   queue.
+
+* i3c_slave_ctrl_get_features()
+
+   The I3C slave function driver should use i3c_slave_ctrl_get_features()
+   to get I3C slave controller supported features.
+
+Other I3C Slave Controller APIs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are other APIs provided by the Controller library. These are used for
+binding the I3C Slave Function device with Controlller device. i3c-cfs.c can
+be used as reference for using these APIs.
+
+* i3c_slave_ctrl_get()
+
+   Get a reference to the I3C slave controller based on the device name of
+   the controller.
+
+* i3c_slave_ctrl_put()
+
+   Release the reference to the I3C slave controller obtained using
+   i3c_slave_ctrl_get()
+
+* i3c_slave_ctrl_add_func()
+
+   Add a I3C slave function to a I3C slave controller.
+
+* i3c_slave_ctrl_remove_func()
+
+   Remove the I3C slave function from I3C slave controller.
+
+I3C Slave Function Library
+----------------------------------
+
+The I3C Slave Function library provides APIs to be used by the function driver
+and the Controller library to provide slave mode functionality.
+
+I3C Slave Function APIs for the I3C Slave Function Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the I3C Slave core provides to be used
+by the I3C slave function driver.
+
+* i3c_slave_func_register_driver()
+
+   The I3C Slave Function driver should implement the following ops:
+	 * bind: ops to perform when a Controller device has been bound to
+	   Function device
+	 * unbind: ops to perform when a binding has been lost between a
+	   Controller device and Function device
+
+  The I3C Function driver can then register the I3C Function driver by using
+  i3c_slave_func_register_driver().
+
+* i3c_slave_func_unregister_driver()
+
+  The I3C Function driver can unregister the I3C Function driver by using
+  i3c_epf_unregister_driver().
+
+APIs for the I3C Slave Controller Library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section lists the APIs that the I3C Slave core provides to be used
+by the I3C slave controller library.
+
+Other I3C Slave APIs
+~~~~~~~~~~~~~~~~~~~~
+
+There are other APIs provided by the Function library. These are used to
+notify the function driver when the Function device is bound to the EPC device.
+i3c-cfs.c can be used as reference for using these APIs.
+
+* i3c_slave_func_create()
+
+   Create a new I3C Function device by passing the name of the I3C EPF device.
+   This name will be used to bind the Function device to a Function driver.
+
+* i3c_slave_func_destroy()
+
+   Destroy the created I3C Function device.
+
+* i3c_slave_func_bind()
+
+   i3c_slave_func_bind() should be invoked when the EPF device has been bound
+   to a Controller device.
+
+* i3c_slave_func_unbind()
+
+   i3c_slave_func_unbind() should be invoked when the binding between EPC
+   device and function device is lost.
diff --git a/Documentation/driver-api/i3c/slave/i3c-tty-function.rst b/Documentation/driver-api/i3c/slave/i3c-tty-function.rst
new file mode 100644
index 0000000000000..3c8521d7aa31a
--- /dev/null
+++ b/Documentation/driver-api/i3c/slave/i3c-tty-function.rst
@@ -0,0 +1,103 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+PCI Test Function
+=================
+
+:Author: Kishon Vijay Abraham I <kishon@ti.com>
+
+Traditionally PCI RC has always been validated by using standard
+PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.
+However with the addition of EP-core in linux kernel, it is possible
+to configure a PCI controller that can operate in EP mode to work as
+a test device.
+
+The PCI endpoint test device is a virtual device (defined in software)
+used to test the endpoint functionality and serve as a sample driver
+for other PCI endpoint devices (to use the EP framework).
+
+The PCI endpoint test device has the following registers:
+
+	1) PCI_ENDPOINT_TEST_MAGIC
+	2) PCI_ENDPOINT_TEST_COMMAND
+	3) PCI_ENDPOINT_TEST_STATUS
+	4) PCI_ENDPOINT_TEST_SRC_ADDR
+	5) PCI_ENDPOINT_TEST_DST_ADDR
+	6) PCI_ENDPOINT_TEST_SIZE
+	7) PCI_ENDPOINT_TEST_CHECKSUM
+	8) PCI_ENDPOINT_TEST_IRQ_TYPE
+	9) PCI_ENDPOINT_TEST_IRQ_NUMBER
+
+* PCI_ENDPOINT_TEST_MAGIC
+
+This register will be used to test BAR0. A known pattern will be written
+and read back from MAGIC register to verify BAR0.
+
+* PCI_ENDPOINT_TEST_COMMAND
+
+This register will be used by the host driver to indicate the function
+that the endpoint device must perform.
+
+========	================================================================
+Bitfield	Description
+========	================================================================
+Bit 0		raise legacy IRQ
+Bit 1		raise MSI IRQ
+Bit 2		raise MSI-X IRQ
+Bit 3		read command (read data from RC buffer)
+Bit 4		write command (write data to RC buffer)
+Bit 5		copy command (copy data from one RC buffer to another RC buffer)
+========	================================================================
+
+* PCI_ENDPOINT_TEST_STATUS
+
+This register reflects the status of the PCI endpoint device.
+
+========	==============================
+Bitfield	Description
+========	==============================
+Bit 0		read success
+Bit 1		read fail
+Bit 2		write success
+Bit 3		write fail
+Bit 4		copy success
+Bit 5		copy fail
+Bit 6		IRQ raised
+Bit 7		source address is invalid
+Bit 8		destination address is invalid
+========	==============================
+
+* PCI_ENDPOINT_TEST_SRC_ADDR
+
+This register contains the source address (RC buffer address) for the
+COPY/READ command.
+
+* PCI_ENDPOINT_TEST_DST_ADDR
+
+This register contains the destination address (RC buffer address) for
+the COPY/WRITE command.
+
+* PCI_ENDPOINT_TEST_IRQ_TYPE
+
+This register contains the interrupt type (Legacy/MSI) triggered
+for the READ/WRITE/COPY and raise IRQ (Legacy/MSI) commands.
+
+Possible types:
+
+======	==
+Legacy	0
+MSI	1
+MSI-X	2
+======	==
+
+* PCI_ENDPOINT_TEST_IRQ_NUMBER
+
+This register contains the triggered ID interrupt.
+
+Admissible values:
+
+======	===========
+Legacy	0
+MSI	[1 .. 32]
+MSI-X	[1 .. 2048]
+======	===========
diff --git a/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst b/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
new file mode 100644
index 0000000000000..11c8900fd16f3
--- /dev/null
+++ b/Documentation/driver-api/i3c/slave/i3c-tty-howto.rst
@@ -0,0 +1,109 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+I3C TTY User Guide
+===================
+
+:Author: Frank Li <Frank.Li@nxp.com>
+
+This document is a guide to help users use i3c-slave-tty function driver
+and i3ctty master driver for testing I3C. The list of steps to be followed in the
+master side and slave side is given below.
+
+Endpoint Device
+===============
+
+Endpoint Controller Devices
+---------------------------
+
+To find the list of slave controller devices in the system::
+
+	# ls  /sys/class/i3c_slave/
+	  44330000.i3c-slave
+
+If CONFIG_I3C_SLAVE_CONFIGFS is enabled::
+
+	# ls /sys/kernel/config/i3c_slave/controllers/
+	  44330000.i3c-slave
+
+
+Endpoint Function Drivers
+-------------------------
+
+To find the list of slave function drivers in the system::
+
+	# ls /sys/bus/i3c_slave_func/drivers
+	  tty
+
+If CONFIG_I3C_SLAVE_CONFIGFS is enabled::
+
+	# ls /sys/kernel/config/i3c_slave/functions
+	  tty
+
+
+Creating i3c-slave-tty Device
+----------------------------
+
+I3C slave function device can be created using the configfs. To create
+i3c-slave-tty device, the following commands can be used::
+
+	# mount -t configfs none /sys/kernel/config
+	# cd /sys/kernel/config/i3c_slave/
+	# mkdir functions/tty/func1
+
+The "mkdir func1" above creates the i3c-slave-tty function device that will
+be probed by i3c tty driver.
+
+The I3C slave framework populates the directory with the following
+configurable fields::
+
+	# ls functions/tty/func1
+	bcr  dcr  ext_id  instance_id  max_read_len  max_write_len
+	part_id  vendor_id  vendor_info
+
+The I3C slave function driver populates these entries with default values
+when the device is bound to the driver. The i3c-slave-tty driver populates
+vendorid with 0xffff and interrupt_pin with 0x0001::
+
+	# cat functions/tty/func1/vendor_id
+	  0x0
+
+Configuring i3c-slave-tty Device
+-------------------------------
+
+The user can configure the i3c-slave-tty device using configfs entry. In order
+to change the vendorid, the following commands can be used::
+
+	# echo 0x011b > functions/tty/func1/vendor_id
+	# echo 0x1000 > functions/tty/func1/part_id
+	# echo 0x6 > functions/tty/t/bcr
+
+Binding i3c-slave-tty Device to slave Controller
+------------------------------------------------
+
+In order for the slave function device to be useful, it has to be bound to
+a I3C slave controller driver. Use the configfs to bind the function
+device to one of the controller driver present in the system::
+
+	# ln -s functions/pci_epf_test/func1 controllers/44330000.i3c-slave/
+
+I3C Master Device
+================
+
+Check I3C tty device is probed
+
+	# ls /sys/bus/i3c/devices/0-23610000000
+	0-23610000000:0  bcr  dcr  driver  dynamic_address  hdrcap
+	modalias  pid  power  subsystem  tty  uevent
+
+Using Slave TTY function Device
+-----------------------------------
+
+Host side:
+	cat /dev/ttyI3C0
+Slave side
+	echo abc >/dev/ttyI3C0
+
+You will see "abc" show at console.
+
+You can use other tty tool to test I3C slave tty device.
diff --git a/Documentation/driver-api/i3c/slave/index.rst b/Documentation/driver-api/i3c/slave/index.rst
new file mode 100644
index 0000000000000..69727ccf985db
--- /dev/null
+++ b/Documentation/driver-api/i3c/slave/index.rst
@@ -0,0 +1,13 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+I3C Slave Framework
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   i3c-slave
+   i3c-slave-cfs
+   i3c-tty-howto
+