RE: [PATCH v2 08/34] misc: xlink-pcie: Add documentation for XLink PCIe driver

Hi Randy,

Thank you for the review.

-----Original Message-----
From: Randy Dunlap <rdunlap@infradead.org>
Sent: Wednesday, January 20, 2021 1:06 AM
To: mgross@linux.intel.com; markgross@kernel.org; arnd@arndb.de;
bp@suse.de; damien.lemoal@wdc.com; dragan.cvetic@xilinx.com;
gregkh@linuxfoundation.org; corbet@lwn.net; leonard.crestez@nxp.com;
palmerdabbelt@google.com; paul.walmsley@sifive.com; peng.fan@nxp.com;
robh+dt@kernel.org; shawnguo@kernel.org; jassisinghbrar@gmail.com
Cc: linux-kernel@vger.kernel.org; Thokala, Srikanth
[off-list ref]; linux-doc@vger.kernel.org
Subject: Re: [PATCH v2 08/34] misc: xlink-pcie: Add documentation for
XLink PCIe driver

Hi,
Here are a few doc comments for you:

On 1/8/21 1:25 PM, mgross@linux.intel.com wrote:

quoted

From: Srikanth Thokala <srikanth.thokala@intel.com>

Provide overview of XLink PCIe driver implementation

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Reviewed-by: Mark Gross <redacted>
Signed-off-by: Srikanth Thokala <srikanth.thokala@intel.com>
---
 Documentation/vpu/index.rst      |  1 +
 Documentation/vpu/xlink-pcie.rst | 90 ++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 Documentation/vpu/xlink-pcie.rst

quoted

diff --git a/Documentation/vpu/xlink-pcie.rst b/Documentation/vpu/xlink-

pcie.rst

quoted

new file mode 100644
index 000000000000..2d877c966b1e

--- /dev/null
+++ b/Documentation/vpu/xlink-pcie.rst

@@ -0,0 +1,90 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Kernel driver: Xlink-pcie driver
+================================
+Supported chips:
+  * Intel Edge.AI Computer Vision platforms: Keem Bay
+    Suffix: Bay
+    Slave address: 6240
+    Datasheet: Publicly available at Intel
+
+Author: Srikanth Thokala Srikanth.Thokala@intel.com
+
+Introduction
+============
+The Xlink-pcie driver provides transport layer implementation for
+the data transfers to support Xlink protocol subsystem communication

with the

quoted

+peer device. i.e, between remote host system and Keem Bay device.

        device, i.e.,

Ok.

quoted

+
+The Keem Bay device is an ARM-based SOC that includes a vision

processing

quoted

+unit (VPU) and deep learning, neural network core in the hardware.
+The Xlink-pcie driver exports a functional device endpoint to the Keem

Bay

quoted

+device and supports two-way communication with the peer device.
+
+High-level architecture
+=======================
+Remote Host: IA CPU
+Local Host: ARM CPU (Keem Bay)::
+
+        +--------------------------------------------------------------

----------+

quoted

+        |  Remote Host IA CPU              | | Local Host ARM CPU (Keem

Bay) |   |

quoted

+

+==================================+=+===============================+===+

quoted

+        |  User App                        | | User App

|   |

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |   XLink UAPI                     | | XLink UAPI

|   |

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |   XLink Core                     | | XLink Core

|   |

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |   XLink PCIe                     | | XLink PCIe

|   |

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |   XLink-PCIe Remote Host driver  | | XLink-PCIe Local Host

driver  |   |

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:|:|:-:-:-:-:-:-:-:-:-:-:-:-

:-:-:-:-:-:|

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+        |     PCIe Host Controller         | | PCIe Device Controller

| HW|

quoted

+        +----------------------------------+-+-------------------------

------+---+

quoted

+               ^                                             ^
+               |                                             |
+               |------------- PCIe x2 Link  -----------------|
+
+This XLink PCIe driver comprises of two variants:
+* Local Host driver
+
+  * Intended for ARM CPU
+  * It is based on PCI Endpoint Framework
+  * Driver path: {tree}/drivers/misc/Xlink-pcie/local_host
+
+* Remote Host driver
+
+       * Intended for IA CPU
+       * It is a PCIe endpoint driver
+       * Driver path: {tree}/drivers/misc/Xlink-pcie/remote_host
+
+XLink PCIe communication between local host and remote host is achieved

through

quoted

+ring buffer management and MSI/Doorbell interrupts.
+
+The Xlink-pcie driver subsystem registers the Keem Bay device as an

endpoint

quoted

+driver and provides standard linux PCIe sysfs interface, #

                                Linux

Ok.

What is the '#' sign for above?

It denotes Linux prompt; I will change it to be more meaningful.

Thanks!
Srikanth

quoted

+/sys/bus/pci/devices/xxxx:xx:xx.0/
+
+
+XLink protocol subsystem
+========================
+Xlink is an abstracted control and communication subsystem based on

channel

quoted

+identification. It is intended to support VPU technology both at SoC

level as

quoted

+well as at IP level, over multiple interfaces.
+
+- The Xlink subsystem abstracts several types of communication channels
+  underneath, allowing the usage of different interfaces with the
+  same function call interface.
+- The Communication channels are full-duplex protocol channels allowing
+  concurrent bidirectional communication.
+- The Xlink subsystem also supports control operations to VPU either
+  from standalone local system or from remote system based on

communication

quoted

+  interface underneath.
+- The Xlink subsystem supports the following communication interfaces:
+    * USB CDC
+    * Gigabit Ethernet
+    * PCIe
+    * IPC

--
~Randy
"He closes his eyes and drops the goggles.  You can't get hurt
by looking at a bitmap.  Or can you?"
(Neal Stephenson: Snow Crash)