Introduction of UACCE

SVA 기반 accelerator framework

UACCE(Unified/User-space-access-intended Accelerator Framework)는 accelerator와 process 사이에 Shared Virtual Addressing(SVA)을 제공하는 것이 목적입니다. 따라서 accelerator가 main CPU의 어떤 data structure에도 접근할 수 있습니다.

이는 CPU와 I/O device가 주소가 아니라 data content만 공유하는 일반적인 data sharing과 다릅니다. Unified address 덕분에 process의 hardware와 userspace는 통신할 때 같은 virtual address를 공유합니다.

UACCE는 hardware accelerator를 heterogeneous processor로 취급합니다. IOMMU는 CPU page table을 공유하므로 virtual address(VA)에서 physical address(PA)로 같은 translation을 수행합니다.

.. SPDX-License-Identifier: GPL-2.0

Introduction of Uacce
---------------------

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
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.

CPU·accelerator의 공통 주소 변환

원문 그림에서 CPU application은 VA를 MMU에, hardware accelerator는 같은 VA를 IOMMU에 전달합니다. 두 translation 경로는 같은 PA의 memory로 수렴합니다.

::

         __________________________       __________________________
        |                          |     |                          |
        |  User application (CPU)  |     |   Hardware Accelerator   |
        |__________________________|     |__________________________|

                     |                                 |
                     | va                              | va
                     V                                 V
                 __________                        __________
                |          |                      |          |
                |   MMU    |                      |  IOMMU   |
                |__________|                      |__________|
                     |                                 |
                     |                                 |
                     V pa                              V pa
                 _______________________________________
                |                                       |
                |              Memory                   |
                |_______________________________________|

Kernel module·WarpDrive·queue

UACCE는 IOMMU와 address sharing을 담당하는 kernel module입니다. User driver와 library는 WarpDrive라고 부릅니다.

IOMMU SVA API를 중심으로 만든 UACCE device는 PASID가 없는 address space를 포함해 여러 address space에 접근할 수 있습니다.

통신에는 `queue`라는 virtual concept를 사용합니다. Queue는 FIFO와 비슷한 interface를 제공하며 application과 관련된 모든 hardware 사이에 unified address space를 유지합니다.

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.

Framework 연결 구조

WarpDrive library는 user API로 user driver를 호출하는 한편 queue file descriptor로 UACCE에 연결됩니다. UACCE와 crypto/NIC 같은 다른 framework는 device driver를 register하고, user driver는 mmap memory와 read/write interface로 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) |
                                                                 |___________________|

Queue 생성과 control·data path

UACCE는 mmap과 IOMMU를 이용합니다. 등록된 device마다 character device(chrdev)를 만들고, user application이 chrdev를 open할 때 새 queue를 생성합니다. 그 file descriptor가 queue의 userspace handle입니다.

Accelerator device는 UACCE object로 자신을 표현하고 userspace에는 chrdev로 export됩니다. Application은 ioctl을 control path로, shared memory를 data path로 사용해 hardware와 통신합니다.

즉 hardware control path는 file operation을 통하고 data path는 queue fd의 mmap space를 통합니다.

How does it work
----------------

Uacce uses mmap and IOMMU to play the trick.

Uacce creates 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
a 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.

Queue file address-space region

`enum uacce_qfrt`는 queue file region type을 정의합니다. `UACCE_QFRT_MMIO=0`은 device MMIO region, `UACCE_QFRT_DUS=1`은 device user-share region입니다.

enum uacce_qfrt {
        UACCE_QFRT_MMIO = 0,
        UACCE_QFRT_DUS = 1,
};

모든 region은 optional이며 device type마다 다릅니다. 각 region은 한 번만 mmap할 수 있고 다시 mmap하면 `-EEXIST`를 반환합니다.

MMIO region은 hardware MMIO space에 mapping되며 일반적으로 doorbell이나 다른 hardware notification에 사용합니다. Data channel로 쓰기에는 충분히 빠르지 않습니다. DUS region은 user process와 device가 data buffer를 공유하는 데 사용합니다.

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.
Each region can be mmapped only once, otherwise -EEXIST returns.

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.

Device 등록 API와 flag 협상

Register API는 `uacce.h`에 정의됩니다. `struct uacce_interface`는 `name`, `flags`, `const struct uacce_ops *ops`를 가집니다.

struct uacce_interface {
  char name[UACCE_MAX_NAME_SIZE];
  unsigned int flags;
  const struct uacce_ops *ops;
};

IOMMU capability에 따라 interface flag로 `UACCE_DEV_SVA`를 사용할 수 있습니다. 이 flag는 Shared Virtual Address, PASID, device page fault(PCI PRI 또는 SMMU Stall) 지원을 뜻하며 `BIT(0)`입니다.

Device lifecycle API는 `uacce_alloc(parent, interface)`, `uacce_register(uacce)`, `uacce_remove(uacce)`입니다.

`uacce_register` 결과는 세 가지입니다. UACCE module을 compile하지 않았으면 `ERR_PTR(-ENODEV)`, 요청한 flag 그대로 성공, 또는 협상된 flag로 성공할 수 있습니다.

예를 들어 `uacce_interface.flags = UACCE_DEV_SVA`를 요청했어도 `uacce->flags = ~UACCE_DEV_SVA`가 될 수 있습니다. 따라서 user driver는 return value뿐 아니라 협상된 `uacce->flags`도 확인해야 합니다.

The Uacce register API
----------------------

The register API is defined in uacce.h.

::

  struct uacce_interface {
    char name[UACCE_MAX_NAME_SIZE];
    unsigned int flags;
    const struct uacce_ops *ops;
  };

According to the IOMMU capability, uacce_interface flags can be:

::

  /**
   * UACCE Device flags:
   * UACCE_DEV_SVA: Shared Virtual Addresses
   *              Support PASID
   *              Support device page faults (PCI PRI or SMMU Stall)
   */
  #define UACCE_DEV_SVA               BIT(0)

  struct uacce_device *uacce_alloc(struct device *parent,
                                   struct uacce_interface *interface);
  int uacce_register(struct uacce_device *uacce);
  void uacce_remove(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.

User driver와 sysfs matching

Queue file의 mmap space에는 communication protocol을 감싸는 user driver가 필요합니다. UACCE는 user driver가 올바른 accelerator를 찾을 수 있도록 sysfs attribute를 제공합니다. 자세한 내용은 `Documentation/ABI/testing/sysfs-driver-uacce`에 있습니다.

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.