Document describing secondary master initialization,
mastership handover and DEFSLVS handling processes.
Signed-off-by: Parshuram Thombare <pthom...@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
