diff --git a/src/kernel/include/los_ld_elflib.h b/src/kernel/include/los_ld_elflib.h index 9a8a543..2ce398c 100644 --- a/src/kernel/include/los_ld_elflib.h +++ b/src/kernel/include/los_ld_elflib.h @@ -54,7 +54,7 @@ enum LOAD_STRATEGY { ZIP, NOZIP }; - +/*这是一个枚举类型的定义，名称为LOAD_STRATEGY。它包含两个成员：ZIP和NOZIP。*/ /** * @ingroup los_dynload * Define the structure of the parameters used for dynamic. @@ -64,7 +64,9 @@ enum LOAD_STRATEGY { typedef struct tagDynloadParam { enum LOAD_STRATEGY enLoadStrategy; } DYNLOAD_PARAM_S; - +/*这个结构体可以用来存储动态加载的参数信息， +其中enLoadStrategy成员表示加载策略，可以是ZIP或者NOZIP。通过使用这个结构体， +可以将加载策略作为参数传递给相关的函数或模块。*/ /** * @ingroup los_dynload * @brief Register the dynamic parameters. @@ -84,7 +86,8 @@ typedef struct tagDynloadParam { * @since Huawei LiteOS V100R001C00 */ extern VOID LOS_DynParamReg(DYNLOAD_PARAM_S *dynloadParam); - +/*通过调用LOS_DynParamReg函数并传递一个指向DYNLOAD_PARAM_S类型对象的指针， +可以将动态加载的参数信息注册到相关的系统或模块中。*/ /** * @ingroup los_dynload * @brief Load a shared object file. @@ -136,7 +139,7 @@ extern VOID *LOS_MemLoad(const CHAR *elfFileName, UINT32 fileNameLen, const CHAR *elfFileBuf, UINT32 bufLen); #endif /* LOSCFG_DYNLOAD_DYN_FROM_MEM */ #endif /* LOSCFG_KERNEL_DYNLOAD_DYN */ - +/*这段代码中使用了条件编译指令#ifdef和#endif，用于在不同的编译环境下选择是否启用动态加载功能。*/ #ifdef LOSCFG_KERNEL_DYNLOAD_REL /** * @ingroup los_dynload @@ -160,7 +163,9 @@ extern VOID *LOS_MemLoad(const CHAR *elfFileName, UINT32 fileNameLen, */ extern VOID *LOS_ObjLoad(CHAR *elfFileName); #endif /* LOSCFG_KERNEL_DYNLOAD_REL */ - +/*如果宏定义LOSCFG_KERNEL_DYNLOAD_REL被定义， +则表示启用了动态链接库的重定位功能，此时函数LOS_ObjLoad被声明为外部函数， +并接受一个指向字符串类型（CHAR）的指针作为参数，返回一个VOID类型的指针。*/ /** * @ingroup los_dynload * @brief Unload a module. @@ -182,7 +187,8 @@ extern VOID *LOS_ObjLoad(CHAR *elfFileName); * @since Huawei LiteOS V100R001C00 */ extern INT32 LOS_ModuleUnload(VOID *handle); - +/*通过调用LOS_ModuleUnload函数并传递一个动态库的句柄， +可以卸载该动态库并释放相关资源。*/ /** * @ingroup los_dynload * @brief Destroy a dynamic loader. @@ -203,7 +209,9 @@ extern INT32 LOS_ModuleUnload(VOID *handle); * @since Huawei LiteOS V100R001C00 */ extern VOID LOS_LdDestroy(VOID); +/*这段代码声明了一个外部函数LOS_LdDestroy，该函数没有参数和返回值。 +通过调用LOS_LdDestroy函数，可以销毁动态加载器（Loader），释放相关资源*/ /** * @ingroup los_dynload * @brief Search for a symbol address. @@ -250,7 +258,8 @@ extern VOID *LOS_FindSymByName(VOID *handle, CHAR *name); * @since Huawei LiteOS V100R001C00 */ extern INT32 LOS_PathAdd(CHAR *path); - +/*通过调用LOS_PathAdd函数并传递一个路径，可以将该路径添加到动态库搜索路径中。 +在动态链接库加载时，系统会按照一定的顺序搜索动态库*/ /** * @ingroup los_dynload * @brief Set the memory pool address used by dynload @@ -273,7 +282,9 @@ extern INT32 LOS_PathAdd(CHAR *path); * @since Huawei LiteOS V200R002C00 */ extern BOOL LOS_DynMemPoolSet(VOID *memPool); - +/*通过调用LOS_DynMemPoolSet函数并传递一个内存池指针， +可以设置动态内存池，用于在加载和执行动态链接库时分配内存。动态链接库可能 +需要在运行时分配内存来存储数据和执行代码，因此需要提供一个合适的内存池。*/ #ifdef __cplusplus #if __cplusplus } diff --git a/src/kernel/include/los_list.h b/src/kernel/include/los_list.h index b9f253d..3bbc961 100644 --- a/src/kernel/include/los_list.h +++ b/src/kernel/include/los_list.h @@ -50,6 +50,10 @@ typedef struct LOS_DL_LIST { struct LOS_DL_LIST *pstPrev; /**< Current node's pointer to the previous node */ struct LOS_DL_LIST *pstNext; /**< Current node's pointer to the next node */ } LOS_DL_LIST; +/*这种结构体通常用于实现双向链表数据结构。 +通过在每个节点中嵌入LOS_DL_LIST结构体， +可以将多个节点连接起来形成链表。 +*/ /** * @ingroup los_list @@ -74,7 +78,11 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListInit(LOS_DL_LIST *list) list->pstNext = list; list->pstPrev = list; } +/*这段代码定义了一个静态内联函数LOS_ListInit， +该函数接受一个指向LOS_DL_LIST结构体的指针list作为参数，没有返回值。 +函数的作用是将传入的链表初始化为空，即将链表头节点的pstNext和pstPrev指 +针都指向头节点本身，表示链表中没有其他节点。*/ /** * @ingroup los_list * @brief Point to the next node of the current node. @@ -93,7 +101,12 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListInit(LOS_DL_LIST *list) * @since Huawei LiteOS V100R001C00 */ #define LOS_DL_LIST_FIRST(object) ((object)->pstNext) +/*这段代码定义了一个宏LOS_DL_LIST_FIRST(object)， +它接受一个指向LOS_DL_LIST结构体的指针object作为参数， +并返回object指向的节点的下一个节点的指针，即链表中的第一个节点。 +这个宏的作用是方便地获取链表中的第一个节点，通过宏展开后， +可以直接访问链表头节点的下一个节点。*/ /** * @ingroup los_list * @brief Point to the previous node of the current node. @@ -112,7 +125,10 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListInit(LOS_DL_LIST *list) * @since Huawei LiteOS V100R001C00 */ #define LOS_DL_LIST_LAST(object) ((object)->pstPrev) - +/*这段代码是一个宏定义，用于获取双向链表中指定节点的前一个节点。 +在这里，传入的参数 object 是一个指向双向链表节点的指针， +pstPrev 是该节点中指向前一个节点的指针。 +该宏的功能是返回指定节点的前一个节点的指针。*/ /** * @ingroup los_list * @brief Insert a new node to a doubly linked list. @@ -138,7 +154,13 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListAdd(LOS_DL_LIST *list, LOS_DL_ list->pstNext->pstPrev = node; list->pstNext = node; } +/*该函数将新节点插入到链表头部，具体步骤如下： +把新节点的 next 指针指向链表头部的下一个节点。 +把新节点的 prev 指针指向链表头部。 +把原链表头部的下一个节点的 prev 指针指向新节点。 +把链表头部的 next 指针指向新节点。 +通过这些步骤，新节点就被成功地添加到了链表头部。*/ /** * @ingroup los_list * @brief Insert a node to a doubly linked list. @@ -161,7 +183,10 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListTailInsert(LOS_DL_LIST *list, { LOS_ListAdd(list->pstPrev, node); } - +/*在该函数中，使用了宏定义 LOS_DL_LIST 来表示链表节点， +使用了 STATIC INLINE 关键字来定义内联函数，以提高代码执行效率。 +函数的实现非常简单，只需调用双向链表的插入操作 LOS_ListAdd， +将新节点添加到链表头部的前一个节点即可。*/ /** * @ingroup los_list * @brief Insert a node to a doubly linked list. @@ -210,7 +235,12 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelete(LOS_DL_LIST *node) node->pstNext = NULL; node->pstPrev = NULL; } +/*该函数的实现非常简单，具体步骤如下： +把被删除节点的 next 节点的 prev 指针指向被删除节点的 prev 节点。 +把被删除节点的 prev 节点的 next 指针指向被删除节点的 next 节点。 +清空被删除节点的 next 指针和 prev 指针。 +通过这些步骤，被指定的节点就从链表中被成功地删除了。*/ /** * @ingroup los_list * @brief Identify whether a specified doubly linked list is empty or not. @@ -233,7 +263,12 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list) { return (BOOL)(list->pstNext == list); } +/*具体步骤如下： +判断链表头部的 pstNext 指针是否等于链表头部本身。 +如果相等，返回 TRUE（表示链表为空）。 +如果不相等，返回 FALSE（表示链表不为空）。 +通过这些步骤，可以判断链表是否为空。*/ /** * @ingroup los_list * @brief Obtain the offset of a structure member relative to the structure start address. @@ -256,7 +291,10 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list) /* Obsolete API, please use LOS_OFF_SET_OF instead */ #define OFFSET_OF_FIELD(type, field) LOS_OFF_SET_OF(type, field) - +/*这些宏的作用是帮助程序员在编写代码时可以方便地获取结构体成员的偏移量。 +通常情况下，结构体成员的偏移量用于在程序中进行内存操作， +比如根据结构体的指针和成员的偏移量， +可以获取到该成员的地址或修改该成员的值。*/ /** * @ingroup los_list * @brief Obtain the pointer to a structure that contains a doubly linked list. @@ -309,7 +347,12 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list) for (item = LOS_DL_LIST_ENTRY((list)->pstNext, type, member); \ &(item)->member != (list); \ item = LOS_DL_LIST_ENTRY((item)->member.pstNext, type, member)) +/*宏的实现通过 for 循环来实现链表的遍历，具体步骤如下： +首先使用 LOS_DL_LIST_ENTRY 宏获取链表头部节点的指针，并将其赋值给 item 变量，从而初始化遍历的起始位置。 +接着判断条件 &(item)->member != (list)，当遍历到链表末尾时，即链表头部时结束遍历，否则继续循环。 +在循环体内，执行对当前节点的操作，并使用 LOS_DL_LIST_ENTRY 宏获取下一个节点的指针，从而实现链表的顺序遍历。 +通过这些步骤，可以方便地遍历双向链表中的每个节点，并对每个节点执行相应的操作。*/ /** * @ingroup los_list * @brief Traverse a doubly linked list which is included in a given type structure. And @@ -343,7 +386,13 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list) next = LOS_DL_LIST_ENTRY((item)->member.pstNext, type, member); \ &(item)->member != (list); \ item = next, next = LOS_DL_LIST_ENTRY((item)->member.pstNext, type, member)) +/*该宏的功能是按顺序遍历链表中的每个节点，并对每个节点执行指定的操作。其参数包括： +item：表示当前遍历到的节点 +next：表示下一个节点的指针 +list：表示链表的头部 +type：表示链表节点所在的结构体类型 +member：表示链表节点在结构体中的成员名*/ /** * @ingroup los_list * @brief Iterate over a doubly linked list of given type, and call hook for any extra procedures every time. @@ -370,7 +419,13 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list) for (item = LOS_DL_LIST_ENTRY((list)->pstNext, type, member), hook; \ &(item)->member != (list); \ item = LOS_DL_LIST_ENTRY((item)->member.pstNext, type, member), hook) +/*该宏的功能是按顺序遍历链表中的每个节点，并在每个节点遍历之前执行指定的钩子函数。其参数包括： +item：表示当前遍历到的节点 +list：表示链表的头部 +type：表示链表节点所在的结构体类型 +member：表示链表节点在结构体中的成员名 +hook：表示要执行的钩子函数*/ /** * @ingroup los_list * @brief Delete a specified node from a doubly linked list and reinitialize the node. @@ -396,7 +451,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list) list->pstPrev->pstNext = list->pstNext; LOS_ListInit(list); } - +/**/ /** * @ingroup los_list * @brief Traverse a doubly linked list. @@ -423,7 +478,12 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list) for (item = (list)->pstNext; \ (item) != (list); \ item = (item)->pstNext) +/*宏的实现通过 for 循环来实现链表的遍历，具体步骤如下： +在循环初始化部分，将 item 初始化为链表头部节点的下一个节点，即 (list)->pstNext。 +在循环条件中，判断条件 (item) != (list)，当 item 等于链表头部时，即遍历到链表末尾时结束遍历，否则继续循环。 +在每次循环结束之后，将 item 更新为下一个节点的指针，即 (item)->pstNext。 +通过这些步骤，可以方便地遍历双向链表中的每个节点，并在循环体内对每个节点执行指定的操作。*/ /** * @ingroup los_list * @brief Traverse a doubly linked list safe against removal of list entry. @@ -475,7 +535,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list) * @since Huawei LiteOS V100R001C00 */ #define LOS_DL_LIST_HEAD(list) LOS_DL_LIST list = { &(list), &(list) } - +/*通过这个宏，可以方便地定义和初始化一个双向链表的头部节点，为链表的后续操作提供了便利。*/ #ifdef __cplusplus #if __cplusplus } diff --git a/src/kernel/include/los_lms.h b/src/kernel/include/los_lms.h index de4ac96..6463dc9 100644 --- a/src/kernel/include/los_lms.h +++ b/src/kernel/include/los_lms.h @@ -51,18 +51,30 @@ extern "C" { #define memmove_s KasanMemmoveSec #define strcat_s KasanStrcatSec #define strcpy_s KasanStrcpySec +/*使用#define预处理指令来重新定义标准库函数的名称。这种技术通常用于调试或测试目的，或者提供这些函数的自定义实现。 +代码片段中，函数memcpy、memmove、strcat和strcpy被重新定义为KasanMemcpy、 +KasanMemmove、KasanStrcat和KasanStrcpy。类似地，memcpy_s、memmove_s、strcat_s和strcpy_s +被重新定义为KasanMemcpySec、KasanMemmoveSec、KasanStrcatSec和KasanStrcpySec。*/ // End: Kernel Address Sanitizer(KASAN) for LiteOS VOID *KasanMemcpy(VOID *__restrict dest, const VOID *__restrict src, size_t copyAmount); VOID *KasanMemmove(VOID *dest, const VOID *src, size_t len); CHAR *KasanStrcat(CHAR *s, const CHAR *append); CHAR *KasanStrcpy(CHAR *dest, const CHAR *src); - +/*KasanMemcpy：类似于标准库中的memcpy，用于在内存中复制一定数量的数据。可能会包含额外的内存访问检查。 +KasanMemmove：类似于标准库中的memmove，用于在内存中移动一定数量的数据。同样可能包含额外的内存访问检查。 +KasanStrcat：类似于标准库中的strcat，用于将一个字符串附加到另一个字符串的末尾。可能包含额外的内存访问检查。 +KasanStrcpy：类似于标准库中的strcpy，用于将一个字符串复制到另一个字符串。同样可能包含额外的内存访问检查。*/ errno_t KasanMemcpySec(VOID *dest, size_t destMax, const VOID *src, size_t copyAmount); errno_t KasanMemmoveSec(VOID *dest, size_t destMax, const VOID *src, size_t len); errno_t KasanStrcatSec(CHAR *s, size_t destMax, const CHAR *append); errno_t KasanStrcpySec(CHAR *dest, size_t destMax, const CHAR *src); +/*主要是用于处理字符串和内存拷贝操作。这里的 destMax 参数通常表示目标缓冲区的最大长度，以防止缓冲区溢出等安全问题。 +KasanMemcpySec：类似于标准库中的memcpy，用于在内存中复制一定数量的数据。增加了目标缓冲区大小的参数，以保证不会发生缓冲区溢出。 +KasanMemmoveSec：类似于标准库中的memmove，用于在内存中移动一定数量的数据。同样增加了目标缓冲区大小的参数。 +KasanStrcatSec：类似于标准库中的strcat，用于将一个字符串附加到另一个字符串的末尾。增加了目标缓冲区大小的参数，以保证不会发生缓冲区溢出。 +KasanStrcpySec：类似于标准库中的strcpy，用于将一个字符串复制到另一个字符串。同样增加了目标缓冲区大小的参数。*/ #endif /* LOSCFG_KERNEL_LMS */ #ifdef __cplusplus diff --git a/src/kernel/include/los_lockdep.h b/src/kernel/include/los_lockdep.h index 848ce53..ce768a9 100644 --- a/src/kernel/include/los_lockdep.h +++ b/src/kernel/include/los_lockdep.h @@ -55,20 +55,33 @@ enum LockDepErrType { /* overflow, needs expand */ LOCKDEP_ERR_OVERFLOW, }; +/*这是一个枚举类型 LockDepErrType，用于表示在锁依赖性检查中可能发生的不同错误类型。下面是该枚举类型定义的各个取值及其含义： +LOCKDEP_SUCCESS：锁依赖性检查成功，没有发现错误。 +LOCKDEP_ERR_DOUBLE_LOCK：发现了重复加锁的错误。表示在某个线程中多次对同一把锁进行了加锁操作。 +LOCKDEP_ERR_DEAD_LOCK：发现了死锁的错误。表示在不同线程之间存在循环的锁依赖关系，导致了死锁的发生。 +LOCKDEP_ERR_UNLOCK_WITHOUT_LOCK：发现了未解锁的错误。表示在某个线程中出现了解锁操作，但该线程之前并未对对应的锁进行过加锁操作。 +LOCKDEP_ERR_OVERFLOW：溢出错误。表示枚举类型需要扩展，因为当前定义的取值已经无法满足需求。*/ typedef struct { VOID *lockPtr; VOID *lockAddr; UINT64 waitTime; UINT64 holdTime; } HeldLocks; - +/*这个结构体主要用于在锁依赖性分析和调试过程中记录当前线程持有的锁的相关信息。通过记录这些信息， +可以对锁的使用情况进行监控和分析，以便发现潜在的死锁、竞争条件等问题。 +lockPtr：表示持有的锁的指针。它是一个 VOID* 类型的指针，通常用于指向被持有的锁的内存地址。 +lockAddr：表示持有的锁的地址。它是一个 VOID* 类型的指针，通常用于指向锁对象的内存地址。 +waitTime：表示等待该锁的时间。它是一个 UINT64 类型的变量，通常表示在获取该锁之前，当前线程等待该锁的时间。 +holdTime：表示持有该锁的时间。它是一个 UINT64 类型的变量，通常表示当前线程已经持有该锁的时间。*/ typedef struct { VOID *waitLock; INT32 lockDepth; HeldLocks heldLocks[MAX_LOCK_DEPTH]; } LockDep; - +/*这个结构体主要用于在锁依赖性分析和调试过程中记录当前线程的锁依赖关系。 +通过记录当前线程正在等待的锁、持有的锁的深度以及每个层次的锁的详细信息， +可以对锁的使用情况进行监控和分析，以便发现潜在的死锁、竞争条件等问题。*/ /** * @ingroup los_lockdep * @@ -88,7 +101,8 @@ typedef struct { * @since Huawei LiteOS V200R003C00 */ extern VOID OsLockDepCheckIn(const SPIN_LOCK_S *lock); - +/*函数名称为 OsLockDepCheckIn，参数类型为 const SPIN_LOCK_S* lock，返回类型为 VOID。该函数的作用是将指定 +的自旋锁 lock 添加到锁依赖性检查中，用于进行锁依赖性的分析和调试。*/ /** * @ingroup los_lockdep * @@ -128,7 +142,8 @@ extern VOID OsLockDepRecord(SPIN_LOCK_S *lock); * @since Huawei LiteOS V200R003C00 */ extern VOID OsLockDepCheckOut(SPIN_LOCK_S *lock); - +/*函数名称为 OsLockDepCheckOut，参数类型为 SPIN_LOCK_S* lock，返回类型为 VOID。该函数的作用 +是从锁依赖性检查中移除指定的自旋锁 lock，用于结束对该锁的依赖性分析和调试。*/ /** * @ingroup los_lockdep * diff --git a/src/kernel/include/los_lowpower.h b/src/kernel/include/los_lowpower.h index fceebf6..936b791 100644 --- a/src/kernel/include/los_lowpower.h +++ b/src/kernel/include/los_lowpower.h @@ -57,7 +57,14 @@ typedef enum LOS_INTERMIT_MODE { LOS_INTERMIT_SHUTDOWN, /**< Shutdown mode */ LOS_INTERMIT_MAX, } LosIntermitMode; +/*这是一个枚举类型 LOS_INTERMIT_MODE 的定义，包含了几个枚举常量： +LOS_INTERMIT_NONE：表示没有中断模式 +LOS_INTERMIT_LIGHT_SLEEP：表示轻度睡眠模式 +LOS_INTERMIT_DEEP_SLEEP：表示深度睡眠模式 +LOS_INTERMIT_STANDBY：表示待机模式 +LOS_INTERMIT_SHUTDOWN：表示关机模式 +LOS_INTERMIT_MAX：该枚举类型的最大值，用于辅助枚举类型的范围检查*/ /** * @ingroup los_lowpower * @@ -70,7 +77,13 @@ typedef enum LOS_FREQ_MODE { LOS_SYS_FREQ_LOW, /**< Low freq */ LOS_SYS_FREQ_MAX, } LosFreqMode; +/*这是另一个枚举类型 LOS_FREQ_MODE 的定义，包含了几个枚举常量： +LOS_SYS_FREQ_SUPER：表示超高频模式 +LOS_SYS_FREQ_HIGH：表示高频模式 +LOS_SYS_FREQ_NORMAL：表示正常频率模式 +LOS_SYS_FREQ_LOW：表示低频模式 +LOS_SYS_FREQ_MAX：该枚举类型的最大值，用于辅助枚举类型的范围检查*/ typedef UINT32 (*LowpowerExternalVoterHandle)(VOID); STATIC INLINE BOOL FreqHigher(LosFreqMode freq1, LosFreqMode freq2) @@ -96,7 +109,19 @@ typedef struct { UINT32 (*getSleepMode)(VOID); /**< Get sleep mode interface, the retval type is LosIntermitMode */ VOID (*setSleepMode)(UINT32 mode); /**< Set sleep mode interface, the param type is LosIntermitMode */ } PowerMgrOps; +/*这是一个结构体类型 PowerMgrOps 的定义，包含了多个函数指针成员： +process：电源管理框架的入口接口 +wakeupFromReset：从镜像中唤醒的恢复接口 +resumeFromInterrupt：从中断中唤醒的恢复接口 +changeFreq：系统频率调节接口，参数为 LosFreqMode +deepSleepVoteBegin：深度睡眠投票标记接口 +deepSleepVoteEnd：深度睡眠投票取消接口 +deepSleepVoteDelay：深度睡眠投票延迟接口，参数为延迟的时钟周期数 +registerExternalVoter：注册外部投票者接口，参数为一个函数指针，返回值为 UINT32 +getDeepSleepVoteCount：获取深度睡眠投票计数接口，返回 UINT32 +getSleepMode：获取睡眠模式接口，返回值类型为 LosIntermitMode +setSleepMode：设置睡眠模式接口，参数类型为 UINT32，表示 LosIntermitMode*/ /** * @ingroup los_lowpower * @brief System main frequency tuning. @@ -115,7 +140,9 @@ typedef struct { * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_PowerMgrChangeFreq(LosFreqMode freq); - +/*这是一个外部声明（extern）的函数 LOS_PowerMgrChangeFreq， +它接受一个 LosFreqMode 类型的参数 freq，用于改变系统的工作频率。 +根据函数名和参数类型来看，这个函数很可能是用于在系统中切换不同的工作频率模式。*/ /** * @ingroup los_lowpower * @brief Vote to enter deep sleep. @@ -153,7 +180,8 @@ extern VOID LOS_PowerMgrDeepSleepVoteBegin(VOID); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_PowerMgrDeepSleepVoteEnd(VOID); - +/*这是一个外部声明（extern）的函数 LOS_PowerMgrDeepSleepVoteEnd，它没有任何参数，返回类型为 VOID。根据函数名来看， +这个函数很可能用于结束深度睡眠投票，即取消之前进行的深度睡眠投票。*/ /** * @ingroup los_lowpower * @brief Sleep delay vote. @@ -172,7 +200,8 @@ extern VOID LOS_PowerMgrDeepSleepVoteEnd(VOID); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_PowerMgrSleepDelay(UINT32 tick); - +/*这是一个外部声明（extern）的函数 LOS_PowerMgrSleepDelay，它接受一个 UINT32 类型的参数 tick， +用于在系统中设置睡眠延迟，即指定一定的时钟周期数作为睡眠延迟。*/ /** * @ingroup los_lowpower * @brief Register the external voter. @@ -191,7 +220,9 @@ extern VOID LOS_PowerMgrSleepDelay(UINT32 tick); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_PowerMgrRegisterExtVoter(UINT32 (*)(VOID)); - +/*这是一个外部声明（extern）的函数 LOS_PowerMgrRegisterExtVoter， +它接受一个函数指针作为参数，该函数指针指向一个不接受任何参数并返回 UINT32 类型的函数。根据函数名来看，这个函数很可能用于注册外部投票者 +，即将提供的函数指针注册为外部投票者的处理函数。*/ /** * @ingroup los_lowpower * @brief Get the sleep mode. @@ -250,7 +281,9 @@ extern UINT32 LOS_PowerMgrGetDeepSleepVoteCount(VOID); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_LowpowerInit(const PowerMgrOps *pmOps); - +/*这是一个外部声明（extern）的函数 LOS_LowpowerInit， +它接受一个 const PowerMgrOps * 类型的指针参数 pmOps，用于初始化低功耗模式下的系统。根据函数名来看，这个函数很可能是用于在系统启动时初始化与低功耗相关的操作和参数， +以便后续能够进入低功耗状态并正确恢复系统。*/ /** * @ingroup los_lowpower * @brief Define the lowpower framework process function type. @@ -269,7 +302,10 @@ extern VOID LOS_LowpowerInit(const PowerMgrOps *pmOps); * @since Huawei LiteOS V200R005C10 */ typedef VOID (*LowPowerHookFn)(VOID); - +/*这是一个类型定义语句，定义了一个名为 LowPowerHookFn 的函数指针类型。 +该函数指针类型指向一个不接受任何参数并返回 VOID 的函数。 +这种类型的函数指针通常用于注册低功耗模式下的钩子函数， +以便在进入或退出低功耗模式时执行特定的操作*/ /** * @ingroup los_lowpower * @brief Register a hook to enter lowpower framework process. @@ -288,7 +324,10 @@ typedef VOID (*LowPowerHookFn)(VOID); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_LowpowerHookReg(LowPowerHookFn hook); - +/*这是一个外部声明（extern）的函数 LOS_LowpowerHookReg， +它接受一个 LowPowerHookFn 类型的参数 hook，用于注册低功耗模式下的钩子函数。 +根据函数名来看，这个函数很可能用于在系统中注册低功耗模式下的钩子函数， +以便在进入或退出低功耗模式时执行特定的操作。*/ /** * @ingroup los_lowpower * @brief Define the lowpower framework wakup function type. @@ -307,7 +346,10 @@ extern VOID LOS_LowpowerHookReg(LowPowerHookFn hook); * @since Huawei LiteOS V200R005C10 */ typedef VOID (*IntWakeupHookFn)(HWI_HANDLE_T hwiNum); - +/*这是一个类型定义语句，定义了一个名为 IntWakeupHookFn 的函数指针类型。 +该函数指针类型指向一个接受 HWI_HANDLE_T 类型参数并返回 VOID 的函数。 +这种类型的函数指针通常用于注册中断唤醒的钩子函数，以便在特定中断唤醒事件发生时执行特定的操作。 +*/ /** * @ingroup los_lowpower * @brief Register a hook to wakeup from interrupt. @@ -326,7 +368,11 @@ typedef VOID (*IntWakeupHookFn)(HWI_HANDLE_T hwiNum); * @since Huawei LiteOS V200R005C10 */ extern VOID LOS_IntWakeupHookReg(IntWakeupHookFn hook); - +/*这是一个外部声明（extern）的函数 LOS_IntWakeupHookReg， +它接受一个 IntWakeupHookFn 类型的参数 hook，用于注册中断唤醒的钩子函数。 +根据函数名来看，这个函数很可能用于在系统中注册中断唤醒的钩子函数， +以便在特定中断唤醒事件发生时执行特定的操作。 +*/ #ifdef __cplusplus #if __cplusplus } diff --git a/src/kernel/include/los_lowpower_impl.h b/src/kernel/include/los_lowpower_impl.h index c319ad2..4a8be8d 100644 --- a/src/kernel/include/los_lowpower_impl.h +++ b/src/kernel/include/los_lowpower_impl.h @@ -59,7 +59,22 @@ typedef struct { UINT32 (*getSleepMode)(VOID); /**< Get sleep mode */ VOID (*setSleepMode)(UINT32 mode); /**< Set sleep mode */ } PowerMgrRunOps; +/*具体来说，该结构体包含以下函数指针成员： +changeFreq：调整系统频率。 +enterLightSleep：进入轻度睡眠（light sleep）模式。 +enterDeepSleep：进入深度睡眠（deep sleep）模式。 +setWakeUpTimer：设置唤醒定时器。 +withdrawWakeUpTimer：撤销唤醒定时器。 +getSleepTime：获取睡眠时间。 +selectSleepMode：选择进入睡眠模式的策略函数。 +preConfig：提供特殊需要在进入睡眠前进行的预配置。 +postConfig：提供特殊需要在唤醒后进行的后配置。 +contextSave：保存上下文。 +contextRestore：恢复上下文。 +getDeepSleepVoteCount：获取深度睡眠投票计数。 +getSleepMode：获取当前睡眠模式。 +setSleepMode：设置睡眠模式。*/ /** * @ingroup los_lowpower * @@ -70,7 +85,11 @@ typedef struct { UINT32 minDeepSleepTicks; /**< Min deep sleep ticks */ UINT32 maxDeepSleepTicks; /**< Max deep sleep ticks */ } PowerMgrConfig; - +/*minLightSleepTicks：最小轻度睡眠（light sleep）时钟周期数。 +minDeepSleepTicks：最小深度睡眠（deep sleep）时钟周期数。 +maxDeepSleepTicks：最大深度睡眠（deep sleep）时钟周期数。 +这些成员变量可能用于配置功耗管理模块的相关参数，以控制系统进入不同级别的睡眠模式， +并限制最小和最大的睡眠时长。具体的含义和用法需要根据上下文和使用场景来确定。*/ /** * @ingroup los_lowpower * @@ -88,7 +107,16 @@ typedef struct { VOID (*otherCoreResume)(VOID); /**< Other core Resume for multi-core scenes */ VOID (*resumeFromReset)(VOID); /**< Resume from image */ } PowerMgrDeepSleepOps; - +/*couldDeepSleep：检查系统是否可以进入深度睡眠状态。 +systemWakeup：唤醒系统。 +suspendPreConfig：提供特殊需要在进入深度睡眠前进行的暂停预配置。 +suspendDevice：进入深度睡眠前暂停设备。 +rollback：如果进入深度睡眠失败，则回滚。 +resumeDevice：从深度睡眠状态恢复后恢复设备。 +resumePostConfig：提供特殊需要在从深度睡眠状态中恢复后进行的恢复后配置。 +resumeCallBack：恢复回调。 +otherCoreResume：多核场景下，其他核心的恢复方法。 +resumeFromReset：从映像中恢复。*/ /** * @ingroup los_lowpower * @@ -99,7 +127,10 @@ typedef struct { PowerMgrDeepSleepOps deepSleepOps; /**< power manager deep sleep operations */ PowerMgrConfig config; /**< power manager config */ } PowerMgrParameter; - +/*runOps：类型为 PowerMgrRunOps 的结构体变量，用于描述系统运行状态下的功耗管理操作集合。 +deepSleepOps：类型为 PowerMgrDeepSleepOps 的结构体变量，用于描述系统进入深度睡眠状态下的功耗管理操作集合。 +config：类型为 PowerMgrConfig 的结构体变量，用于配置功耗管理模块的相关参数，控制系统进入不同级别的睡眠模式。 +通过将这些结构体变量组合到 PowerMgrParameter 结构体中，可以实现对系统运行状态和深度睡眠状态下的功耗管理操作进行统一管理和配置。*/ /** * @ingroup los_lowpower * @brief Init the power manager framework. diff --git a/src/kernel/include/los_membox.h b/src/kernel/include/los_membox.h index a2bf88d..8e0d4e7 100644 --- a/src/kernel/include/los_membox.h +++ b/src/kernel/include/los_membox.h @@ -75,7 +75,17 @@ extern "C" { * Head size of each node in staic memory pool */ #define OS_MEMBOX_NODE_HEAD_SIZE sizeof(LOS_MEMBOX_NODE) + /*LOS_MEMBOX_ALLIGNED(memAddr) 宏用于对内存地址进行对齐操作。 + 它将 memAddr 强制转换为 UINTPTR 类型，然后加上 sizeof(UINTPTR) - + 1，再进行按位取反操作，最后与 ~(sizeof(UINTPTR) - 1) 进行按位与运算。 + 这样可以确保地址按照 sizeof(UINTPTR) 字节对齐。 +OS_MEMBOX_NEXT(addr, blkSize) 宏用于获取静态内存池中下一个节点的地址。 +它将 addr 强制转换为 UINT8* 类型，然后加上 blkSize，得到下一个节点的地址。 + +OS_MEMBOX_NODE_HEAD_SIZE 宏定义了静态内存池中每个节点的头部大小，即 LOS_MEMBOX_NODE 的大小。 + +这些宏在静态内存池的实现中起到了辅助作用，用于计算和管理内存节点的地址和大小。*/ /** * @ingroup los_membox * @brief Obtain the size of the static memory pool. @@ -98,7 +108,10 @@ extern "C" { */ #define LOS_MEMBOX_SIZE(blkSize, blkNum) \ (sizeof(LOS_MEMBOX_INFO) + (LOS_MEMBOX_ALLIGNED((blkSize) + OS_MEMBOX_NODE_HEAD_SIZE) * (blkNum))) + /*该宏首先使用 LOS_MEMBOX_ALLIGNED 宏对 (blkSize) + OS_MEMBOX_NODE_HEAD_SIZE 进行对齐操作，确保每个内存块都按照节点大小对齐。然后将对齐后的大小乘以 blkNum，并加上 sizeof(LOS_MEMBOX_INFO)，得到静态内存池的总大小。 +其中，sizeof(LOS_MEMBOX_INFO) 表示静态内存池的元信息（头部）大小， +包括内存池起始地址、内存块大小、内存块数量等信息。*/ /** * @ingroup los_membox * Structure of a free node in a static memory pool @@ -124,7 +137,11 @@ typedef struct { } LOS_MEMBOX_INFO; typedef LOS_MEMBOX_INFO OS_MEMBOX_S; +/*LOS_MEMBOX_INFO：静态内存池的元信息结构体。包含了静态内存池的起始地址、 +内存块大小、内存块数量等信息。同时还包含了 uwBlkCnt 记录已分配内存块数量的成员变量 +和 stFreeList 用于记录空闲内存块的链表（仅在 LOSCFG_KERNEL_MEMBOX_STATIC 宏定义时可用）。 +OS_MEMBOX_S：与 LOS_MEMBOX_INFO 结构体等价的别名。*/ /** * @ingroup los_membox * @brief Initialize a static memory pool. @@ -153,7 +170,8 @@ typedef LOS_MEMBOX_INFO OS_MEMBOX_S; * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxInit(VOID *pool, UINT32 poolSize, UINT32 blkSize); - +/*该函数会使用提供的内存池起始地址和大小来初始化静态内存池，并指定每个内存块的大小。 +在初始化完成后，该内存池将可以被用于分配内存块。*/ /** * @ingroup los_membox * @brief Request a static memory block. @@ -202,7 +220,7 @@ extern VOID *LOS_MemboxAlloc(VOID *pool); * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxFree(VOID *pool, VOID *box); - +/*调用该函数将会释放 box 所指向的内存块，并将其重新加入到内存池的空闲内存块链表中，以便下次分配使用。*/ /** * @ingroup los_membox * @brief Clear a static memory block. @@ -226,7 +244,8 @@ extern UINT32 LOS_MemboxFree(VOID *pool, VOID *box); * @since Huawei LiteOS V100R001C00 */ extern VOID LOS_MemboxClr(VOID *pool, VOID *box); - +/*调用该函数将会将 box 所指向的内存块的数据内容清零，使其变为初始状态。 +该函数通常用于在重新使用内存块之前清除其中的旧数据，以免对后续操作产生影响。*/ /** * @ingroup los_membox * @brief show static memory pool information. @@ -277,7 +296,9 @@ extern VOID LOS_ShowBox(VOID *pool); * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemboxStatisticsGet(const VOID *boxMem, UINT32 *maxBlk, UINT32 *blkCnt, UINT32 *blkSize); - +/*调用该函数将会获取静态内存池的统计信息，包括最大可分配内存块数量、 +已分配内存块数量以及每个内存块的大小，并通过传入的指针参数返回给调用者。 +这些统计信息可以用于监控和调试内存池的使用情况。*/ #ifdef __cplusplus #if __cplusplus } diff --git a/src/kernel/include/los_memory.h b/src/kernel/include/los_memory.h index 9859d7f..ad3cdae 100644 --- a/src/kernel/include/los_memory.h +++ b/src/kernel/include/los_memory.h @@ -155,7 +155,12 @@ extern UINTPTR g_excInteractMemSize; * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemMalloc(VOID *pool, UINT32 size, UINT32 moduleId); - +/*pool：指向内存池起始地址的指针。 +size：要分配的内存块大小。 +moduleId：分配内存块所属的模块 ID。 +调用该函数将会在指定的内存池中分配大小为 size 的内存块，并将其地址返回给调用者。 +若内存池中无法分配足够的内存块，则返回 NULL 指针表示分配失败。 +分配的内存块所属的模块 ID 由 moduleId 参数指定，通常用于管理内存使用情况。*/ /** * @ingroup los_memory * @brief Allocate aligned memory. @@ -185,7 +190,10 @@ extern VOID *LOS_MemMalloc(VOID *pool, UINT32 size, UINT32 moduleId); * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemMallocAlign(VOID *pool, UINT32 size, UINT32 boundary, UINT32 moduleId); - +/*调用该函数将会在指定的内存池中按照指定的对齐边界（boundary）分配大小为 size 的内存块，并将其地址返回给调用者。 +对齐边界表示内存块起始地址相对于内存池起始地址的偏移量必须是 boundary 的倍数。 +若内存池中无法分配足够的对齐内存块，则返回 NULL 指针表示分配失败。 +分配的内存块所属的模块 ID 由 moduleId 参数指定，通常用于管理内存使用情况。*/ /** * @ingroup los_memory * @brief Free dynamic memory. @@ -212,7 +220,9 @@ extern VOID *LOS_MemMallocAlign(VOID *pool, UINT32 size, UINT32 boundary, UINT32 * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemMfree(VOID *pool, VOID *ptr, UINT32 moduleId); +/*调用该函数将会释放由 ptr 指向的内存块，并将其归还给指定的内存池。同时，通过 moduleId 参数指定要释放的内存块所属的模块 ID，以便进行相关的内存管理操作。 +在调用该函数之前，需要确保要释放的内存块确实是之前通过 LOS_MemMalloc 或 LOS_MemMallocAlign 分配得到的，并且未被重复释放。否则可能会导致内存管理错误和程序异常行为。*/ /** * @ingroup los_memory * @brief Re-allocate a memory block. @@ -324,7 +334,14 @@ typedef struct { UINT32 uwUsageWaterLine; /**< this structure member is defined only when LOSCFG_MEM_TASK_STAT is defined. */ #endif } LOS_MEM_POOL_STATUS; - +/*uwTotalUsedSize：内存池中已使用的总大小（单位：字节）。 +uwTotalFreeSize：内存池中未使用的总大小（单位：字节）。 +uwMaxFreeNodeSize：内存池中最大的可用内存块大小（单位：字节）。 +uwUsedNodeNum：内存池中已使用的内存块数量。 +uwFreeNodeNum：内存池中未使用的内存块数量。 +uwUsageWaterLine（仅在 LOSCFG_MEM_TASK_STAT 定义时有效）：内存池的使用水位线，表示内存池在运行过程中达到的最高使用量。 +通过使用该结构体，可以获取内存池的详细状态信息，例如已使用的总大小、未使用的总大小、可用的最大内存块大小以及相关的内存块数量。 +其中，如果定义了 LOSCFG_MEM_TASK_STAT，还可以获取内存池的使用水位线。*/ /** * @ingroup los_memory * @brief Initialize dynamic memory. @@ -353,7 +370,8 @@ typedef struct { * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemInit(VOID *pool, UINT32 size); - +/*调用该函数将会对指定的内存池进行初始化操作，使其具备可用于分配和管理内存块的能力。 +在初始化完成后，该内存池可以被用于动态分配和释放内存块。*/ /** * @ingroup los_memory * @brief Allocate dynamic memory. @@ -380,7 +398,8 @@ extern UINT32 LOS_MemInit(VOID *pool, UINT32 size); * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemAlloc(VOID *pool, UINT32 size); - +/*通过该函数可以动态地从内存池中获取一块指定大小的内存块，以满足程序运行时的内存需求。分配的内存块可以根据实际需要进行读写操作 +，并在不再需要时通过相应的内存释放函数进行释放和回收。*/ /** * @ingroup los_memory * @brief Free dynamic memory. @@ -444,7 +463,7 @@ extern UINT32 LOS_MemFree(VOID *pool, VOID *ptr); * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemRealloc(VOID *pool, VOID *ptr, UINT32 size); - +//通过该函数可以动态地调整已分配内存块的大小，以满足程序运行时动态变化的内存需求。 /** * @ingroup los_memory * @brief Allocate aligned memory. @@ -472,7 +491,9 @@ extern VOID *LOS_MemRealloc(VOID *pool, VOID *ptr, UINT32 size); * @since Huawei LiteOS V100R001C00 */ extern VOID *LOS_MemAllocAlign(VOID *pool, UINT32 size, UINT32 boundary); - +/*通过该函数可以动态地从内存池中获取一块指定大小并满足对齐要求的内存块， +以满足程序运行时的内存需求。分配的内存块可以根据实际需要进行读写操作， +并在不再需要时通过相应的内存释放函数进行释放和回收。*/ /** * @ingroup los_memory * @brief Get the size of memory pool's size. @@ -613,7 +634,9 @@ extern UINTPTR LOS_MemLastUsedGet(VOID *pool); * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemInfoGet(VOID *pool, LOS_MEM_POOL_STATUS *poolStatus); +/*调用该函数将会获取指定内存池的状态信息，并将其保存到指定的 LOS_MEM_POOL_STATUS 结构体中。如果获取成功，返回 LOS_OK；否则返回错误码。 +通过该函数可以获取当前内存池的总容量、已使用的容量、剩余的容量等信息，以便于进行内存管理和优化。*/ /** * @ingroup los_memory * @brief Get the number of free node in every size. @@ -658,6 +681,10 @@ extern UINT32 LOS_MemFreeNodeShow(VOID *pool); extern UINT32 LOS_MemIntegrityCheck(VOID *pool); #ifdef LOSCFG_BASE_MEM_NODE_SIZE_CHECK +/*调用该函数将会对指定的内存池进行完整性检查，以确保内存池中分配的内存块没有损坏或越界等问题。如果检查通过，返回 LOS_OK；否则返回错误码。 + +在代码中还有一个条件编译的宏定义 #ifdef LOSCFG_BASE_MEM_NODE_SIZE_CHECK，用于判断是否开启了基于内存节点大小的检查。如果该宏定义存在且为真， +则执行相应的代码逻辑；否则忽略该部分代码。*/ /** * @ingroup los_memory * @brief Check the size of the specified memory node. @@ -690,7 +717,9 @@ extern UINT32 LOS_MemIntegrityCheck(VOID *pool); * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MemNodeSizeCheck(VOID *pool, VOID *ptr, UINT32 *totalSize, UINT32 *availSize); +/*调用该函数将会检查指定内存池中给定内存节点的大小，并将总大小和可用大小分别保存到指定的变量中。如果检查成功，返回 LOS_OK；否则返回错误码。 +使用该函数可以获得指定内存节点的总大小和可用大小信息。这对于动态管理内存节点、调试内存分配问题以及优化内存使用非常有用。*/ /** * @ingroup los_memory * @brief Set the memory check level. diff --git a/src/kernel/include/los_mux.h b/src/kernel/include/los_mux.h index 73c5b27..8ef776e 100644 --- a/src/kernel/include/los_mux.h +++ b/src/kernel/include/los_mux.h @@ -54,7 +54,10 @@ extern "C" { * Solution: Decrease the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. */ #define LOS_ERRNO_MUX_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x00) +/*这段代码定义了一个名为 LOS_ERRNO_MUX_NO_MEMORY 的宏，用于表示互斥锁分配内存失败的错误码。 +LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块， +0x00 是该错误码在该模块中的具体数值。*/ /** * @ingroup los_mux * Mutex error code: The mutex is not usable. @@ -64,7 +67,7 @@ extern "C" { * Solution: Check whether the mutex ID and the mutex state are applicable for the current operation. */ #define LOS_ERRNO_MUX_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x01) - +//LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x01 是该错误码在该模块中的具体数值。 /** * @ingroup los_mux * Mutex error code: Null pointer. @@ -74,7 +77,8 @@ extern "C" { * Solution: Check whether the input parameter is usable. */ #define LOS_ERRNO_MUX_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x02) - +//这段代码定义了一个名为 LOS_ERRNO_MUX_PTR_NULL 的宏，用于表示互斥锁指针为空的错误码。 +//LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x02 是该错误码在该模块中的具体数值。 /** * @ingroup los_mux * Mutex error code: No mutex is available and the mutex request fails. @@ -84,7 +88,9 @@ extern "C" { * Solution: Increase the number of mutexes defined by LOSCFG_BASE_IPC_MUX_LIMIT. */ #define LOS_ERRNO_MUX_ALL_BUSY LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x03) +/*这段代码定义了一个名为 LOS_ERRNO_MUX_ALL_BUSY 的宏，用于表示互斥锁已全部被占用的错误码。 +LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x03 是该错误码在该模块中的具体数值。*/ /** * @ingroup los_mux * Mutex error code: The mutex fails to be locked in non-blocking mode because it is locked by another thread. @@ -94,7 +100,9 @@ extern "C" { * Solution: Lock the mutex after it is unlocked by the thread that owns it, or set a waiting time. */ #define LOS_ERRNO_MUX_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x04) +/*这段代码定义了一个名为 LOS_ERRNO_MUX_UNAVAILABLE 的宏，用于表示互斥锁不可用的错误码。 +LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x04 是该错误码在该模块中的具体数值。*/ /** * @ingroup los_mux * Mutex error code: The mutex is being locked during an interrupt. @@ -104,7 +112,9 @@ extern "C" { * Solution: Check whether the mutex is being locked during an interrupt. */ #define LOS_ERRNO_MUX_PEND_INTERR LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x05) + /*这段代码定义了一个名为 LOS_ERRNO_MUX_PEND_INTERR 的宏，用于表示互斥锁等待被阻塞时发生中断错误的错误码。 +LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x05 是该错误码在该模块中的具体数值。*/ /** * @ingroup los_mux * Mutex error code: A thread locks a mutex after waiting for the mutex to be unlocked by another thread @@ -116,7 +126,9 @@ extern "C" { * thread will not wait for the mutex to become available. */ #define LOS_ERRNO_MUX_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x06) +/*这段代码定义了一个名为 LOS_ERRNO_MUX_PEND_IN_LOCK 的宏，用于表示在互斥锁上等待时发生死锁错误的错误码。 +LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x06 是该错误码在该模块中的具体数值。*/ /** * @ingroup los_mux * Mutex error code: The mutex locking times out. @@ -126,7 +138,7 @@ extern "C" { * Solution: Increase the waiting time or set the waiting time to LOS_WAIT_FOREVER (forever-blocking mode). */ #define LOS_ERRNO_MUX_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x07) - +//LOS_ERRNO_OS_ERROR 是一个宏，用于生成具有模块和错误码的错误码值。在这里，LOS_MOD_MUX 表示错误所属的模块是互斥锁模块，0x07 是该错误码在该模块中的具体数值。 /** * @ingroup los_mux * The error code is not in use temporarily. @@ -175,7 +187,9 @@ extern "C" { * @deprecated This error code is obsolete since LiteOS 5.0.0. */ #define LOS_ERRNO_MUX_PEND_IN_SYSTEM_TASK LOS_ERRNO_OS_ERROR(LOS_MOD_MUX, 0x0C) +/*其中 LOS_ERRNO_OS_ERROR 是一个宏函数，用于生成错误码。该宏函数接受两个参数：模块号和错误码。在这里，模块号为 LOS_MOD_MUX，错误码为 0x0C。 +通过这个宏定义，可以方便地识别并处理在系统任务中使用互斥信号量时发生的错误情况。*/ /** * @ingroup los_mux * @brief Create a mutex. @@ -261,7 +275,14 @@ extern UINT32 LOS_MuxDelete(UINT32 muxHandle); * @since Huawei LiteOS V100R001C00 */ extern UINT32 LOS_MuxPend(UINT32 muxHandle, UINT32 timeout); +/*参数说明： + +muxHandle：互斥信号量句柄，即互斥信号量创建成功后返回的值。 +timeout：等待互斥信号量的超时时间，单位为系统时钟节拍。如果设置为0，则表示永久等待。 +返回值说明： +返回 LOS_OK 表示成功获取互斥信号量。 +返回错误码表示获取互斥信号量失败，可能是由于传入的参数无效或者超时等原因导致。*/ /** * @ingroup los_mux * @brief Release a mutex. diff --git a/src/kernel/include/los_perf.h b/src/kernel/include/los_perf.h index b026162..b075948 100644 --- a/src/kernel/include/los_perf.h +++ b/src/kernel/include/los_perf.h @@ -75,7 +75,12 @@ enum PerfStatus { PERF_STARTED, /**< perf is started */ PERF_STOPED, /**< perf is stopped */ }; +/*枚举类型 PerfStatus 包含了三个枚举常量： +PERF_UNINIT：表示性能监控未初始化的状态。 +PERF_STARTED：表示性能监控已经开始的状态。 +PERF_STOPED：表示性能监控已经停止的状态。 +通过使用这个枚举类型，可以方便地表示和判断性能监控的当前状态。*/ /** * @ingroup los_perf * Define the type of the perf sample data buffer water mark hook function. @@ -182,7 +187,13 @@ enum PerfEventType { PERF_EVENT_TYPE_MAX }; +/*枚举类型 PerfEventType 包含了四个枚举常量： +PERF_EVENT_TYPE_HW：表示硬件事件类型，用于表示板载通用硬件事件。 +PERF_EVENT_TYPE_TIMED：表示定时事件类型，用于表示高精度定时器定时事件。 +PERF_EVENT_TYPE_SW：表示软件事件类型，用于表示软件跟踪事件。 +PERF_EVENT_TYPE_RAW：表示原始事件类型，用于表示特殊板载硬件事件，在对应的架构头文件中有关于枚举 PmuEventType 的定义。 +通过使用这个枚举类型，可以方便地表示和区分不同类型的性能事件，便于在代码中进行处理和管理。*/ /** * @ingroup los_perf * Common hardware pmu events @@ -199,7 +210,17 @@ enum PmuHwId { PERF_COUNT_HW_MAX, }; - +/*枚举类型 PmuHwId 包含了多个枚举常量，每个常量代表一个具体的硬件事件： + +PERF_COUNT_HW_CPU_CYCLES：表示 CPU 循环周期事件。 +PERF_COUNT_HW_INSTRUCTIONS：表示指令执行事件。 +PERF_COUNT_HW_DCACHE_REFERENCES：表示数据缓存访问事件。 +PERF_COUNT_HW_DCACHE_MISSES：表示数据缓存缺失事件。 +PERF_COUNT_HW_ICACHE_REFERENCES：表示指令缓存访问事件。 +PERF_COUNT_HW_ICACHE_MISSES：表示指令缓存缺失事件。 +PERF_COUNT_HW_BRANCH_INSTRUCTIONS：表示分支指令事件。 +PERF_COUNT_HW_BRANCH_MISSES：表示分支缺失事件。 +通过使用这个枚举类型的常量，可以指定要监控的硬件事件，方便地在代码中进行配置和统计。*/ /** * @ingroup los_perf * Common hrtimer timed events @@ -220,7 +241,13 @@ enum PmuSwId { PERF_COUNT_SW_MAX, }; +/*枚举类型 PmuSwId 包含了多个枚举常量，每个常量代表一个具体的软件事件： +PERF_COUNT_SW_TASK_SWITCH：表示任务切换事件。 +PERF_COUNT_SW_IRQ_RESPONSE：表示中断响应事件。 +PERF_COUNT_SW_MEM_ALLOC：表示内存分配事件。 +PERF_COUNT_SW_MUX_PEND：表示互斥锁挂起事件。 +通过使用这个枚举类型的常量，可以指定要监控的软件事件，方便地在代码中进行配置和统计。*/ /** * @ingroup los_perf * perf sample data types @@ -235,7 +262,16 @@ enum PerfSampleType { PERF_RECORD_IP = 1U << 5, /**< record instruction pointer */ PERF_RECORD_CALLCHAIN = 1U << 6, /**< record backtrace */ }; - +/*枚举类型 PerfSampleType 包含了多个枚举常量，每个常量代表一个具体的采样数据类型： + +PERF_RECORD_CPU：记录当前 CPU 的 ID。 +PERF_RECORD_TID：记录当前任务的 ID。 +PERF_RECORD_TYPE：记录事件类型。 +PERF_RECORD_PERIOD：记录事件周期。 +PERF_RECORD_TIMESTAMP：记录时间戳。 +PERF_RECORD_IP：记录指令指针。 +PERF_RECORD_CALLCHAIN：记录回溯信息。 +通过使用这个枚举类型的常量，可以方便地表示和区分不同类型的性能采样数据，便于在代码中进行处理和管理。*/ /** * @ingroup los_perf * perf configuration sub event information @@ -253,7 +289,12 @@ typedef struct { BOOL predivided; /**< whether to prescaler (once every 64 counts), which only take effect on cpu cycle hardware event */ } PerfEventConfig; - +/*type：表示性能事件类型，是一个 UINT32 类型的值，对应于 PerfEventType 枚举。 +events：一个数组，用于存储具体的事件信息。每个元素都包含两个成员变量： +eventId：表示特定事件的标识符，是一个 UINT32 类型的值。 +period：表示事件的周期，即每隔多少次事件发生时记录一次样本，是一个 UINT32 类型的值。 +eventsNr：表示总共的性能事件数量，是一个 UINT32 类型的值。 +predivided：表示是否进行预分频（每64个计数器进行一次），仅对CPU循环硬件事件有效。它是一个 BOOL 类型的值，用于表示是否进行预分频操作。*/ /** * @ingroup los_perf * perf configuration main information @@ -279,7 +320,17 @@ extern VOID OsPerfHook(UINT32 event); #else #define LOS_PERF(EVENT) #endif +/*PerfConfigAttr 结构体包含以下成员变量： + +eventsCfg：表示性能事件的配置信息，是一个 PerfEventConfig 结构体类型的值。 +taskIds：表示任务 ID 的过滤列表，是一个 UINT32 类型的数组，最多可以存储 PERF_MAX_FILTER_TSKS 个任务 ID。 +taskIdsNr：表示任务 ID 的数量，是一个 UINT32 类型的值。 +sampleType：表示需要采样的数据类型，是一个 UINT32 类型的值，对应于 PerfSampleType 枚举。 +needSample：表示是否需要采样数据，是一个 BOOL 类型的值。 +taskFilterEnable：表示是否启用任务过滤器，是一个 BOOL 类型的值。 +OsPerfHook 函数用于处理性能事件的回调函数，接收一个 UINT32 类型的参数 event，表示触发的性能事件类型。 +LOS_PERF 宏定义用于触发性能事件，如果操作系统配置了 LOSCFG_KERNEL_PERF 和 LOSCFG_PERF_SW_PMU 宏，则会调用 OsPerfHook 函数，否则该宏为空操作。*/ /** * @ingroup los_perf * @brief Init perf. diff --git a/src/kernel/include/los_printf.h b/src/kernel/include/los_printf.h index 67fa9cf..adc7ca7 100644 --- a/src/kernel/include/los_printf.h +++ b/src/kernel/include/los_printf.h @@ -46,7 +46,14 @@ extern "C" { #ifdef LOSCFG_SHELL_LK extern void LOS_LkPrint(int level, const char *func, int line, const char *fmt, ...); #endif +/*LOS_LkPrint 函数接受以下参数： +level：表示打印消息的级别，是一个整数。 +func：表示打印消息的函数名，是一个指向字符常量的指针。 +line：表示打印消息所在的行号，是一个整数。 +fmt：表示打印消息的格式字符串，是一个指向字符常量的指针。 +...：表示可变参数列表，用于根据格式字符串打印相应的消息内容。 +该函数用于在操作系统中打印消息，可以根据不同的级别和格式打印出不同的信息，用于调试或记录运行时的相关信息。函数的实现可能在其他地方定义。*/ /** * @ingroup los_printf * log print level definition, LOS_EMG_LEVEL is set to 0, it means the log is emergency. @@ -97,7 +104,14 @@ extern void LOS_LkPrint(int level, const char *func, int line, const char *fmt, #endif typedef VOID (*pf_OUTPUT)(const CHAR *fmt, ...); +/*这段代码定义了一个名为 PRINT_LEVEL 的宏以及一个名为 pf_OUTPUT 的函数指针类型。 +PRINT_LEVEL 宏根据条件判断是否定义为 LOS_DEBUG_LEVEL 或者 LOS_ERR_LEVEL。 + +如果宏 LOSCFG_SHELL_LK 被定义，则 PRINT_LEVEL 被定义为 LOS_DEBUG_LEVEL。 +否则， PRINT_LEVEL 被定义为 LOS_ERR_LEVEL。 +pf_OUTPUT 是一个函数指针类型，指向一个返回值为 VOID 的函数， +该函数接受一个格式化字符串参数 fmt 和可变参数列表 ...。该函数指针类型可以用于声明指向相应函数的指针变量，使得函数的调用可以通过该指针进行。*/ /** * @ingroup los_printf * @brief Format and print data. @@ -153,7 +167,15 @@ extern void dprintf(const char *fmt, ...); #endif #endif #endif +/*当宏 PRINT_DEBUG 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_DEBUG_LEVEL。如果是，则将 PRINT_DEBUG 宏定义为空操作；否则，进入下一层条件编译。 + +当宏 LOSCFG_SHELL_LK 被定义时，PRINT_DEBUG 宏被定义为调用 LOS_LkPrint 函数， +输出 [DEBUG] 级别的日志信息，其中第一个参数为日志级别 LOS_DEBUG_LEVEL， +第二个参数为当前函数名 __FUNCTION__，第三个参数为当前行号 __LINE__， +第四个参数为格式化字符串 fmt，后面的可变参数列表 ... +用于补充格式化字符串中占位符的值。 +否则，PRINT_DEBUG 宏被定义为输出 [DEBUG] 级别的日志信息到控制台。*/ /** * @ingroup los_printf * @brief Format and print information log. @@ -187,7 +209,15 @@ extern void dprintf(const char *fmt, ...); #endif #endif #endif +/*当宏 PRINT_INFO 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_INFO_LEVEL。 +如果是，则将 PRINT_INFO 宏定义为空操作；否则，进入下一层条件编译。 +当宏 LOSCFG_SHELL_LK 被定义时，PRINT_INFO 宏被定义为调用 LOS_LkPrint 函数， +输出 [INFO] 级别的日志信息，其中第一个参数为日志级别 LOS_INFO_LEVEL， +第二个参数为当前函数名 __FUNCTION__，第三个参数为当前行号 __LINE__， +第四个参数为格式化字符串 fmt，后面的可变参数列表 ... 用于补充格式化字符串中占位符的值。 + +否则，PRINT_INFO 宏被定义为输出 [INFO] 级别的日志信息到控制台。*/ /** * @ingroup los_printf * @brief Format and print warning log. @@ -221,7 +251,14 @@ extern void dprintf(const char *fmt, ...); #endif #endif #endif +/*当宏 PRINT_WARN 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_WARN_LEVEL。如果是，则将 PRINT_WARN 宏定义为空操作；否则，进入下一层条件编译。 + +当宏 LOSCFG_SHELL_LK 被定义时，PRINT_WARN 宏被定义为调用 LOS_LkPrint 函数， +输出 [WARN] 级别的日志信息，其中第一个参数为日志级别 LOS_WARN_LEVEL， +第二个参数为当前函数名 __FUNCTION__，第三个参数为当前行号 __LINE__， +第四个参数为格式化字符串 fmt，后面的可变参数列表 ... 用于补充格式化字符串中占位符的值。 +否则，PRINT_WARN 宏被定义为输出 [WARN] 级别的日志信息到控制台。*/ /** * @ingroup los_printf * @brief Format and print error log. @@ -255,7 +292,14 @@ extern void dprintf(const char *fmt, ...); #endif #endif #endif +/*当宏 PRINT_ERR 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_ERR_LEVEL。如果是，则将 PRINT_ERR 宏定义为空操作；否则，进入下一层条件编译。 +当宏 LOSCFG_SHELL_LK 被定义时，PRINT_ERR 宏被定义为调用 LOS_LkPrint 函数， +输出 [ERR] 级别的日志信息，其中第一个参数为日志级别 LOS_ERR_LEVEL +，第二个参数为当前函数名 __FUNCTION__，第三个参数为当前行号 __LINE__， +第四个参数为格式化字符串 fmt，后面的可变参数列表 ... 用于补充格式化字符串中占位符的值。 + +否则，PRINT_ERR 宏被定义为输出 [ERR] 级别的日志信息到控制台。*/ /** * @ingroup los_printf * @brief Format and print common log. @@ -287,7 +331,16 @@ extern void dprintf(const char *fmt, ...); #endif #endif #endif +/*这段代码定义了一个名为 PRINTK 的宏。 + +当宏 PRINTK 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_COMMOM_LEVEL。如果是，则将 PRINTK 宏定义为空操作；否则，进入下一层条件编译。 +当宏 LOSCFG_SHELL_LK 被定义时，PRINTK 宏被定义为调用 LOS_LkPrint 函数， +输出 [COMM] 级别的日志信息，其中第一个参数为日志级别 LOS_COMMOM_LEVEL， +第二个参数为当前函数名 __FUNCTION__，第三个参数为当前行号 __LINE__， +第四个参数为格式化字符串 fmt，后面的可变参数列表 ... 用于补充格式化字符串中占位符的值。 + +否则，PRINTK 宏被定义为输出格式化字符串到控制台。*/ /** * @ingroup los_printf * @brief Format and print emergency log. @@ -317,7 +370,11 @@ extern void dprintf(const char *fmt, ...); } while (0) #endif #endif +/*这段代码定义了一个名为 PRINT_EMG 的宏。 + +当宏 PRINT_EMG 未被定义时，通过条件编译判断 PRINT_LEVEL 是否小于 LOS_EMG_LEVEL。如果是，则将 PRINT_EMG 宏定义为空操作；否则，进入下一层条件编译。 +在 PRINT_LEVEL 大于等于 LOS_EMG_LEVEL 时，PRINT_EMG 宏被定义为输出 [EMG] 级别的日志信息到控制台。*/ /** * @ingroup los_printf * @brief Format and print log. diff --git a/src/kernel/include/los_queue.h b/src/kernel/include/los_queue.h index 093ef2e..a4ffe5e 100644 --- a/src/kernel/include/los_queue.h +++ b/src/kernel/include/los_queue.h @@ -55,7 +55,9 @@ extern "C" { * @deprecated This error code is obsolete since LiteOS 5.0.0. */ #define LOS_ERRNO_QUEUE_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x00) +/*宏的定义使用了 LOS_ERRNO_OS_ERROR 宏，并指定了参数 LOS_MOD_QUE 和 0x00。根据上下文推测，LOS_MOD_QUE 可能是表示与队列相关的模块。 +该宏的作用是生成一个错误码，用于表示队列的最大数量为零的错误情况。具体的错误码值可能在其他地方定义。*/ /** * @ingroup los_queue * Queue error code: The queue block memory fails to be initialized. @@ -66,7 +68,11 @@ extern "C" { * number of queue resources. */ #define LOS_ERRNO_QUEUE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x01) +/*这段代码定义了一个名为 LOS_ERRNO_QUEUE_NO_MEMORY 的宏，用于表示队列分配内存失败时的错误码。 +宏的定义使用了 LOS_ERRNO_OS_ERROR 宏，并指定了参数 LOS_MOD_QUE 和 0x01。根据上下文推测，LOS_MOD_QUE 可能是表示与队列相关的模块。 + +该宏的作用是生成一个错误码，用于表示队列分配内存失败的错误情况。具体的错误码值可能在其他地方定义。*/ /** * @ingroup los_queue * Queue error code: The memory for queue creation fails to be requested. @@ -77,7 +83,11 @@ extern "C" { * the number of nodes in the queue to be created. */ #define LOS_ERRNO_QUEUE_CREATE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x02) +/*这段代码定义了一个名为 LOS_ERRNO_QUEUE_CREATE_NO_MEMORY 的宏，用于表示创建队列时内存分配失败的错误码。 + +该宏使用了 LOS_ERRNO_OS_ERROR 宏，并指定了参数 LOS_MOD_QUE 和 0x02。根据上下文推测，LOS_MOD_QUE 可能是表示与队列相关的模块。 +因此，该宏的作用是生成一个错误码，用于表示创建队列时内存分配失败的错误情况。具体的错误码值可能在其他地方定义。*/ /** * @ingroup los_queue * Queue error code: The size of the biggest message in the created queue is too big. @@ -87,6 +97,9 @@ extern "C" { * Solution: Change the size of the biggest message in the created queue. */ #define LOS_ERRNO_QUEUE_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x03) + /*宏的定义使用了 LOS_ERRNO_OS_ERROR 宏，并指定了参数 LOS_MOD_QUE 和 0x00。根据上下文推测，LOS_MOD_QUE 可能是表示与队列相关的模块。 + + 该宏的作用是生成一个错误码，用于表示队列的最大数量为零的错误情况。具体的错误码值可能在其他地方定义。*/ /** * @ingroup los_queue @@ -97,6 +110,11 @@ extern "C" { * Solution: Increase the configured number of resources for queues. */ #define LOS_ERRNO_QUEUE_CB_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x04) + /*这段代码定义了一个名为 LOS_ERRNO_QUEUE_NO_MEMORY 的宏，用于表示队列分配内存失败时的错误码。 + + 宏的定义使用了 LOS_ERRNO_OS_ERROR 宏，并指定了参数 LOS_MOD_QUE 和 0x01。根据上下文推测，LOS_MOD_QUE 可能是表示与队列相关的模块。 + + 该宏的作用是生成一个错误码，用于表示队列分配内存失败的错误情况。具体的错误码值可能在其他地方定义。*/ /** * @ingroup los_queue @@ -356,6 +374,21 @@ typedef struct tagQueueInfo { } QUEUE_INFO_S; #ifdef LOSCFG_QUEUE_STATIC_ALLOCATION +/*这段代码定义了一个结构体 QUEUE_INFO_S，用于描述队列（Queue）的信息。 + +成员变量解释如下： + +uwQueueID：队列 ID。 +usQueueLen：队列长度，即队列中节点的数量。 +usQueueSize：队列中每个节点的大小。 +usQueueHead：队列头节点的位置，是一个数组下标。 +usQueueTail：队列尾节点的位置，是一个数组下标。 +usWritableCnt：可写入的资源数。 +usReadableCnt：可读取的资源数。 +uwWaitReadTask：等待读取消息的任务。是一个 64 位的无符号整数，每个二进制位表示一个任务 ID。因此，可以表示 64 个任务，最大任务 ID 是 63。 +uwWaitWriteTask：等待写入消息的任务。同 uwWaitReadTask。 +uwWaitMemTask：等待内存的任务。同 uwWaitReadTask。 +如果宏 LOSCFG_QUEUE_STATIC_ALLOCATION 被定义，则这个结构体用于动态分配内存时不起作用。*/ /** * @ingroup los_queue * @brief Create a message queue. @@ -397,7 +430,16 @@ extern UINT32 LOS_QueueCreateStatic(const CHAR *queueName, VOID *queueMem, UINT16 memSize); #endif +/*该函数用于静态创建一个队列（Queue），具体参数如下： +queueName：队列的名称，类型为 const CHAR*。 +len：队列的长度，即队列中节点的数量，类型为 UINT16。 +queueId：指向一个 UINT32 类型的指针，用于存储创建得到的队列 ID。 +flags：队列的标志，类型为 UINT32。 +maxMsgSize：队列中每个节点的最大消息大小，类型为 UINT16。 +queueMem：指向预分配的队列内存的指针，类型为 VOID*。 +memSize：预分配的队列内存的大小，类型为 UINT16。 +该函数的作用是在预分配的静态内存空间上创建一个队列，并返回队列的 ID*/ /** * @ingroup los_queue * @brief Create a message queue. @@ -431,7 +473,14 @@ extern UINT32 LOS_QueueCreate(const CHAR *queueName, UINT32 *queueId, UINT32 flags, UINT16 maxMsgSize); +/*该函数用于动态创建一个队列（Queue），具体参数如下： +queueName：队列的名称，类型为 const CHAR*。 +len：队列的长度，即队列中节点的数量，类型为 UINT16。 +queueId：指向一个 UINT32 类型的指针，用于存储创建得到的队列 ID。 +flags：队列的标志，类型为 UINT32。 +maxMsgSize：队列中每个节点的最大消息大小，类型为 UINT16。 +该函数的作用是在运行时动态分配内存空间来创建一个队列，并返回队列的 ID。*/ /** * @ingroup los_queue * @brief Read a queue. @@ -481,7 +530,7 @@ extern UINT32 LOS_QueueReadCopy(UINT32 queueId, VOID *bufferAddr, UINT32 *bufferSize, UINT32 timeout); - +/*该函数的作用是从队列中读取数据，并将数据复制到指定的缓冲区中。如果队列中没有数据可读，则根据超时时间等待数据可读，如果在超时时间内仍然没有数据可读，则返回错误码。*/ /** * @ingroup los_queue * @brief Write data into a queue. @@ -529,7 +578,13 @@ extern UINT32 LOS_QueueWriteCopy(UINT32 queueId, VOID *bufferAddr, UINT32 bufferSize, UINT32 timeout); +/*该函数用于向指定的队列中写入数据，具体参数如下： +queueId：要写入数据的队列 ID，类型为 UINT32。 +bufferAddr：指向待写入数据的缓冲区地址，类型为 VOID*。 +bufferSize：待写入数据的大小，类型为 UINT32。 +timeout：写入数据的超时时间，单位为 Tick。如果设置为 0，则表示不等待，立即返回。如果设置为 LOS_WAIT_FOREVER，则表示一直等待，直到有空间可写入为止，类型为 UINT32。 +该函数的作用是向队列中写入数据，如果队列已满，则根据超时时间等待空间可写入，如果在超时时间内仍然没有空间可写入，则返回错误码。*/ /** * @ingroup los_queue * @brief Read a queue. @@ -581,7 +636,13 @@ extern UINT32 LOS_QueueRead(UINT32 queueId, VOID *bufferAddr, UINT32 bufferSize, UINT32 timeout); +/*该函数用于从指定的队列中读取数据，具体参数如下： +queueId：要读取数据的队列 ID，类型为 UINT32。 +bufferAddr：指向存储读取数据的缓冲区地址，类型为 VOID*。 +bufferSize：指定缓冲区的大小，即期望读取的数据大小，类型为 UINT32。 +timeout：读取数据的超时时间，单位为 Tick。如果设置为 0，则表示不等待，立即返回。如果设置为 LOS_WAIT_FOREVER，则表示一直等待，直到有数据可读为止，类型为 UINT32。 +该函数的作用是从队列中读取数据并存储到指定的缓冲区中。如果队列中没有足够的数据可读，则根据超时时间等待数据可读，如果在超时时间内仍然没有足够的数据可读，则返回错误码。*/ /** * @ingroup los_queue * @brief Write data into a queue. @@ -630,7 +691,13 @@ extern UINT32 LOS_QueueWrite(UINT32 queueId, VOID *bufferAddr, UINT32 bufferSize, UINT32 timeout); +/*该函数用于向指定的队列中写入数据，具体参数如下： +queueId：要写入数据的队列 ID，类型为 UINT32。 +bufferAddr：指向待写入数据的缓冲区地址，类型为 VOID*。 +bufferSize：待写入数据的大小，类型为 UINT32。 +timeout：写入数据的超时时间，单位为 Tick。如果设置为 0，则表示不等待，立即返回。如果设置为 LOS_WAIT_FOREVER，则表示一直等待，直到有空间可写入为止，类型为 UINT32。 +该函数的作用是向队列中写入数据，如果队列已满，则根据超时时间等待空间可写入，如果在超时时间内仍然没有空间可写入，则返回错误码。*/ /** * @ingroup los_queue * @brief Write data into a queue header. @@ -679,7 +746,13 @@ extern UINT32 LOS_QueueWriteHead(UINT32 queueId, VOID *bufferAddr, UINT32 bufferSize, UINT32 timeout); +/*该函数用于向指定队列的队首写入数据，具体参数如下： +queueId：要写入数据的队列 ID，类型为 UINT32。 +bufferAddr：指向待写入数据的缓冲区地址，类型为 VOID*。 +bufferSize：待写入数据的大小，类型为 UINT32。 +timeout：写入数据的超时时间，单位为 Tick。如果设置为 0，则表示不等待，立即返回。如果设置为 LOS_WAIT_FOREVER，则表示一直等待，直到有空间可写入为止，类型为 UINT32。 +该函数的作用是向队列的队首写入数据，如果队列已满，则根据超时时间等待空间可写入，如果在超时时间内仍然没有空间可写入，则返回错误码。写入数据到队首可能会导致队列中原本的数据被挤出。*/ /** * @ingroup los_queue * @brief Write data into a queue header. diff --git a/src/kernel/include/los_ringbuf.h b/src/kernel/include/los_ringbuf.h index b56971d..4f362af 100644 --- a/src/kernel/include/los_ringbuf.h +++ b/src/kernel/include/los_ringbuf.h @@ -51,7 +51,14 @@ typedef enum { RBUF_UNINIT, /**< Ringbuf is not inited. */ RBUF_INITED /**< Ringbuf is inited. */ } RingbufStatus; +/*这段代码定义了一个名为 RingbufStatus 的枚举类型，表示环形缓冲区的状态。 +该枚举类型包含两个枚举值： + +RBUF_UNINIT：表示环形缓冲区尚未初始化。 +RBUF_INITED：表示环形缓冲区已经初始化。 +通过使用这个枚举类型，可以方便地标识和判断环形缓冲区的状态。 +在使用环形缓冲区时，可以根据不同的状态进行相应的操作或处理。*/ /** * @ingroup los_ringbuf * Ringbuf information structure. @@ -66,7 +73,18 @@ typedef struct { RingbufStatus status; /**< Ringbuf status */ CHAR *fifo; /**< Buf to store data */ } Ringbuf; +/*这段代码定义了一个名为 Ringbuf 的结构体，用于表示环形缓冲区的属性和状态。 + +该结构体包含以下成员： +startIdx：环形缓冲区的读取索引。 +endIdx：环形缓冲区的写入索引。 +size：环形缓冲区的总大小。 +remain：环形缓冲区的剩余可用空间大小。 +lock：用于读取和写入操作的自旋锁。 +status：环形缓冲区的状态，类型为 RingbufStatus 枚举类型。 +fifo：用于存储数据的缓冲区。 +通过这个结构体，可以方便地管理环形缓冲区的属性和状态，并进行相应的数据读写操作。*/ /** * @ingroup los_ringbuf * @brief Init a ringbuf. @@ -89,7 +107,8 @@ typedef struct { * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufInit(Ringbuf *ringbuf, CHAR *fifo, UINT32 size); - +/*该函数的作用是根据给定的参数初始化环形缓冲区对象，并分配必要的资源。通过调用这个函数，可以将一个已经定义的 Ringbuf +结构体对象与指定的缓冲区关联起来，并设置初始状态和属性。*/ /** * @ingroup los_ringbuf * @brief Reset a ringbuf. @@ -131,7 +150,9 @@ extern VOID LOS_RingbufReset(Ringbuf *ringbuf); * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufWrite(Ringbuf *ringbuf, const CHAR *buf, UINT32 size); +/*该函数的作用是将指定大小的数据从源缓冲区写入到目标环形缓冲区中。写入操作会更新环形缓冲区的写入索引，并根据需要循环覆盖已有数据。如果环形缓冲区的空间不足以容纳全部数据，只会写入部分数据。 +通过调用这个函数，可以方便地将数据写入到环形缓冲区中，并实现数据的循环存储和覆盖。*/ /** * @ingroup los_ringbuf * @brief Read data from ringbuf. @@ -153,7 +174,9 @@ extern UINT32 LOS_RingbufWrite(Ringbuf *ringbuf, const CHAR *buf, UINT32 size); * @since Huawei LiteOS V200R005C00 */ extern UINT32 LOS_RingbufRead(Ringbuf *ringbuf, CHAR *buf, UINT32 size); +/*该函数的作用是从指定大小的数据中读取数据，并将其存储到目标缓冲区。读取操作会更新环形缓冲区的读取索引，并根据需要循环读取已有数据。如果环形缓冲区中的数据不足以满足全部读取请求，只会读取部分数据。 +通过调用这个函数，可以方便地从环形缓冲区中读取数据，并实现数据的循环读取和覆盖。*/ /** * @ingroup los_ringbuf * @brief Get a ringbuf's used size.