diff --git a/docs/en/using_the_kae.md b/docs/en/using_the_kae.md new file mode 100644 index 0000000000000000000000000000000000000000..eeb067bd0588cba59d1b1ce81138e17f3a8e2c21 --- /dev/null +++ b/docs/en/using_the_kae.md @@ -0,0 +1,724 @@ +# Using the Kunpeng Accelerator Engine (KAE) + +## Overview + +Kunpeng Accelerator Engine \(KAE\) is a software acceleration library of openEuler, which provides hardware acceleration engine function on the Kunpeng 920 processor. It supports symmetric encryption, asymmetric encryption, and digital signature. It is ideal for accelerating SSL/TLS applications, reducing processor consumption and improving processor efficiency. In addition, users can quickly migrate existing services through the standard OpenSSL interface. + +The KAE supports the following algorithms: + +- Digest algorithm SM3, which supports asynchronous mode. +- Symmetric encryption algorithm SM4, which supports asynchronous, CTR, XTS, and CBC modes. +- Symmetric encryption algorithm AES, which supports asynchronous, ECB, CTR, XTS, and CBC modes. +- Asymmetric algorithm RSA, which supports asynchronous mode and key sizes 1024, 2048, 3072, and 4096. +- Key negotiation algorithm DH, which supports asynchronous mode and key sizes 768, 1024, 1536, 2048, 3072, and 4096. + +## Application Scenarios + +The KAE applies to the following scenarios, as shown in [Table 1](#table11915824163418). + +**Table 1** Application scenarios + + + + + + + + + + + + + + + + + + + +

Scenario

+

Data

+

Big data

+

Stream data

+

Data encryption

+

Block data

+

Intelligent security protection

+

Video stream data

+

Web service

+

Handshake connections

+
+ +## Installing, Running, and Uninstalling the KAE + +### Installing the Accelerator Software Packages + +#### Preparing for Installation + +##### Environment Requirements + +- The accelerator engine is enabled on TaiShan 200 servers. + +> [!NOTE]NOTE + +- You need to import the accelerator license. For details, see section "License Management" in the [TaiShan Rack Server iBMC \(V500 or Later\) User Guide](https://support.huawei.com/enterprise/en/doc/EDOC1100121685/426cffd9?idPath=7919749%257C9856522%257C21782478%257C8060757). +- If the accelerator is used in the physical machine scenario, the SMMU must be disabled. For details, see the [TaiShan 200 Server BIOS Parameter Reference](https://support.huawei.com/enterprise/en/doc/EDOC1100088647). + +- CPU: Kunpeng 920 +- OS: openEuler-21.09-aarch64-dvd.iso + +##### KAE Software Description + +**Table 2** RPM software packages of the KAE + + + + + + + + + + + + + + + + +

Software Package

+

Description

+

kae_driver-version_num-1.OS_type.aarch64.rpm

+

Accelerator driver, including the uacce.ko, hisi_qm.ko, hisi_sec2.ko, and hisi_hpre.ko kernel modules.

+

Algorithms supported: SM3, SM4, AES, RSA, and DH.

+

libwd-version_num-1.OS_type.aarch64.rpm

+

Coverage: libwd.so dynamic link library

+

It provides interfaces for the KAE.

+

libkae-version_num-1.OS_type.aarch64.rpm

+

Dependency: libwd RPM package

+

Coverage: libkae.so dynamic link library

+

Algorithms supported: SM3, SM4, AES, RSA, and DH.

+
+ +#### Installing the Accelerator Software Package + +##### Prerequisites + +- The remote SSH login tool has been installed on the local PC. +- The openEuler OS has been installed. +- The RPM tool is running properly. +- OpenSSL 1.1.1a or a later version has been installed. + + You can run the following commands to query the version number of OpenSSL: + + - openssl version + +##### Procedure + +1. Log in to the openEuler OS CLI as user **root**. +2. Create a directory for storing accelerator engine software packages. +3. Use SSH to copy all accelerator engine software packages to the created directory. +4. In the directory, run the **rpm -ivh** command to install the accelerator engine software packages. + + > [!NOTE]NOTE + > Install the **libwd** package first because the **libkae** package installation depends on the **libwd** package. + + ```shell + rpm -ivh uacce*.rpm hisi*.rpm libwd-*.rpm libkae*.rpm + ``` + + ```text + Verifying... ################################# [100%] + Preparing... ################################# [100%] + checking installed modules + uacce modules start to install + Updating / installing... + 1:uacce-1.2.10-4.oe1 ################################# [ 14%] + uacce modules installed + 2:libwd-1.2.10-3.oe1 ################################# [ 29%] + 3:libkae-1.2.10-3.oe1 ################################# [ 43%] + checking installed modules + hisi_hpre modules start to install + 4:hisi_hpre-1.2.10-4.oe1 ################################# [ 57%] + hisi_hpre modules installed + checking installed modules + hisi_rde modules start to install + 5:hisi_rde-1.2.10-4.oe1 ################################# [ 71%] + hisi_rde modules installed + checking installed modules + hisi_sec2 modules start to install + 6:hisi_sec2-1.2.10-4.oe1 ################################# [ 86%] + hisi_sec2 modules installed + checking installed modules + hisi_zip modules start to install + 7:hisi_zip-1.2.10-4.oe1 ################################# [100%] + hisi_zip modules installed + ``` + +5. Run the **rpm -qa** command to check whether the accelerator software packages have been installed successfully. Run the **rpm -ql** command to check whether files in the software packages are correct. The following is an example: + + ```shell + rpm -qa|grep -E "hisi|uacce|libwd|libkae" + ``` + + ```text + hisi_rde-1.2.10-4.oe1.aarch64 + hisi_sec2-1.2.10-4.oe1.aarch64 + libkae-1.2.10-3.oe1.aarch64 + hisi_hpre-1.2.10-4.oe1.aarch64 + uacce-1.2.10-4.oe1.aarch64 + libwd-1.2.10-3.oe1.aarch64 + hisi_zip-1.2.10-4.oe1.aarch64 + ``` + + ```shell + rpm -ql uacce hisi* libwd* libkae + ``` + + ```text + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_qm.ko + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/uacce.ko + /etc/modprobe.d/hisi_hpre.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_hpre.ko + /etc/modprobe.d/hisi_rde.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_rde.ko + /etc/modprobe.d/hisi_sec2.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_sec2.ko + /etc/modprobe.d/hisi_zip.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_zip.ko + /usr/include/warpdrive/config.h + /usr/include/warpdrive/include/uacce.h + /usr/include/warpdrive/smm.h + /usr/include/warpdrive/wd.h + /usr/include/warpdrive/wd_bmm.h + /usr/include/warpdrive/wd_cipher.h + /usr/include/warpdrive/wd_comp.h + /usr/include/warpdrive/wd_dh.h + /usr/include/warpdrive/wd_digest.h + /usr/include/warpdrive/wd_rsa.h + /usr/lib64/libwd.so.1.2.10 + /usr/local/lib/engines-1.1/libkae.so.1.2.10 + ``` + +6. Restart the system or run commands to manually load the accelerator engine drivers to the kernel in sequence, and check whether the drivers are successfully loaded. + + ```shell + modprobe uacce + lsmod | grep uacce + modprobe hisi_qm + lsmod | grep hisi_qm + modprobe hisi_sec2 # Loads the hisi_sec2 driver to the kernel based on the configuration file in /etc/modprobe.d/hisi_sec2.conf. + modprobe hisi_hpre # Loads the hisi_hpre driver to the kernel based on the configuration file in /etc/modprobe.d/hisi_hpre.conf. + ``` + +##### Environment Variables Setup + +Run the following command to export the environment variables \(If you have specified the installation directory, set **/usr/local** to the actual one\): + +```shell +export OPENSSL_ENGINES=/usr/local/lib/engines-1.1 +``` + +##### Post-Installation Check + +Run the **rpm -qa** command to check whether the accelerator engine software packages are successfully installed. + +If the command output contains _software package name_**-**_version number_**-**, the software packages are successfully installed. The following is an example: + +```shell +rpm -qa|grep -E "hisi|uacce|libwd|libkae" +``` + +```text +hisi_rde-1.2.10-4.oe1.aarch64 +hisi_sec2-1.2.10-4.oe1.aarch64 +libkae-1.2.10-3.oe1.aarch64 +hisi_hpre-1.2.10-4.oe1.aarch64 +uacce-1.2.10-4.oe1.aarch64 +libwd-1.2.10-3.oe1.aarch64 +hisi_zip-1.2.10-4.oe1.aarch64 +``` + +#### Required Operations After Installation + +##### Testing the OpenSSL Accelerator Engine + +You can run the following commands to test some accelerator functions. + +- Use the OpenSSL software algorithm to test the RSA performance. + + ```shell + $ ./openssl speed -elapsed rsa2048 + ... + sign verify sign/s verify/s + rsa 2048 bits 0.001384s 0.000035s 724.1 28365.8. + ``` + +- Use the KAE to test the RSA performance. + + ```shell + $ ./openssl speed -elapsed -engine kae rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.000355s 0.000022s 2819.0 45478.4 + ``` + +> [!NOTE]NOTE +> After the KAE is used, the signature performance is improved from 724.1 sign/s to 2819 sign/s. + +- Use the OpenSSL software algorithm to test the asynchronous RSA performance. + + ```shell + $ ./openssl speed -elapsed -async_jobs 36 rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.001318s 0.000032s 735.7 28555 + ``` + +- Use the KAE to test the asynchronous RSA performance. + + ```shell + $ ./openssl speed -engine kae -elapsed -async_jobs 36 rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.000018s 0.000009s 54384.1 105317.0 + ``` + +> [!NOTE]NOTE +> After the KAE is used, the asynchronous RSA signature performance is improved from 735.7 sign/s to 54384.1 sign/s. + +- Use the OpenSSL software algorithm to test the performance of the SM4 CBC mode. + + ```shell + $ ./openssl speed -elapsed -evp sm4-cbc + You have chosen to measure elapsed time instead of user CPU time. + .... + Doing sm4-cbc for 3s on 10240 size blocks: 2196 sm4-cbc's in 3.00s .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm4-cbc 82312.53k 85196.80k 85284.18k 85000.85k 85284.18k 85261.26k + ``` + +- Use the KAE to test the SM4 CBC mode performance. + + ```shell + $ ./openssl speed -elapsed -engine kae -evp sm4-cbc + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + ... + Doing sm4-cbc for 3s on 1048576 size blocks: 11409 sm4-cbc's in 3.00s + ... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm4-cbc 383317.33k 389427.20k 395313.15k 392954.73k 394264.58k 394264.58k + ``` + +> [!NOTE]NOTE +> After the KAE is used, the SM4 CBC mode performance is improved from 82312.53 kbit/s to 383317.33 kbit/s when the input data block size is 8 MB. + +- Use the OpenSSL software algorithm to test the SM3 mode performance. + + ```shell + $ ./openssl speed -elapsed -evp sm3 + You have chosen to measure elapsed time instead of user CPU time. + Doing sm3 for 3s on 102400 size blocks: 1536 sm3's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm3 50568.53k 52428.80k 52428.80k 52428.80k 52428.80k 52428.80k + ``` + +- Use the KAE to test the SM3 mode performance. + + ```shell + $ ./openssl speed -elapsed -engine kae -evp sm3 + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + Doing sm3 for 3s on 102400 size blocks: 19540 sm3's in 3.00s + .... + type 51200 bytes 102400 bytes 1048576 bytes 2097152 bytes 4194304 bytes 8388608 bytes + sm3 648243.20k 666965.33k 677030.57k 678778.20k 676681.05k 668292.44k + ``` + +> [!NOTE]NOTE +> After the KAE is used, the SM3 algorithm performance is improved from 52428.80 kbit/s to 668292.44 kbit/s when the input data block size is 8 MB. + +- Use the OpenSSL software algorithm to test the asynchronous performance of the AES algorithm in CBC mode. + + ```shell + $ ./openssl speed -elapsed -evp aes-128-cbc -async_jobs 4 + You have chosen to measure elapsed time instead of user CPU time. + Doing aes-128-cbc for 3s on 51200 size blocks: 65773 aes-128-cbc's in 3.00s + Doing aes-128-cbc for 3s on 102400 size blocks: 32910 aes-128-cbc's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + aes-128-cbc 1122525.87k 1123328.00k 1120578.22k 1121277.27k 1119879.17k 1115684.86k + ``` + +- Use the KEA engine to test the asynchronous performance of the AES algorithm in CBC mode. + + ```shell + $ ./openssl speed -elapsed -evp aes-128-cbc -async_jobs 4 -engine kae + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + Doing aes-128-cbc for 3s on 51200 size blocks: 219553 aes-128-cbc's in 3.00s + Doing aes-128-cbc for 3s on 102400 size blocks: 117093 aes-128-cbc's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + aes-128-cbc 3747037.87k 3996774.40k 1189085.18k 1196774.74k 1196979.11k 1199570.94k + ``` + +> [!NOTE]NOTE + +- The AES algorithm supports only asynchronous mode when the data length is 256 KB or less. +- After the KAE is used, the AES algorithm performance is improved from 1123328.00 kbit/s to 3996774.40 kbit/s when the input data block size is 100 KB. + +### Upgrading the Accelerator Software Packages + +#### Scenario + +You can run the **rpm -Uvh** command to upgrade the accelerator software. + +#### Procedure + +1. Download the latest accelerator engine software packages from the openEuler community. +2. Use SSH to log in to the Linux CLI as user **root**. +3. Save the downloaded software packages to a directory. +4. In the directory, run the **rpm -Uvh** command to upgrade the accelerator driver package and engine library package. The following is an example: + + The command and output are as follows: + + ![](./figures/en-us_image_0231143189.png) + + ![](./figures/en-us_image_0231143191.png) + +5. Run the **rpm -qa** command to check whether the upgrade is successful. Ensure that the queried version is the latest version. + + ![](./figures/en-us_image_0231143193.png) + + ![](./figures/en-us_image_0231143195.png) + +6. Restart the system or run the following commands to manually uninstall the drivers of the earlier version, load the drivers of the latest version, and check whether the new drivers are successfully loaded. + + ```shell + # Uninstall the existing drivers. + $ lsmod | grep uacce + uacce 262144 3 hisi_hpre,hisi_sec2,hisi_qm + $ + $ rmmod hisi_hpre + $ rmmod hisi_sec2 + $ rmmod hisi_qm + $ rmmod uacce + $ lsmod | grep uacce + $ + # Load the new drivers. + $ modprobe uacce + $ modprobe hisi_qm + $ modprobe hisi_sec2 # Loads the hisi_sec2 driver to the kernel based on the configuration file in /etc/modprobe.d/hisi_sec2.conf. + $ modprobe hisi_hpre # Loads the hisi_hpre driver to the kernel based on the configuration file in /etc/modprobe.d/hisi_hpre.conf. + $ lsmod | grep uacce + uacce 36864 3 hisi_sec2,hisi_qm,hisi_hpre + ``` + +### Uninstalling the Accelerator Software Packages + +#### Scenario + +You do not need the accelerator engine software or you want to install a new one. + +#### Procedure + +1. Use SSH to log in to the Linux CLI as user **root**. +2. Restart the system or run commands to manually uninstall the accelerator drivers loaded to the kernel, and check whether the drivers are successfully uninstalled. + + ```shell + # lsmod | grep uacce + uacce 36864 3 hisi_sec2,hisi_qm,hisi_hpre + # rmmod hisi_hpre + # rmmod hisi_sec2 + # rmmod hisi_qm + # rmmod uacce + # lsmod | grep uacce + # + ``` + +3. Run the **rpm -e** command to uninstall the accelerator engine software packages. The following is an example: + + > [!NOTE]NOTE + > Due to the dependency relationships, the **libkae** package must be uninstalled before the **libwd** package. + + ![](./figures/en-us_image_0231143196.png) + + ![](./figures/en-us_image_0231143197.png) + +4. Run the **rpm -qa \|grep** command to check whether the uninstallation is successful. + + ![](./figures/en-us_image_0231143198.png) + +## Querying Logs + +[Table 3](#table52821836) lists log information related to the accelerator engine. + +**Table 3** Log information + + + + + + + + + + + + + + + + +

Directory

+

File

+

Description

+

/var/log/

+

kae.log

+

By default, the log level of the OpenSSL engine log is error. To set the log level, perform the following procedure:

+
  1. Run export KAE_CONF_ENV=/var/log/.
  2. Create the kae.cnf file in /var/log/.
  3. In the kae.cnf file, configure the content as follows:

    [LogSection]

    +

    debug_level=error #Value: none, error, info, warning or debug

    +
+
NOTE:

In normal cases, you are advised not to enable the info or debug log level. Otherwise, the accelerator performance will deteriorate.

+
+

/var/log/

+

messages/syslog

+
  • Kernel logs are stored in the /var/log/messages directory.
+
NOTE:

Alternatively, you can run the dmesg > /var/log/dmesg.log command to collect driver and kernel logs.

+
+
+ +## Acceleration Engine Application + +> [!NOTE]NOTE +> If you have not purchased the engine license, you are advised not to use the KAE to invoke the corresponding algorithms. Otherwise, the performance of the OpenSSL encryption algorithm may be affected. + +### Example Code for the KAE + +```c +#include + +#include + +/* OpenSSL headers */ + +#include + +#include + +#include + +#include + +int main(int argc, char **argv) + +{ + + /* Initializing OpenSSL */ + + SSL_load_error_strings(); + + ERR_load_BIO_strings(); + + OpenSSL_add_all_algorithms(); + + /*You can use ENGINE_by_id Function to get the handle of the Huawei Accelerator Engine*/ + + ENGINE *e = ENGINE_by_id("kae"); + + /* Enable the accelerator asynchronization function. This parameter is optional. The value 0 indicates disabled, and the value 1 indicates enabled. The asynchronous function is enabled by default. */ + + ENGINE_ctrl_cmd_string(e, "KAE_CMD_ENABLE_ASYNC", "1", 0) + + ENGINE_init(e); + + RSA*rsa=RSA_new_method(e);#Specify the engine for RSA encryption and decryption. + + /*The user code*/ + + ...... + +; + + ENGINE_free(e); + +; + +} +``` + +### Usage of the KAE in the OpenSSL Configuration File openssl.cnf + +Create the **openssl.cnf** file and add the following configuration information to the file: + +```text +openssl_conf=openssl_def +[openssl_def] +engines=engine_section +[engine_section] +kae=kae_section +[kae_section] +engine_id=kae +dynamic_path=/usr/local/lib/engines-1.1/kae.so +KAE_CMD_ENABLE_ASYNC=1 #The value 0 indicates that the asynchronous function is disabled. The value 1 indicates that the asynchronous function is enabled. The asynchronous function is enabled by default. +default_algorithms=ALL +init=1 +``` + +Export the environment variable **OPENSSL\_CONF**. + +```shell +export OPENSSL_CONF=/home/app/openssl.cnf #Path for storing the openssl.cnf file +``` + +The following is an example of the OpenSSL configuration file: + +```c +#include + +#include + +/* OpenSSL headers */ + +#include + +#include + +#include + +#include + +int main(int argc, char **argv) + +{ + + /* Initializing OpenSSL */ + + SSL_load_error_strings(); + + ERR_load_BIO_strings(); + +#Load openssl configure + +OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL); OpenSSL_add_all_algorithms(); + + /*You can use ENGINE_by_id Function to get the handle of the Huawei Accelerator Engine*/ + + ENGINE *e = ENGINE_by_id("kae"); + + /*The user code*/ + + ...... + +; + + ENGINE_free(e); + +; +} +``` + +## Troubleshooting + +### Failed to Initialize the Accelerator Engine + +#### Symptom + +The accelerator engine is not completely loaded. + +#### Solution + +1. Check whether the accelerator drivers are loaded successfully. Specifically, run the **lsmod** command to check whether uacce.ko, qm.ko, sgl.ko, hisi\_sec2.ko, hisi\_hpre.ko, hisi\_zip.ko, and hisi\_rde.ko exist. + + ```shell + $ lsmod | grep uacce + uacce 262144 2 hisi_hpre,hisi_qm,hisi_sec2,hisi_zip,hisi_rde + ``` + +2. Check whether the accelerator engine library exists in **/usr/lib64** \(directory for RPM installation\) or **/usr/local/lib** \(directory for source code installation\) and the OpenSSL installation directory, and check whether the correct soft link is established. + + ```shell + $ ll /usr/local/lib/engines-1.1/ |grep kae + # Check whether the KAE has been correctly installed and whether a soft link has been established. If yes, the displayed information is as follows: + lrwxrwxrwx. 1 root root 22 Nov 12 02:33 kae.so -> kae.so.1.0.1 + lrwxrwxrwx. 1 root root 22 Nov 12 02:33 kae.so.0 -> kae.so.1.0.1 + -rwxr-xr-x. 1 root root 112632 May 25 2019 kae.so.1.0.1 + $ + $ ll /usr/lib64/ | grep libwd + # Check whether libwd has been correctly installed and whether a soft link has been established. If yes, the displayed information is as follows: + lrwxrwxrwx. 1 root root 14 Nov 12 02:33 libwd.so -> libwd.so.1.0.1 + lrwxrwxrwx. 1 root root 14 Nov 12 02:33 libwd.so.0 -> libwd.so.1.0.1 + -rwxr-xr-x. 1 root root 137120 May 25 2019 libwd.so.1.0.1 + $ + ``` + +3. Check whether the path of the OpenSSL engine library can be exported by running the **export** command. + + ```shell + $ echo $OPENSSL_ENGINES + $ export OPENSSL_ENGINES=/usr/local/lib/engines-1.1 + $ echo $OPENSSL_ENGINES + /usr/local/lib/engines-1.1 + ``` + +### Failed to Identify Accelerator Devices After the Acceleration Engine Is Installed + +#### Symptom + +After the acceleration engine is installed, the accelerator devices cannot be identified. + +#### Solution + +1. Check whether the device exists in the virtual file system. Normally, the following accelerator devices are displayed: + + ```shell + $ ls -al /sys/class/uacce/ + total 0 + lrwxrwxrwx. 1 root root 0 Nov 14 03:45 hisi_hpre-2 -> ../../devices/pci0000:78/0000:78:00.0/0000:79:00.0/uacce/hisi_hpre-2 + lrwxrwxrwx. 1 root root 0 Nov 14 03:45 hisi_hpre-3 -> ../../devices/pci0000:b8/0000:b8:00.0/0000:b9:00.0/uacce/hisi_hpre-3 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_rde-4 -> ../../devices/pci0000:78/0000:78:01.0/uacce/hisi_rde-4 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_rde-5 -> ../../devices/pci0000:b8/0000:b8:01.0/uacce/hisi_rde-5 + lrwxrwxrwx. 1 root root 0 Nov 14 08:39 hisi_sec-0 -> ../../devices/pci0000:74/0000:74:01.0/0000:76:00.0/uacce/hisi_sec-0 + lrwxrwxrwx. 1 root root 0 Nov 14 08:39 hisi_sec-1 -> ../../devices/pci0000:b4/0000:b4:01.0/0000:b6:00.0/uacce/hisi_sec-1 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_zip-6 -> ../../devices/pci0000:74/0000:74:00.0/0000:75:00.0/uacce/hisi_zip-6 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_zip-7 -> ../../devices/pci0000:b4/0000:b4:00.0/0000:b5:00.0/uacce/hisi_zip-7 + ``` + +2. If you want to use the HPRE device but the device is not found in [1](#li1760055514614), check whether the accelerator software is correctly installed by referring to [Failed to Upgrade the Accelerator Drivers](#failed-to-upgrade-the-accelerator-drivers). +3. If the accelerator software is correctly installed, run the **lspci** command to check whether the physical device exists. + + ```shell + $ lspci | grep HPRE + 79:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon HPRE Engine (rev 21) + b9:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon HPRE Engine (rev 21) + $ lspci | grep SEC + 76:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon SEC Engine (rev 21) + b6:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon SEC Engine (rev 21) + $ lspci | grep RDE + 78:01.0 RAID bus controller: Huawei Technologies Co., Ltd. HiSilicon RDE Engine (rev 21) + b8:01.0 RAID bus controller: Huawei Technologies Co., Ltd. HiSilicon RDE Engine (rev 21) + $ lspci | grep ZIP + 75:00.0 Processing accelerators: Huawei Technologies Co., Ltd. HiSilicon ZIP Engine (rev 21) + b5:00.0 Processing accelerators: Huawei Technologies Co., Ltd. HiSilicon ZIP Engine (rev 21) + $ + ``` + +4. If no physical device is found in [3](#li1560012551369), perform the following operations: + - Check whether the accelerator license has been imported. If no, import the accelerator license. For details, see "License Management" in the [TaiShan Rack Server iBMC \(V500 or Later\) User Guide](https://support.huawei.com/enterprise/en/doc/EDOC1100121685/426cffd9?idPath=7919749%257C9856522%257C21782478%257C8060757). After the accelerator license is imported, power off and restart the iBMC to enable the license. + - Check whether the iBMC and BIOS versions support the accelerator feature. + +### Failed to Upgrade the Accelerator Drivers + +#### Symptom + +After the accelerator drivers are upgraded, the driver version is not changed after the system is restarted. + +#### Possible Cause + +Before the accelerator drivers are upgraded, the system upgrades other driver packages. These driver packages may update the boot file system initramfs, and update the accelerator drivers to initramfs before upgrade. For example, if the NIC driver is updated or initramfs is manually updated, the system loads the accelerator drivers from initramfs first during restart. + +#### Solution + +After the accelerator drivers are upgraded, run the **dracut \-\-force** command to update initramfs again. diff --git "a/docs/zh/\344\275\277\347\224\250KAE\345\212\240\351\200\237\345\274\225\346\223\216.md" "b/docs/zh/\344\275\277\347\224\250KAE\345\212\240\351\200\237\345\274\225\346\223\216.md" new file mode 100644 index 0000000000000000000000000000000000000000..206ff46933534822e2c711daa2a173b8b1aaf3d1 --- /dev/null +++ "b/docs/zh/\344\275\277\347\224\250KAE\345\212\240\351\200\237\345\274\225\346\223\216.md" @@ -0,0 +1,709 @@ +# 使用KAE加速引擎 + +## 简介 + +KAE加速引擎为openEuler的一个软件加速库，搭载在Kunpeng 920处理器上联合提供硬件加速引擎功能，包含了对称加密、非对称加密和数字签名，用于加速SSL/TLS应用，可以显著降低处理器消耗，提高处理器效率。此外，用户通过OpenSSL标准接口可实现业务快速迁移。 + +KAE加速引擎支持以下算法： + +- 摘要算法SM3, 支持异步模式。 +- 对称加密算法SM4，支持异步模式，支持CTR/XTS/CBC模式。 +- 对称加密算法AES, 支持异步模式，支持ECB/CTR/XTS/CBC模式。 +- 非对称算法RSA，支持异步模式，支持 Key Sizes 1024/2048/3072/4096。 +- 密钥协商算法DH, 支持异步模式，支持 Key Sizes 768/1024/1536/2048/3072/4096。 + +## 应用场景 + +KAE加速引擎主要有以下应用场景，如[表1](#table11915824163418)所示。 + +**表 1** 应用场景 + + + + + + + + + + + + + + + + + + + +

场景

+

数据

+

大数据

+

流数据

+

数据加密

+

块数据

+

智能安防

+

视频流数据

+

Web服务

+

握手连接

+
+ +## 安装、升级和卸载 + +### 安装加速器软件包 + +#### 安装前准备 + +##### 环境要求 + +- TaiShan 200服务器，开启加速引擎功能 + +> [!NOTE]说明 +> +> 需要导入加速器许可证，具体操作请参考《[TaiShan 机架服务器 iBMC \(V500及以上\) 用户指南](https://support.huawei.com/enterprise/zh/doc/EDOC1100121687)》中“许可证管理”章节。 +> 物理机场景使用加速器需要关闭SMMU，具体操作请参考《[TaiShan 200服务器BIOS参数参考](https://support.huawei.com/enterprise/zh/doc/EDOC1100088653)》。 + +- CPU：Kunpeng 920 +- 操作系统：openEuler-21.09-aarch64-dvd.iso + +##### KAE加速引擎软件说明 + +**表 2** 加速引擎的rpm软件包 + + + + + + + + + + + + + + + + +

软件包名称

+

软件包说明

+

kae_driver-版本号-1.OS类型.aarch64.rpm

+

加速器驱动，包含内容：uacce.ko、hisi_qm.ko、hisi_sec2.ko、hisi_hpre.ko内核模块

+

支持：SM3/SM4/AES/RSA/DH算法

+

libwd-版本号-1.OS类型.aarch64.rpm

+

包含内容：libwd.so动态链接库

+

提供接口给KAE引擎

+

libkae-版本号-1.OS类型.aarch64.rpm

+

依赖：libwd rpm包

+

包含内容：libkae.so动态库

+

支持：SM3/SM4/AES/RSA/DH等算法

+
+ +#### 安装加速器软件包 + +##### 前提条件 + +- 已在本地安装远程SSH登录工具 +- 已安装openEuler操作系统 +- RPM工具能正常使用。 +- 已安装OpenSSL 1.1.1a或以上版本。 + + 使用如下命令查询OpenSSL的版本号 + + - openssl version + +##### 安装步骤 + +1. 以root帐号登录openEuler OS命令行界面。 +2. 新建目录用于存放加速器引擎软件包。 +3. 使用SSH远程登录工具，将所有加速引擎软件包拷贝到已建好的目录下。 +4. 在存放加速引擎软件包目录下，使用rpm -ivh命令安装加速器引擎软件包。 + + > [!NOTE]说明 + > 由于libkae包的安装依赖libwd包，所以libwd的安装必须先于libkae。 + + ```shell + # rpm -ivh uacce*.rpm hisi*.rpm libwd-*.rpm libkae*.rpm + Verifying... ################################# [100%] + Preparing... ################################# [100%] + checking installed modules + uacce modules start to install + Updating / installing... + 1:uacce-1.2.10-4.oe1 ################################# [ 14%] + uacce modules installed + 2:libwd-1.2.10-3.oe1 ################################# [ 29%] + 3:libkae-1.2.10-3.oe1 ################################# [ 43%] + checking installed modules + hisi_hpre modules start to install + 4:hisi_hpre-1.2.10-4.oe1 ################################# [ 57%] + hisi_hpre modules installed + checking installed modules + hisi_rde modules start to install + 5:hisi_rde-1.2.10-4.oe1 ################################# [ 71%] + hisi_rde modules installed + checking installed modules + hisi_sec2 modules start to install + 6:hisi_sec2-1.2.10-4.oe1 ################################# [ 86%] + hisi_sec2 modules installed + checking installed modules + hisi_zip modules start to install + 7:hisi_zip-1.2.10-4.oe1 ################################# [100%] + hisi_zip modules installed + ``` + +5. 使用rpm -qa命令，查看加速器软件包是否已正常安装到系统内。使用rpm -ql命令 ，查看软件包的文件是否正确。示例如下。 + + ```shell + # rpm -qa|grep -E "hisi|uacce|libwd|libkae" + hisi_rde-1.2.10-4.oe1.aarch64 + hisi_sec2-1.2.10-4.oe1.aarch64 + libkae-1.2.10-3.oe1.aarch64 + hisi_hpre-1.2.10-4.oe1.aarch64 + uacce-1.2.10-4.oe1.aarch64 + libwd-1.2.10-3.oe1.aarch64 + hisi_zip-1.2.10-4.oe1.aarch64 + ``` + + ```shell + # rpm -ql uacce hisi* libwd* libkae + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_qm.ko + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/uacce.ko + /etc/modprobe.d/hisi_hpre.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_hpre.ko + /etc/modprobe.d/hisi_rde.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_rde.ko + /etc/modprobe.d/hisi_sec2.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_sec2.ko + /etc/modprobe.d/hisi_zip.conf + /lib/modules/4.19.90-2003.4.0.0036.oe1.aarch64/extra/hisi_zip.ko + /usr/include/warpdrive/config.h + /usr/include/warpdrive/include/uacce.h + /usr/include/warpdrive/smm.h + /usr/include/warpdrive/wd.h + /usr/include/warpdrive/wd_bmm.h + /usr/include/warpdrive/wd_cipher.h + /usr/include/warpdrive/wd_comp.h + /usr/include/warpdrive/wd_dh.h + /usr/include/warpdrive/wd_digest.h + /usr/include/warpdrive/wd_rsa.h + /usr/lib64/libwd.so.1.2.10 + /usr/local/lib/engines-1.1/libkae.so.1.2.10 + ``` + +6. 重启系统或通过命令行手动依次加载加速器引擎驱动到内核，并查看是否加载成功。 + + ```shell + # modprobe uacce + # lsmod | grep uacce + # modprobe hisi_qm + # lsmod | grep hisi_qm + # modprobe hisi_sec2 #加载hisi_sec2驱动时将根据/etc/modprobe.d/hisi_sec2.conf 下的配置文件加载到内核 + # modprobe hisi_hpre #加载hisi_hpre驱动时将根据/etc/modprobe.d/hisi_hpre.conf 下的配置文件加载到内核 + ``` + +##### 设置环境变量 + +通过以下命令导出环境变量：如果用户指定安装路径，则下面/usr/local应根据实际安装路径进行修改。 + +```shell +export OPENSSL_ENGINES=/usr/local/lib/engines-1.1 +``` + +##### 安装后检查 + +执行**rpm -qa**命令查看加速器引擎软件包是否安装成功。 + +打印信息中包含“ _软件包名-版本号-_ ”表示该软件包安装成功。示例如下。 + +```shell +# rpm -qa|grep -E "hisi|uacce|libwd|libkae" +hisi_rde-1.2.10-4.oe1.aarch64 +hisi_sec2-1.2.10-4.oe1.aarch64 +libkae-1.2.10-3.oe1.aarch64 +hisi_hpre-1.2.10-4.oe1.aarch64 +uacce-1.2.10-4.oe1.aarch64 +libwd-1.2.10-3.oe1.aarch64 +hisi_zip-1.2.10-4.oe1.aarch64 +``` + +#### 安装后操作 + +##### OpenSSL加速器引擎测试 + +用户可以通过以下命令测试部分加速器功能。 + +- 使用OpenSSL的软件算法测试RSA性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed rsa2048 + ... + sign verify sign/s verify/s + rsa 2048 bits 0.001384s 0.000035s 724.1 28365.8. + ``` + +- 使用KAE引擎的测试RSA性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -engine kae rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.000355s 0.000022s 2819.0 45478.4 + ``` + +> [!NOTE]说明 +> 使用KAE引擎加速后签名性能从724.1sign/s提升到2819sign/s。 + +- 使用OpenSSL的软件算法测试异步RSA性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -async_jobs 36 rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.001318s 0.000032s 735.7 28555 + ``` + +- 使用KAE引擎的测试异步RSA性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -engine kae -elapsed -async_jobs 36 rsa2048 + .... + sign verify sign/s verify/s + rsa 2048 bits 0.000018s 0.000009s 54384.1 105317.0 + ``` + +> [!NOTE]说明 +> 使用KAE引擎加速后异步RSA签名性能从735.7 sign/s提升到 54384.1sign/s。 + +- 使用OpenSSL的软件算法测试SM4 CBC模式性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -evp sm4-cbc + You have chosen to measure elapsed time instead of user CPU time. + .... + Doing sm4-cbc for 3s on 10240 size blocks: 2196 sm4-cbc's in 3.00s .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm4-cbc 82312.53k 85196.80k 85284.18k 85000.85k 85284.18k 85261.26k + ``` + +- 使用KAE引擎的测试SM4 CBC模式性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -engine kae -evp sm4-cbc + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + ... + Doing sm4-cbc for 3s on 1048576 size blocks: 11409 sm4-cbc's in 3.00s + ... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm4-cbc 383317.33k 389427.20k 395313.15k 392954.73k 394264.58k 394264.58k + ``` + +> [!NOTE]说明 +> 使用KAE加速后SM4 CBC模式在输入数据块大小为8M时，从82312.53k/s提升到383317.33k/s。 + +- 使用OpenSSL的软件算法测试SM3模式性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -evp sm3 + You have chosen to measure elapsed time instead of user CPU time. + Doing sm3 for 3s on 102400 size blocks: 1536 sm3's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + sm3 50568.53k 52428.80k 52428.80k 52428.80k 52428.80k 52428.80k + ``` + +- 使用KAE引擎测试SM3模式性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -engine kae -evp sm3 + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + Doing sm3 for 3s on 102400 size blocks: 19540 sm3's in 3.00s + .... + type 51200 bytes 102400 bytes 1048576 bytes 2097152 bytes 4194304 bytes 8388608 bytes + sm3 648243.20k 666965.33k 677030.57k 678778.20k 676681.05k 668292.44k + ``` + +> [!NOTE]说明 +> 使用KAE加速后SM3算法在输入数据块大小为8M时，从52428.80 k/s提升到668292.44k/s。 + +- 使用OpenSSL软件算法测试AES算法CBC模式异步性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -evp aes-128-cbc -async_jobs 4 + You have chosen to measure elapsed time instead of user CPU time. + Doing aes-128-cbc for 3s on 51200 size blocks: 65773 aes-128-cbc's in 3.00s + Doing aes-128-cbc for 3s on 102400 size blocks: 32910 aes-128-cbc's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + aes-128-cbc 1122525.87k 1123328.00k 1120578.22k 1121277.27k 1119879.17k 1115684.86k + ``` + +- 使用KAE引擎测试AES算法CBC模式异步性能。 + + ```shell + linux-rmw4:/usr/local/bin # ./openssl speed -elapsed -evp aes-128-cbc -async_jobs 4 -engine kae + engine "kae" set. + You have chosen to measure elapsed time instead of user CPU time. + Doing aes-128-cbc for 3s on 51200 size blocks: 219553 aes-128-cbc's in 3.00s + Doing aes-128-cbc for 3s on 102400 size blocks: 117093 aes-128-cbc's in 3.00s + .... + type 51200 bytes 102400 bytes1048576 bytes2097152 bytes4194304 bytes8388608 bytes + aes-128-cbc 3747037.87k 3996774.40k 1189085.18k 1196774.74k 1196979.11k 1199570.94k + ``` + +> [!NOTE]说明 +> AES仅支持数据长度为256KB及以下场景的异步使用。 +> 使用KAE加速后AES算法在输入数据块为100K大小时，从1123328.00k/s提升到3996774.40 k/s 。 + +### 升级加速器软件包 + +#### 使用场景 + +当需要更新加速器软件版本时可以使用rpm -Uvh方式进行升级。 + +#### 操作步骤 + +1. 从openEuler社区下载最新版本的加速引擎软件包。 +2. 使用SSH远程登录工具，以root帐号进入Linux操作系统命令行界面。 +3. 将下载下来的最新版本的软件包都放在某个路径下。 +4. 在存放软件包的路径下使用rpm -Uvh 命令升级加速器驱动包及引擎库包。示例如下。 + + 命令和信息回显如下所示。 + + ![](./figures/zh-cn_image_0231143189.png) + + ![](./figures/zh-cn_image_0231143191.png) + +5. 使用rpm -qa 命令查询是否升级成功。确认查询到的版本是最新的升级后版本。 + + ![](./figures/zh-cn_image_0231143193.png) + + ![](./figures/zh-cn_image_0231143195.png) + +6. 重启系统或通过命令行手动卸载旧版本驱动，然后加载新版本驱动，并查看是否加载成功 + + ```shell + 卸载旧驱动 + # lsmod | grep uacce + uacce 262144 3 hisi_hpre,hisi_sec2,hisi_qm + # + # rmmod hisi_hpre + # rmmod hisi_sec2 + # rmmod hisi_qm + # rmmod uacce + # lsmod | grep uacce + # + 加载新驱动# modprobe uacce + # modprobe hisi_qm# modprobe hisi_sec2 #加载hisi_sec2驱动时将根据/etc/modprobe.d/hisi_sec2.conf 下的配置文件加载到内核 + # modprobe hisi_hpre #加载hisi_hpre驱动时将根据/etc/modprobe.d/hisi_hpre.conf 下的配置文件加载到内核 + # lsmod | grep uacce + uacce 36864 3 hisi_sec2,hisi_qm,hisi_hpre + ``` + +### 卸载加速器软件包 + +#### 使用场景 + +用户不再使用加速引擎软件，或进行新版本加速引擎软件的安装。 + +#### 操作步骤 + +1. 使用SSH远程登录工具，以root帐号进入Linux操作系统命令行界面。 +2. 重启系统或通过命令行手动将已加载到内核的驱动卸载掉，并查看是否卸载成功。 + + ```shell + # lsmod | grep uacce + uacce 36864 3 hisi_sec2,hisi_qm,hisi_hpre + # rmmod hisi_hpre + # rmmod hisi_sec2 + # rmmod hisi_qm + # rmmod uacce + # lsmod | grep uacce + # + ``` + +3. 通过rpm -e 命令卸载加速引擎软件包。示例如下。 + + > [!NOTE]说明 + > 由于存在依赖关系，卸载libwd前须先卸载libkae引擎软件包。 + + ![](./figures/zh-cn_image_0231143196.png) + + ![](./figures/zh-cn_image_0231143197.png) + +4. 使用rpm -qa |grep 软件包名命令查询是否卸载成功。 + + ![](./figures/zh-cn_image_0231143198.png) + +## 日志查询 + +加速器引擎涉及日志信息如[表3](#table52821836)所示。 + +**表 3** 日志信息 + + + + + + + + + + + + + + + + +

目录

+

文件名

+

文件内容说明

+

/var/log/

+

kae.log

+

OpenSSL引擎日志默认打印等级为error级别，如需要设置日志级别按照如下操作：

+
  1. export KAE_CONF_ENV=/var/log/
  2. 在/var/log/下创建文件kae.cnf
  3. 在kae.cnf 文件中设置如下：

    [LogSection]

    +

    debug_level=error #取值内容none/error/info/warning/debug

    +
+
说明：

正常情况下不建议开启info或debug级别日志，否则会导致加速器性能的下降。

+
+

/var/log/

+

message/syslog

+
  • 内核日志路径为/var/log/message。
+
说明：

或通过dmesg > /var/log/dmesg.log日志收集内核相关日志，包含驱动及内核态日志。

+
+
+ +## 加速引擎的应用 + +> [!NOTE]说明 +> 如果用户未购买引擎许可证，建议用户不要通过kae引擎调用相应算法，否则可能会影响openSSL加密算法的性能。 + +### KAE引擎使用示例代码 + +```c +#include + +#include + +/* OpenSSL headers */ + +#include + +#include + +#include + +#include + +int main(int argc, char **argv) + +{ + + /* Initializing OpenSSL */ + + SSL_load_error_strings(); + + ERR_load_BIO_strings(); + + OpenSSL_add_all_algorithms(); + + /*You can use ENGINE_by_id Function to get the handle of the Huawei Accelerator Engine*/ + + ENGINE *e = ENGINE_by_id("kae"); + + /*使能加速器异步功能，可选配置，设置为“0”表示不使能，设置为“1”表示使能，默认使能异步功能*/ + + ENGINE_ctrl_cmd_string(e, "KAE_CMD_ENABLE_ASYNC", "1", 0) + + ENGINE_init(e); + + + RSA *rsa = RSA_new_method(e);#指定引擎用于RSA加解密 + + /*The user code*/ + + …… + +; + + ENGINE_free(e); + +; + +} +``` + +### 通过OpenSSL配置文件openssl.cnf使用KAE引擎 + +新建openssl.cnf 需要添加如下配置信息 + +```text +openssl_conf=openssl_def +[openssl_def] +engines=engine_section +[engine_section] +kae=kae_section +[kae_section] +engine_id=kae +dynamic_path=/usr/local/lib/engines-1.1/kae.so +KAE_CMD_ENABLE_ASYNC=1 # 0，表示不使能异步功能，1表示使能异步功能，默认使能 +default_algorithms=ALL +init=1 +``` + +导出OPENSSL\_CONF环境变量： + +```shell +export OPENSSL_CONF=/home/app/openssl.cnf #该路径为openssl.cnf存放路径 +``` + +使用OpenSSL配置文件示例如下： + +```c +#include + +#include + +/* OpenSSL headers */ + +#include + +#include + +#include + +#include + +int main(int argc, char **argv) + +{ + + /* Initializing OpenSSL */ + + SSL_load_error_strings(); + + ERR_load_BIO_strings(); + +#Load openssl configure + +OPENSSL_init_crypto(OPENSSL_INIT_LOAD_CONFIG, NULL); OpenSSL_add_all_algorithms(); + + /*You can use ENGINE_by_id Function to get the handle of the Huawei Accelerator Engine*/ + + ENGINE *e = ENGINE_by_id("kae"); + + /*The user code*/ + + …… + +; + + ENGINE_free(e); + +; +} +``` + +## 故障处理 + +### 初始化失败 + +#### 故障现象 + +加速器引擎没有完全加载成功。 + +#### 处理步骤 + +1. 检查加速器驱动是否加载成功，运行lsmod 命令查看uacce.ko、qm.ko 、sgl.ko 、hisi\_sec2.ko 、hisi\_hpre.ko 、hisi\_zip.ko、 hisi\_rde.ko是否在位。 + + ```shell + # lsmod | grep uacce + uacce 262144 2 hisi_hpre,hisi_qm,hisi_sec2,hisi_zip,hisi_rde + ``` + +2. 检查/usr/lib64（RPM方式安装时目录）或者/usr/local/lib（源码方式安装时目录）和OpenSSL安装目录是否有加速器引擎库，且建立正确的软链接。 + + ```shell + # 查询kae是否正确安装并建立软链接，如果有正确安装显示如下内容 + # ll /usr/local/lib/engines-1.1/ |grep kae + lrwxrwxrwx. 1 root root 22 Nov 12 02:33 kae.so -> kae.so.1.0.1 + lrwxrwxrwx. 1 root root 22 Nov 12 02:33 kae.so.0 -> kae.so.1.0.1 + -rwxr-xr-x. 1 root root 112632 May 25 2019 kae.so.1.0.1 + + # 查询libwd是否正确安装并建立软链接，如果有正确安装显示如下内容 + # ll /usr/lib64/ | grep libwd + lrwxrwxrwx. 1 root root 14 Nov 12 02:33 libwd.so -> libwd.so.1.0.1 + lrwxrwxrwx. 1 root root 14 Nov 12 02:33 libwd.so.0 -> libwd.so.1.0.1 + -rwxr-xr-x. 1 root root 137120 May 25 2019 libwd.so.1.0.1 + ``` + +3. 检查OpenSSL引擎库的路径是否能通过export命令进行导出。 + + ```shell + # echo $OPENSSL_ENGINES + # export OPENSSL_ENGINES=/usr/local/lib/engines-1.1 + # echo $OPENSSL_ENGINES + /usr/local/lib/engines-1.1 + ``` + +### 安装完加速器引擎之后，查找不到加速器设备 + +#### 故障现象 + +安装完加速器引擎之后，查找不到加速器设备。 + +#### 解决方法 + +1. 检查虚拟文件系统下是否有相应设备。正常情况下有如下相应的加速器设备。 + + ```shell + # ls -al /sys/class/uacce/ + total 0 + lrwxrwxrwx. 1 root root 0 Nov 14 03:45 hisi_hpre-2 -> ../../devices/pci0000:78/0000:78:00.0/0000:79:00.0/uacce/hisi_hpre-2 + lrwxrwxrwx. 1 root root 0 Nov 14 03:45 hisi_hpre-3 -> ../../devices/pci0000:b8/0000:b8:00.0/0000:b9:00.0/uacce/hisi_hpre-3 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_rde-4 -> ../../devices/pci0000:78/0000:78:01.0/uacce/hisi_rde-4 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_rde-5 -> ../../devices/pci0000:b8/0000:b8:01.0/uacce/hisi_rde-5 + lrwxrwxrwx. 1 root root 0 Nov 14 08:39 hisi_sec-0 -> ../../devices/pci0000:74/0000:74:01.0/0000:76:00.0/uacce/hisi_sec-0 + lrwxrwxrwx. 1 root root 0 Nov 14 08:39 hisi_sec-1 -> ../../devices/pci0000:b4/0000:b4:01.0/0000:b6:00.0/uacce/hisi_sec-1 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_zip-6 -> ../../devices/pci0000:74/0000:74:00.0/0000:75:00.0/uacce/hisi_zip-6 + lrwxrwxrwx. 1 root root 0 Nov 17 22:09 hisi_zip-7 -> ../../devices/pci0000:b4/0000:b4:00.0/0000:b5:00.0/uacce/hisi_zip-7 + ``` + +2. 若要使用hpre设备但是在[1](#li1760055514614)中未查询到，请按[初始化失败](#初始化失败)排查加速器软件是否已正确安装。 +3. 若[2](#li1600175515610)已确认加速器软件正确安装，请通过lspci命令排查物理设备是否存在。 + + ```shell + # lspci | grep HPRE + 79:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon HPRE Engine (rev 21) + b9:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon HPRE Engine (rev 21) + ## lspci | grep SEC + 76:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon SEC Engine (rev 21) + b6:00.0 Network and computing encryption device: Huawei Technologies Co., Ltd. HiSilicon SEC Engine (rev 21) + ## lspci | grep RDE + 78:01.0 RAID bus controller: Huawei Technologies Co., Ltd. HiSilicon RDE Engine (rev 21) + b8:01.0 RAID bus controller: Huawei Technologies Co., Ltd. HiSilicon RDE Engine (rev 21) + ## lspci | grep ZIP + 75:00.0 Processing accelerators: Huawei Technologies Co., Ltd. HiSilicon ZIP Engine (rev 21) + b5:00.0 Processing accelerators: Huawei Technologies Co., Ltd. HiSilicon ZIP Engine (rev 21) + # + ``` + +4. 若[3](#li1560012551369)未查询到相应的物理设备，请确认以下，不分先后： + - 确认是否已导入加速器许可证，若未导入，请参考《[TaiShan 机架服务器 iBMC \(V500及以上\) 用户指南](https://support.huawei.com/enterprise/zh/doc/EDOC1100121687)》中“许可证管理”章节，导入加速器许可证。导入加速器许可证之后，需要掉电重启iBMC，使能License。 + - 确认iBMC和BIOS版本是否支持加速器特性。 + +### 升级加速器驱动失败 + +#### 故障现象 + +升级加速器驱动后，重启系统驱动版本仍为旧版本。 + +#### 可能原因 + +在升级加速器驱动前，系统更新了其他驱动包，这些驱动包可能重新更新了引导文件系统initramfs，将未升级前的加速器驱动一起更新到了initramfs文件系统中。例如系统更新了网卡驱动，或者人为更新了initramfs文件系统，导致系统重启时优先从initramfs文件系统中加载加速器驱动。 + +#### 处理步骤 + +升级加速器驱动版本后，通过执行dracut \-\-force命令重新更新initramfs文件系统。 diff --git a/kae-v2.spec b/kae-v2.spec index f387bd294f210aa2223dd81315742465d2c7edb5..eee239001865abd571bc549b39d4f128d4816681 100644 --- a/kae-v2.spec +++ b/kae-v2.spec @@ -1,7 +1,7 @@ Name: kae Summary: Huawei Kunpeng Accelerator Engine Zip Version: 2.0.0 -Release: 5 +Release: 6 License: GPL-2.0 Source: %{name}-%{version}.tar.gz ExclusiveOS: linux @@ -497,6 +497,9 @@ fi %changelog +* Tue Aug 12 2025 nieweiqiang 2.0.0-6 +- Add usr giude for KAE + * Tue Apr 2 2024 liuyang 2.0.0-5 - Second Spec Version Include kunpeng accelerator engine Code