| Message ID | 20231018215809.3477437-6-Frank.Li@nxp.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | I3C slave mode support | expand |
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 >
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 +
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