Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Received-SPF: Pass (protection.outlook.com: domain of cadence.com designates
 199.43.4.23 as permitted sender) receiver=protection.outlook.com;
 client-ip=199.43.4.23; helo=rmmaillnx1.cadence.com;
X-CrossPremisesHeadersFilteredBySendConnector: maileu3.global.cadence.com
Received: from maileu3.global.cadence.com (10.160.88.99) by
 maileu3.global.cadence.com (10.160.88.99) with Microsoft SMTP Server (TLS) id
 15.0.1367.3; Fri, 17 Apr 2020 18:20:44 +0200
Received: from vleu-orange.cadence.com (10.160.88.83) by
 maileu3.global.cadence.com (10.160.88.99) with Microsoft SMTP Server (TLS) id
 15.0.1367.3 via Frontend Transport; Fri, 17 Apr 2020 18:20:44 +0200
Received: from vleu-orange.cadence.com (localhost.localdomain [127.0.0.1])
        by vleu-orange.cadence.com (8.14.4/8.14.4) with ESMTP id 03HGKiwD029988;
        Fri, 17 Apr 2020 18:20:44 +0200
Received: (from pthombar@localhost)
        by vleu-orange.cadence.com (8.14.4/8.14.4/Submit) id 03HGKico029987;
        Fri, 17 Apr 2020 18:20:44 +0200
From:   Parshuram Thombare <pthombar@cadence.com>
To:     <bbrezillon@kernel.org>, <vitor.soares@synopsys.com>
CC:     <pgaj@cadence.com>, <linux-i3c@lists.infradead.org>,
        <linux-kernel@vger.kernel.org>, <mparab@cadence.com>,
        <praneeth@ti.com>, Parshuram Thombare <pthombar@cadence.com>
Subject: [PATCH v6 1/8] i3c: master: mastership handover document
Date:   Fri, 17 Apr 2020 18:20:42 +0200
Message-ID: <1587140442-29932-1-git-send-email-pthombar@cadence.com>
X-Mailer: git-send-email 2.2.2
In-Reply-To: <1587140398-29473-1-git-send-email-pthombar@cadence.com>
References: <1587140398-29473-1-git-send-email-pthombar@cadence.com>
MIME-Version: 1.0
Content-Type: text/plain
X-OrganizationHeadersPreserved: maileu3.global.cadence.com
X-EOPAttributedMessage: 0
X-Forefront-Antispam-Report: CIP:199.43.4.23;CTRY:US;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:rmmaillnx1.cadence.com;PTR:InfoDomainNonexistent;CAT:NONE;SFTY:;SFS:(10009020)(4636009)(39860400002)(136003)(346002)(396003)(376002)(36092001)(46966005)(82740400003)(47076004)(2906002)(81156014)(356005)(81166007)(2616005)(478600001)(4326008)(8676002)(26826003)(426003)(5660300002)(107886003)(36756003)(336012)(86362001)(42186006)(26005)(316002)(36906005)(186003)(54906003)(110136005)(70586007)(8936002)(70206006);DIR:OUT;SFP:1101;
X-MS-PublicTrafficType: Email
X-MS-Office365-Filtering-Correlation-Id: f08ebfe6-314d-4985-de41-08d7e2eb4a2b
X-MS-TrafficTypeDiagnostic: BN7PR07MB4483:
X-Microsoft-Antispam-PRVS: <BN7PR07MB4483414F90580BCE99774A2BC1D90@BN7PR07MB4483.namprd07.prod.outlook.com>
X-MS-Oob-TLC-OOBClassifiers: OLM:2958;
X-Forefront-PRVS: 0376ECF4DD
X-MS-Exchange-SenderADCheck: 1
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: TuPR8ZeixU7GWYk8QXu0ZiGmdB928KQ7m/kcXdHIEgtexLH09HubKMS6Oh7h+cPq1YDrATUl4ch/n/NZdpTAd1U6/yBt+vS4uH+NvqWCjBE0qhZc2JHYm0EVzNCc2IAKN+rdGDbtOv4yHYFc0qSFvebgvXyKNha7IdbDNfW0SfdKwwtSjTpV4SSPzjdqNxGOoNmFsSiufpXrJYUmOKESDJj6Y1MgEgxcr9dab5pYsX6cdkOkohtzG36j8VsXUYIBiMeUbsnKJxiUMkpGmIm5vmtOGROI5+ogDYT5430bzQDKpcAdfoZcd7HIyGyirgr2gkamWgT5yMPIJqKG1vSsJaJeSB4s7FJ41ZoCuh7EYib+Aug+e4jYsvofaTzFsFJRQWy2f1ZLHjHLofQPW/gpkz6+z2tX8WW2Q/0EuX26NFW2y98ScoppH2+i0pl7LyOC50HnFJxv2gTU8/Ndqv7sOT043wP/YvaypsN+B3tza1OD27mSd4GKx1CH7+2tuL5oJr/D5iiUNt57NqfrXdt0qVzvE00156+aOc3q4dU69Fo=
X-OriginatorOrg: cadence.com
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Apr 2020 16:20:48.5545
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: f08ebfe6-314d-4985-de41-08d7e2eb4a2b
X-MS-Exchange-CrossTenant-Id: d36035c5-6ce6-4662-a3dc-e762e61ae4c9
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=d36035c5-6ce6-4662-a3dc-e762e61ae4c9;Ip=[199.43.4.23];Helo=[rmmaillnx1.cadence.com]
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN7PR07MB4483
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.138,18.0.676
 definitions=2020-04-17_07:2020-04-17,2020-04-17 signatures=0
X-Proofpoint-Spam-Details: rule=outbound_check_notspam policy=outbound_check score=0 impostorscore=0
 lowpriorityscore=0 bulkscore=0 phishscore=0 malwarescore=0 clxscore=1015
 priorityscore=1501 mlxscore=0 spamscore=0 adultscore=0 mlxlogscore=999
 suspectscore=0 classifier=spam adjust=0 reason=mlx scancount=1
 engine=8.12.0-2003020000 definitions=main-2004170129
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

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

Signed-off-by: Parshuram Thombare <pthombar@cadence.com>
---
 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