1=========================================================
2User Space Accelerator Development Kit (UADK) Compression
3=========================================================
4UADK is a general-purpose user space accelerator framework that uses shared
5virtual addressing (SVA) to provide a unified programming interface for
6hardware acceleration of cryptographic and compression algorithms.
7
8UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE),
9which enables hardware accelerators from different vendors that support SVA to
10adapt to UADK.
11
12Currently, HiSilicon Kunpeng hardware accelerators have been registered with
13UACCE. Through the UADK framework, users can run cryptographic and compression
14algorithms using hardware accelerators instead of CPUs, freeing up CPU
15computing power and improving computing performance.
16
17https://github.com/Linaro/uadk/tree/master/docs
18
19UADK Framework
20==============
21UADK consists of UACCE, vendors' drivers, and an algorithm layer. UADK requires
22the hardware accelerator to support SVA, and the operating system to support
23IOMMU and SVA. Hardware accelerators from different vendors are registered as
24different character devices with UACCE by using kernel-mode drivers of the
25vendors. A user can access the hardware accelerators by performing user-mode
26operations on the character devices.
27
28::
29
30          +----------------------------------+
31          |                apps              |
32          +----+------------------------+----+
33               |                        |
34               |                        |
35       +-------+--------+       +-------+-------+
36       |   scheduler    |       | alg libraries |
37       +-------+--------+       +-------+-------+
38               |                         |
39               |                         |
40               |                         |
41               |                +--------+------+
42               |                | vendor drivers|
43               |                +-+-------------+
44               |                  |
45               |                  |
46            +--+------------------+--+
47            |         libwd          |
48    User    +----+-------------+-----+
49    --------------------------------------------------
50    Kernel    +--+-----+   +------+
51              | uacce  |   | smmu |
52              +---+----+   +------+
53                  |
54              +---+------------------+
55              | vendor kernel driver |
56              +----------------------+
57    --------------------------------------------------
58             +----------------------+
59             |   HW Accelerators    |
60             +----------------------+
61
62UADK Installation
63-----------------
64Build UADK
65^^^^^^^^^^
66
67.. code-block:: shell
68
69    git clone https://github.com/Linaro/uadk.git
70    cd uadk
71    mkdir build
72    ./autogen.sh
73    ./configure --prefix=$PWD/build
74    make
75    make install
76
77Without --prefix, UADK will be installed to /usr/local/lib by default.
78If get error:"cannot find -lnuma", please install the libnuma-dev
79
80Run pkg-config libwd to ensure env is setup correctly
81^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
82
83* export PKG_CONFIG_PATH=$PWD/build/lib/pkgconfig
84* pkg-config libwd --cflags --libs
85  -I/usr/local/include -L/usr/local/lib -lwd
86
87* export PKG_CONFIG_PATH is required on demand.
88  Not required if UADK is installed to /usr/local/lib
89
90UADK Host Kernel Requirements
91-----------------------------
92User needs to make sure that ``UACCE`` is already supported in Linux kernel.
93The kernel version should be at least v5.9 with SVA (Shared Virtual
94Addressing) enabled.
95
96Kernel Configuration
97^^^^^^^^^^^^^^^^^^^^
98
99``UACCE`` could be built as module or built-in.
100
101Here's an example to enable UACCE with hardware accelerator in HiSilicon
102Kunpeng platform.
103
104*    CONFIG_IOMMU_SVA_LIB=y
105*    CONFIG_ARM_SMMU=y
106*    CONFIG_ARM_SMMU_V3=y
107*    CONFIG_ARM_SMMU_V3_SVA=y
108*    CONFIG_PCI_PASID=y
109*    CONFIG_UACCE=y
110*    CONFIG_CRYPTO_DEV_HISI_QM=y
111*    CONFIG_CRYPTO_DEV_HISI_ZIP=y
112
113Make sure all these above kernel configurations are selected.
114
115Accelerator dev node permissions
116--------------------------------
117Harware accelerators(eg: HiSilicon Kunpeng Zip accelerator) gets registered to
118UADK and char devices are created in dev directory. In order to access resources
119on hardware accelerator devices, write permission should be provided to user.
120
121.. code-block:: shell
122
123    $ sudo chmod 777 /dev/hisi_zip-*
124
125How To Use UADK Compression In QEMU Migration
126---------------------------------------------
127* Make sure UADK is installed as above
128* Build ``QEMU`` with ``--enable-uadk`` parameter
129
130  E.g. configure --target-list=aarch64-softmmu --enable-kvm ``--enable-uadk``
131
132* Enable ``UADK`` compression during migration
133
134  Set ``migrate_set_parameter multifd-compression uadk``
135
136Since UADK uses Shared Virtual Addressing(SVA) and device access virtual memory
137directly it is possible that SMMUv3 may enounter page faults while walking the
138IO page tables. This may impact the performance. In order to mitigate this,
139please make sure to specify ``-mem-prealloc`` parameter to the destination VM
140boot parameters.
141
142Though both UADK and ZLIB are based on the deflate compression algorithm, UADK
143is not fully compatible with ZLIB. Hence, please make sure to use ``uadk`` on
144both source and destination during migration.
145