[PATCH v6 1/8] i3c: master: mastership handover document

[Parshuram Thombare]

Flow diagram for I3C mastership handover, DEFSLVS
processing and secondary master initialization.

Signed-off-by: Parshuram Thombare <pthombar@xxxxxxxxxxx>
---
 Documentation/driver-api/i3c/index.rst        |   1 +
 .../i3c/mastership-handover-flow-diagram.rst  | 209 ++++++++++++++++++
 2 files changed, 210 insertions(+)
 create mode 100644 Documentation/driver-api/i3c/mastership-handover-flow-diagram.rst

diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst
index 783d6dad054b..9a38c5ba87cb 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
+   mastership-handover-flow-diagram
diff --git a/Documentation/driver-api/i3c/mastership-handover-flow-diagram.rst b/Documentation/driver-api/i3c/mastership-handover-flow-diagram.rst
new file mode 100644
index 000000000000..04cd9f1283e0
--- /dev/null
+++ b/Documentation/driver-api/i3c/mastership-handover-flow-diagram.rst
@@ -0,0 +1,209 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
+I3C mastership handover flow
+============================
+
+Main master		Sec Master1		Sec Master 2
+
+1. Initialize I3C	1. Initialize I3C	1. Initialize I3C
+   bus in Pure mode	   bus in Pure mode	   bus in Pure mode
+
+defslvs_done flag	defslvs_done flag	defslvs_done flag
+    = true			= false		= false
+
+2. Do DAA + SETDASA	2. Spawn init. thread	2. Spawn init. thread
+			Initialization thread	Initialization thread
+			Wait for DEFSLVS	Wait for DEFSLVS
+			processing		processing
+			Wait for		Wait for
+			defslvs_done flag	defslvs_done flag
+				= true		= true
+
+3. Send DEFSLVS		DEFSLVS ISR		DEFSLVS ISR
+			Set flag to indicate	Set flag to indicate
+			DEFSLVS	processing is	DEFSLVS	processing is
+			pending			pending
+			defslvs_done flag	defslvs_done flag
+				= false			= false
+
+			Defer DEFSLVS		Defer DEFSLVS
+			processing to bottom	processing to bottom
+			half			half
+
+
+			DEFSLVS bottom half	DEFSLVS bottom half
+			Try to acquire bus	Try to acquire bus
+			i3c_master_acquire_bus	i3c_master_acquire_bus
+
+
+			i3c_sec_mst_acquire_bus i3c_sec_mst_acquire_bus
+			state machine
+			1. Wait until DA is
+			   assigned
+
+4. Register all
+   slaves and
+   master devive
+
+5. Program bus mode
+   as per board
+   info (DTS)
+
+6. Send ENEC MR,
+   HJ, SIR CCC
+   Initialization
+   complete
+
+			2. Check if DISEC MR	2. Check if DISEC MR
+			   is received		   is received
+			   If not, initiate	   If not, initiate
+			   MR request		   MR request
+
+
+		Sec master with highest priority (lowest address) get
+		mastership. Some controllers may not have way of knowing
+		if mastership is granted and can keep waiting for
+		GETACCMST.To avoid this, on reception of MR request
+		from highest priority secondary master, current master
+		send DISEC MR, HJ events to remaining master devices.
+
+MR request ISR
+1. Disable IBI
+   in controller
+
+MR request
+bottom half
+1. Send DISEC
+   MR, HJ
+   to all but
+   master device
+   to which MR
+   is granted
+						3. Received DISEC MR
+						   Go back to WAIT
+						   DA state
+
+						1. Wait until DA
+						   is assigned
+						2. Check if DISEC MR
+						   is received
+						   Wait until ENEC MR
+						   is received before
+						   sending next MR request
+
+2. Send GETACCMST
+   to secondary		3. Wait for MR DONE
+   master to which
+   mastership is to
+   be granted
+			4. MR granted
+			5. Update
+			   current_master
+
+
+			DEFSLVS bottom half
+			continue...
+			Controller driver read
+			out DEFSLVS data in
+			defslvs_data structure
+
+			Call
+			i3c_master_process_defslvs
+			until it is processed
+			successfully. And set
+			defslvs_done flag = true.
+
+			i3c_master_process_defslvs
+			1. Bus init to correct
+			   mode based on
+			   defslvs data
+			2. Register I2C devices
+			   from defslvs_data
+			   Since I3C devices are not
+			   hot pluggable this is
+			   done only once
+			3. Register all I3C devices
+			   from defslvs_data, make
+			   sure if device is already
+			   registered, i3cdev and
+			   IBI data is retained
+			   i3cdev is the link between
+			   I3C driver and I3C subsystem
+			4. Delete I3C device from
+			   older device list which are
+			   not found in defslvs_data
+			   (Unplugged ?)
+
+			Initialization thread
+			continue...
+			3. Register master device,
+			   and I3C/I2C device created
+			   based on defslvs_data
+			4. Enable controller IBI
+			5. Send ENEC MR, HJ
+			   Initialization complete
+							3. Initiate MR request
+
+
+			MR request ISR
+			Disable IBI in controller
+
+			MR request bottom half
+			Send DISEC MR, HJ to
+			other master devices
+
+			Send GETACCMST to secondary	4. Wait for MR DONE
+			master to which mastership
+			is to be granted
+
+							5. MR granted
+							6. Update
+							   current_master
+
+
+							DEFSLVS bottom half
+							continue...
+							Controller driver read
+							out DEFSLVS data in
+							defslvs_data structure
+
+							Call
+							i3c_master_process_defslvs
+							until it is processed
+							successfully. And set
+							defslvs_done flag = true
+
+							i3c_master_process_defslvs
+							1. Bus init to correct
+							   mode based on
+							   defslvs data
+							2. Register I2C devices
+							   from defslvs_data
+							   Since I3C devices are
+							   not hot pluggable
+							   this is done only once
+							3. Register all I3C devices
+							   from defslvs_data, make
+							   sure if device is
+							   already registered,
+							   i3cdev and IBI data is
+							   retained
+							   i3cdev is the link
+							   between I3C driver and
+							   I3C subsystem
+							4. Delete I3C device from
+							   older device list which
+							   are not found in
+							   defslvs_data
+							   (Unplugged ?)
+
+							Initialization thread
+							continue...
+							3. Register master
+							   device, and I3C/I2C
+							   device created
+							   based on defslvs_data
+							4. Enable controller IBI
+							5. Send ENEC MR, HJ
+							   Initialization complete
-- 
2.17.1