完善控制台注解

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

@@ -40,24 +40,24 @@ extern "C" {
 #endif /* __cplusplus */
 #endif /* __cplusplus */
 
-#define SHELL_ENTRY_STACKSIZE   0x1000
-#define SHELL_TASK_STACKSIZE    0x3000
+#define SHELL_ENTRY_STACKSIZE   0x1000	///< shell客户端栈大小 4K
+#define SHELL_TASK_STACKSIZE    0x3000  ///< shell服务端栈大小 12K
 
-#define SHELL_EXEC_COMMAND          "exec"
+#define SHELL_EXEC_COMMAND          "exec"	///< 运行 elf 命令 例如: exec bin/hello
 #define SHELL_EXEC_COMMAND_BYTES    4
 #define CMD_EXEC_COMMAND            SHELL_EXEC_COMMAND" "
 #define CMD_EXEC_COMMAND_BYTES      (SHELL_EXEC_COMMAND_BYTES+1)
-#define CMD_EXIT_COMMAND            "exit"
+#define CMD_EXIT_COMMAND            "exit" ///< 退出命令
 #define CMD_EXIT_COMMAND_BYTES      4
 #define CMD_EXIT_CODE_BASE_DEC      10
 
 #define CONSOLE_IOC_MAGIC   'c'
-#define CONSOLE_CONTROL_REG_USERTASK _IO(CONSOLE_IOC_MAGIC, 7)
+#define CONSOLE_CONTROL_REG_USERTASK _IO(CONSOLE_IOC_MAGIC, 7) ///< 注册用户任务 shell 客户端
 
 #define COLOR_NONE     "\e[0m"
 #define COLOR_RED      "\e[0;31m"
 #define COLOR_L_RED    "\e[1;31m"
-#define SHELL_PROMPT   COLOR_L_RED"OHOS # "COLOR_NONE
+#define SHELL_PROMPT   COLOR_L_RED"OHOS # "COLOR_NONE ///< shell 红色提示 OHOS # 	
 
 typedef void (*OutputFunc)(const char *fmt, ...);
 extern int ShellTaskInit(ShellCB *shellCB);

apps/shell/src/shmsg.c

@@ -646,7 +646,7 @@ int ShellTaskInit(ShellCB *shellCB)
 
     return ret;
 }
-
+///< 给控制台注册一个shell客户端任务
 static int ShellKernelReg(unsigned int shellHandle)
 {
     return ioctl(STDIN_FILENO, CONSOLE_CONTROL_REG_USERTASK, shellHandle);
@@ -666,21 +666,21 @@ void *ShellEntry(void *argv)
 
     (void)memset_s(shellCB->shellBuf, SHOW_MAX_LEN, 0, SHOW_MAX_LEN);
 
-    ret = prctl(PR_SET_NAME, "ShellEntry");
+    ret = prctl(PR_SET_NAME, "ShellEntry");//创建一个shell客户端任务
     if (ret != SH_OK) {
         return NULL;
     }
 
-    ret = ShellKernelReg((int)tid);
+    ret = ShellKernelReg((int)tid);///< 将shell客户端任务和控制台绑定
     if (ret != 0) {
         printf("another shell is already running!\n");
         exit(-1);
     }
 
     while (1) {
-        n = read(0, &ch, 1);
+        n = read(0, &ch, 1);//读取输入字符
         if (n == 1) {
-            ShellCmdLineParse(ch, (OutputFunc)printf, shellCB);
+            ShellCmdLineParse(ch, (OutputFunc)printf, shellCB);//对命令行内容进行解析
         }
     }
     return NULL;

kernel/base/include/los_process_pri.h

@@ -75,7 +75,10 @@ typedef struct {
     LOS_DL_LIST exitProcessList; /**< List of closed processes (zombie processes) under this group | 进程组的僵死进程链表*/
     LOS_DL_LIST groupList;       /**< Process group list | 进程组链表,上面挂的都是进程组*/
 } ProcessGroup;
-/*! 进程控制块*/
+
+/**
+ *  进程控制块.
+ */
 typedef struct ProcessCB {
     CHAR                 processName[OS_PCB_NAME_LEN]; /**< Process name | 进程名称 */
     UINT32               processID;                    /**< Process ID = leader thread ID | 进程ID,由进程池分配,范围[0,64] */
@@ -115,8 +118,8 @@ typedef struct ProcessCB {
     timer_t             timerID;       /**< iTimer */
 
 #ifdef LOSCFG_SECURITY_CAPABILITY	//安全能力
-    User                *user;		//进程的拥有者
-    UINT32              capability;	//安全能力范围 对应 CAP_SETGID
+    User                *user;		///< 进程的拥有者
+    UINT32              capability;	///< 安全能力范围 对应 CAP_SETGID
 #endif
 #ifdef LOSCFG_SECURITY_VID	//虚拟ID映射功能
     TimerIdMap          timerIdMap;
@@ -124,7 +127,7 @@ typedef struct ProcessCB {
 #ifdef LOSCFG_DRIVERS_TZDRIVER
     struct Vnode        *execVnode;     /**< Exec bin of the process | 进程的可执行文件 */
 #endif
-    mode_t               umask;///< umask(user file-creatiopn mode mask)为用户文件创建掩码，是创建文件或文件夹时默认权限的基础。
+    mode_t               umask; ///< umask(user file-creatiopn mode mask)为用户文件创建掩码，是创建文件或文件夹时默认权限的基础。
 #ifdef LOSCFG_KERNEL_CPUP
     OsCpupBase           *processCpup; /**< Process cpu usage | 进程占用CPU情况统计*/
 #endif

kernel/base/include/los_vm_filemap.h

+/*!
+ * @file    los_vm_filemap.h
+ * @brief
+ * @link
+   @verbatim
+    磁盘高速缓存是一种软件机制，它允许系统把通常存放在磁盘上的一些数据保留在 RAM 中，以便对那些数据的
+    进一步访问不用再访问磁盘而能尽快得到满足。
+    页高速缓存中的信息单位是一个完整的页。
+    一个页包含的磁盘块在物理上不一定相邻，所以不能用设备号和块号标识，而是通过页的所有者和所有者数据中的索引来识别。
+    页高速缓存可以缓存以下内容
+	    A.普通文件数据
+	    B.含有目录的页 
+	    C.直接从快设备读取的页 
+	    D.用户进程数据的页
+	    E.特殊文件系统的文件页
+   @endverbatim
+ * @version 
+ * @author  weharmonyos.com | 鸿蒙研究站 | 每天死磕一点点
+ * @date    2021-12-9
+ */
 /*
  * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
  * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
@@ -51,41 +71,26 @@ extern "C" {
 #endif /* __cplusplus */
 #endif /* __cplusplus */
 
-/**
- * @brief 
- * @verbatim 
-    磁盘高速缓存是一种软件机制，它允许系统把通常存放在磁盘上的一些数据保留在 RAM 中，以便对那些数据的
-    进一步访问不用再访问磁盘而能尽快得到满足。
-    页高速缓存中的信息单位是一个完整的页。
-    一个页包含的磁盘块在物理上不一定相邻，所以不能用设备号和块号标识，而是通过页的所有者和所有者数据中的索引来识别。
-    页高速缓存可以缓存以下内容
-    A.普通文件数据
-    B.含有目录的页 
-    C.直接从快设备读取的页 
-    D.用户进程数据的页
-    E.特殊文件系统的文件页
- * @endverbatim
- * 
- */
 #if 0 //@note_#if0 
 //page_mapping描述的是一个文件在内存中被映射了多少页,<文件,文件页的关系>
 /* file mapped in VMM pages */
 struct page_mapping {//记录文件页和文件关系的结构体,叫文件页映射
-  LOS_DL_LIST                           page_list;    /* all pages */ //链表上挂的是属于该文件的所有FilePage，这些页的内容都来源同一个文件
-  SPIN_LOCK_S                           list_lock;    /* lock protecting it */ //操作page_list的自旋锁
-  LosMux                                mux_lock;     /* mutex lock */	//		//操作page_mapping的互斥量
-  unsigned long                         nrpages;      /* number of total pages */ //page_list的节点数量	
-  unsigned long                         flags;			//@note_why 全量代码中也没查到源码中对其操作	
-  Atomic                                ref;          /* reference counting */	//引用次数(自增/自减),对应add_mapping/dec_mapping
-  struct file                           *host;        /* owner of this mapping *///属于哪个文件的映射
+  LOS_DL_LIST                           page_list;    /* all pages | 链表上挂的是属于该文件的所有FilePage，这些页的内容都来源同一个文件*/
+  SPIN_LOCK_S                           list_lock;    /* lock protecting it | 操作page_list的自旋锁*/
+  LosMux                                mux_lock;     /* mutex lock | 操作page_mapping的互斥量*/
+  unsigned long                         nrpages;      /* number of total pages |page_list的节点数量 */
+  unsigned long                         flags;		  ///< @note_why 全量代码中也没查到源码中对其操作
+  Atomic                                ref;          /* reference counting | 引用次数(自增/自减),对应add_mapping/dec_mapping*/
+  struct Vnode                          *host;        /* owner of this mapping | 属于哪个文件的映射*/
 };
 
+
 /* map: full_path(owner) <-> mapping */ //叫文件映射
 struct file_map { //为在内核层面文件在内存的身份证,每个需映射到内存的文件必须创建一个file_map，都挂到全局g_file_mapping链表上
-  LOS_DL_LIST           head;		//链表节点,用于挂到g_file_mapping上
+  LOS_DL_LIST           head;		///< 链表节点,用于挂到g_file_mapping上
   LosMux                lock;         /* lock to protect this mapping */
-  struct page_mapping   mapping;	//每个文件都有唯一的page_mapping标识其在内存的身份
-  char                  *owner;     /* owner: full path of file *///文件全路径来标识唯一性
+  struct page_mapping   mapping;	///< 每个文件都有唯一的page_mapping标识其在内存的身份
+  char                  *owner;     /* owner: full path of file | 文件全路径来标识唯一性*/
 };
 
 #endif

kernel/base/include/los_vm_zone.h

@@ -3,8 +3,7 @@
  * @brief
  * @link
    @verbatim
-   	@note_pic
-   虚拟地址空间全景图 从 0x00000000U 至 0xFFFFFFFFU ,外设和主存采用统一编址方式
+   虚拟地址空间全景图 从 0x00000000U 至 0xFFFFFFFFU ,外设和主存采用统一编址方式 @note_pic
    鸿蒙源码分析系列篇: 		   https://blog.csdn.net/kuangyufei 
 					   https://my.oschina.net/u/3751245
    

kernel/common/console.c

@@ -194,7 +194,7 @@ STATIC INT32 ConsoleCtrlCaptureLine(CONSOLE_CB *consoleCB)
 
     return LOS_OK;
 }
-
+///< 铺捉到 ctrl + 字符, 例如 ctrl + c 
 STATIC INT32 ConsoleCtrlCaptureChar(CONSOLE_CB *consoleCB)
 {
     struct termios consoleTermios = {0};
@@ -208,14 +208,15 @@ STATIC INT32 ConsoleCtrlCaptureChar(CONSOLE_CB *consoleCB)
 
     return LOS_OK;
 }
-
+///< 铺捉到 ctrl + 右方向键(>)
 STATIC INT32 ConsoleCtrlRightsCapture(CONSOLE_CB *consoleCB)
 {
     (VOID)LOS_SemPend(consoleCB->consoleSem, LOS_WAIT_FOREVER);
     if ((ConsoleRefcountGet(consoleCB) == 0) &&
-        (OsCurrTaskGet()->taskID != consoleCB->shellEntryId)) {
-        /* not 0:indicate that shellentry is in uart_read, suspend shellentry task directly */
-        (VOID)LOS_TaskSuspend(consoleCB->shellEntryId);
+        (OsCurrTaskGet()->taskID != consoleCB->shellEntryId)) { //控制台没有任务使用且当前任务不是接收终端输入的shell entry 任务
+        /* not 0:indicate that shellentry is in uart_read, suspend shellentry task directly 
+		| 表示shellentry在uart_read中，直接挂起shellentry任务*/
+        (VOID)LOS_TaskSuspend(consoleCB->shellEntryId);//挂起任务,意味着不接受输入
     }
     ConsoleRefcountSet(consoleCB, TRUE);
     return LOS_OK;
@@ -260,7 +261,7 @@ STATIC CONSOLE_CB *OsGetConsoleByDevice(const CHAR *deviceName)
         return NULL;
     }
 }
-///获取控制台ID,(/dev/serial = 1, /dev/telnet = 2)
+///获取控制台ID,(/dev/console1 = SERIAL, /dev/console2 = telnet)
 STATIC INT32 OsGetConsoleID(const CHAR *deviceName)
 {
     if ((deviceName != NULL) &&
@@ -374,7 +375,7 @@ STATIC INLINE VOID UserEndOfRead(CONSOLE_CB *consoleCB, struct file *filep,
 }
 ///根据VT终端标准 <ESC>[37m 为设置前景色
 enum {
-    STAT_NORMAL_KEY,	///< 普通按键
+    STAT_NORMAL_KEY,///< 普通按键
     STAT_ESC_KEY,	///< 控制按键,只有 ESC 是
     STAT_MULTI_KEY	///< 多个按键,只有 [ 是
 };
@@ -677,7 +678,7 @@ STATIC ssize_t DoRead(CONSOLE_CB *consoleCB, CHAR *buffer, size_t bufLen,
 
     return ret;
 }
-///用户任务从控制台读数据
+///任务从控制台读数据
 STATIC ssize_t ConsoleRead(struct file *filep, CHAR *buffer, size_t bufLen)
 {
     INT32 ret;
@@ -808,8 +809,8 @@ STATIC ssize_t ConsoleWrite(struct file *filep, const CHAR *buffer, size_t bufLe
     cirBufSendCB = ((CONSOLE_CB *)filep->f_priv)->cirBufSendCB;
 
     /*
-     * adopt uart open function to read data from buffer
-     * and write data to filep (filep is
+     * adopt uart open function to read data from buffer | 用uart open函数从buffer中读取数据
+     * and write data to filep (filep is | 向filep写入数据（filep对应/dev/console的filep）
      * corresponding to filep of /dev/console)
      */
     sbuffer = userBuf ? LOS_MemAlloc(m_aucSysMem0, bufLen) : (CHAR *)buffer;
@@ -817,12 +818,12 @@ STATIC ssize_t ConsoleWrite(struct file *filep, const CHAR *buffer, size_t bufLe
         ret = ENOMEM;
         goto ERROUT;
     }
-
+	//将用户空间的数据拷贝进内核空间
     if (userBuf && (LOS_ArchCopyFromUser(sbuffer, buffer, bufLen) != 0)) {
         ret = EFAULT;
         goto ERROUT;
     }
-    ret = DoWrite(cirBufSendCB, sbuffer, bufLen);//真正的写操作
+    ret = DoWrite(cirBufSendCB, sbuffer, bufLen);//真正的写操作,向控制台任务发起写入事件
 
     if (userBuf) {
         LOS_MemFree(m_aucSysMem0, sbuffer);
@@ -906,7 +907,7 @@ INT32 ConsoleGetPgrp(CONSOLE_CB *consoleCB, unsigned long arg)
     }
     return LOS_OK;
 }
-
+///< 对控制台i/o操作
 STATIC INT32 ConsoleIoctl(struct file *filep, INT32 cmd, unsigned long arg)
 {
     INT32 ret;
@@ -944,7 +945,7 @@ STATIC INT32 ConsoleIoctl(struct file *filep, INT32 cmd, unsigned long arg)
         case CONSOLE_CONTROL_CAPTURE_CHAR:
             ret = ConsoleCtrlCaptureChar(consoleCB);
             break;
-        case CONSOLE_CONTROL_REG_USERTASK:
+        case CONSOLE_CONTROL_REG_USERTASK: //注册shell 客户端    http://weharmonyos.com/blog/72.html
             ret = ConsoleTaskReg(consoleCB->consoleID, arg);
             break;
         case TIOCGWINSZ:
@@ -1071,7 +1072,7 @@ STATIC INT32 OsConsoleFileInit(CONSOLE_CB *consoleCB)
         goto ERROUT;
     }
 
-    filep = files_allocate(vnode, O_RDWR, 0, consoleCB, FILE_START_FD);
+    filep = files_allocate(vnode, O_RDWR, 0, consoleCB, FILE_START_FD);//3号文件描述符分配给了控制台
     if (filep == NULL) {
         ret = EMFILE;
         goto ERROUT;
@@ -1288,7 +1289,7 @@ STATIC CONSOLE_CB *OsConsoleCreate(UINT32 consoleID, const CHAR *deviceName)
     }
 
     ret = snprintf_s(consoleCB->name, CONSOLE_NAMELEN, CONSOLE_NAMELEN - 1,
-                     "%s%u", CONSOLE, consoleCB->consoleID);//通过printf方式得到name
+                     "%s%u", CONSOLE, consoleCB->consoleID);//通过printf方式得到name 例如: /dev/console1
     if (ret == -1) {
         PRINT_ERR("consoleCB->name snprintf_s failed\n");
         goto ERR_WITH_NAME;
@@ -1376,7 +1377,7 @@ INT32 system_console_init(const CHAR *deviceName)//deviceName: /dev/serial /dev/
     }
 
     LOS_SpinLockSave(&g_consoleSpin, &intSave);
-    g_console[consoleID - 1] = consoleCB;//全局变量,  g_console最大值只有2 ,代表当前0,1指向哪个任务.
+    g_console[consoleID - 1] = consoleCB;//全局变量,  g_console最大值只有2 ,所有任务共用控制台.
     if (OsCurrTaskGet() != NULL) {//当前task
         g_taskConsoleIDArray[OsCurrTaskGet()->taskID] = (UINT8)consoleID;//任务绑定控制台ID
     }
@@ -1467,15 +1468,15 @@ BOOL ConsoleEnable(VOID)
 
     return FALSE;
 }
-
+///<  ShellEntry是否在运行,其为负责接受来自终端敲入的一个个字符
 BOOL IsShellEntryRunning(UINT32 shellEntryId)
 {
     LosTaskCB *taskCB = NULL;
     if (shellEntryId == SHELL_ENTRYID_INVALID) {
         return FALSE;
     }
-    taskCB = OsGetTaskCB(shellEntryId);
-    return !OsTaskIsUnused(taskCB) &&
+    taskCB = OsGetTaskCB(shellEntryId);//获取任务
+    return !OsTaskIsUnused(taskCB) && //确定名为"ShellEntry"的任务
            (strlen(taskCB->taskName) == SHELL_ENTRY_NAME_LEN &&
             strncmp(taskCB->taskName, SHELL_ENTRY_NAME, SHELL_ENTRY_NAME_LEN) == 0);
 }
@@ -1485,8 +1486,8 @@ INT32 ConsoleTaskReg(INT32 consoleID, UINT32 taskID)
     UINT32 intSave;
 
     LOS_SpinLockSave(&g_consoleSpin, &intSave);
-    if (!IsShellEntryRunning(g_console[consoleID - 1]->shellEntryId)) {
-        g_console[consoleID - 1]->shellEntryId = taskID;	//ID捆绑
+    if (!IsShellEntryRunning(g_console[consoleID - 1]->shellEntryId)) {//如果控制台还没有捆绑shell客户端任务 
+        g_console[consoleID - 1]->shellEntryId = taskID;	//给控制台捆绑一个shell客户端任务,接受终端输入.
         LOS_SpinUnlockRestore(&g_consoleSpin, intSave);
         (VOID)OsSetCurrProcessGroupID(OsGetUserInitProcessID());// @notethinking 为何要在此处设置当前进程的组ID?
         return LOS_OK;
@@ -1632,13 +1633,13 @@ STATIC ssize_t WriteToTerminal(const CONSOLE_CB *consoleCB, const CHAR *buffer,
 
     fd = consoleCB->fd;//获取文件描述符
     ret = fs_getfilep(fd, &filep);//获取文件指针
-    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取文件的操作方法
+    ret = GetFilepOps(filep, &privFilep, &fileOps);//获取终端设备私有操作方法
 
     if ((fileOps == NULL) || (fileOps->write == NULL)) {
         ret = EFAULT;
         goto ERROUT;
     }
-    (VOID)fileOps->write(privFilep, buffer, bufLen);//写入文件,控制台的本质就是一个文件，这里写入文件就是在终端设备上呈现出来
+    (VOID)fileOps->write(privFilep, buffer, bufLen);//写入终端设备,在终端设备上呈现出来
 
     return cnt;
 

kernel/common/console.h

+/*!
+ * @file    console.h
+ * @brief
+ * @link
+   @verbatim
+   https://www.cnblogs.com/sparkdev/p/11460821.html
+   
+   TTY 是 Teletype 或 Teletypewriter 的缩写，字符设备的通称,原来是指电传打字机，
+   后来这种设备逐渐键盘和显示器取代。不管是电传打字机还是键盘,显示器，
+   都是作为计算机的终端设备存在的，所以 TTY 也泛指计算机的终端(terminal)设备。
+   为了支持这些 TTY 设备，Linux 实现了一个叫做 TTY 的子系统。所以 TTY 既指终端，也指 Linux 的 TTY 子系统
+   
+   /dev/console是一个虚拟的tty，在鸿蒙它映射到真正的dev/ttyS0(UART0)上
+   能直接显示系统消息的那个终端称为控制台，其他的则称为终端
+
+   @endverbatim
+ * @version 
+ * @author  weharmonyos.com | 鸿蒙研究站 | 每天死磕一点点
+ * @date    2021-12-8
+ */
 /*
  * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
  * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
@@ -51,7 +71,7 @@ extern "C" {
 
 #ifdef LOSCFG_FS_VFS
 
-/* Define two fixed console id for Console ID. | 两种固定的控制台id */
+/* Define two fixed console id for Console ID. | 默认两种固定的控制台id */
 #define CONSOLE_SERIAL 1	///< 串行方式
 #define CONSOLE_TELNET 2	///< 远程登录
 //POSIX 定义了 STDIN_FILENO、STDOUT_FILENO 和 STDERR_FILENO 来代表 0、1、2 
@@ -59,17 +79,7 @@ extern "C" {
 #define STDIN  0	///< 标准输入
 #define STDOUT 1	///< 标准输出
 #define STDERR 2	///< 错误
-/**********************************************************
-https://www.cnblogs.com/sparkdev/p/11460821.html
-
-TTY 是 Teletype 或 Teletypewriter 的缩写，字符设备的通称,原来是指电传打字机，
-后来这种设备逐渐键盘和显示器取代。不管是电传打字机还是键盘,显示器，
-都是作为计算机的终端设备存在的，所以 TTY 也泛指计算机的终端(terminal)设备。
-为了支持这些 TTY 设备，Linux 实现了一个叫做 TTY 的子系统。所以 TTY 既指终端，也指 Linux 的 TTY 子系统
 
-/dev/console是一个虚拟的tty，在鸿蒙它映射到真正的dev/ttyS0(UART0)上
-能直接显示系统消息的那个终端称为控制台，其他的则称为终端
-**********************************************************/
 #define CONSOLE  "/dev/console"	
 #define CONSOLE_NAMELEN 16
 #define CONSOLE_RD_BLOCK               1
@@ -93,21 +103,21 @@ typedef struct {
  * @brief 控制台控制块(描述符)
  */
 typedef struct {
-    UINT32 consoleID;	///< 控制台ID
+    UINT32 consoleID;	///< 控制台ID    例如 : 1 | 串口 , 2 | 远程登录
     UINT32 consoleType;	///< 控制台类型
     UINT32 consoleSem;	///< 控制台信号量
     UINT32 consoleMask;	///< 控制台掩码
     struct Vnode *devVnode;	///< 索引节点
-    CHAR *name;	///< 名称
-    INT32 fd;	///< 系统文件句柄
+    CHAR *name;	///< 名称 例如: /dev/console1 
+    INT32 fd;	///< 系统文件句柄, 鸿蒙将 3 分配给了控制台
     UINT32 refCount;	///< 引用次数
-    UINT32 shellEntryId; ///< shell 入口ID,一般为任务ID
+    UINT32 shellEntryId; ///<  负责接受来自终端信息的 "ShellEntry"任务,这个值在运行过程中可能会被换掉,它始终指向当前正在运行的shell客户端
     INT32 pgrpId;	///< 进程组ID
     BOOL isNonBlock; ///< 是否无锁方式		
 #ifdef LOSCFG_SHELL
     VOID *shellHandle;	///< shell句柄,本质是 shell控制块 ShellCB
 #endif
-    UINT32 sendTaskID;	///< 发送任务ID
+    UINT32 sendTaskID;	///< 创建任务通过事件接收数据, 见于OsConsoleBufInit
     /*--以下为 一家子 start---------*/
     CirBufSendCB *cirBufSendCB;	///< 循环缓冲发送控制块
     UINT8 fifo[CONSOLE_FIFO_SIZE]; ///< 控制台缓冲区大小 1K
@@ -115,7 +125,7 @@ typedef struct {
     UINT32 fifoIn;	///< 对fifo的标记,输入位置
     UINT32 currentLen;	///< 当前fifo位置
     /*---以上为 一家子 end------- https://man7.org/linux/man-pages/man3/tcflow.3.html */
-    struct termios consoleTermios; ///< vtermios 函数描述了一个通用的终端接口用于控制异步通信端口
+    struct termios consoleTermios; ///< 行规程
 } CONSOLE_CB;
 
 /**
@@ -155,15 +165,15 @@ extern VOID OsWakeConsoleSendTask(VOID);
 #endif
 extern VOID KillPgrp(UINT16 consoleId);
 
-/* console ioctl */
+/* console ioctl | 控制台常见控制操作*/
 #define CONSOLE_IOC_MAGIC   'c'
-#define CONSOLE_CMD_RD_BLOCK_SERIAL    _IO(CONSOLE_IOC_MAGIC, 1)
-#define CONSOLE_CMD_RD_BLOCK_TELNET    _IO(CONSOLE_IOC_MAGIC, 2)
-#define CONSOLE_CONTROL_RIGHTS_CAPTURE _IO(CONSOLE_IOC_MAGIC, 3)
+#define CONSOLE_CMD_RD_BLOCK_SERIAL    _IO(CONSOLE_IOC_MAGIC, 1) ///< 设置串口方式
+#define CONSOLE_CMD_RD_BLOCK_TELNET    _IO(CONSOLE_IOC_MAGIC, 2) ///< 设置远程登录方式
+#define CONSOLE_CONTROL_RIGHTS_CAPTURE _IO(CONSOLE_IOC_MAGIC, 3) ///< 
 #define CONSOLE_CONTROL_RIGHTS_RELEASE _IO(CONSOLE_IOC_MAGIC, 4)
 #define CONSOLE_CONTROL_CAPTURE_LINE   _IO(CONSOLE_IOC_MAGIC, 5)
 #define CONSOLE_CONTROL_CAPTURE_CHAR   _IO(CONSOLE_IOC_MAGIC, 6)
-#define CONSOLE_CONTROL_REG_USERTASK   _IO(CONSOLE_IOC_MAGIC, 7)
+#define CONSOLE_CONTROL_REG_USERTASK   _IO(CONSOLE_IOC_MAGIC, 7) ///< 注册用户任务 shell 客户端
 
 #endif
 

kernel/common/main.c

@@ -34,7 +34,7 @@
 
 /**
  * @brief 
- * 内核入口函数,由汇编调用,见于reset_vector_up.S 和 reset_vector_mp.S \n
+ * 内核入口函数,由汇编调用,见于reset_vector_up.S 和 reset_vector_mp.S 
  * up指单核CPU, mp指多核CPU bl        main
  * @return LITE_OS_SEC_TEXT_INIT 
  */

kernel/common/virtual_serial.h

@@ -46,7 +46,7 @@ extern "C" {
 
 #ifdef LOSCFG_FS_VFS //将设备虚拟为文件统一来操作,对鸿蒙来说一切皆为文件
 #define SERIAL         "/dev/serial"
-#define SERIAL_TTYGS0  "/dev/ttyGS0" 
+#define SERIAL_TTYGS0  "/dev/ttyGS0" //串口0 /dev/console映射到此
 #define SERIAL_UARTDEV "/dev/uartdev"
 
 #define SERIAL_TYPE_UART_DEV   1

kernel/include/los_list.h

+/*!
+ * @file    los_list.h
+ * @brief	双向链表由内联函数实现
+ * @link dll http://weharmonyos.com/openharmony/zh-cn/device-dev/kernel/kernel-small-apx-dll.html @endlink
+   @verbatim
+   基本概念
+	   双向链表是指含有往前和往后两个方向的链表，即每个结点中除存放下一个节点指针外，
+	   还增加一个指向前一个节点的指针。其头指针head是唯一确定的。
+   
+	   从双向链表中的任意一个结点开始，都可以很方便地访问它的前驱结点和后继结点，这种
+	   数据结构形式使得双向链表在查找时更加方便，特别是大量数据的遍历。由于双向链表
+	   具有对称性，能方便地完成各种插入、删除等操作，但需要注意前后方向的操作。
+   
+   双向链表的典型开发流程：
+	   调用LOS_ListInit/LOS_DL_LIST_HEAD初始双向链表。
+	   调用LOS_ListAdd/LOS_ListHeadInsert向链表头部插入节点。
+	   调用LOS_ListTailInsert向链表尾部插入节点。
+	   调用LOS_ListDelete删除指定节点。
+	   调用LOS_ListEmpty判断链表是否为空。
+	   调用LOS_ListDelInit删除指定节点并以此节点初始化链表。 
+   
+   注意事项
+	   需要注意节点指针前后方向的操作。
+	   链表操作接口，为底层接口，不对入参进行判空，需要使用者确保传参合法。
+	   如果链表节点的内存是动态申请的，删除节点时，要注意释放内存。
+   @endverbatim
+ * @version 
+ * @author  weharmonyos.com | 鸿蒙研究站 | 每天死磕一点点
+ * @date    2021-12-7
+ */
 /*
  * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved.
  * Copyright (c) 2020-2021 Huawei Device Co., Ltd. All rights reserved.
@@ -44,31 +74,6 @@
 extern "C" {
 #endif /* __cplusplus */
 #endif /* __cplusplus */
-/**
- * @brief 删除链:删除由装入点管理的文件
- * @verbatim 
-    基本概念
-        双向链表是指含有往前和往后两个方向的链表，即每个结点中除存放下一个节点指针外，
-        还增加一个指向前一个节点的指针。其头指针head是唯一确定的。
-
-        从双向链表中的任意一个结点开始，都可以很方便地访问它的前驱结点和后继结点，这种
-        数据结构形式使得双向链表在查找时更加方便，特别是大量数据的遍历。由于双向链表
-        具有对称性，能方便地完成各种插入、删除等操作，但需要注意前后方向的操作。
-
-    双向链表的典型开发流程：
-        调用LOS_ListInit/LOS_DL_LIST_HEAD初始双向链表。
-        调用LOS_ListAdd/LOS_ListHeadInsert向链表头部插入节点。
-        调用LOS_ListTailInsert向链表尾部插入节点。
-        调用LOS_ListDelete删除指定节点。
-        调用LOS_ListEmpty判断链表是否为空。
-        调用LOS_ListDelInit删除指定节点并以此节点初始化链表。 
-
-    注意事项
-        需要注意节点指针前后方向的操作。
-        链表操作接口，为底层接口，不对入参进行判空，需要使用者确保传参合法。
-        如果链表节点的内存是动态申请的，删除节点时，要注意释放内存。
- * @endverbatim
- */
 
 /**
  * @ingroup los_list

net/telnet/src/telnet_dev.c

@@ -382,7 +382,7 @@ INT32 TelnetDevInit(INT32 clientFd)
         PRINT_ERR("Invalid telnet clientFd.\n");
         return -1;
     }
-    ret = system_console_init(TELNET);
+    ret = system_console_init(TELNET);//创建虚拟设备
     if (ret != 0) {
         PRINT_ERR("Telnet console init error.\n");
         return ret;

shell/full/src/base/shmsg.c

@@ -465,12 +465,12 @@ LITE_OS_SEC_TEXT_MINOR UINT32 ShellEntryInit(ShellCB *shellCB)
     initParam.usTaskPrio   = 9; /* 9:shell task priority */
     initParam.auwArgs[0]   = (UINTPTR)shellCB;
     initParam.uwStackSize  = 0x1000;
-    initParam.pcName       = name;
+    initParam.pcName       = name;	//任务名称
     initParam.uwResved     = LOS_TASK_STATUS_DETACHED;
 
-    ret = LOS_TaskCreate(&shellCB->shellEntryHandle, &initParam);//创建任务
+    ret = LOS_TaskCreate(&shellCB->shellEntryHandle, &initParam);//创建shell任务
 #ifdef LOSCFG_PLATFORM_CONSOLE
-    (VOID)ConsoleTaskReg((INT32)shellCB->consoleID, shellCB->shellEntryHandle);//将任务注册到控制台
+    (VOID)ConsoleTaskReg((INT32)shellCB->consoleID, shellCB->shellEntryHandle);//将shell注册到控制台
 #endif
 
     return ret;

zzz/git/push.sh

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