3ae9bd9782
Document UADK(User Space Accelerator Development Kit) library details and how to use that for migration. Signed-off-by: Shameer Kolothum <shameerali.kolothum.thodi@huawei.com> Reviewed-by: Zhangfei Gao <zhangfei.gao@linaro.org> [s/Qemu/QEMU in docs] Signed-off-by: Fabiano Rosas <farosas@suse.de>
145 lines
5.2 KiB
ReStructuredText
145 lines
5.2 KiB
ReStructuredText
=========================================================
|
||
User Space Accelerator Development Kit (UADK) Compression
|
||
=========================================================
|
||
UADK is a general-purpose user space accelerator framework that uses shared
|
||
virtual addressing (SVA) to provide a unified programming interface for
|
||
hardware acceleration of cryptographic and compression algorithms.
|
||
|
||
UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE),
|
||
which enables hardware accelerators from different vendors that support SVA to
|
||
adapt to UADK.
|
||
|
||
Currently, HiSilicon Kunpeng hardware accelerators have been registered with
|
||
UACCE. Through the UADK framework, users can run cryptographic and compression
|
||
algorithms using hardware accelerators instead of CPUs, freeing up CPU
|
||
computing power and improving computing performance.
|
||
|
||
https://github.com/Linaro/uadk/tree/master/docs
|
||
|
||
UADK Framework
|
||
==============
|
||
UADK consists of UACCE, vendors' drivers, and an algorithm layer. UADK requires
|
||
the hardware accelerator to support SVA, and the operating system to support
|
||
IOMMU and SVA. Hardware accelerators from different vendors are registered as
|
||
different character devices with UACCE by using kernel-mode drivers of the
|
||
vendors. A user can access the hardware accelerators by performing user-mode
|
||
operations on the character devices.
|
||
|
||
::
|
||
|
||
+----------------------------------+
|
||
| apps |
|
||
+----+------------------------+----+
|
||
| |
|
||
| |
|
||
+-------+--------+ +-------+-------+
|
||
| scheduler | | alg libraries |
|
||
+-------+--------+ +-------+-------+
|
||
| |
|
||
| |
|
||
| |
|
||
| +--------+------+
|
||
| | vendor drivers|
|
||
| +-+-------------+
|
||
| |
|
||
| |
|
||
+--+------------------+--+
|
||
| libwd |
|
||
User +----+-------------+-----+
|
||
--------------------------------------------------
|
||
Kernel +--+-----+ +------+
|
||
| uacce | | smmu |
|
||
+---+----+ +------+
|
||
|
|
||
+---+------------------+
|
||
| vendor kernel driver |
|
||
+----------------------+
|
||
--------------------------------------------------
|
||
+----------------------+
|
||
| HW Accelerators |
|
||
+----------------------+
|
||
|
||
UADK Installation
|
||
-----------------
|
||
Build UADK
|
||
^^^^^^^^^^
|
||
|
||
.. code-block:: shell
|
||
|
||
git clone https://github.com/Linaro/uadk.git
|
||
cd uadk
|
||
mkdir build
|
||
./autogen.sh
|
||
./configure --prefix=$PWD/build
|
||
make
|
||
make install
|
||
|
||
Without --prefix, UADK will be installed to /usr/local/lib by default.
|
||
If get error:"cannot find -lnuma", please install the libnuma-dev
|
||
|
||
Run pkg-config libwd to ensure env is setup correctly
|
||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||
|
||
* export PKG_CONFIG_PATH=$PWD/build/lib/pkgconfig
|
||
* pkg-config libwd --cflags --libs
|
||
-I/usr/local/include -L/usr/local/lib -lwd
|
||
|
||
* export PKG_CONFIG_PATH is required on demand.
|
||
Not required if UADK is installed to /usr/local/lib
|
||
|
||
UADK Host Kernel Requirements
|
||
-----------------------------
|
||
User needs to make sure that ``UACCE`` is already supported in Linux kernel.
|
||
The kernel version should be at least v5.9 with SVA (Shared Virtual
|
||
Addressing) enabled.
|
||
|
||
Kernel Configuration
|
||
^^^^^^^^^^^^^^^^^^^^
|
||
|
||
``UACCE`` could be built as module or built-in.
|
||
|
||
Here's an example to enable UACCE with hardware accelerator in HiSilicon
|
||
Kunpeng platform.
|
||
|
||
* CONFIG_IOMMU_SVA_LIB=y
|
||
* CONFIG_ARM_SMMU=y
|
||
* CONFIG_ARM_SMMU_V3=y
|
||
* CONFIG_ARM_SMMU_V3_SVA=y
|
||
* CONFIG_PCI_PASID=y
|
||
* CONFIG_UACCE=y
|
||
* CONFIG_CRYPTO_DEV_HISI_QM=y
|
||
* CONFIG_CRYPTO_DEV_HISI_ZIP=y
|
||
|
||
Make sure all these above kernel configurations are selected.
|
||
|
||
Accelerator dev node permissions
|
||
--------------------------------
|
||
Harware accelerators(eg: HiSilicon Kunpeng Zip accelerator) gets registered to
|
||
UADK and char devices are created in dev directory. In order to access resources
|
||
on hardware accelerator devices, write permission should be provided to user.
|
||
|
||
.. code-block:: shell
|
||
|
||
$ sudo chmod 777 /dev/hisi_zip-*
|
||
|
||
How To Use UADK Compression In QEMU Migration
|
||
---------------------------------------------
|
||
* Make sure UADK is installed as above
|
||
* Build ``QEMU`` with ``--enable-uadk`` parameter
|
||
|
||
E.g. configure --target-list=aarch64-softmmu --enable-kvm ``--enable-uadk``
|
||
|
||
* Enable ``UADK`` compression during migration
|
||
|
||
Set ``migrate_set_parameter multifd-compression uadk``
|
||
|
||
Since UADK uses Shared Virtual Addressing(SVA) and device access virtual memory
|
||
directly it is possible that SMMUv3 may enounter page faults while walking the
|
||
IO page tables. This may impact the performance. In order to mitigate this,
|
||
please make sure to specify ``-mem-prealloc`` parameter to the destination VM
|
||
boot parameters.
|
||
|
||
Though both UADK and ZLIB are based on the deflate compression algorithm, UADK
|
||
is not fully compatible with ZLIB. Hence, please make sure to use ``uadk`` on
|
||
both source and destination during migration.
|