trace模块分离线和在线两种模式,详细注解其实现细节

    百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
    鸿蒙研究站 | http://weharmonyos.com (国内)
              | https://weharmony.github.io (国外)
    oschina | https://my.oschina.net/weharmony
    博客园 | https://www.cnblogs.com/weharmony/
    知乎 | https://www.zhihu.com/people/weharmonyos
    csdn | https://blog.csdn.net/kuangyufei
    51cto | https://harmonyos.51cto.com/column/34
    掘金 | https://juejin.cn/user/756888642000808
    公众号 | 鸿蒙研究站 (weharmonyos)

kernel/extended/trace/cnv/trace_cnv.c

@@ -266,7 +266,7 @@ STATIC VOID LOS_TraceUsrEvent(VOID *buffer, UINT32 len)
     LOS_MemFree(m_aucSysMem0, buffer);
 #endif
 }
-///< 为输出日志而注册的钩子函数
+///< 为输出日志而注册的钩子函数 ,谁能告诉我 cnv 是啥意思?  @note_thinking
 VOID OsTraceCnvInit(VOID)
 {
     LOS_HookReg(LOS_HOOK_TYPE_MEM_ALLOC, LOS_TraceMemAlloc);
@@ -291,14 +291,14 @@ VOID OsTraceCnvInit(VOID)
     LOS_HookReg(LOS_HOOK_TYPE_MUX_POST, LOS_TraceMuxPost);
     LOS_HookReg(LOS_HOOK_TYPE_MUX_PEND, LOS_TraceMuxPend);
     LOS_HookReg(LOS_HOOK_TYPE_MUX_DELETE, LOS_TraceMuxDelete);
-    LOS_HookReg(LOS_HOOK_TYPE_TASK_PRIMODIFY, LOS_TraceTaskPriModify);
-    LOS_HookReg(LOS_HOOK_TYPE_TASK_DELETE, LOS_TraceTaskDelete);
-    LOS_HookReg(LOS_HOOK_TYPE_TASK_CREATE, LOS_TraceTaskCreate);
-    LOS_HookReg(LOS_HOOK_TYPE_TASK_SWITCHEDIN, LOS_TraceTaskSwitchedIn);
-    LOS_HookReg(LOS_HOOK_TYPE_MOVEDTASKTOREADYSTATE, LOS_TraceTaskResume);
-    LOS_HookReg(LOS_HOOK_TYPE_MOVEDTASKTOSUSPENDEDLIST, LOS_TraceTaskSuspend);
-    LOS_HookReg(LOS_HOOK_TYPE_ISR_ENTER, LOS_TraceIsrEnter);
-    LOS_HookReg(LOS_HOOK_TYPE_ISR_EXIT, LOS_TraceIsrExit);
+    LOS_HookReg(LOS_HOOK_TYPE_TASK_PRIMODIFY, LOS_TraceTaskPriModify);		///< 修改任务优先级
+    LOS_HookReg(LOS_HOOK_TYPE_TASK_DELETE, LOS_TraceTaskDelete);			///< 删除任务
+    LOS_HookReg(LOS_HOOK_TYPE_TASK_CREATE, LOS_TraceTaskCreate);			///< 创建任务
+    LOS_HookReg(LOS_HOOK_TYPE_TASK_SWITCHEDIN, LOS_TraceTaskSwitchedIn);	///< 任务切换中
+    LOS_HookReg(LOS_HOOK_TYPE_MOVEDTASKTOREADYSTATE, LOS_TraceTaskResume);	///< 恢复任务
+    LOS_HookReg(LOS_HOOK_TYPE_MOVEDTASKTOSUSPENDEDLIST, LOS_TraceTaskSuspend);///< 暂停任务
+    LOS_HookReg(LOS_HOOK_TYPE_ISR_ENTER, LOS_TraceIsrEnter);			///< 进入中断
+    LOS_HookReg(LOS_HOOK_TYPE_ISR_EXIT, LOS_TraceIsrExit);				///< 完成中断
     LOS_HookReg(LOS_HOOK_TYPE_SWTMR_CREATE, LOS_TraceSwtmrCreate);		///< 创建定时器
     LOS_HookReg(LOS_HOOK_TYPE_SWTMR_DELETE, LOS_TraceSwtmrDelete);		///< 删除定时器
     LOS_HookReg(LOS_HOOK_TYPE_SWTMR_EXPIRED, LOS_TraceSwtmrExpired);	///< 定时器时间到

kernel/extended/trace/los_trace.c

@@ -171,30 +171,41 @@ VOID OsTraceSetObj(ObjData *obj, const LosTaskCB *tcb)
     }
 }
 
+/*!
+ * @brief OsTraceHook	
+ * 事件统一处理函数
+ * @param eventType	
+ * @param identity	
+ * @param paramCount	
+ * @param params	
+ * @return	
+ *
+ * @see
+ */
 VOID OsTraceHook(UINT32 eventType, UINTPTR identity, const UINTPTR *params, UINT16 paramCount)
 {
-    TraceEventFrame frame;
-    if ((eventType == TASK_CREATE) || (eventType == TASK_PRIOSET)) {
+    TraceEventFrame frame;//离线和在线模式下, trace数据的保存和传送以帧为单位
+    if ((eventType == TASK_CREATE) || (eventType == TASK_PRIOSET)) {//创建任务和设置任务优先级
         OsTraceObjAdd(eventType, identity); /* handle important obj info, these can not be filtered */
     }
 
-    if ((g_enableTrace == TRUE) && (eventType & g_traceMask)) {
+    if ((g_enableTrace == TRUE) && (eventType & g_traceMask)) {//使能跟踪模块且事件未屏蔽
         UINTPTR id = identity;
-        if (TRACE_GET_MODE_FLAG(eventType) == TRACE_HWI_FLAG) {
-            if (OsTraceHwiFilter(identity)) {
+        if (TRACE_GET_MODE_FLAG(eventType) == TRACE_HWI_FLAG) {//关于硬中断的事件
+            if (OsTraceHwiFilter(identity)) {//检查中断号是否过滤掉了,注意:中断控制器本身是可以屏蔽中断号的
                 return;
             }
-        } else if (TRACE_GET_MODE_FLAG(eventType) == TRACE_TASK_FLAG) {
-            id = OsTraceGetMaskTid(identity);
-        } else if (eventType == MEM_INFO_REQ) {
+        } else if (TRACE_GET_MODE_FLAG(eventType) == TRACE_TASK_FLAG) {//关于任务的事件
+            id = OsTraceGetMaskTid(identity);//获取任务ID
+        } else if (eventType == MEM_INFO_REQ) {//内存信息事件
             LOS_MEM_POOL_STATUS status;
-            LOS_MemInfoGet((VOID *)identity, &status);
-            LOS_TRACE(MEM_INFO, identity, status.totalUsedSize, status.totalFreeSize);
+            LOS_MemInfoGet((VOID *)identity, &status);//获取内存各项信息
+            LOS_TRACE(MEM_INFO, identity, status.totalUsedSize, status.totalFreeSize);//打印信息
             return;
         }
 
-        OsTraceSetFrame(&frame, eventType, id, params, paramCount);
-        OsTraceWriteOrSendEvent(&frame);
+        OsTraceSetFrame(&frame, eventType, id, params, paramCount);//创建帧数据
+        OsTraceWriteOrSendEvent(&frame);//保存(离线模式下)或者发送(在线模式下)帧数据
     }
 }
 
@@ -202,7 +213,7 @@ BOOL OsTraceIsEnable(VOID)
 {
     return g_enableTrace;
 }
-
+/// 初始化事件处理函数
 STATIC VOID OsTraceHookInstall(VOID)
 {
     g_traceEventHook = OsTraceHook;
@@ -241,7 +252,7 @@ STATIC VOID OsTraceCmdHandle(const TraceClientCmd *msg)
             break;
     }
 }
-
+///< trace任务的入口函数
 VOID TraceAgent(VOID)
 {
     UINT32 ret;
@@ -257,20 +268,27 @@ VOID TraceAgent(VOID)
     }
 }
 
+/*!
+ * @brief OsCreateTraceAgentTask 创建trace任务	
+ * 
+ * @return	
+ *
+ * @see
+ */
 STATIC UINT32 OsCreateTraceAgentTask(VOID)
 {
     UINT32 ret;
     TSK_INIT_PARAM_S taskInitParam;
 
     (VOID)memset_s((VOID *)(&taskInitParam), sizeof(TSK_INIT_PARAM_S), 0, sizeof(TSK_INIT_PARAM_S));
-    taskInitParam.pfnTaskEntry = (TSK_ENTRY_FUNC)TraceAgent;
-    taskInitParam.usTaskPrio = LOSCFG_TRACE_TASK_PRIORITY;
-    taskInitParam.pcName = "TraceAgent";
-    taskInitParam.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE;
+    taskInitParam.pfnTaskEntry = (TSK_ENTRY_FUNC)TraceAgent;	//任务入口函数
+    taskInitParam.usTaskPrio = LOSCFG_TRACE_TASK_PRIORITY;	//任务优先级 2
+    taskInitParam.pcName = "TraceAgent";	//任务名称
+    taskInitParam.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; //内核栈大小 16K
 #ifdef LOSCFG_KERNEL_SMP
-    taskInitParam.usCpuAffiMask = CPUID_TO_AFFI_MASK(ArchCurrCpuid());
+    taskInitParam.usCpuAffiMask = CPUID_TO_AFFI_MASK(ArchCurrCpuid());//指定为当前CPU执行
 #endif
-    ret = LOS_TaskCreate(&g_traceTaskId, &taskInitParam);
+    ret = LOS_TaskCreate(&g_traceTaskId, &taskInitParam);//创建任务并产生调度
     return ret;
 }
 #endif
@@ -285,14 +303,14 @@ STATIC UINT32 OsTraceInit(VOID)
         goto LOS_ERREND;
     }
 
-#ifdef LOSCFG_TRACE_CLIENT_INTERACT
-    ret = OsTracePipelineInit();
+#ifdef LOSCFG_TRACE_CLIENT_INTERACT //使能与Trace IDE （dev tools）的交互，包括数据可视化和流程控制
+    ret = OsTracePipelineInit();//在线模式(管道模式)的初始化
     if (ret != LOS_OK) {
         goto LOS_ERREND;
     }
 #endif
 
-#ifdef LOSCFG_TRACE_CONTROL_AGENT
+#ifdef LOSCFG_TRACE_CONTROL_AGENT //trace任务代理开关,所谓代理是创建专门的任务来处理 trace
     ret = OsCreateTraceAgentTask();
     if (ret != LOS_OK) {
         TRACE_ERROR("trace init create agentTask error :0x%x\n", ret);
@@ -303,7 +321,7 @@ STATIC UINT32 OsTraceInit(VOID)
 #ifdef LOSCFG_RECORDER_MODE_OFFLINE //trace离线模式开关
 //离线模式会将trace frame记录到预先申请好的循环buffer中。如果循环buffer记录的frame过多则可能出现翻转，
 //会覆盖之前的记录，故保持记录的信息始终是最新的信息。
-    ret = OsTraceBufInit(LOSCFG_TRACE_BUFFER_SIZE);
+    ret = OsTraceBufInit(LOSCFG_TRACE_BUFFER_SIZE); //离线模式下buf 大小,这个大小决定了装多少 ObjData 和 TraceEventFrame
     if (ret != LOS_OK) {
 #ifdef LOSCFG_TRACE_CONTROL_AGENT
         (VOID)LOS_TaskDelete(g_traceTaskId);
@@ -312,7 +330,7 @@ STATIC UINT32 OsTraceInit(VOID)
     }
 #endif
 
-    OsTraceHookInstall();
+    OsTraceHookInstall();//安装HOOK框架
     OsTraceCnvInit();
 
     g_traceEventCount = 0;

kernel/extended/trace/los_trace_pri.h

@@ -97,22 +97,22 @@ typedef struct {
  * struct to store the event infomation
  */
 typedef struct {
-    UINT32 cmd;     /* trace start or stop cmd */
-    UINT32 param;   /* magic numb stand for notify msg */
+    UINT32 cmd;     /* trace start or stop cmd | 开始和结束跟踪命令*/
+    UINT32 param;   /* magic numb stand for notify msg | 命令参数*/
 } TraceNotifyFrame;
 
 /**
  * @ingroup los_trace
- * struct to store the trace config information.
+ * struct to store the trace config information. | 离线模式是将数据保存在缓存中,需要信息来记录整体数据.
  */
 typedef struct {
     struct WriteCtrl {//内容控制器
-        UINT16 curIndex;            /* The current record index | 当前记录索引位*/
-        UINT16 maxRecordCount;      /* The max num of trace items | 记录上限数*/
-        UINT16 curObjIndex;         /* The current obj index | 当前内容索引位*/
-        UINT16 maxObjCount;         /* The max num of obj index | 内容上限数*/
-        ObjData *objBuf;            /* Pointer to obj info data | 指向内容数据域*/
-        TraceEventFrame *frameBuf;  /* Pointer to the trace items | 所有trace条目的开始位*/
+        UINT16 curIndex;            /* The current record index | 当前帧数据索引位*/
+        UINT16 maxRecordCount;      /* The max num of trace items | 记录帧数据上限数*/
+        UINT16 curObjIndex;         /* The current obj index | 当前对象索引位*/
+        UINT16 maxObjCount;         /* The max num of obj index | 对象上限数*/
+        ObjData *objBuf;            /* Pointer to obj info data | 循环buf,数组保存任务数据 ObjData*/
+        TraceEventFrame *frameBuf;  /* Pointer to the trace items | 循环buf,数组保存帧数据 TraceEventFrame*/
     } ctrl;
     OfflineHead *head;///< 离线模式头部信息
 } TraceOfflineHeaderInfo;
@@ -128,13 +128,13 @@ extern OfflineHead *OsTraceRecordGet(VOID);
 extern VOID OsTraceSendHead(VOID);
 extern VOID OsTraceSendObjTable(VOID);
 extern VOID OsTraceSendNotify(UINT32 type, UINT32 value);
-/// 通知系统trace开始
+/// 在线模式下,通知系统trace开始
 #define OsTraceNotifyStart() do {                                \
         OsTraceSendNotify(SYS_START, TRACE_CTL_MAGIC_NUM);       \
         OsTraceSendHead();                                       \
         OsTraceSendObjTable();                                   \
     } while (0)
-/// 通知系统trace结束
+/// 在线模式下,通知系统trace结束
 #define OsTraceNotifyStop() do {                                 \
         OsTraceSendNotify(SYS_STOP, TRACE_CTL_MAGIC_NUM);        \
     } while (0)

kernel/extended/trace/pipeline/trace_pipeline.h

@@ -49,10 +49,10 @@ typedef struct { // 串口实现方式:g_serialOps
 
 /* used as tlv's tag */
 enum TraceMsgType {
-    NOTIFY,		///< 通知
-    HEAD,		///< 数据头
-    OBJ,		///< 数据体
-    EVENT,		///< 事件
+    NOTIFY,		///< 通知信息 即发送 TraceNotifyFrame
+    HEAD,		///< 数据头信息, 即发送 TraceBaseHeaderInfo
+    OBJ,		///< 指对象(例如:任务) 即发送 ObjData
+    EVENT,		///< 指事件(例如:定时器开始) 即发送 TraceEventFrame
     TRACE_MSG_MAX,
 };
 

kernel/extended/trace/trace_offline.c

+/*!
+ * @file    trace_offline.c
+ * @brief
+ * @link
+   @verbatim
+   基本概念
+   	Trace调测旨在帮助开发者获取内核的运行流程，各个模块、任务的执行顺序，从而可以辅助开发者定位一些时序问题或者了解内核的代码运行过程。
+
+   运行机制
+   	内核提供一套Hook框架，将Hook点预埋在各个模块的主要流程中, 在内核启动初期完成Trace功能的初始化，并注册Trace的处理函数到Hook中。
+   当系统触发到一个Hook点时，Trace模块会对输入信息进行封装，添加Trace帧头信息，包含事件类型、运行的cpuid、运行的任务id、运行的相对时间戳等信息；
+
+   Trace提供2种工作模式，离线模式和在线模式。此处为离线模式下的实现
+   @endverbatim
+ * @version 
+ * @author  weharmonyos.com
+ * @date    2021-11-22
+ */
 /*
  * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
  * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
@@ -34,8 +52,8 @@
 
 #define BITS_NUM_FOR_TASK_ID 16
 
-LITE_OS_SEC_BSS STATIC TraceOfflineHeaderInfo g_traceRecoder;
-LITE_OS_SEC_BSS STATIC UINT32 g_tidMask[LOSCFG_BASE_CORE_TSK_LIMIT] = {0};
+LITE_OS_SEC_BSS STATIC TraceOfflineHeaderInfo g_traceRecoder; ///< 离线模式下的记录方式
+LITE_OS_SEC_BSS STATIC UINT32 g_tidMask[LOSCFG_BASE_CORE_TSK_LIMIT] = {0};///< 记录屏蔽任务情况
 
 UINT32 OsTraceGetMaskTid(UINT32 tid)
 {
@@ -53,32 +71,32 @@ UINT32 OsTraceBufInit(UINT32 size)
     }
 
 
-    buf = LOS_MemAlloc(m_aucSysMem0, size);
+    buf = LOS_MemAlloc(m_aucSysMem0, size);//在内核堆空间中申请内存
     if (buf == NULL) {
         return LOS_ERRNO_TRACE_NO_MEMORY;
     }
 
     (VOID)memset_s(buf, size, 0, size);
     g_traceRecoder.head = (OfflineHead *)buf;
-    g_traceRecoder.head->baseInfo.bigLittleEndian = TRACE_BIGLITTLE_WORD;
-    g_traceRecoder.head->baseInfo.version         = TRACE_VERSION(TRACE_MODE_OFFLINE);
-    g_traceRecoder.head->baseInfo.clockFreq       = OS_SYS_CLOCK;
-    g_traceRecoder.head->objSize                  = sizeof(ObjData);
-    g_traceRecoder.head->frameSize                = sizeof(TraceEventFrame);
-    g_traceRecoder.head->objOffset                = sizeof(OfflineHead);
-    g_traceRecoder.head->frameOffset              = headSize;
-    g_traceRecoder.head->totalLen                 = size;
-
-    g_traceRecoder.ctrl.curIndex       = 0;
-    g_traceRecoder.ctrl.curObjIndex    = 0;
-    g_traceRecoder.ctrl.maxObjCount    = LOSCFG_TRACE_OBJ_MAX_NUM;
-    g_traceRecoder.ctrl.maxRecordCount = (size - headSize) / sizeof(TraceEventFrame);
+    g_traceRecoder.head->baseInfo.bigLittleEndian = TRACE_BIGLITTLE_WORD;//大小端
+    g_traceRecoder.head->baseInfo.version         = TRACE_VERSION(TRACE_MODE_OFFLINE);//离线模式
+    g_traceRecoder.head->baseInfo.clockFreq       = OS_SYS_CLOCK;//CPU时钟频率
+    g_traceRecoder.head->objSize                  = sizeof(ObjData);//对象大小
+    g_traceRecoder.head->frameSize                = sizeof(TraceEventFrame);//帧大小
+    g_traceRecoder.head->objOffset                = sizeof(OfflineHead);//对象开始位置
+    g_traceRecoder.head->frameOffset              = headSize;//帧开始位置
+    g_traceRecoder.head->totalLen                 = size;//头部大小
+
+    g_traceRecoder.ctrl.curIndex       = 0;	//当前帧位置
+    g_traceRecoder.ctrl.curObjIndex    = 0;	//当前对象位置
+    g_traceRecoder.ctrl.maxObjCount    = LOSCFG_TRACE_OBJ_MAX_NUM;//最大
+    g_traceRecoder.ctrl.maxRecordCount = (size - headSize) / sizeof(TraceEventFrame);//最大记录数
     g_traceRecoder.ctrl.objBuf         = (ObjData *)((UINTPTR)buf + g_traceRecoder.head->objOffset);
     g_traceRecoder.ctrl.frameBuf       = (TraceEventFrame *)((UINTPTR)buf + g_traceRecoder.head->frameOffset);
 
     return LOS_OK;
 }
-
+/// 添加一个任务
 VOID OsTraceObjAdd(UINT32 eventType, UINT32 taskId)
 {
     UINT32 intSave;
@@ -107,23 +125,23 @@ VOID OsTraceObjAdd(UINT32 eventType, UINT32 taskId)
     /* add obj end */
     TRACE_UNLOCK(intSave);
 }
-
+/// 离线模式下保存帧数据 @note_thinking 此处未封装好,会懵逼,文件名中体现了对离线模式的保存或对在线模式的发送这样真的好吗? .
 VOID OsTraceWriteOrSendEvent(const TraceEventFrame *frame)
 {
     UINT16 index;
     UINT32 intSave;
 
     TRACE_LOCK(intSave);
-    index = g_traceRecoder.ctrl.curIndex;
-    (VOID)memcpy_s(&g_traceRecoder.ctrl.frameBuf[index], sizeof(TraceEventFrame), frame, sizeof(TraceEventFrame));
+    index = g_traceRecoder.ctrl.curIndex;//获取当前位置,离线模式会将trace frame记录到预先申请好的循环buffer中
+    (VOID)memcpy_s(&g_traceRecoder.ctrl.frameBuf[index], sizeof(TraceEventFrame), frame, sizeof(TraceEventFrame));//保存帧内容至frameBuf中
 
-    g_traceRecoder.ctrl.curIndex++;
-    if (g_traceRecoder.ctrl.curIndex >= g_traceRecoder.ctrl.maxRecordCount) {
-        g_traceRecoder.ctrl.curIndex = 0;
+    g_traceRecoder.ctrl.curIndex++;//当前位置向前滚
+    if (g_traceRecoder.ctrl.curIndex >= g_traceRecoder.ctrl.maxRecordCount) {//循环写入,这里可以看出,如果循环buffer记录的frame过多则可能出现翻转，
+        g_traceRecoder.ctrl.curIndex = 0;//会覆盖之前的记录，保持记录的信息始终是最新的信息。
     }
     TRACE_UNLOCK(intSave);
 }
-
+/// 重置循环buf
 VOID OsTraceReset(VOID)
 {
     UINT32 intSave;

kernel/extended/trace/trace_online.c

+/*!
+ * @file    trace_online.c
+ * @brief 在线模式需要配合IDE使用，实时将trace frame记录发送给IDE，IDE端进行解析并可视化展示
+ * @link
+   @verbatim
+   Trace调测旨在帮助开发者获取内核的运行流程，各个模块、任务的执行顺序，从而可以辅助开发者定位一些时序问题或者了解内核的代码运行过程。
+   
+   内核提供一套Hook框架，将Hook点预埋在各个模块的主要流程中, 在内核启动初期完成Trace功能的初始化，并注册Trace的处理函数到Hook中。
+
+   当系统触发到一个Hook点时，Trace模块会对输入信息进行封装，添加Trace帧头信息，包含事件类型、运行的cpuid、运行的任务id、运行的相对时间戳等信息；
+
+   Trace提供2种工作模式，离线模式和在线模式。
+   本文件为 在线模式
+   @endverbatim
+ * @version 
+ * @author  weharmonyos.com
+ * @date    2021-11-22
+ */
 /*
  * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
  * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
@@ -36,7 +54,7 @@ UINT32 OsTraceGetMaskTid(UINT32 taskId)
 {
     return taskId;
 }
-
+/// 发送头信息
 VOID OsTraceSendHead(VOID)
 {
     TraceBaseHeaderInfo head = {
@@ -47,7 +65,7 @@ VOID OsTraceSendHead(VOID)
 
     OsTraceDataSend(HEAD, sizeof(TraceBaseHeaderInfo), (UINT8 *)&head);
 }
-
+/// 发送通知类信息(启动,停止 trace 等通知)
 VOID OsTraceSendNotify(UINT32 type, UINT32 value)
 {
     TraceNotifyFrame frame = {
@@ -57,15 +75,15 @@ VOID OsTraceSendNotify(UINT32 type, UINT32 value)
 
     OsTraceDataSend(NOTIFY, sizeof(TraceNotifyFrame), (UINT8 *)&frame);
 }
-
+/// 向串口发送一个类型为对象的trace
 STATIC VOID OsTraceSendObj(const LosTaskCB *tcb)
 {
     ObjData obj;
 
     OsTraceSetObj(&obj, tcb);
-    OsTraceDataSend(OBJ, sizeof(ObjData), (UINT8 *)&obj);
+    OsTraceDataSend(OBJ, sizeof(ObjData), (UINT8 *)&obj);//发送任务信息到串口
 }
-
+///发送所有任务对象至串口
 VOID OsTraceSendObjTable(VOID)
 {
     UINT32 loop;
@@ -73,23 +91,23 @@ VOID OsTraceSendObjTable(VOID)
 
     for (loop = 0; loop < g_taskMaxNum; ++loop) {
         tcb = g_taskCBArray + loop;
-        if (tcb->taskStatus & OS_TASK_STATUS_UNUSED) {
+        if (tcb->taskStatus & OS_TASK_STATUS_UNUSED) {//过滤掉已使用任务
             continue;
         }
-        OsTraceSendObj(tcb);
+        OsTraceSendObj(tcb);//向串口发送数据
     }
 }
-
+/// 添加一个对象(任务) trace
 VOID OsTraceObjAdd(UINT32 eventType, UINT32 taskId)
 {
     if (OsTraceIsEnable()) {
         OsTraceSendObj(OS_TCB_FROM_TID(taskId));
     }
 }
-
+/// 在线模式下发送数据给 IDE, Trace模块会对输入信息进行封装，添加Trace帧头信息，包含事件类型、运行的cpuid、运行的任务id、运行的相对时间戳等信息
 VOID OsTraceWriteOrSendEvent(const TraceEventFrame *frame)
 {
-    OsTraceDataSend(EVENT, sizeof(TraceEventFrame), (UINT8 *)frame);
+    OsTraceDataSend(EVENT, sizeof(TraceEventFrame), (UINT8 *)frame);// 编码TLV并向串口发送
 }
 
 OfflineHead *OsTraceRecordGet(VOID)

kernel/include/los_trace.h

@@ -52,10 +52,10 @@ extern "C" {
  * @ingroup los_trace
  * Trace Control agent task's priority.
  */
-#define LOSCFG_TRACE_TASK_PRIORITY                              2
+#define LOSCFG_TRACE_TASK_PRIORITY                              2	///< trace 任务的优先级为 2, 也挺高的,仅次于软件定时器 0 
 #endif
 
-#define LOSCFG_TRACE_OBJ_MAX_NAME_SIZE                          LOS_TASK_NAMELEN
+#define LOSCFG_TRACE_OBJ_MAX_NAME_SIZE                          LOS_TASK_NAMELEN ///< Trace 对象的名称（内核对象，如任务）
 
 #define LOS_TRACE_LR_RECORD                                     5
 #define LOS_TRACE_LR_IGNORE                                     0
@@ -64,7 +64,7 @@ extern "C" {
  * Trace records the max number of objects(kernel object, like tasks), range is [0, LOSCFG_BASE_CORE_TSK_LIMIT].
  * if set to 0, trace will not record any object.
  */
-#define LOSCFG_TRACE_OBJ_MAX_NUM                                0
+#define LOSCFG_TRACE_OBJ_MAX_NUM                                0 ///< Trace 记录对象的最大数量（内核对象，如任务）
 
 /**
  * @ingroup los_trace
@@ -147,8 +147,8 @@ typedef enum {
 typedef enum { //跟进模块的具体事件
     /* 0x10~0x1F */
     SYS_ERROR             = TRACE_SYS_FLAG | 0,
-    SYS_START             = TRACE_SYS_FLAG | 1,	///< 系统开始
-    SYS_STOP              = TRACE_SYS_FLAG | 2,
+    SYS_START             = TRACE_SYS_FLAG | 1,	///< trace模块开始
+    SYS_STOP              = TRACE_SYS_FLAG | 2, ///< trace模块停止
 
     /* 0x20~0x2F */
     HWI_CREATE              = TRACE_HWI_FLAG | 0,
@@ -249,7 +249,8 @@ typedef struct {
 
 /**
  * @ingroup los_trace
- * struct to store the event infomation | 保存跟踪事件的信息
+ * struct to store the event infomation | 保存跟踪事件的信息 ,Trace模块会对输入信息进行封装，
+ * 添加Trace帧头信息，包含事件类型、运行的cpuid、运行的任务id、运行的相对时间戳等信息
  */
 typedef struct {
     UINT32  eventType;                               /**< event type | 事件类型*/
@@ -268,7 +269,7 @@ typedef struct {
 #endif
 
 #ifdef LOSCFG_TRACE_FRAME_EVENT_COUNT
-    UINT32  eventCount;                               /**< the sequence of happend events  */
+    UINT32  eventCount;                               /**< the sequence of happend events | 事件发生的顺序 */
 #endif
 
 #ifdef LOS_TRACE_FRAME_LR
@@ -291,6 +292,7 @@ typedef struct {
 /**
  * @ingroup los_trace
  * struct to store the kernel obj information, we defined task as kernel obj in this system.
+ * 存储内核对象信息, 在本系统中就是指任务
  */
 typedef struct {
     UINT32      id;                                     /**< kernel obj's id | 这里对象一般指任务ID*/
@@ -300,7 +302,7 @@ typedef struct {
 
 /**
  * @ingroup los_trace
- * struct to store the trace data.
+ * struct to store the trace data. | 离线模式头信息
  */
 typedef struct {
     TraceBaseHeaderInfo baseInfo;          /**< basic info, include bigLittleEndian flag, system clock freq | 基础信息*/
@@ -308,7 +310,7 @@ typedef struct {
     UINT16 objSize;                        /**< sizeof #ObjData | 对象大小*/
     UINT16 frameSize;                      /**< sizeof #TraceEventFrame | 事件帧大小*/
     UINT16 objOffset;                      /**< the offset of the first obj data to record beginning | 开始对象数据位置*/
-    UINT16 frameOffset;                    /**< the offset of the first event frame data to record beginning | 开始事件帧数据位置*/
+    UINT16 frameOffset;                    /**< the offset of the first event frame data to record beginning | 开始事件帧数据位置 g_traceRecoder.ctrl.frameBuf*/
 } OfflineHead;
 
 

zzz/git/push.sh

 git add -A
-git commit -m  ' 注解内核如何监测CPU
+git commit -m  ' trace模块分离线和在线两种模式,详细注解其实现细节
     百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
     鸿蒙研究站 | http://weharmonyos.com (国内) 
               | https://weharmony.github.io (国外)