ID²设备端SDK适配接口
本文介绍了设备端适配过程中涉及的接口。
1. OSA适配接口
1.1 基础接口
void ls_osa_print(const char *fmt, …)
功能：打印函数，用于向串口或其他标准，输出打印日志或调试信息。
参数：
"fmt"：格式化字符串。
"..."： 可变参数列表。
返回值：实际写入缓冲区的字符串长度。
int ls_osa_snprintf(char *str, size_t size, const char *fmt, ...)
功能：打印函数，向内存缓冲区格式化构建一个字符串。
参数：
"str"： 指向字符串缓冲的指针。
"size"：缓冲区的长度。
"fmt"：格式化字符串。
"..."： 可变参数列表。
返回值：实际写入缓冲区的字符串长度。
void *ls_osa_malloc(size_t size)
功能：申请一块堆内存。
参数：
"size"：申请内存的字节大小。
返回值：指向申请内存首地址的指针, 失败时返回NULL。
void *ls_osa_calloc(size_t nmemb, size_t size)
功能：分配nmemb个长度为size的连续堆内存，且内存数据置为0。
参数：
"nmemb"：内存块的数量。
"size": 单个内存的字节长度。
返回值：指向申请内存首地址的指针, 失败时返回NULL。
void ls_osa_free(void *ptr)
功能：释放参数ptr指向的一块堆内存。
参数：
"ptr": 指向要释放的堆内存的地址。
void ls_osa_msleep(unsigned int msec)
功能：睡眠函数，是当前执行线程睡眠指定的毫秒数。
参数：
"msec": 线程挂起的时间，单位为毫秒。
long long ls_osa_get_time_ms(void)
功能：获取当前系统时间戳的大小。
返回值：系统的时间戳的大小（以毫秒为单位）。
1.2 网络接口
int ls_osa_net_connect(const char *host, const char *port, int type)
功能：创建由host：port指定的，特定类型的网络连接。
参数：
"host"：连接的主机地址。
"port": 连接的端口号。
"type"： 网络类型，LS_NET_TYPE_XXX。
返回值：网络连接的句柄；失败返回-1。
void ls_osa_net_disconnect(int fd)
功能：断开网络连接，并释放相应资源。
参数：
"fd": 网络连接的句柄。
int ls_osa_net_send(int fd, unsigned char *buf, size_t len, int *ret_orig)
功能：发送数据到指定的网络中。
参数：
"fd"：网络连接的句柄。
"buf": 发送数据的内存。
"len"：发送数据的字节长度。
"ret_orig"：接口返回失败时，指向具体的错误码。
返回值：实际发送数据的长度；失败返回-1。
int ls_osa_net_recv(int fd, unsigned char *buf, size_t len, int timeout, int *ret_orig)
功能：在指定的时间内，从网络中读取最多len字节的数据。
参数：
"fd"：网络连接的句柄。
"buf": 接收数据的内存。
"len"：内存的最大长度。
"timeout"：读取数据的时间值，0代码阻塞。
"ret_orig"：接口返回失败时，指向具体的错误码。
返回值：实际接收数据的长度；失败返回-1。
1.3 互斥锁接口
int ls_osa_mutex_create(void **mutex)
功能：创建一个互斥锁，用于多线程下的同步访问。
参数：
"mutex"：指向创建互斥锁的句柄。
返回值：成功返回0；失败返回-1。
void ls_osa_mutex_destroy(void *mutex)
功能：销毁互斥锁。
参数：
"mutex"：互斥锁的句柄。
int ls_osa_mutex_lock(void *mutex)
功能：锁住一个互斥量。
参数：
"mutex"：互斥量的句柄。
返回值：成功返回0；失败返回-1。
int ls_osa_mutex_unlock(void *mutex)
功能：解锁一个互斥量。
参数：
"mutex"：互斥量的句柄。
返回值：成功返回0；失败返回-1。
1.4 信号量接口
ls_osa_sem_t ls_osa_sem_create(uint32_t init_val)
功能：创建一个信号量。
参数：信号量的初始值。
返回值：创建的信号量句柄。
void ls_osa_sem_destroy(ls_osa_sem_t sem)
功能：销毁一个信号量。
参数：信号量句柄。
int ls_osa_sem_wait(ls_osa_sem_t sem, uint32_t time_ms)
功能：执行信号量sem_wait操作。
参数：
sem：信号量句柄。
time_ms：当信号量阻塞时，等待的时间；当time_ms == LS_TIME_INFINITE时，阻塞直到执行sem_post唤醒。
返回值：成功返回0；失败返回-1。
void ls_osa_sem_post(ls_osa_sem_t sem)
功能：执行信号量sem_post操作。
参数：
sem：信号量句柄。
1.5 多线程接口
ls_osa_thread_t ls_osa_thread_create(const char *name, void(*func)(void *), void *arg, size_t stack_size)
功能：创建一个新的线程。
参数：
name：创建线程的名字。
func：创建线程的执行函数。
arg：创建线程的执行函数的参数。
stack_size：线程的最小栈大小
返回值：创建的线程句柄。
void ls_osa_thread_destroy(ls_osa_thread_t thread)
功能：销毁一个线程。
参数：
thread：线程句柄。
2. HAL适配接口
只针对ID² Soft-KM载体情况，其他安全载体不需要适配。
2.1 适配硬件ID
int ls_hal_get_dev_id(uint8_t *dev_id, uint32_t *id_len)
功能：获取设备硬件唯一ID。
参数：
"dev_id"：存储设备硬件唯一ID的内存。
"id_len"： 内存长度的指针。输入时，标明内存的大小；输出时，返回设备ID的大小。
返回值：成功返回0；失败返回-1。
2.2 预留分区操作
int ls_hal_open_rsvd_part(int flag)
功能：根据指定的权限flag打开预留的管理分区。如不支持文件系统，直接返回0。
参数：
"flag"：指定管理分区的权限，如LS_HAL_READ。
返回值：文件句柄或0；失败返回-1。
系统中预留至少2K的Flash存储空间，用于ID²密钥数据的存储。正常使用和OTA升级时，数据不被擦除。
int ls_hal_write_rsvd_part(int fd, uint32_t offset, void *data, uint32_t data_len)
功能：向指定的分区中，写入指定字节的数据。
参数：
"fd"：文件句柄；没有文件系统时忽略。
"offset"：写数据的偏移量。
"data"： 写入的数据。
"data_len"：写入数据的字节长度。
返回值：成功返回0；失败返回-1。
int ls_hal_read_rsvd_part(int fd, uint32_t offset, void *buffer, uint32_t read_len)
功能：从指定的分区中，读取指定字节的数据。
参数：
"fd"：文件句柄；没有文件系统时忽略。
"offset"：读数据的偏移量。
"buffer"： 读取数据的内存。
"read_len"：读取数据的字节长度。
返回值：成功返回0；失败返回-1。
int ls_hal_close_rsvd_part(int fd)
功能：关闭打开的预留分区。
参数：
"fd"：文件句柄；没有文件系统时忽略。
返回值：成功返回0；失败返回-1。