Re: [PATCH 18/22] xlink-core: Add xlink core driver xLink

[Randy Dunlap <rdunlap@infradead.org>]

Hi--

On 12/1/20 2:35 PM, mgross@linux.intel.com wrote:
> From: Seamus Kelly <seamus.kelly@intel.com>
> 
> 
> Cc: linux-doc@vger.kernel.org
> Reviewed-by: Mark Gross <mgross@linux.intel.com>
> Signed-off-by: Seamus Kelly <seamus.kelly@intel.com>
> ---
>  Documentation/vpu/index.rst                 |   1 +
>  Documentation/vpu/xlink-core.rst            |  80 ++
>  MAINTAINERS                                 |  12 +
>  drivers/misc/Kconfig                        |   1 +
>  drivers/misc/Makefile                       |   1 +
>  drivers/misc/xlink-core/Kconfig             |  33 +
>  drivers/misc/xlink-core/Makefile            |   5 +
>  drivers/misc/xlink-core/xlink-core.c        | 870 ++++++++++++++++++++
>  drivers/misc/xlink-core/xlink-defs.h        | 175 ++++
>  drivers/misc/xlink-core/xlink-multiplexer.c | 534 ++++++++++++
>  drivers/misc/xlink-core/xlink-multiplexer.h |  35 +
>  drivers/misc/xlink-core/xlink-platform.c    | 160 ++++
>  drivers/misc/xlink-core/xlink-platform.h    |  65 ++
>  include/linux/xlink.h                       | 108 +++
>  include/uapi/misc/xlink_uapi.h              | 145 ++++
>  15 files changed, 2225 insertions(+)
>  create mode 100644 Documentation/vpu/xlink-core.rst
>  create mode 100644 drivers/misc/xlink-core/Kconfig
>  create mode 100644 drivers/misc/xlink-core/Makefile
>  create mode 100644 drivers/misc/xlink-core/xlink-core.c
>  create mode 100644 drivers/misc/xlink-core/xlink-defs.h
>  create mode 100644 drivers/misc/xlink-core/xlink-multiplexer.c
>  create mode 100644 drivers/misc/xlink-core/xlink-multiplexer.h
>  create mode 100644 drivers/misc/xlink-core/xlink-platform.c
>  create mode 100644 drivers/misc/xlink-core/xlink-platform.h
>  create mode 100644 include/linux/xlink.h
>  create mode 100644 include/uapi/misc/xlink_uapi.h

> diff --git a/Documentation/vpu/xlink-core.rst b/Documentation/vpu/xlink-core.rst
> new file mode 100644
> index 000000000000..5410755ff13a
> --- /dev/null
> +++ b/Documentation/vpu/xlink-core.rst
> @@ -0,0 +1,80 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +xLink-core software sub-system

                       subsystem

> +==============================
> +
> +The purpose of the xLink software sub-system is to facilitate communication

                                     subsystem  {throughout/everywhere}

> +between multiple users on multiple nodes in the system.
> +
> +There are three types of xLink nodes:
> +
> +1. Remote Host: this is an external IA/x86 host system that is only capable of
> +   communicating directly to the Local Host node on VPU 2.x products.
> +2. Local Host: this is the ARM core within the VPU 2.x  SoC. The Local Host can
> +   communicate upstream to the Remote Host node, and downstream to the VPU IP
> +   node.
> +3. VPU IP: this is the Leon RT core within the VPU 2.x SoC. The VPU IP can only
> +   communicate upstream to the Local Host node.
> +
> +xLink provides a common API across all interfaces for users to access xLink
> +functions and provides user space APIs via an IOCTL interface implemented in
> +the xLink core.
> +
> +xLink manages communications from one interface to another and provides routing
> +of data through multiple channels across a single physical interface.
> +
> +It exposes a common API across all interfaces at both kernel and user level for

                                                                         levels

> +processes/applications to access.
> +
> +It has typical APIs types (open, close, read, write) that you would associate

                  API types

> +with a communication interface.
> +
> +It also has other APIs that are related to other functions that the device can
> +perform e.g. boot, reset get/set device mode.

   perform,

> +The driver is broken down into 4 source files.
> +
> +xlink-core:
> +Contains driver initialization, driver API and IOCTL interface (for user
> +space).
> +
> +xlink-multiplexer:
> +The Multiplexer component is responsible for securely routing messages through
> +multiple communication channels over a single physical interface.
> +
> +xlink-dispatcher:
> +The Dispatcher component is responsible for queueing and handling xLink
> +communication requests from all users in the system and invoking the underlying
> +platform interface drivers.
> +
> +xlink-platform:
> +provides abstraction to each interface supported (PCIe, USB, IPC, etc).
> +
> +Typical xLink transaction (simplified):
> +When a user wants to send data across an interface via xLink it firstly calls
> +xlink connect which connects to the relevant interface (PCIe, USB,IPC,etc) and

                                                                 USB, IPC, etc.) and

> +then xlink open channel.
> +
> +Then it calls xlink write function, this takes the data passes it to the kernel

                                                      data, passes

> +which packages up the data and channel and then adds it to a tx transaction

s/tx/transmit/

> +queue.
> +
> +A separate thread reads this transaction queue and pops off data if available
> +and passes the data to the underlying interface (e.g. PCIe) write function.
> +Using this thread provides serialization of transactions and decouples the user
> +write from the platform write.
> +
> +On the other side of the interface, a thread is continually reading the
> +interface (e.g. PCIe) via the platform interface read function and if it reads
> +any data it adds it to channel packet container.
> +
> +The application at this side of the interface will have called xlink connect,
> +opened the channel and called xlink read function to read data from the
> +interface and if any exists for that channel , the data gets popped from the

                                        channel,

> +channel packet container and copied from kernel space to user space buffer
> +provided by the call.
> +
> +xLink can handle API requests from multi-process and multi-threaded
> +application/processes.
> +
> +xLink maintains 4096 channels per device connected ( via xlink connect ) and

                                                      (via xlink connect) and

> +maintains a separate channel infrastructure for each device.

> diff --git a/drivers/misc/xlink-core/Kconfig b/drivers/misc/xlink-core/Kconfig
> new file mode 100644
> index 000000000000..3ae7dc01007f
> --- /dev/null
> +++ b/drivers/misc/xlink-core/Kconfig
> @@ -0,0 +1,33 @@
> +config XLINK_CORE
> +	tristate "Support for XLINK CORE"
> +	depends on ((XLINK_PCIE_RH_DRIVER || XBAY_XLINK_PCIE_RH_DRIVER) || (XLINK_LOCAL_HOST && (XLINK_PCIE_LH_DRIVER || XBAY_XLINK_PCIE_RH_DRIVER)))
> +	help
> +	  XLINK CORE enables the communication/control Sub-System.

	                                               subsystem {no hyphen]

> +
> +	  If unsure, say N.
> +
> +	  To compile this driver as a module, choose M here: the
> +	  module will be called xlink.ko.
> +
> +config XLINK_LOCAL_HOST
> +	tristate "Support for XLINK LOCAL HOST"
> +	depends on XLINK_IPC
> +	help
> +	  XLINK LOCAL HOST enables local host functionality for
> +	  the communication/control Sub-System.

	                            subsystem.

> +
> +	  Enable this config when building the kernel for the Inel Vision

	                                                      Intel

> +	  Processing Unit (VPU) Local Host core.
> +
> +	  If building for a Remote Host kernel, say N.
> +
> +config XLINK_PSS
> +	tristate "Support for XLINK PSS"
> +	depends on XLINK_LOCAL_HOST
> +	help
> +	  XLINK PSS enables the communication/control Sub-System on a PSS platform.

	                                              subsystem

Where is PSS defined?
Please spell out that acronym somewhere, e.g.:

	tristate "Support for XLINK PSS (Please Say Something)"


> +
> +	  Enable this config when building the kernel for the Intel Vision
> +	  Processing Unit (VPU) in a simulated env.
> +
> +	  If building for a VPU silicon, say N.


-- 
~Randy