linux-crypto.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jonathan Cameron <jonathan.cameron@huawei.com>
To: Zhangfei Gao <zhangfei.gao@linaro.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Arnd Bergmann <arnd@arndb.de>,
	Herbert Xu <herbert@gondor.apana.org.au>, <grant.likely@arm.com>,
	jean-philippe <jean-philippe@linaro.org>,
	"Jerome Glisse" <jglisse@redhat.com>,
	<ilias.apalodimas@linaro.org>, <francois.ozog@linaro.org>,
	<kenneth-lee-2012@foxmail.com>,
	Wangzhou <wangzhou1@hisilicon.com>,
	"haojian . zhuang" <haojian.zhuang@linaro.org>,
	<guodong.xu@linaro.org>, <linux-accelerators@lists.ozlabs.org>,
	<linux-kernel@vger.kernel.org>, <linux-crypto@vger.kernel.org>,
	<iommu@lists.linux-foundation.org>,
	Kenneth Lee <liguozhu@hisilicon.com>,
	Zaibo Xu <xuzaibo@huawei.com>
Subject: Re: [PATCH v7 1/3] uacce: Add documents for uacce
Date: Thu, 31 Oct 2019 15:37:11 +0000	[thread overview]
Message-ID: <20191031153711.00001708@huawei.com> (raw)
In-Reply-To: <1572331216-9503-2-git-send-email-zhangfei.gao@linaro.org>

On Tue, 29 Oct 2019 14:40:14 +0800
Zhangfei Gao <zhangfei.gao@linaro.org> wrote:

> From: Kenneth Lee <liguozhu@hisilicon.com>
> 
> Uacce (Unified/User-space-access-intended Accelerator Framework) is
> a kernel module targets to provide Shared Virtual Addressing (SVA)
> between the accelerator and process.
> 
> This patch add document to explain how it works.
> 
> Signed-off-by: Kenneth Lee <liguozhu@hisilicon.com>
> Signed-off-by: Zaibo Xu <xuzaibo@huawei.com>
> Signed-off-by: Zhou Wang <wangzhou1@hisilicon.com>
> Signed-off-by: Zhangfei Gao <zhangfei.gao@linaro.org>
> ---
>  Documentation/misc-devices/uacce.rst | 160 +++++++++++++++++++++++++++++++++++
>  1 file changed, 160 insertions(+)
>  create mode 100644 Documentation/misc-devices/uacce.rst
> 
> diff --git a/Documentation/misc-devices/uacce.rst b/Documentation/misc-devices/uacce.rst
> new file mode 100644
> index 0000000..ecd5d8b
> --- /dev/null
> +++ b/Documentation/misc-devices/uacce.rst
> @@ -0,0 +1,160 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Introduction of Uacce
> +=========================

Fix the underline length to match the title.

> +
> +Uacce (Unified/User-space-access-intended Accelerator Framework) targets to
> +provide Shared Virtual Addressing (SVA) between accelerators and processes.
> +So accelerator can access any data structure of the main cpu.
> +This differs from the data sharing between cpu and io device, which share
> +data content rather than address.

which share only data content rather than address.

> +Because of the unified address, hardware and user space of process can
> +share the same virtual address in the communication.
> +Uacce takes the hardware accelerator as a heterogeneous processor, while
> +IOMMU share the same CPU page tables and as a result the same translation
> +from va to pa.
> +
> +	 __________________________       __________________________
> +	|                          |     |                          |
> +	|  User application (CPU)  |     |   Hardware Accelerator   |
> +	|__________________________|     |__________________________|
> +
> +	             |                                 |
> +	             | va                              | va
> +	             V                                 V
> +                 __________                        __________
> +                |          |                      |          |
> +                |   MMU    |                      |  IOMMU   |
> +                |__________|                      |__________|
> +		     |                                 |
> +	             |                                 |
> +	             V pa                              V pa
> +		 _______________________________________
> +		|                                       |
> +		|              Memory                   |
> +		|_______________________________________|
> +
> +
> +
> +Architecture
> +------------
> +
> +Uacce is the kernel module, taking charge of iommu and address sharing.
> +The user drivers and libraries are called WarpDrive.
> +
> +The uacce device, built around the IOMMU SVA API, can access multiple
> +address spaces, including the one without PASID.
> +
> +A virtual concept, queue, is used for the communication. It provides a
> +FIFO-like interface. And it maintains a unified address space between the
> +application and all involved hardware.
> +
> +                             ___________________                  ________________
> +                            |                   |   user API     |                |
> +                            | WarpDrive library | ------------>  |  user driver   |
> +                            |___________________|                |________________|
> +                                     |                                    |
> +                                     |                                    |
> +                                     | queue fd                           |
> +                                     |                                    |
> +                                     |                                    |
> +                                     v                                    |
> +     ___________________         _________                                |
> +    |                   |       |         |                               | mmap memory
> +    | Other framework   |       |  uacce  |                               | r/w interface
> +    | crypto/nic/others |       |_________|                               |
> +    |___________________|                                                 |
> +             |                       |                                    |
> +             | register              | register                           |
> +             |                       |                                    |
> +             |                       |                                    |
> +             |                _________________       __________          |
> +             |               |                 |     |          |         |
> +              -------------  |  Device Driver  |     |  IOMMU   |         |
> +                             |_________________|     |__________|         |
> +                                     |                                    |
> +                                     |                                    V
> +                                     |                            ___________________
> +                                     |                           |                   |
> +                                     --------------------------  |  Device(Hardware) |
> +                                                                 |___________________|
> +
> +
> +How does it work
> +================
> +
> +Uacce uses mmap and IOMMU to play the trick.
> +
> +Uacce create a chrdev for every device registered to it. New queue is
> +created when user application open the chrdev. The file descriptor is used
> +as the user handle of the queue.
> +The accelerator device present itself as an Uacce object, which exports as
> +chrdev to the user space. The user application communicates with the
> +hardware by ioctl (as control path) or share memory (as data path).
> +
> +The control path to the hardware is via file operation, while data path is
> +via mmap space of the queue fd.
> +
> +The queue file address space:
> +/**
> + * enum uacce_qfrt: qfrt type
> + * @UACCE_QFRT_MMIO: device mmio region
> + * @UACCE_QFRT_DUS: device user share region
> + */
> +enum uacce_qfrt {
> +	UACCE_QFRT_MMIO = 0,
> +	UACCE_QFRT_DUS = 1,
> +};
> +
> +All regions are optional and differ from device type to type. The
> +communication protocol is wrapped by the user driver.

Can you have more than one of each? If not state this clearly.

> +
> +The device mmio region is mapped to the hardware mmio space. It is generally
> +used for doorbell or other notification to the hardware. It is not fast enough
> +as data channel.
> +
> +The device user share region is used for share data buffer between user process
> +and device.
> +
> +
> +The Uacce register API
> +-----------------------
blank line here.

> +The register API is defined in uacce.h.
> +
> +struct uacce_interface {
> +	char name[UACCE_MAX_NAME_SIZE];
> +	enum uacce_dev_flag flags;

Having an enum for a flags variable / bitmap is odd.  Just use an
appropriate sized integer.

> +	struct uacce_ops *ops;
> +};
Use indenting to get literal formatting of this block. Will
give formatting like the code blocks in here compiled:
https://www.kernel.org/doc/html/latest/driver-api/iio/buffers.html

> +
> +According to the IOMMU capability, uacce_interface flags can be:
> +
> +/**
> + * enum uacce_dev_flag: Device flags:
> + * @UACCE_DEV_SVA: Shared Virtual Addresses
> + *		   Support PASID
> + *		   Support device page faults (PCI PRI or SMMU Stall)
> + */
> +enum uacce_dev_flag {
> +	UACCE_DEV_SVA = BIT(0),
> +};
> +
> +struct uacce_device *uacce_register(struct device *parent,
> +				    struct uacce_interface *interface);
> +void uacce_unregister(struct uacce_device *uacce);
> +
> +uacce_register results can be:
> +a. If uacce module is not compiled, ERR_PTR(-ENODEV)
> +b. Succeed with the desired flags
> +c. Succeed with the negotiated flags, for example
> +   uacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA
> +So user driver need check return value as well as the negotiated uacce->flags.
> +
> +
> +The user driver
> +---------------
> +
> +The queue file mmap space will need a user driver to wrap the communication
> +protocol. Uacce provides some attributes in sysfs for the user driver to
> +match the right accelerator accordingly.
> +More details in Documentation/ABI/testing/sysfs-driver-uacce.



  reply	other threads:[~2019-10-31 17:54 UTC|newest]

Thread overview: 16+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-29  6:40 [PATCH v7 0/3] Add uacce module for Accelerator Zhangfei Gao
2019-10-29  6:40 ` [PATCH v7 1/3] uacce: Add documents for uacce Zhangfei Gao
2019-10-31 15:37   ` Jonathan Cameron [this message]
2019-10-29  6:40 ` [PATCH v7 2/3] uacce: add uacce driver Zhangfei Gao
2019-10-31 17:13   ` Jonathan Cameron
2019-11-05  7:43     ` zhangfei
2019-11-11 11:19       ` Jonathan Cameron
2019-11-05 11:48   ` Jean-Philippe Brucker
2019-11-06  8:17     ` zhangfei
2019-11-06 15:32       ` Jean-Philippe Brucker
2019-11-07 13:23         ` zhangfei
2019-11-08  7:48           ` Jean-Philippe Brucker
2019-10-29  6:40 ` [PATCH v7 3/3] crypto: hisilicon - register zip engine to uacce Zhangfei Gao
2019-10-31 17:53   ` Jonathan Cameron
2019-11-05  8:34     ` zhangfei
2019-11-11 11:30       ` Jonathan Cameron

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191031153711.00001708@huawei.com \
    --to=jonathan.cameron@huawei.com \
    --cc=arnd@arndb.de \
    --cc=francois.ozog@linaro.org \
    --cc=grant.likely@arm.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=guodong.xu@linaro.org \
    --cc=haojian.zhuang@linaro.org \
    --cc=herbert@gondor.apana.org.au \
    --cc=ilias.apalodimas@linaro.org \
    --cc=iommu@lists.linux-foundation.org \
    --cc=jean-philippe@linaro.org \
    --cc=jglisse@redhat.com \
    --cc=kenneth-lee-2012@foxmail.com \
    --cc=liguozhu@hisilicon.com \
    --cc=linux-accelerators@lists.ozlabs.org \
    --cc=linux-crypto@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=wangzhou1@hisilicon.com \
    --cc=xuzaibo@huawei.com \
    --cc=zhangfei.gao@linaro.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).