文档

ID²设备端SDK适配接口

更新时间:

本文介绍了设备端适配过程中涉及的接口。

1. OSA适配接口

1.1 基础接口

  1. void ls_osa_print(const char *fmt, …)

  • 功能:打印函数,用于向串口或其他标准,输出打印日志或调试信息。

  • 参数:

    • "fmt":格式化字符串。

    • "...": 可变参数列表。

  • 返回值:实际写入缓冲区的字符串长度。

  1. int ls_osa_snprintf(char *str, size_t size, const char *fmt, ...)

  • 功能:打印函数,向内存缓冲区格式化构建一个字符串。

  • 参数:

    • "str": 指向字符串缓冲的指针。

    • "size":缓冲区的长度。

    • "fmt":格式化字符串。

    • "...": 可变参数列表。

  • 返回值:实际写入缓冲区的字符串长度。

  1. void *ls_osa_malloc(size_t size)

  • 功能:申请一块堆内存。

  • 参数:

    • "size":申请内存的字节大小。

  • 返回值:指向申请内存首地址的指针, 失败时返回NULL。

  1. void *ls_osa_calloc(size_t nmemb, size_t size)

  • 功能:分配nmemb个长度为size的连续堆内存,且内存数据置为0。

  • 参数:

    • "nmemb":内存块的数量。

    • "size": 单个内存的字节长度。

  • 返回值:指向申请内存首地址的指针, 失败时返回NULL。

  1. void ls_osa_free(void *ptr)

  • 功能:释放参数ptr指向的一块堆内存。

  • 参数:

    • "ptr": 指向要释放的堆内存的地址。

  1. void ls_osa_msleep(unsigned int msec)

  • 功能:睡眠函数,是当前执行线程睡眠指定的毫秒数。

  • 参数:

    • "msec": 线程挂起的时间,单位为毫秒。

  1. long long ls_osa_get_time_ms(void)

  • 功能:获取当前系统时间戳的大小。

  • 返回值:系统的时间戳的大小(以毫秒为单位)。

1.2 网络接口

  1. int ls_osa_net_connect(const char *host, const char *port, int type)

  • 功能:创建由host:port指定的,特定类型的网络连接。

  • 参数:

    • "host":连接的主机地址。

    • "port": 连接的端口号。

    • "type": 网络类型,LS_NET_TYPE_XXX。

  • 返回值:网络连接的句柄;失败返回-1。

  1. void ls_osa_net_disconnect(int fd)

  • 功能:断开网络连接,并释放相应资源。

  • 参数:

    • "fd": 网络连接的句柄。

  1. int ls_osa_net_send(int fd, unsigned char *buf, size_t len, int *ret_orig)

  • 功能:发送数据到指定的网络中。

  • 参数:

    • "fd":网络连接的句柄。

    • "buf": 发送数据的内存。

    • "len":发送数据的字节长度。

    • "ret_orig":接口返回失败时,指向具体的错误码。

  • 返回值:实际发送数据的长度;失败返回-1。

  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 互斥锁接口

  1. int ls_osa_mutex_create(void **mutex)

  • 功能:创建一个互斥锁,用于多线程下的同步访问。

  • 参数:

    • "mutex":指向创建互斥锁的句柄。

  • 返回值:成功返回0;失败返回-1。

  1. void ls_osa_mutex_destroy(void *mutex)

  • 功能:销毁互斥锁。

  • 参数:

    • "mutex":互斥锁的句柄。

  1. int ls_osa_mutex_lock(void *mutex)

  • 功能:锁住一个互斥量。

  • 参数:

    • "mutex":互斥量的句柄。

  • 返回值:成功返回0;失败返回-1。

  1. int ls_osa_mutex_unlock(void *mutex)

  • 功能:解锁一个互斥量。

  • 参数:

    • "mutex":互斥量的句柄。

  • 返回值:成功返回0;失败返回-1。

1.4 信号量接口

  1. ls_osa_sem_t ls_osa_sem_create(uint32_t init_val)

  • 功能:创建一个信号量。

  • 参数:信号量的初始值。

  • 返回值:创建的信号量句柄。

  1. void ls_osa_sem_destroy(ls_osa_sem_t sem)

  • 功能:销毁一个信号量。

  • 参数:信号量句柄。

  1. 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。

  1. void ls_osa_sem_post(ls_osa_sem_t sem)

  • 功能:执行信号量sem_post操作。

  • 参数:

    • sem:信号量句柄。

1.5 多线程接口

  1. 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:线程的最小栈大小

  • 返回值:创建的线程句柄。

  1. void ls_osa_thread_destroy(ls_osa_thread_t thread)

  • 功能:销毁一个线程。

  • 参数:

    • thread:线程句柄。

2. HAL适配接口

只针对ID² Soft-KM载体情况,其他安全载体不需要适配。

2.1 适配硬件ID

  1. 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 预留分区操作

  1. int ls_hal_open_rsvd_part(int flag)

  • 功能:根据指定的权限flag打开预留的管理分区。如不支持文件系统,直接返回0。

  • 参数:

    • "flag":指定管理分区的权限,如LS_HAL_READ。

  • 返回值:文件句柄或0;失败返回-1。

注意

系统中预留至少2K的Flash存储空间,用于ID²密钥数据的存储。正常使用和OTA升级时,数据不被擦除。

  1. int ls_hal_write_rsvd_part(int fd, uint32_t offset, void *data, uint32_t data_len)

  • 功能:向指定的分区中,写入指定字节的数据。

  • 参数:

    • "fd":文件句柄;没有文件系统时忽略。

    • "offset":写数据的偏移量。

    • "data": 写入的数据。

    • "data_len":写入数据的字节长度。

  • 返回值:成功返回0;失败返回-1。

  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。

  1. int ls_hal_close_rsvd_part(int fd)

  • 功能:关闭打开的预留分区。

  • 参数:

    • "fd":文件句柄;没有文件系统时忽略。

  • 返回值:成功返回0;失败返回-1。