docs/devel/migration/uadk-compression.rst

   1 =========================================================
   2 User Space Accelerator Development Kit (UADK) Compression
   3 =========================================================
   4 UADK is a general-purpose user space accelerator framework that uses shared
   5 virtual addressing (SVA) to provide a unified programming interface for
   6 hardware acceleration of cryptographic and compression algorithms.
   7
   8 UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE),
   9 which enables hardware accelerators from different vendors that support SVA to
  10 adapt to UADK.
  11
  12 Currently, HiSilicon Kunpeng hardware accelerators have been registered with
  13 UACCE. Through the UADK framework, users can run cryptographic and compression
  14 algorithms using hardware accelerators instead of CPUs, freeing up CPU
  15 computing power and improving computing performance.
  16
  17 https://github.com/Linaro/uadk/tree/master/docs
  18
  19 UADK Framework
  20 ==============
  21 UADK consists of UACCE, vendors' drivers, and an algorithm layer. UADK requires
  22 the hardware accelerator to support SVA, and the operating system to support
  23 IOMMU and SVA. Hardware accelerators from different vendors are registered as
  24 different character devices with UACCE by using kernel-mode drivers of the
  25 vendors. A user can access the hardware accelerators by performing user-mode
  26 operations 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
  62 UADK Installation
  63 -----------------
  64 Build 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
  77 Without --prefix, UADK will be installed to /usr/local/lib by default.
  78 If get error:"cannot find -lnuma", please install the libnuma-dev
  79
  80 Run 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
  90 UADK Host Kernel Requirements
  91 -----------------------------
  92 User needs to make sure that ``UACCE`` is already supported in Linux kernel.
  93 The kernel version should be at least v5.9 with SVA (Shared Virtual
  94 Addressing) enabled.
  95
  96 Kernel Configuration
  97 ^^^^^^^^^^^^^^^^^^^^
  98
  99 ``UACCE`` could be built as module or built-in.
 100
 101 Here's an example to enable UACCE with hardware accelerator in HiSilicon
 102 Kunpeng 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
 113 Make sure all these above kernel configurations are selected.
 114
 115 Accelerator dev node permissions
 116 --------------------------------
 117 Hardware accelerators (eg: HiSilicon Kunpeng Zip accelerator) gets registered to
 118 UADK and char devices are created in dev directory. In order to access resources
 119 on hardware accelerator devices, write permission should be provided to user.
 120
 121 .. code-block:: shell
 122
 123     $ sudo chmod 777 /dev/hisi_zip-*
 124
 125 How 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
 136 Since UADK uses Shared Virtual Addressing(SVA) and device access virtual memory
 137 directly it is possible that SMMUv3 may encounter page faults while walking the
 138 IO page tables. This may impact the performance. In order to mitigate this,
 139 please make sure to specify ``-mem-prealloc`` parameter to the destination VM
 140 boot parameters.
 141
 142 Though both UADK and ZLIB are based on the deflate compression algorithm, UADK
 143 is not fully compatible with ZLIB. Hence, please make sure to use ``uadk`` on
 144 both source and destination during migration.