寒武纪MLU SDK 之CNNL介绍和使用说明

简要概述

       Cambricon CNNL（寒武纪人工智能计算库）是一个基于寒武纪MLU并针对人工智能网络的计算库。Cambricon CNNL针对人工智能网络应用场景，提供了高度优化的常用算子，同时也为用户提供简洁、高效、通用、灵活并且可扩展的编程接口。

有关MLU系列产品介绍详细信息请查阅大大通博文《寒武纪产品简介》。

       Cambricon CNNL主要支持特性如下：

1. 丰富的基本算子：常见的网络算子，如卷积、池化、激活等。
2. 矩阵、计算类算子：矩阵乘、张量运算及变换、三角类变换等。
3. 循环网络算子：Long Short-Term Memory（LSTM），Gate Recurrent Unit（GRU）。
4. TensorFlow和Pytorch常用算子：Embedding前向和反向计算，Nllloss前向和反向计算。
5. 设计过程中充分考虑易用性，以通用为基本设计原则，算子支持不同的数据布局、灵活的维度限制以及多样的数据类型。
6. 结合寒武纪的硬件架构特点，优化Cambricon CNNL算子，使算子具有最佳性能，并且尽最大可能减少内存占用。
7. 提供包含资源管理的接口，满足用户更多线程、多板卡的应用场景。

 

部署CNNL

       Cambricon CNNL的使用依赖于CNToolkit工具包。用户在使用Cambricon CNNL库之前需要先安装寒武纪CNToolkit工具包，详细安装步骤可以参考大大通博文《寒武纪MLU SDK 之CNToolkit介绍和使用说明》。

     安装完成CNToolkit工具包后，执行下面命令部署Cambricon CNNL。默认头文件（cnnl.h）会安装在 /usr/local/neuware/include 目录下，链接库文件（libcnnl.so、libcnnl.a）会安装在 /usr/local/neuware/lib64 目录下，示例程序会安装在 /usr/local/neuware/samples/cnnl 目录下，其目录结构及说明如下：

|-- cnnl

  |-- CMakeLists.txt cmake描述文件，用于编译样例。

  |-- env.sh   设置必要的环境变量，指明动态库所在路径。

  |-- build.sh 自动化编译脚本，可在其中配置需要编译的样例，默认编译所有样例。

  |-- README.md 样例描述与指导。

  |-- conv_sample 卷积算子样例。

  |   |-- CMakeLists.txt 编译描述文件，用于编译样例程序。

  |   |-- conv_sample.cc 样例主程序，完成一次卷积运算。

  |   |-- tool.cc 辅助函数实现。

  |   |-- tool.h 辅助函数声明。

  |   |-- run_conv_sample.sh 运行样例程序的示例。

  |-- fault_demo 故障处理示例文件目录，其中代码可以引发典型的mlu unfinished错误，用于验证用户手册中调试方法的可行性。

  |   |-- fault_demo.cc 运行代码样例，执行后将会引发mlu unfinished错误。

  |   |-- fault_kernel.mlu 可以引发mlu unfinished的kernel代码。

  |   |-- fault_kernel.h 可以引发mlu unfinished的kernel代码。

1. For Ubuntu

命令行执行如下命令安装：

sudo apt install cnnl_1.3.0-2.ubuntu16.04_amd64.deb [cnnl_<x.y.z>-1.ubuntu<a.b>_<arch>.deb]

2. For Centos

命令行执行如下命令安装：

sudo yum install cnnl-<x.y.z>-1.el7.<arch>.rpm

3. For Edge-linux

『寒武纪边缘端嵌入式Linux系统基于ARM64，不具备包管理工具，因此需要通过解压的方式进行安装Cambricon CNNL，或者先在中心主机端系统下进行部署，然后拷贝到边缘端。同时，边缘端系统不具备直接编译、生成应用的能力，如果要在端侧运行Cambricon CNNL的示例程序或者二次开发，需要在ARM64主机端直接编译或者x86主机端交叉编译，再将生成的应用拷贝到边缘端。』

 

编译运行

进入docker环境

sudo ./run-cambricon-pytorch-docker-1604.sh

1. 全局编译或一键编译

cd path2/cnnl

source env.sh 设置环境变量，指定库路径

./build.sh运行脚本编译所有sample，可执行文件会存放到sample/build/bin目录下

也可以单独编译：

       cd path2/cnnl/conv_sample

       make clean && make生成可执行文件conv_sample

1. 运行样例

cd path2/cnnl/build/bin

./xxx_sample -[param1][param1_value]  -[param2][param2_value] -[param3][param3_value] ... 运行样例（后接参数）

样例：

./conv_sample -ni1 -hi14 -wi14 -ci256 -co256 -kh3 -kw3 -sh1 -sw1 -dh1 -dw1 -pt1 -pb1 -pl1 -pr1 -id3 -wd3 -od1 -hb0 -gc1

./conv_sample -ni1 -hi16 -wi16 -ci64 -co512 -kh3 -kw3 -sh1 -sw1 -dh1 -dw1 -pt0 -pb0 -pl0 -pr0 -id3 -wd3 -od1 -hb0 -gc1



执行./fault_demo 即可引发mlu unfinished错误。如果开启了 NEUWARE_LOGINFO 环境变量，屏幕上会打印出传入的参数 handle、input、workspace、output_desc、output 的指针地址，以及 split_num、axis、workspace_size 参数的赋值。input_desc 为 cnnlTensorDescriptor_t 类型，所以返回输入张量的数据类型、排列方式、各维度大小等信息，用以帮助调试错误。



在运行Cambricon CNNL算子接口前，用户可以设置 NEUWARE_LOGINFO环境变量，在运行算子接口时将传入的参数信息打印在屏幕上。该方法可以帮助用户检查参数是否传入正确。

设置方法如下：export NEUWARE_LOGINFO=cnnl

然后再次执行./fault_demo

『基本概念

1. 张量：具有统一数据类型的多维数组。
2. 张量描述符：描述所指向的张量具体信息的载体，包含了张量数据的数据布局、数据类型、维度个数、维度大小、步长大小等信息。通过张量描述符的表征，每一块张量数据才得以具有实际的语义信息，进而可以用来表示图像、语音或视频等各领域的数据。
3. 句柄：MLU设备资源不能被直接使用，Cambricon CNNL算子计算时通过句柄（handle）来维护MLU设备信息和队列信息等Cambricon CNNL 库运行环境的上下文。因此，需要在使用 Cambricon CNNL 库时，创建句柄并将句柄绑定到使用的MLU设备和队列上。
4. 工作空间：Cambricon CNNL 库中部分算子除了输入和输出数据的存放需要内存空间外，还需要额外的内存空间用于算子计算的优化。这部分额外的内存空间被称为工作空间 （workspace）。
5. 额外输入：Cambricon CNNL 库中的部分算子除了算子语义上的输入和输出外，还需要一个额外的输入内存空间（extraInput）用于算子的性能优化。extraInput 和正常的输入具有相同的特点。用户在使用带有 extraInput 参数的算子接口时，需要将MLU 设备端的 extraInput 指针传入算子接口中。Cambricon CNNL 会提供相关的接口和操作机制来对 extraInput 指向的内存进行赋值，用户只需要调用相关接口完成extraInput内存的数据赋值即可。』

 

参考资料

https://www.cambricon.com/docs/sdk_1.7.0/cambricon_cnnl_1.12.1/user_guide/3_quickstart/index.html#