Hi3403开发文档
前言¶
OTP是一种非易失性存储器。其主要特性是对应存储空间的位内容由0写为1后，或根据锁机制，锁定对应的区域后，就不能再修改。OTP主要用于保存一些特定的数据，如用于CIPHER模块的root key，安全使能标志等信息。
说明： 未有特殊说明，SS528V100与SS625V100、SS524V100与SS522V100、SS927V100与SS928V100内容一致。
与本文档相对应的产品版本如下。
本文档（本指南）主要适用于以下工程师：
技术支持工程师
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
概述¶
OTP模块提供驱动一次性编程的MPI接口，实现CIPHER模块root key烧写，jtag key烧写，key烧写状态校验，用户预留空间数据读写等功能。
OTP中密钥使用机制¶
OTP使用注意事项¶
OTP部署在不同场景下时，使用方式可能会有所不同。
在Linux环境下
用户态使用OTP可以通过链接静态库libss_otp.a或动态库libss_otp.so的方式，依赖libsecurec.a或libsecurec.so。
内核态OTP使用模块插入方式，即insmod ot_otp.ko，需要依赖ot_osal.ko，ot_base.ko，sys_config.ko，ot_sys.ko。
在OPTEE环境下，用户态调用OTP对外接口由Linux环境下的ss_mpi_xxx命名形式对应更改为ot_tee_xxx。
在UBOOT环境下，用户态调用OTP对外接口由Linux环境下的ss_mpi_xxx命名形式对应变更为ot_mpi_xxx。
API参考¶
OTP提供以下API：
ss_mpi_otp_init：初始化OTP模块。
ss_mpi_otp_deinit：去初始化OTP模块。
ss_mpi_otp_set_user_data：设置OTP用户空间数据。
ss_mpi_otp_get_user_data：读取OTP用户空间数据。
ss_mpi_otp_set_user_data_lock：设置OTP用户数据锁
ss_mpi_otp_get_user_data_lock：获取OTP用户数据锁
ss_mpi_otp_burn_product_pv：烧写PV的数据和锁标志到芯片内部OTP。
ss_mpi_otp_read_product_pv：获取芯片内部OTP的PV数据或锁标志。
ss_mpi_otp_get_key_verify_status：获取芯片内部OTP中存储KEY的校验状态。
ss_mpi_otp_init¶
【描述】
初始化OTP模块。
【语法】
td_s32 ss_mpi_otp_init(td_void);
【参数】
无。
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
初始化和去初始化必须成对存在。
【举例】
无。
ss_mpi_otp_deinit¶
【描述】
去初始化OTP模块。
【语法】
td_s32 ss_mpi_otp_deinit(td_void);
【参数】
无。
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
初始化和去初始化必须成对存在。
【举例】
无。
ss_mpi_otp_set_user_data¶
【描述】
设置OTP用户空间数据。
【语法】
td_s32 ss_mpi_otp_set_user_data(const td_char *field_name, td_u32 offset, const td_u8 *value, td_u32 value_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数field_name设定参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
offset必须 4 字节对齐。
value_len为value的字节长度。
参数offset，value_len取值范围参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“位宽”列。offset + value_len不能大于最大字节长度。
【举例】
无。
ss_mpi_otp_get_user_data¶
【描述】
获取OTP用户空间数据。
【语法】
td_s32 ss_mpi_otp_get_user_data(const td_char *field_name, td_u32 offset, td_u8 *value, td_u32 value_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数field_name设定参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
offset 必须 4 字节对齐。
value_len 为value字节长度。
参数offset，value_len取值范围参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“位宽”列。offset + value_len 不能大于最大取值。
【举例】
无。
ss_mpi_otp_set_user_data_lock¶
【描述】
设置OTP用户空间数据锁。
【语法】
td_s32 ss_mpi_otp_set_user_data_lock(const td_char *field_name, td_u32 offset, td_u32 value_len);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数field_name设定参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
offset 必须 4 字节对齐。
参数offset，value_len取值范围参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义定义”中“位宽”列。offset + value_len 不能大于最大取值。
SS528V100、SS524V100 不支持该接口。
【举例】
无。
ss_mpi_otp_get_user_data_lock¶
【描述】
获取OTP用户空间数据锁。
【语法】
td_s32 ss_mpi_otp_get_user_data_lock(const td_char *field_name, td_u32 offset, td_u32 value_len, ot_otp_lock_status *lock);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数field_name设定参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
offset 必须 4 字节对齐。
参数offset，value_len取值范围参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“位宽”列。offset + value_len 不能大于最大取值。
SS528V100、SS524V100 不支持该接口。
【举例】
无。
ss_mpi_otp_burn_product_pv¶
【描述】
烧写PV的数据和锁标志到芯片内部OTP。
【语法】
td_s32 ss_mpi_otp_burn_product_pv(const ot_otp_burn_pv_item *pv, td_u32 num);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数pv的成员burn必须设为TD_TRUE。
参数pv的成员field_name设定参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
参数pv的成员value_len为 value 的位长度，取值参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“位宽”列。
参数pv的成员value取值参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“说明”列。
参数pv的成员lock取值为TD_TRUE或TD_FALSE，《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“说明”列，自动lock的field_name配置任何值均会锁定。
参数num有效取值范围是1~500。
【举例】
无。
ss_mpi_otp_read_product_pv¶
【描述】
获取芯片内部OTP的PV数据或锁标志。
【语法】
td_s32 ss_mpi_otp_read_product_pv(ot_otp_burn_pv_item *pv, td_u32 num);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数pv的成员burn必须设为TD_FALSE。
参数pv的成员field_name设定《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
参数pv的成员value_len为value的位长度，取值参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“位宽”列。
参数pv的成员value取值参考《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“说明”列。
参数num有效取值范围是1~500。
【举例】
无。
ss_mpi_otp_get_key_verify_status¶
【描述】
获取芯片内部OTP中存储KEY的校验状态。
【语法】
td_s32 ss_mpi_otp_get_key_verify_status(const td_char *key_name, td_bool *status);
【参数】
【返回值】
参见错误码。 |
【需求】
头文件：ot_common_otp.h、ss_mpi_otp.h
库文件：libss_otp.a
【注意】
参数key_name设定《安全子系统使用说明》2.2章节“SSxxxx OTP字段定义”中“字段名称”列。
【举例】
无。
数据类型¶
相关数据类型、数据结构定义如下：
ot_otp_burn_pv_item：OTP PV数据类型。
ot_otp_lock_status：定义OTP数据锁状态。
OT_OTP_PV_NAME_MAX_LEN：字段名称最大字节长度（单位：byte）。
OT_OTP_PV_VALUE_MAX_LEN：ot_otp_burn_pv_item成员value最大字节长度（单位：byte）。
ot_otp_burn_pv_item¶
【说明】
OTP PV数据类型。
【定义】
typedef struct {
td_bool burn;
td_char field_name[OT_OTP_PV_NAME_MAX_LEN];
td_u32 value_len;
td_u8 value[OT_OTP_PV_VALUE_MAX_LEN];
td_bool lock;
} ot_otp_burn_pv_item;
【成员】
【注意事项】
value_len指向value的位宽长度。
【相关数据类型及接口】
ot_otp_lock_status¶
【说明】
定义OTP数据锁状态。
【定义】
typedef enum {
OT_OTP_STA_ALL_UNLOCKED = 0, /**< user data area is all unlock. */
OT_OTP_STA_PARTIAL_LOCKED, /**< user data area is partial unlock. */
OT_OTP_STA_ALL_LOCKED, /**< user data area is all lock. */
OT_OTP_STA_BUTT, /**< invalid param. */
} ot_otp_lock_status;
【成员】
【注意事项】
无。
【相关数据类型及接口】
OT_OTP_PV_NAME_MAX_LEN¶
【说明】
字段名称最大字节长度（单位：byte）。
【定义】
#define OT_OTP_PV_NAME_MAX_LEN 32
【成员】
无。
【注意事项】
无。
【相关数据类型及接口】
OT_OTP_PV_VALUE_MAX_LEN¶
【说明】
ot_otp_burn_pv_item成员value最大字节长度（单位：byte）。
【定义】
#define OT_OTP_PV_VALUE_MAX_LEN 32
【成员】
无。
【注意事项】
无。
【相关数据类型及接口】
错误码¶
OTP提供的错误码如下所示。
表 1 OTP模块的错误码