完善串口注解

    百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
    鸿蒙研究站 | 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)

apps/shell/src/shmsg.c

@@ -657,7 +657,7 @@ void *ShellEntry(void *argv)
     char ch;
     int ret;
     int n;
-    pid_t tid = syscall(__NR_gettid);
+    pid_t tid = syscall(__NR_gettid);//获取当前任务/线程ID, 即 "Shell Entry" 任务的ID
     ShellCB *shellCB = (ShellCB *)argv;
 
     if (shellCB == NULL) {
@@ -666,12 +666,12 @@ void *ShellEntry(void *argv)
 
     (void)memset_s(shellCB->shellBuf, SHOW_MAX_LEN, 0, SHOW_MAX_LEN);
 
-    ret = prctl(PR_SET_NAME, "ShellEntry");//创建一个shell客户端任务
+    ret = prctl(PR_SET_NAME, "ShellEntry");//将任务的名称设置成 ShellEntry
     if (ret != SH_OK) {
         return NULL;
     }
 
-    ret = ShellKernelReg((int)tid);///< 将shell客户端任务和控制台绑定
+    ret = ShellKernelReg((int)tid);//向内核注册shell,和控制台捆绑在一块
     if (ret != 0) {
         printf("another shell is already running!\n");
         exit(-1);

kernel/common/console.c

@@ -462,7 +462,7 @@ VOID KillPgrp(UINT16 consoleId)
     }
     (VOID)OsKillLock(consoleCB->pgrpId, SIGINT);//发送信号 SIGINT对应 键盘中断（ctrl + c）信号
 }
-///用户使用参数buffer将控制台的buf接走
+///使用参数buffer将控制台的buf接走
 STATIC INT32 UserFilepRead(CONSOLE_CB *consoleCB, struct file *filep, const struct file_operations_vfs *fops,
                            CHAR *buffer, size_t bufLen)
 {
@@ -531,7 +531,7 @@ INT32 FilepRead(struct file *filep, const struct file_operations_vfs *fops, CHAR
      * adopt uart read function to read data from filep
      * and write data to buffer (filep is
      * corresponding to filep of /dev/console)
-     */
+     *///采用uart read函数从文件中读取数据，将数据写入缓冲区（文件对应/dev/console的filep）
     ret = fops->read(filep, buffer, bufLen);
     if (ret < 0) {
         return -EPERM;
@@ -721,7 +721,7 @@ STATIC ssize_t ConsoleRead(struct file *filep, CHAR *buffer, size_t bufLen)
         goto ERROUT;
     }
 
-    ret = DoRead(consoleCB, sbuffer, bufLen, privFilep, fileOps);//真正的读数据
+    ret = DoRead(consoleCB, sbuffer, bufLen, privFilep, fileOps);//从 console buf中取数据
     if (ret < 0) {
         goto ERROUT;
     }
@@ -1159,7 +1159,7 @@ ERROUT:
     set_errno(ret);
     return LOS_NOK;
 }
-/// 控制台设备去初始化
+/// 注销控制台设备
 STATIC UINT32 OsConsoleDevDeinit(const CONSOLE_CB *consoleCB)
 {
     return unregister_driver(consoleCB->name);//注销驱动
@@ -1240,7 +1240,7 @@ STATIC UINT32 OsConsoleBufInit(CONSOLE_CB *consoleCB)
     }//永久等待读取 CONSOLE_SEND_TASK_RUNNING 事件,CONSOLE_SEND_TASK_RUNNING 由 ConsoleSendTask 发出.
     (VOID)LOS_EventRead(&consoleCB->cirBufSendCB->sendEvent, CONSOLE_SEND_TASK_RUNNING,
                         LOS_WAITMODE_OR | LOS_WAITMODE_CLR, LOS_WAIT_FOREVER);
-
+	// ... 读取到 CONSOLE_SEND_TASK_RUNNING 事件才会往下执行  
     return LOS_OK;
 }
 /// 控制台buf去初始化
@@ -1313,17 +1313,17 @@ STATIC CONSOLE_CB *OsConsoleCreate(UINT32 consoleID, const CHAR *deviceName)
         goto ERR_WITH_SEM;
     }
 
-    ret = OsConsoleFileInit(consoleCB);	//控制台文件初始化,其中file要绑定驱动程序
+    ret = OsConsoleFileInit(consoleCB);	//为 /dev/console(n|1:2)分配fd(3)
     if (ret != LOS_OK) {
         PRINT_ERR("console OsConsoleFileInit error. %d\n", ret);
         goto ERR_WITH_DEV;
     }
 
-    OsConsoleTermiosInit(consoleCB, deviceName);//控制台术语/控制初始化
+    OsConsoleTermiosInit(consoleCB, deviceName);//控制台行规程初始化
     return consoleCB;
 
 ERR_WITH_DEV:
-    ret = (INT32)OsConsoleDevDeinit(consoleCB);//控制台设备去初始化
+    ret = (INT32)OsConsoleDevDeinit(consoleCB);//控制台设备注销
     if (ret != LOS_OK) {
         PRINT_ERR("OsConsoleDevDeinit failed!\n");
     }

kernel/common/virtual_serial.c

@@ -58,7 +58,7 @@ UART 串口通信有几个重要的参数，分别是波特率、起始位、数
 */
 
 STATIC volatile UINT32 g_serialType = 0;
-STATIC struct file g_serialFilep;
+STATIC struct file g_serialFilep;// COM0 /dev/uartdev-0 在内核层的表述 属于 .bbs段
 
 //获取串口类型
 UINT32 SerialTypeGet(VOID)
@@ -125,13 +125,13 @@ STATIC ssize_t SerialRead(struct file *filep, CHAR *buffer, size_t bufLen)
     struct file *privFilep = NULL;
     const struct file_operations_vfs *fileOps = NULL;
 
-    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取控制台file实例
+    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取COM口在内核的file实例
     if (ret != ENOERR) {
         ret = -EINVAL;
         goto ERROUT;
     }
 
-    ret = FilepRead(privFilep, fileOps, buffer, bufLen);//从控制台读buf
+    ret = FilepRead(privFilep, fileOps, buffer, bufLen);//从COM口读buf
     if (ret < 0) {
         goto ERROUT;
     }
@@ -149,7 +149,7 @@ STATIC ssize_t SerialWrite(struct file *filep,  const CHAR *buffer, size_t bufLe
     struct file *privFilep = NULL;
     const struct file_operations_vfs *fileOps = NULL;
 
-    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取控制台file实例
+    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取COM口在内核的file实例
     if (ret != ENOERR) {
         ret = -EINVAL;
         goto ERROUT;
@@ -235,7 +235,7 @@ INT32 virtual_serial_init(const CHAR *deviceName)
         goto ERROUT;
     }
 
-    SerialTypeSet(deviceName);//设置串口类型
+    SerialTypeSet(deviceName);//例如: /dev/uartdev-0 <--> /dev/console1
 
     VnodeHold();
     ret = VnodeLookup(deviceName, &vnode, V_DUMMY);//由deviceName查询vnode节点
@@ -255,8 +255,8 @@ INT32 virtual_serial_init(const CHAR *deviceName)
         ret = EFAULT;
         PRINTK("virtual_serial_init %s open is NULL\n", deviceName);
         goto ERROUT;
-    }//这是真正的注册串口的驱动程序
-    (VOID)register_driver(SERIAL, &g_serialDevOps, DEFFILEMODE, &g_serialFilep);
+    }
+    (VOID)register_driver(SERIAL, &g_serialDevOps, DEFFILEMODE, &g_serialFilep);//这是真正的注册串口的驱动程序
 
     VnodeDrop();
     return ENOERR;

kernel/extended/trace/los_trace.c

@@ -236,12 +236,12 @@ STATIC VOID OsTraceCmdHandle(const TraceClientCmd *msg)
 
     switch (msg->cmd) {
         case TRACE_CMD_START:
-            LOS_TraceStart();
+            LOS_TraceStart();//启动trace
             break;
         case TRACE_CMD_STOP:
-            LOS_TraceStop();
+            LOS_TraceStop();//关闭trace
             break;
-        case TRACE_CMD_SET_EVENT_MASK:
+        case TRACE_CMD_SET_EVENT_MASK://设置事件掩码
             /* 4 params(UINT8) composition the mask(UINT32) */
             LOS_TraceEventMaskSet(TRACE_MASK_COMBINE(msg->param1, msg->param2, msg->param3, msg->param4));
             break;
@@ -252,7 +252,7 @@ STATIC VOID OsTraceCmdHandle(const TraceClientCmd *msg)
             break;
     }
 }
-///< trace任务的入口函数
+///< trace任务的入口函数,接收串口数据
 VOID TraceAgent(VOID)
 {
     UINT32 ret;
@@ -260,10 +260,10 @@ VOID TraceAgent(VOID)
 
     while (1) {
         (VOID)memset_s(&msg, sizeof(TraceClientCmd), 0, sizeof(TraceClientCmd));
-        ret = OsTraceDataWait();
+        ret = OsTraceDataWait();//等待数据到来
         if (ret == LOS_OK) {
             OsTraceDataRecv((UINT8 *)&msg, sizeof(TraceClientCmd), 0);
-            OsTraceCmdHandle(&msg);
+            OsTraceCmdHandle(&msg);//处理数据
         }
     }
 }

kernel/extended/trace/pipeline/serial/trace_pipeline_serial.c

@@ -37,7 +37,7 @@ UINT32 SerialPipelineInit(VOID)
 {
     return uart_hwiCreate();
 }
-
+///< 接收串口数据
 UINT32 SerialDataReceive(UINT8 *data, UINT32 size, UINT32 timeout)
 {
     return uart_read(data, size, timeout);
@@ -70,7 +70,7 @@ VOID SerialDataSend(UINT16 len, UINT8 *data)
 {
     UartPuts((CHAR *)data, len, 1);
 }
-///< 用串口打印trace数据
+///< 串口数据处理
 STATIC const TracePipelineOps g_serialOps = {
     .init = SerialPipelineInit,
     .dataSend = SerialDataSend,

kernel/extended/trace/pipeline/trace_pipeline.c

@@ -126,7 +126,7 @@ VOID OsTracePipelineReg(const TracePipelineOps *ops)
 {
     g_tracePipelineOps = ops;
 }
-
+///< 向串口发送数据
 VOID OsTraceDataSend(UINT8 type, UINT16 len, UINT8 *data)
 {
     UINT32 intSave;
@@ -135,14 +135,14 @@ VOID OsTraceDataSend(UINT8 type, UINT16 len, UINT8 *data)
     if ((type > TRACE_MSG_MAX) || (len > LOSCFG_TRACE_TLV_BUF_SIZE)) {
         return;
     }
-
+	//将发送前先将数据编码
     len = OsTraceDataEncode(type, g_traceTlvTbl[type], data, &outBuf[0], sizeof(outBuf));
 
     PIPE_LOCK(intSave);
     g_tracePipelineOps->dataSend(len, &outBuf[0]);
     PIPE_UNLOCK(intSave);
 }
-
+///< 接收串口数据
 UINT32 OsTraceDataRecv(UINT8 *data, UINT32 size, UINT32 timeout)
 {
     return g_tracePipelineOps->dataRecv(data, size, timeout);

net/telnet/src/telnet_dev.c

@@ -53,7 +53,7 @@
 #define TELNET_EVENT_MORE_CMD   0x01 ///< 还有很多命令在FIFO中等待运行的事件
 #define TELNET_DEV_DRV_MODE     0666 ///< 文件权限 chmod = 666 
 
-STATIC TELNET_DEV_S g_telnetDev;
+STATIC TELNET_DEV_S g_telnetDev;	///< 远程登录设备
 STATIC EVENT_CB_S *g_event;
 STATIC struct Vnode *g_currentVnode;
 

shell/full/src/base/shmsg.c

@@ -401,7 +401,7 @@ LITE_OS_SEC_TEXT_MINOR UINT32 ShellTask(UINTPTR param1,
     (VOID)param4;
 
     while (1) {
-        PRINTK("\nOHOS # ");//读取shell 输入事件 例如: cat weharmony.net 命令
+        PRINTK("\nOHOS # ");//在没有事件的时候,会一直停留在此, 读取shell 输入事件 例如: cat weharmony.net 命令
         ret = LOS_EventRead(&shellCB->shellEvent,
                             0xFFF, LOS_WAITMODE_OR | LOS_WAITMODE_CLR, LOS_WAIT_FOREVER);
         if (ret == SHELL_CMD_PARSE_EVENT) {//获得解析命令事件

shell/full/src/base/show.c

@@ -46,7 +46,7 @@ STATIC UINT32 OsShellCmdInit(VOID)
 
     return OsShellSysCmdRegister();//系统自带的shell命令初始化
 }
-///创建shell任务
+///创建shell服务端任务
 STATIC UINT32 OsShellCreateTask(ShellCB *shellCB)
 {
     UINT32 ret = ShellTaskInit(shellCB);//执行shell命令的任务初始化

zzz/git/push.sh

 git add -A
-git commit -m  ' 完善控制台注解
+git commit -m  ' 完善串口注解
     百万汉字注解 + 百篇博客分析 => 挖透鸿蒙内核源码
     鸿蒙研究站 | http://weharmonyos.com (国内) 
               | https://weharmony.github.io (国外)