update:完善注释

components/fskv/luat_fskv.h

@@ -1,82 +1,99 @@
-/*
- * Copyright (c) 2022 OpenLuat & AirM2M
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of
- * this software and associated documentation files (the "Software"), to deal in
- * the Software without restriction, including without limitation the rights to
- * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
- * the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
- * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
- * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
- * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
- * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- */
-
-#ifndef LUAT_FSKV_H
-#define LUAT_FSKV_H
-
-#include "lfs.h"
-
-
-
-/**
- * @defgroup luatos_fskv 持久化数据存储接口
- * @{
- */
-
-/**
- * @brief 初始化kv数据存储
- * 
- * @return int == 0 正常 != 0失败
- */
-int luat_fskv_init(void);
-
-/**
- * @brief 删除指定的key
- * @param key[IN] 待删除的key值
- * @return int == 0 正常 != 0失败
- */
-int luat_fskv_del(const char* key);
-
-/**
- * @brief 写入指定key的数据
- * @param key[IN] 待写入的key值,不能为NULL,必须是\0结尾,最大长度64字节
- * @param data[IN] 待写入的数据, 不需要\0结尾
- * @param len[IN] 待写入的数据长度, 不含\0,当前支持最大长度255字节
- * @return 实际写入的长度
- */
-int luat_fskv_set(const char* key, void* data, size_t len);
-
-int luat_fskv_size(const char* key, char buff[4]);
-
-/**
- * @brief 读取指定key的数据
- * @param key[IN] 待读取的key值,不能为NULL,必须是\0结尾
- * @param data[IN] 待读取的数据, 可写入空间必须大于等于len值
- * @param len[IN] 待读取的数据长度最大长度, 不含\0
- * @return int > 0 实际读取的长度, <=0 失败
- */
-int luat_fskv_get(const char* key, void* data, size_t len);
-
-/**
- * @brief 清空所有数据
- * @return int == 0 正常 != 0失败
- */
-int luat_fskv_clear(void);
-
-int luat_fskv_stat(size_t *using_sz, size_t *max_sz, size_t *kv_count);
-
-int luat_fskv_next(char* buff, size_t offset);
-
-/**
- * @}
- */
-
-#endif
+/*
+ * Copyright (c) 2022 OpenLuat & AirM2M
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef LUAT_FSKV_H
+#define LUAT_FSKV_H
+
+#include "lfs.h"
+
+
+
+/**
+ * @defgroup luatos_fskv 持久化数据存储接口
+ * @{
+ */
+
+/**
+ * @brief 初始化kv数据存储
+ * 
+ * @return int == 0 正常 != 0失败
+ */
+int luat_fskv_init(void);
+
+/**
+ * @brief 删除指定的key
+ * @param key[IN] 待删除的key值
+ * @return int == 0 正常 != 0失败
+ */
+int luat_fskv_del(const char* key);
+
+/**
+ * @brief 写入指定key的数据
+ * @param key[IN] 待写入的key值,不能为NULL,必须是\0结尾,最大长度64字节
+ * @param data[IN] 待写入的数据, 不需要\0结尾
+ * @param len[IN] 待写入的数据长度, 不含\0,当前支持最大长度255字节
+ * @return 实际写入的长度
+ */
+int luat_fskv_set(const char* key, void* data, size_t len);
+
+/**
+ * @brief 读取key大小
+ * @param key key值,不能为NULL,必须是\0结尾,最大长度64字节
+ * @param buff 缓冲区
+ * @return  长度,<=0 失败
+ */
+int luat_fskv_size(const char* key, char buff[4]);
+
+/**
+ * @brief 读取指定key的数据
+ * @param key[IN] 待读取的key值,不能为NULL,必须是\0结尾
+ * @param data[IN] 待读取的数据, 可写入空间必须大于等于len值
+ * @param len[IN] 待读取的数据长度最大长度, 不含\0
+ * @return int > 0 实际读取的长度, <=0 失败
+ */
+int luat_fskv_get(const char* key, void* data, size_t len);
+
+/**
+ * @brief 清空所有数据
+ * @return int == 0 正常 != 0失败
+ */
+int luat_fskv_clear(void);
+/**
+ * @brief 获取kv数据库状态
+ * @param using_sz 已使用的空间,单位字节
+ * @param max_sz 总可用空间, 单位字节
+ * @param kv_count 总kv键值对数量, 单位个
+ * @return 0 成功，其他失败
+ */
+int luat_fskv_stat(size_t *using_sz, size_t *max_sz, size_t *kv_count);
+/**
+ * @brief 读取下一个偏移的数据
+ * @param buff 读取数据
+ * @param offset 偏移
+ * @return 0 成功，其他失败
+ */
+int luat_fskv_next(char* buff, size_t offset);
+
+/**
+ * @}
+ */
+
+#endif

components/mobile/luat_mobile.h

@@ -691,8 +691,12 @@ int luat_mobile_event_deregister_handler(void);
  * @return int =0成功，其他失败
  */
 int luat_mobile_sms_sdk_event_register_handler(luat_mobile_sms_event_callback_t callback_fun);
+
 /**
- * @brief 和luat_mobile_sms_sdk_event_register_handler一样，只是为了兼容老的BSP
+ * @brief 注册底层短信消息回调函数，后续改为统一消息处理(和luat_mobile_sms_sdk_event_register_handler一样，只是为了兼容老的BSP)
+ *
+ * @param callback_fun 短信消息回调函数，如果为NULL，则是注销
+ * @return int =0成功，其他失败
  */
 int luat_mobile_sms_event_register_handler(luat_mobile_sms_event_callback_t callback_fun);
 /* ------------------------------------------------- mobile status end ------------------------------------------------ */

luat/include/luat_fs.h

@@ -36,9 +36,20 @@ typedef struct luat_fs_info
  * @return int =0成功，其他失败
  */
 int luat_fs_init(void);
-
+/**
+ * @brief 文件系统格式化
+ * @return int =0成功，其他失败
+ */
 int luat_fs_mkfs(luat_fs_conf_t *conf);
+/**
+ * @brief 文件系统挂载
+ * @return int =0成功，其他失败
+ */
 int luat_fs_mount(luat_fs_conf_t *conf);
+/**
+ * @brief 文件系统取消挂载
+ * @return int =0成功，其他失败
+ */
 int luat_fs_umount(luat_fs_conf_t *conf);
 
 /**
@@ -150,7 +161,15 @@ size_t luat_fs_fsize(const char *filename);
  * @return int =0不存在,否则存在
  */
 int luat_fs_fexist(const char *filename);
+/**
+ * @brief 行读取
+ * @param buf[OUT] 读取缓冲区
+ * @param bufsize[IN] 缓冲区大小
+ * @param stream[IN] 文件句柄
+ * @return int >=0实际写入的数量,<0出错
+ */
 int luat_fs_readline(char * buf, int bufsize, FILE * stream);
+
 void* luat_fs_mmap(FILE * stream);
 
 // TODO 文件夹相关的API
@@ -188,6 +207,13 @@ int luat_fs_rmdir(char const* _DirName);
 
 int luat_fs_lsdir(char const* _DirName, luat_fs_dirent_t* ents, size_t offset, size_t len);
 
+
+/**
+ * @brief 文件截断
+ * @param filename[IN] 文件名
+ * @param len[IN] 长度
+ * @return int =>0读取到文件个数,否则失败
+ */
 int luat_fs_truncate(const char* filename, size_t len);
 /**
  * @brief 文件夹是否存在

luat/include/luat_i2c.h

@@ -1,103 +1,137 @@
-#ifndef LUAT_I2C_H
-#define LUAT_I2C_H
-
-#include "luat_base.h"
-/**
- * @defgroup luatos_device_i2c I2C接口
- * @{
-*/
-
-/**
- * @brief 检查i2c是否存在
- * 
- * @param id i2c_id
- * @return 1存在 0不存在
- */
-int luat_i2c_exist(int id);
-
-/**
- * @brief 初始化i2c
- * 
- * @param id i2c_id
- * @param speed i2c 速度
- * @return 0成功 其他失败
- */
-int luat_i2c_setup(int id, int speed);
-
-/**
- * @brief 关闭 i2c
- * 
- * @param id i2c_id
- * @return 0成功 其他失败
- */
-
-int luat_i2c_close(int id);
-/**
- * @brief I2C 发送数据
- * 
- * @param id i2c_id
- * @param addr 7位设备地址
- * @param buff 数据buff
- * @param len 数据长度
- * @param stop 是否发送停止位
- * @return 0成功 其他失败
- */
-
-int luat_i2c_send(int id, int addr, void* buff, size_t len, uint8_t stop);
-
-/**
- * @brief I2C 接受数据
- * 
- * @param id i2c_id
- * @param addr 7位设备地址
- * @param buff 数据buff
- * @param len 数据长度
- * @return 0成功 其他失败
- */
-
-int luat_i2c_recv(int id, int addr, void* buff, size_t len);
-
-int luat_i2c_write_reg(int id, int addr, int reg, uint16_t value, uint8_t stop);
-int luat_i2c_read_reg(int id, int addr, int reg, uint16_t* value);
-/**
- * @brief I2C 收发数据
- * 
- * @param id i2c_id
- * @param addr 7位设备地址
- * @param reg 读的寄存器
- * @param reg_len 寄存器长度
- * @param buff 如果reg，reg_len 不为NULL，buff 为读的数据保存缓冲区，反之为写的缓冲区
- * @param len 数据长度
- * @return 0成功 其他失败
- */
-int luat_i2c_transfer(int id, int addr, uint8_t *reg, size_t reg_len, uint8_t *buff, size_t len);
-int luat_i2c_no_block_transfer(int id, int addr, uint8_t is_read, uint8_t *reg, size_t reg_len, uint8_t *buff, size_t len, uint16_t Toms, void *CB, void *pParam);
-
-/**
- * @brief 设置i2c复用
- * @attention 
- * @attention 
- * @param id i2c_id
- * @return -1 失败 其他正常
- */
-int luat_i2c_set_iomux(int id, uint8_t value);
-
-int luat_i2c_set_polling_mode(int id, uint8_t on_off);
-/** @}*/
-
-#define LUAT_EI2C_TYPE "EI2C*"
-
-typedef struct luat_ei2c {
-    int8_t sda;
-    int8_t scl;
-    int16_t udelay;
-} luat_ei2c_t;//软件i2c
-
-void i2c_soft_start(luat_ei2c_t *ei2c);
-char i2c_soft_recv(luat_ei2c_t *ei2c, unsigned char addr, char *buff, size_t len);
-char i2c_soft_send(luat_ei2c_t *ei2c, unsigned char addr, char *data, size_t len, uint8_t stop);
-
-
-#define toei2c(L) ((luat_ei2c_t *)luaL_checkudata(L, 1, LUAT_EI2C_TYPE))
-
-#endif
+#ifndef LUAT_I2C_H
+#define LUAT_I2C_H
+
+#include "luat_base.h"
+/**
+ * @defgroup luatos_device_i2c I2C接口
+ * @{
+*/
+
+/**
+ * @brief 检查i2c是否存在
+ * 
+ * @param id i2c_id
+ * @return 1存在 0不存在
+ */
+int luat_i2c_exist(int id);
+
+/**
+ * @brief 初始化i2c
+ * 
+ * @param id i2c_id
+ * @param speed i2c 速度
+ * @return 0成功 其他失败
+ */
+int luat_i2c_setup(int id, int speed);
+
+/**
+ * @brief 关闭 i2c
+ * 
+ * @param id i2c_id
+ * @return 0成功 其他失败
+ */
+
+int luat_i2c_close(int id);
+/**
+ * @brief I2C 发送数据
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param buff 数据buff
+ * @param len 数据长度
+ * @param stop 是否发送停止位
+ * @return 0成功 其他失败
+ */
+
+int luat_i2c_send(int id, int addr, void* buff, size_t len, uint8_t stop);
+
+/**
+ * @brief I2C 接受数据
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param buff 数据buff
+ * @param len 数据长度
+ * @return 0成功 其他失败
+ */
+int luat_i2c_recv(int id, int addr, void* buff, size_t len);
+
+/**
+ * @brief I2C 写寄存器
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param reg 寄存器地址
+ * @param value 数据
+ * @param stop 是否发送停止位
+ * @return 0成功 其他失败
+ */
+int luat_i2c_write_reg(int id, int addr, int reg, uint16_t value, uint8_t stop);
+/**
+ * @brief I2C 读寄存器
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param reg 寄存器地址
+ * @param value 数据
+ * @return 0成功 其他失败
+ */
+int luat_i2c_read_reg(int id, int addr, int reg, uint16_t* value);
+/**
+ * @brief I2C 收发数据
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param reg 读的寄存器
+ * @param reg_len 寄存器长度
+ * @param buff 如果reg，reg_len 不为NULL，buff 为读的数据保存缓冲区，反之为写的缓冲区
+ * @param len 数据长度
+ * @return 0成功 其他失败
+ */
+int luat_i2c_transfer(int id, int addr, uint8_t *reg, size_t reg_len, uint8_t *buff, size_t len);
+
+/**
+ * @brief I2C 收发数据(异步)
+ * 
+ * @param id i2c_id
+ * @param addr 7位设备地址
+ * @param is_read 是否为读写
+ * @param reg 读的寄存器
+ * @param reg_len 寄存器长度
+ * @param buff 如果reg，reg_len 不为NULL，buff 为读的数据保存缓冲区，反之为写的缓冲区
+ * @param len 数据长度
+ * @param Toms 数据长度
+ * @param CB 回调函数
+ * @param pParam 回调函数参数
+ * @return 0成功 其他失败
+ */
+int luat_i2c_no_block_transfer(int id, int addr, uint8_t is_read, uint8_t *reg, size_t reg_len, uint8_t *buff, size_t len, uint16_t Toms, void *CB, void *pParam);
+
+/**
+ * @brief 设置i2c复用
+ * @attention 
+ * @attention 
+ * @param id i2c_id
+ * @return -1 失败 其他正常
+ */
+int luat_i2c_set_iomux(int id, uint8_t value);
+
+int luat_i2c_set_polling_mode(int id, uint8_t on_off);
+/** @}*/
+
+#define LUAT_EI2C_TYPE "EI2C*"
+
+typedef struct luat_ei2c {
+    int8_t sda;
+    int8_t scl;
+    int16_t udelay;
+} luat_ei2c_t;//软件i2c
+
+void i2c_soft_start(luat_ei2c_t *ei2c);
+char i2c_soft_recv(luat_ei2c_t *ei2c, unsigned char addr, char *buff, size_t len);
+char i2c_soft_send(luat_ei2c_t *ei2c, unsigned char addr, char *data, size_t len, uint8_t stop);
+
+
+#define toei2c(L) ((luat_ei2c_t *)luaL_checkudata(L, 1, LUAT_EI2C_TYPE))
+
+#endif