[PATCH v7 1/7] i3c: master: secondary master initialization document
From: Parshuram Thombare
Date: Mon May 11 2020 - 09:13:03 EST
Document describing secondary master initialization,
mastership handover and DEFSLVS handling processes.
Signed-off-by: Parshuram Thombare <pthombar@xxxxxxxxxxx>
---
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