# HIFI5用户指南

## 概述

HiFi 子系统是一个用于语音控制/音频处理以及 DDR 动态频率缩放的子系统。该子系统集成了 HiFi5 DSP 和多个外设，例如 I2S、PDM 和 SPI。音频系统中还集成了一些其他外设，例如定时器、I2C 和 UART。 HiFi5 DSP 处理器可用于处理语音和音频数据。

基础系统采用`xos`，驱动层提供独立API，配合中间件进行开发。中间件包含语音处理和系统管理两部分，前者采用`SSF`路由软件框架，后者包含时间同步、看门狗、性能监控类工具包等。应用层的语音处理，可以自定义处理节点，插入到现有的pipeline中，也可以直接给予xos/驱动层接口进行嵌入式开发，开发自己的线程处理函数和中断回调等。

### 硬件架构

![HIFI_HW](./_static/_images/HIFI_HW.png)

### 软件架构
![Software_architecture_diagram](./_static/_images/Software_architecture_diagram.png)

关键词说明：\
KWS（Keyword Spotting）: 唤醒词识别\
VAD（Voice Activity Detection）：人声检测\
ASR（Automatic Speech Recognition）：语音识别\
AGC（Automatic Gain Control）：自动增益控制\
NS（Noise Suppression）：噪声抑制\
AEC（Acoustic Echo Cancellation）：自动回声消除\
DOA（Direction of Arrival）：声源定位\
BF（Beamforming）：波束成型\
ASR（Automatic Speech Recognition）：语音唤醒\
Speech Front-End Processing ：语音前端处理\
Primary Wake-up 一级唤醒\
Secondary Wake-up Front-end 二级唤醒前端处理\
Time Sync：时间同步\
Wake-up Scheme ： 唤醒方案

## <span id="quick_start"/> 快速开始

### 源码目录结构

`adsp`目录包含以下内容：

```
├── application             # HIFI5中间件入口
├── bsp_project             # 驱动代码
├── core_config             # xos工具链相关，编译依赖
├── custom_lsp              #
├── env_hf5.sh              # 环境配置脚本
├── Makefile                # 编译文件
├── Makefile.in             # 编译配置文件
├── output                  # 核心输出
├── output_sdk              # sdk输出
├── sample_wakeup           # A core 集成示例
├── ssf                     # 路由中间件
└── toolchain               # 编译工具链
```

其中示例`sample_wakeup`目录包含以下内容：
```
├── build                   # 编译目录
├── CMakeLists.txt          # cmake编译文件
├── hobot_speech_x5_sdk     # 算法SDK
├── i2c_control.sh          # 音频板加载脚本
├── include                 # 头文件目录
├── out                     # 输出目录
├── README.md               # 介绍
├── src                     # 源文件
├── x5audio_init.sh         # 板端使用的环境初始化脚本
└── xbuild.sh               # 编译脚本
```

### 编译

编译依赖：首先要编译SDK的`bsp`源码，选择相应开发板的版本。详情见[环境搭建及编译说明](../../bsp_develop.html)，并刷机；需要获取adsp编译工具链并放在adsp/toolchain目录下。

在adsp目录下执行

```bash
# firmware编译
source env_hf5.sh  # 选择编译的版本，输入0编译debug版本，再输入0不需编译测试用例
make clean # 清除历史数据
make application

# 进入示例目录，编译示例文件
cd sample_wakeup
./xbuild.sh
```
### 自动环境部署

Acore dts默认使能`dsp_dma`，系统启动加载dma controller，影响adsp firmware语音功能测试。因此在进行`adsp`测试时，
在uboot下通过环境变量关闭kernel dts中`dsp_dma`节点。

```bash
#关闭：
setenv fdt-blacklist "/soc/dsp_apb/dma-controller@32080000"

#打开：
setenv fdt-whitelist "/soc/dsp_apb/dma-controller@32080000"

#保存设置，执行
saveenv
#setenv设置后，每次刷机后单次设置后即可
boot
#进入kernel
```
**注意：手动关闭dsp_dma节点为临时方案**

`sample_wakeup`编译的时候会将结果输出到`sample_wakeup/out`目录中。

检查板端是否有读写权限，可使用
```bash
mount / -o rw,remount
```
命令打开读写权限。然后即可使用adb命，将整个`sample_wakeup/out`目录`adb push`到开发板的使用目录，如`/mnt`下后，示例目录如下所示：

```
sh-5.1# pwd
/mnt/out
sh-5.1# ls
adsp                      hrsc_sdk_demo_lp_to_normal  hrsc_sdk_demo_pipeline4
hobot_speech_device_test  hrsc_sdk_demo_pipeline0     i2c_control.sh
hrsc                      hrsc_sdk_demo_pipeline1     lib
hrsc_sdk_demo_files       hrsc_sdk_demo_pipeline2     x5audio_init.sh
```

执行
```bash
chmod 777 x5audio_init.sh
./x5audio_init.sh
```
即可完成环境部署。可以提供5个pipeline录音，1个pipeline播放的功能。

可以通过以下命令进行语音录音测试。
```bash
arecord -D hw:0,0 -c 4 -f S16_LE -r 16000 ./normal_record.wav   # 未经算法处理的原生音频 3mic+1ref
arecord -D hw:0,1 -c 1 -f S16_LE -r 16000 ./asr_record.wav      # 单通道asr音频
arecord -D hw:0,2 -c 2 -f S16_LE -r 16000 ./history_buffer.wav  # 2通道降噪后音频，用以语音唤醒
arecord -D hw:0,3 -c 4 -f S16_LE -r 16000 ./hisf_lp.wav         # 4通道低功耗降噪后音频
arecord -D hw:0,4 -c 4 -f S16_LE -r 16000 ./hisf_normal.wav     # 4通道经过降噪的音频，前三通道为mic降噪音频，用以唤醒，
                                                                # 第四通道为ASR音频，用以语音识别
aplay -D hw:0,0 test.wav                                        #支持2通道48k采样率16bit位宽的音频播放
```
pipeline定义如下图所示。要注意以下两点：
1. pipeline3链路上不会将数据送给alsa，如果使用arecord命令测试，alsa框架在10s无数据后触发超时给用户空间返回异常。
2.  pipeline2链路上数据依赖history buffer送出来的数据，单独启动pipeline2不会控制配置i2s驱动，alsa框架10s后触发超时用户空间返回异常。

![pipeline](./_static/_images/pipeline.png)

关于pipeline详细功能介绍、A core语音唤醒以及低功耗休眠唤醒相关介绍，请参阅[语音休眠唤醒示例](hifi5_02_sample.html#语音休眠唤醒示例)。

### 手动环境部署

1. firmware默认加载路径是：/lib/firmware
    V1.0.12版本acore会把firmware打包到镜像中
    镜像烧写默认将firmware安装在/usr/hobot/lib/firmware路径下，因此需要执行以下命令增加可查找的firmware路径：

    ```shell
    echo -n "/usr/hobot/lib/firmware" > /sys/module/firmware_class/parameters/path
    ```

2. 设置firmware名称。用户可根据实际fw名称在加载fw之前进行调整

    ```shell
    echo <adsp> > /sys/class/remoteproc/remoteproc0/firmware
    ```

    注意：`<>`尖括号不需要附加，`<>`中间的内容为`/usr/hobot/lib/firmware`路径下需要加载的固件文件名。

3. 加载firmware

    ```shell
    echo start > /sys/class/remoteproc/remoteproc0/state
    //测试...
    ```

4. 卸载firmware

    ```shell
    echo stop > /sys/class/remoteproc/remoteproc0/state
    ```
