4. 系统flash写保护(flash_write_protect_v3)

本说明适用于AD24开源SDK，主要介绍如何将系统flash的代码与资源区域设置为写保护状态，包括以下几点：

系统flash写保护功能说明；

开发者在使用AD24 SDK开启写保护时需要的修改；

对于内封flash的芯片，如何获取对应flash型号的写保护参数；

对于A0芯片，介绍用户如何根据flash手册添加写保护参数；

介绍程序中如何打开与关闭内置flash写保护，介绍写保护相关接口；

注：该章节讲解的系统flash写保护与AD14/15/16/17/18、AC104以及AW30N不通用，如果要了解上述芯片的系统flash写保护相关信息，请参考对应芯片的SDK文档。

支持flash_write_protect_v3的SDK版本

芯片

支持的SDK版本

AD24N

ad24-release_v1.0.0 以及之后的SDK

本章节分为以下几个部分进行介绍说明：

1. “系统flash写保护的功能说明与须知”

2. “使用系统flash写保护时需要开启的配置”

3. “内封flash芯片如何获取写保护参数”

4. “A0芯片如何添加写保护参数”

5. “写保护参数下载到flash的步骤说明”

6. “系统flash写保护相关函数说明”

4.1. 系统flash写保护的功能说明与须知

SDK的系统flash写保护主要分为软件和硬件两种：

软件写保护，是指在底层驱动通过检测擦写的地址在保护范围内则不进行擦写，通过软件方式保护代码和资源文件。

硬件写保护，则是需要用户将写保护参数烧写到系统flash，然后通过SDK从系统flash读取写保护参数，然后将写保护参数配置给系统flash寄存器实现的硬件写保护。

软件写保护与硬件写保护的保护范围：

软件写保护的保护范围 由函数flash_code_protect_callback决定，一般保护vm区之前的区域。

硬件写保护的保护范围 与代码+资源的大小以及用户填入的写保护参数有关，SDK流程上会选择 写保护参数保护范围<=代码+资源 的范围进行保护，如果用户输入了多组写保护参数，SDK会 选择最接近并且小于代码+资源大小的写保护参数 进行使用。例如，代码+资源占用的大小为1028KB，用户填入的写保护参数组中最接近固件大小的保护范围是1024KB，则硬件写保护的范围是1024KB。

系统flash硬件写保护的一些特殊机制：

部分flash支持BP保护（保护范围不一定从0地址开始，且保护范围需要参考flash_datasheet）和WPS保护（保护的最小单位为块，保护范围比较灵活）两种机制

如果写保护参数中同时存在BP保护和WPS保护两种机制的参数，则SDK优先选择WPS保护机制的参数进行使用

4.2. 使用系统flash写保护时需要开启的配置

SDK系统flash的软件写保护默认开启，详细见flash_code_protect_callback函数。

系统flash的硬件写保护的功能需要开启部分配置，具体说明如下。

4.2.1. app_modules.h的配置

用户在需要使用系统flash写保护功能时，需要开启CONFIG_FLASH_WPS_EN宏，并且全编译。

图1 flash写保护功能开关

4.2.2. isd_config_ini.c配置

使用系统flash写保护功能时，需要在isd_config_ini.c添加以下语句。

图2 isd_config_ini.c写保护相关配置

4.3. A0芯片如何添加写保护参数

4.3.1. flash写保护工具说明

SDK的下载目录（路径：app\post_build\sh5x\voice_toy(工程)\）中存放有“flash_write_protect”文件夹，文件夹中包含以下文件：

0x—–_v3.xlsx：该文件以文本形式记录与文件名一致的flash的写保护参数。例如文件名为0xEF4017_v3.xlsx的文件，存储的则是flash_id为0xEF4017的flash写保护参数

flash_list_to_bin_v3.bat：该脚本实现将上述xlsx表格文件转成小机可识别的dir_sys_info文件

图2.1 flash写保护工具
用户将写保护参数填入到xlsx文件之后，点击flash_list_to_bin_v3.bat可生成flash_param_v3.bin文件，用于烧写到flash中给SDK读取使用。

4.3.2. 如何添加flash写保护参数（本文以华邦W25Q64为例，flash_id为0xEF4017）

如下对于A0的芯片，用户可自行根据需要使用的flash的datasheet，在0x—–_v3.xlsx文件中添加写保护参数以及相关指令，下文以华邦W25Q64 FLASH（flash_id为0xEF4017_v3）为例，介绍根据手册添加参数。我司配置flash写保护范围从0地址开始，向后覆盖。

4.3.2.1. flash状态寄存器读写指令集（flash_sta_cmd）

查询flash datasheet的instruction_set_table1，将状态寄存器的读写指令填入表格的flash_sta_cmd结构体

flash状态寄存器读写指令集

4.3.2.2. flash_otp_cfg配置

查询flash datasheet的instruction_set_table1和erase security registers，将写使能指令和flash支持的页大小和offset信息写入flash_otp_cfg结构体

flash_otp_cfg配置

4.3.2.3. flash_wp_cfg与wp_table配置（BP保护使用的配置）

该部分配置为SDK使用BP保护方式配置保护范围。用户可查询flash datasheet的instruction_set_table1和Status Register Memory Protection，将对应的写保护的寄存器配置填入表格的flash_wp_cfg结构体和wp_table，该部分分为两小节讲解。

flash_wp_cfg&wp_table配置

4.3.2.3.1. flash_wp_cfg配置

用户可查询flash datasheet的instruction_set_table1和Status Register Memory Protection得知BP保护中所使用到的flash状态寄存器有效位，然后将有效位写1映射的对应的状态寄存器的出所有状态寄存器的有效位，如下图

flash_wp_cfg配置

4.3.2.3.2. wp_table配置

用户可查询Status Register Memory Protection来选择自己需要的写保护范围写到表格中。例如加入256KB写保护范围的参数时，可按照以下步骤

wp_table配置

4.3.2.4. flash_wps_cfg（WPS保护使用的配置）

用户可查询Status Register中WPS位对应的寄存器，算出其有效位和寄存器值即可，可参考下图

flash_wps_cfg配置

4.4. 内封flash芯片如何获取写保护参数

用户在使用内封flash芯片时，可以从下载目录或者我司链接获取写保护参数

AD24N_V1.1.0版本开始可以从下载目录获取到内封flash的写保护参数

下载目录中的芯片内封flash写保护参数
芯片内封flash写保护参数获取链接 https://doc.zh-jieli.com/Tools/zh-cn/dev_tools/toolchains/otp_cfg.html

从链接获取到的写保护参数一般为flash_param_xxxxxxxx_v3.bin文件

4.5. 写保护参数下载到flash的步骤说明

将获取到的写保护参数文件(flash_param_v3.bin)拷贝到下载目录，在download_bat.c输入以下命令，点击编译下载即可以下载写保护参数到flash。

图3 flash参数下载命令

4.6. 系统flash写保护相关函数说明

4.6.1. 函数u32 flash_code_protect_callback(u32 offset, u32 len)

该函数为SDK使用系统flash软件写保护时，注册到底层的回调函数，因此底层flash驱动会调用到该函数，该函数决定软件写保护的保护范围。其中参数：:
1、返回值：
    超过正常擦写区域，不进行擦写操作 返回1；
    正常进行擦写 返回0；

4.6.2. 函数void tzflash_change_mode()

该函数为系统flash硬件写保护功能入口，该函数在功能开关开启后会读取烧到flash的写保护参数并且配置到flash的寄存器

4.6.3. 函数void tzflash_dump()

该函数在系统flash硬件写保护入口后调用，用户可通过打印信息得知写保护参数是否配置成功。

如果使用的是BP保护，则对照寄存器使用到的bit是否和参数表一样被置上，保护范围是否和参数表一致。如果两者均正确，则配置成功，如果寄存器值错误或者没有保护范围的打印，则配置失败。

如果使用的是WPS保护，则观察打印是否有显示保护范围。有则配置成功。