Skip to content

Commit 1e4f788

Browse files
zdover23zdover23
authored
Merge pull request ceph#59514 from kevinzs2048/add-uadk-doc
Compressor: Add UADK document Reviewed-by: Zac Dover <[email protected]>
2 parents 6258acb + 9173434 commit 1e4f788

File tree

2 files changed

+133
-1
lines changed

2 files changed

+133
-1
lines changed

‎doc/radosgw/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,4 +88,4 @@ Cluster with one API and then retrieve that data with the other API.
8888
D3N Data Cache <d3n_datacache>
8989
Cloud Transition <cloud-transition>
9090
Metrics <metrics>
91-
91+
UADK Acceleration for Compression <uadk-accel>

‎doc/radosgw/uadk-accel.rst‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
===============================================
2+
UADK Acceleration for Compression
3+
===============================================
4+
5+
UADK is a framework for applications to access hardware accelerators in a
6+
unified, secure, and efficient way. UADK is comprised of UACCE, libwd and many
7+
other algorithm libraries.
8+
9+
See `Compressor UADK Support`_.
10+
11+
12+
UADK in the Software Stack
13+
==========================
14+
15+
UADK is a general-purpose user space accelerator framework that uses shared
16+
virtual addressing (SVA) to provide a unified programming interface for hardware
17+
acceleration of cryptographic and compression algorithms.
18+
19+
UADK includes Unified/User-space-access-intended Accelerator Framework (UACCE),
20+
which enables hardware accelerators that support SVA to adapt to UADK.
21+
22+
Currently, HiSilicon Kunpeng hardware accelerators have been registered with
23+
UACCE. Through the UADK framework, users can run cryptographic and compression
24+
algorithms using hardware accelerators instead of CPUs, freeing up CPU computing
25+
power and improving computing performance.
26+
27+
A user can access the hardware accelerators by performing user-mode operations on
28+
the character devices, or the use of UADK can be done via frameworks that have
29+
been enabled by others including UADK support (for example, OpenSSL* libcrypto*,
30+
DPDK, and the Linux* Kernel Crypto Framework).
31+
32+
See `OpenSSL UADK Engine`_.
33+
34+
UADK Environment Setup
35+
======================
36+
UADK consists of UACCE, vendors’ drivers, and an algorithm layer. UADK requires the
37+
hardware accelerator to support SVA, and the operating system to support IOMMU and
38+
SVA. Hardware accelerators from different vendors are registered as different character
39+
devices with UACCE by using kernel-mode drivers of the vendors.
40+
41+
::
42+
43+
+----------------------------------+
44+
| apps |
45+
+----+------------------------+----+
46+
| |
47+
| |
48+
+-------+--------+ +-------+-------+
49+
| scheduler | | alg libraries |
50+
+-------+--------+ +-------+-------+
51+
| |
52+
| |
53+
| |
54+
| +--------+------+
55+
| | vendor drivers|
56+
| +-+-------------+
57+
| |
58+
| |
59+
+--+------------------+--+
60+
| libwd |
61+
User +----+-------------+-----+
62+
--------------------------------------------------
63+
Kernel +--+-----+ +------+
64+
| uacce | | smmu |
65+
+---+----+ +------+
66+
|
67+
+---+------------------+
68+
| vendor kernel driver |
69+
+----------------------+
70+
--------------------------------------------------
71+
+----------------------+
72+
| HW Accelerators |
73+
+----------------------+
74+
75+
Configuration
76+
=============
77+
78+
#. Kernel Requirement
79+
80+
User needs to make sure that UACCE is already supported in Linux kernel. The kernel version
81+
should be at least v5.9 with SVA (Shared Virtual Addressing) enabled.
82+
83+
UACCE may be built as a module or built into the kernel. Here's an example to build UACCE
84+
with hardware accelerators for the HiSilicon Kunpeng platform.
85+
86+
.. prompt:: bash $
87+
88+
CONFIG_IOMMU_SVA_LIB=y
89+
CONFIG_ARM_SMMU=y
90+
CONFIG_ARM_SMMU_V3=y
91+
CONFIG_ARM_SMMU_V3_SVA=y
92+
CONFIG_PCI_PASID=y
93+
CONFIG_UACCE=y
94+
CONFIG_CRYPTO_DEV_HISI_QM=y
95+
CONFIG_CRYPTO_DEV_HISI_ZIP=y
96+
97+
Make sure all these above kernel configurations are selected.
98+
99+
#. UADK enablement
100+
If the architecture is aarch64, it will automatically download the UADK source code to build
101+
the static library. If it runs on other architecture, user can enable it with build parameters
102+
`-DWITH_UADK=true`
103+
104+
#. Manual Build UADK
105+
As the above paragraph shows, the UADK is enabled automatically, no need to build manually.
106+
For developer who is interested in UADK, you can refer to the below steps for building.
107+
108+
.. prompt:: bash $
109+
110+
git clone https://github.com/Linaro/uadk.git
111+
cd uadk
112+
mkdir build
113+
./autogen.sh
114+
./configure --prefix=$PWD/build
115+
make
116+
make install
117+
118+
.. note:: Without –prefix, UADK will be installed to /usr/local/lib by
119+
default. If get error:"cannot find -lnuma", please install
120+
the `libnuma-dev`.
121+
122+
#. Configure
123+
124+
Edit the Ceph configuration file (usually ``ceph.conf``) to enable UADK
125+
support for *zlib* compression::
126+
127+
uadk_compressor_enabled=true
128+
129+
The default value in `global.yaml.in` for `uadk_compressor_enabled` is false.
130+
131+
.. _Compressor UADK Support: https://github.com/ceph/ceph/pull/58336
132+
.. _OpenSSL UADK Engine: https://github.com/Linaro/uadk_engine

0 commit comments

Comments
 (0)