OTP API 参考
前言
OTP是一种非易失性存储器。其主要特性是对应存储空间的位内容由0写为1后，或根据锁机制，锁定对应的区域后，就不能再修改。OTP主要用于保存一些特定的数据，如用于CIPHER模块的root key，安全使能标志等信息。
本文档（本指南）主要适用于以下工程师：
- 技术支持工程师
- 软件开发工程师
修订记录累积了每次文档更新的说明。最新版本的文档包含以前所有文档版本的更新内容。
概述
OTP模块提供驱动一次性编程的MPI接口，实现CIPHER模块root key烧写，jtag key烧写，key烧写状态校验，用户预留空间数据读写等功能。
OTP中密钥使用机制
图 1 SS528V100、SS524V100 OTP中密钥使用机制
图 2 Hi3403V100、SS626V100 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模块。
【语法】
【参数】
无。
【返回值】
参见错误码。 |
【需求】
- 头文件：ot_common_otp.h、ss_mpi_otp.h
- 库文件：libss_otp.a
【注意】
初始化和去初始化必须成对存在。
【举例】
无。
ss_mpi_otp_deinit
【描述】
去初始化OTP模块。
【语法】
【参数】
无。
【返回值】
参见错误码。 |
【需求】
- 头文件：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用户空间数据锁。
【语法】
【参数】
【返回值】
参见错误码。 |
【需求】
- 头文件：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。
【语法】
【参数】
【返回值】
参见错误码。 |
【需求】
- 头文件：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数据或锁标志。
【语法】
【参数】
【返回值】
参见错误码。 |
【需求】
- 头文件：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的校验状态。
【语法】
【参数】
【返回值】
参见错误码。 |
【需求】
- 头文件：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）。
【定义】
【成员】
无。
【注意事项】
无。
【相关数据类型及接口】
OT_OTP_PV_VALUE_MAX_LEN
【说明】
ot_otp_burn_pv_item成员value最大字节长度（单位：byte）。
【定义】
【成员】
无。
【注意事项】
无。
【相关数据类型及接口】
错误码
OTP提供的错误码如下所示。
表 1 OTP模块的错误码