[PATCH v7 1/7] i3c: master: secondary master initialization document

[Parshuram Thombare <pthombar@cadence.com>]

Document describing secondary master initialization,
mastership handover and DEFSLVS handling processes.

Signed-off-by: Parshuram Thombare <pthombar@cadence.com>
---
 Documentation/driver-api/i3c/index.rst        |   1 +
 .../i3c/secondary-master-initialization.rst   | 118 ++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 Documentation/driver-api/i3c/secondary-master-initialization.rst

diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst
index 783d6dad054b..af2a0aa68f5b 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
+   secondary-master-initialization
diff --git a/Documentation/driver-api/i3c/secondary-master-initialization.rst b/Documentation/driver-api/i3c/secondary-master-initialization.rst
new file mode 100644
index 000000000000..9d1869550807
--- /dev/null
+++ b/Documentation/driver-api/i3c/secondary-master-initialization.rst
@@ -0,0 +1,118 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+I3C Secondary Master Initialization
+===================================
+
++-----------------------------------------+-------------------------------------------+
+| **Main master**                         | **Secondary master**                      |
++=========================================+===========================================+
+|                                         |                                           |
+| | Do I3C master controller specific     | | Do I3C master controller specefic       |
+|   initialization.                       |   initialization, except enabling         |
+|                                         |   the DEFSLVS interrupt.                  |
+| | Call i3c_master_register              | | Call i3c_secondary_master_register      |
+|                                         |                                           |
+|   *i3c_master_register*                 |   *i3c_secondary_master_register*         |
+|    | Initialize I3C master controller   |    | Initialize I3C master controller     |
+|      object.                            |      object.                              |
+|    | Scan I3C and I2C devices from DTS. |    | Scan I2C devices from DTS.           |
+|    | Set appropriate bus mode based on  |    | Set appropriate bus mode based on    |
+|      I2C devices information.           |      I3C and I2C devices information.     |
+|    | Create a work queue.               |    | Create a work queue.                 |
+|    | Call i3c_master_bus_init           |    | Call i3c_secondary_master_bus_init   |
+|                                         |                                           |
+|      *i3c_master_bus_init*              |      *i3c_secondary_master_bus_init*      |
+|       | Call bus_init to do controller  |       | Call bus_init to do controller    |
+|         specific bus initialization and |         specific bus initialization and   |
+|         enabling the controller.        |         enabling the controller.          |
+|       | Create I3C device representing a|       | Create I3C device representing a  |
+|         master and add it to the I3C    |         master and add it to the I3C      |
+|         device list.                    |         device list.                      |
+|       | Set current master to the device|                                           |
+|         created to represent I3C master |    | Allocate memory for 'defslvs_data',  |
+|         device.                         |      that will be used to pass I3C        |
+|       | Reset all dynamic address that  |      device list received in DEFSLVS      |
+|         may have been assigned before.  |      to I3C core DEFSLVS processing       |
+|       | Disable all slave events before |    | Add I3C device representing this     |
+|         starting DAA.                   |      master to the system.                |
+|       | Pre-assign dynamic address and  |    | Expose our I3C bus as an I2C adapter |
+|         retrieve device information if  |      so that I2C devices are exposed      |
+|         needed.                         |      through the I2C subsystem.           |
+|       | Do dynamic address assignment to|                                           |
+|         all I3C devices currenly present| | Enable DEFSLVS interrupt.               |
+|         on the bus.                     |                                           |
+|       | Create I3C devices representing |                                           |
+|         those found during DAA.         +-------------------------------------------+
+|       | Send DEFSVLS message            | | *DEFSLVS interrupt*                     |
+|         containing information about all| | Controller driver can chose how to      |
+|         known I3C and I2C devices.      |   to handle I2C devices received in       |
+|                                         |   DEFSLVS e.g. Cadence's controller       |
+|                                         |   driver ignore I2C devices from          |
+|                                         |   DEFSLVS and only uses I2C device        |
+|                                         |   information from DTS.                   |
+|                                         | | Read all I3C devices information        |
+|                                         |   from DEFSLVS message in hardware to     |
+|                                         |   defslvs_data in master object.          |
+|                                         | | Call i3c_master_process_defslvs         |
+|                                         |                                           |
+|                                         |   *i3c_master_process_defslvs*            |
+|                                         |    | Acquire I3c bus                      |
+|                                         |                                           |
+|                                         |      *i3c_master_acquire_bus*             |
+|    | Add I3C device representing this   |       | If device is already holding the  |
+|      master to the system.              |         mastership, just broadcast DISEC  |
+|    | Expose our I3C bus as an I2C       |         MR, HJ message and return.        |
+|      adapter so that I2C devices are    |       | Check if device has got a address |
+|      exposed through the I2C subsystem. |         by polling with a timeout.        |
+|    | Register all I3C devices.          |                                           |
+|                                         |       | Send MR request: Controller driver|
+|                                         |         should check if it is already in  |
+|                                         |         master mode, to handle the case   |
+|                                         |         of mastership yielded but due to  |
+|                                         |         poll timeout acquire failed.      |
+|                                         |       | If not a master, wait until MR    |
+|                                         |         ENEC is received if currently it  |
+|                                         |         is disabled.                      |
+|    | Broadcast ENEC MR, HJ message.     |       | Send MR request.                  |
++-----------------------------------------+                                           |
+| | *MR request interrupt*                |                                           |
+|                                         |                                           |
+|   *i3c_master_yield_bus*                |                                           |
+|    | Check if this device is still a    |                                           |
+|      master to handle a case of         |                                           |
+|      multiple MR requests from different|                                           |
+|      devices at a same time.            |                                           |
+|    | Broadcast DISEC MR, HJ message.    |                                           |
+|      New master should broadcast ENEC   |                                           |
+|      MR, HJ once it's usage of bus is   |                                           |
+|      done.                              |                                           |
+|    | Get accept mastership acknowldege  |                                           |
+|      from requesting master.            |                                           |
+|    | Mastership hand over is done.      |       | Check if device enter master      |
+|    | In case of failure reenable        |         mode by polling with a timeout.   |
+|      MR requests by broadcasting ENEC   |                                           |
+|      MR, HJ.                            |    Handle I3C device list from DEFSLVS.   |
+|                                         |                                           |
+|                                         |    *i3c_master_populate_bus*              |
+|                                         |     | Free up all I3C addresses to handle |
+|                                         |       address re assignment by main       |
+|                                         |       master.                             |
+|                                         |     | Move all devices from I3C list to a |
+|                                         |       temporary list.                     |
+|                                         |     | For every device from defslvs_data  |
+|                                         |       list except the receiving master    |
+|                                         |       device, retrieve pid and compare it |
+|                                         |       with already known I3C devices from |
+|                                         |       I3C list. If match is found,        |
+|                                         |       allocate new address and move the   |
+|                                         |       device to the original I3C device   |
+|                                         |       list. If no match is found, it is a |
+|                                         |       new device. Register and add it to  |
+|                                         |       the original I3C list.              |
+|                                         |     | At the end if temporary list is not |
+|                                         |       empty, it contains unplugged I3C    |
+|                                         |       device. Deregister and delete them. |
+|                                         |                                           |
+|                                         |     Broadcast ENEC MR, HJ message.        |
++-----------------------------------------+-------------------------------------------+
-- 
2.17.1