On Mon, 11 May 2020 15:12:39 +0200 Parshuram Thombare <pthom...@cadence.com> wrote:
> Document describing secondary master initialization, > mastership handover and DEFSLVS handling processes. Thanks for doing that, but you probably didn't try to compile the doc (the formatting is all messed up). # make htmldocs and then check the output in Documentation/output/ (open index.html with a web-browser and go to the i3c section). > > 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. | > ++-----------------------------------------+-------------------------------------------+