Re: [PATCH 06/22] misc: xlink-pcie: Add documentation for XLink PCIe driver

[mark gross <mgross@linux.intel.com>]

On Fri, Dec 18, 2020 at 02:59:00PM -0800, Randy Dunlap wrote:
> On 12/1/20 2:34 PM, mgross@linux.intel.com wrote:
> > From: Srikanth Thokala <srikanth.thokala@intel.com>
> > 
> > Provide overview of XLink PCIe driver implementation
> > 
> > Cc: linux-doc@vger.kernel.org
> > Reviewed-by: Mark Gross <mgross@linux.intel.com>
> > Signed-off-by: Srikanth Thokala <srikanth.thokala@intel.com>
> > ---
> >  Documentation/vpu/index.rst      |  1 +
> >  Documentation/vpu/xlink-pcie.rst | 91 ++++++++++++++++++++++++++++++++
> >  2 files changed, 92 insertions(+)
> >  create mode 100644 Documentation/vpu/xlink-pcie.rst
> > 
> 
> Hi--
> 
> For document, chapter, section, etc., headings, please read & use
> Documentation/doc-guide/sphinx.rst:
> 
> * Please stick to this order of heading adornments:
> 
>   1. ``=`` with overline for document title::
> 
>        ==============
>        Document title
>        ==============
> 
>   2. ``=`` for chapters::
> 
>        Chapters
>        ========
> 
>   3. ``-`` for sections::
> 
>        Section
>        -------
> 
>   4. ``~`` for subsections::
> 
>        Subsection
>        ~~~~~~~~~~
Thanks for the help!  I'm new to the sphix markup language and appreciate your
advice.  I'll reread that doc-guide.

We'll address the issues on our next posting once the marge window closes.

thanks again for the reviews!

--mark


> 
> > diff --git a/Documentation/vpu/xlink-pcie.rst b/Documentation/vpu/xlink-pcie.rst
> > new file mode 100644
> > index 000000000000..bc64b566989d
> > --- /dev/null
> > +++ b/Documentation/vpu/xlink-pcie.rst
> > @@ -0,0 +1,91 @@
> > +.. SPDX-License-Identifier: GPL-2.0-only
> > +
> > +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:
> 
> No colon at end of chapter/section headings.
> 
> > +-------------
> > +The xlink-pcie driver in linux-5.4 provides transport layer implementation for
> 
>                             Linux 5.4 (?)
> 
> > +the data transfers to support xlink protocol subsystem communication with the
> 
>                                  Xlink
> 
> > +peer device. i.e, between remote host system and the local Keem Bay device.
> 
>         device, i.e., between the remote host system and
> 
> > +
> > +The Keem Bay device is an ARM based SOC that includes a vision processing
> 
>                              ARM-based
> 
> > +unit (VPU) and deep learning, neural network core in the hardware.
> > +The xlink-pcie driver exports a functional device endpoint to the Keem Bay device
> > +and supports two-way communication with peer device.
> 
>                                       with the peer device.
> 
> > +
> > +------------------------
> > +High-level architecture:
> > +------------------------
> > +Remote Host: IA CPU
> > +Local Host: ARM CPU (Keem Bay)::
> > +
> > +        +------------------------------------------------------------------------+
> > +        |  Remote Host IA CPU              | | Local Host ARM CPU (Keem Bay) |   |
> > +        +==================================+=+===============================+===+
> > +        |  User App                        | | User App                      |   |
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |   XLink UAPI                     | | XLink UAPI                    |   |
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |   XLink Core                     | | XLink Core                    |   |
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |   XLink PCIe                     | | XLink PCIe                    |   |
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |   XLink-PCIe Remote Host driver  | | XLink-PCIe Local Host driver  |   |
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:|:|:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:-:|
> > +        +----------------------------------+-+-------------------------------+---+
> > +        |     PCIe Host Controller         | | PCIe Device Controller        | HW|
> > +        +----------------------------------+-+-------------------------------+---+
> > +               ^                                             ^
> > +               |                                             |
> > +               |------------- 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
> > +ring buffer management and MSI/Doorbell interrupts.
> > +
> > +The xlink-pcie driver subsystem registers Keem Bay device as an endpoint driver
> 
>                                    registers the
> 
> > +and provides standard linux pcie sysfs interface, # /sys/bus/pci/devices/xxxx:xx:xx.0/
> 
>                          Linux PCIe
> 
> > +
> > +
> > +-------------------------
> > +XLink protocol subsystem:
> 
> No colon at end.
> 
> > +-------------------------
> > +xlink is an abstracted control and communication subsystem based on channel
> 
>    Xlink
> 
> > +identification. It is intended to support VPU technology both at SoC level as
> > +well as at IP level, over multiple interfaces.
> > +
> > +- The xlink subsystem abstracts several types of communication channels
> 
>          Xlink
> 
> > +  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
> 
>          Xlink
> 
> > +  from standalone local system or from remote system based on communication
> > +  interface underneath.
> > +- The xlink subsystem supports following communication interfaces:
> 
>          Xlink           supports the following
> 
> 
> > +    * USB CDC
> > +    * Gigabit Ethernet
> > +    * PCIe
> > +    * IPC
> > 
> 
> 
> cheers.
> -- 
> ~Randy
>