/* ----------------------------------------------------------------------------
 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2020. All rights reserved.
 * Description: System Console HeadFile
 * Author: Huawei LiteOS Team
 * Create: 2013-01-01
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 1. Redistributions of source code must retain the above copyright notice, this list of
 * conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
 * of conditions and the following disclaimer in the documentation and/or other materials
 * provided with the distribution.
 * 3. Neither the name of the copyright holder nor the names of its contributors may be used
 * to endorse or promote products derived from this software without specific prior written
 * permission.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * --------------------------------------------------------------------------- */
//在LiteOS操作系统中，console头文件通常用于定义与控制台交互相关的函数和数据结构。
#ifndef _CONSOLE_H
#define _CONSOLE_H
//代码中，首先使用了条件编译防护，以确保头文件内容只被包含一次。接着定义了控制台输入输出缓冲区的大小，并声明了控制台初始化、打印和读取等函数。
#include "los_config.h"//引用了系统配置文件，用于获取操作系统的一些设置和属性。
#ifdef LOSCFG_FS_VFS//使用条件编译指令判断是否定义了宏LOSCFG_FS_VFS，如果已经定义，则编译下面的代码块，否则跳过。
#include "termios.h"//包含了 POSIX 终端控制定义的头文件，用于对终端进行控制。
#ifdef LOSCFG_NET_TELNET//使用条件编译指令判断是否定义了宏,如果已经定义，则编译下面的代码块，否则跳过。
#include "telnet_dev.h"//包含了 Telnet 设备驱动的头文件，用于实现 Telnet 连接。
#endif//结束条件编译指令。
#include "virtual_serial.h"//包含了虚拟串口的头文件，用于实现虚拟串口的功能。
#include "los_ringbuf.h"//包含了环形缓冲区的头文件，用于实现缓冲区的读写操作。
#endif

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif /* __cplusplus */
#endif /* __cplusplus */

#ifdef LOSCFG_KERNEL_CONSOLE

/* Define two fixed console id for Console ID. */
#define CONSOLE_SERIAL 1
#define CONSOLE_TELNET 2

#define STDIN  0
#define STDOUT 1
#define STDERR 2

#define CONSOLE  "/dev/console"
#define CONSOLE_NAMELEN 16
//这段代码定义了一些宏和常量，它们的含义如下：
#define CONSOLE_CMD_RD_BLOCK_SERIAL    0x104//表示从串口读取数据的阻塞命令，其值为0x104。
#define CONSOLE_CMD_RD_BLOCK_TELNET    101//表示从Telnet连接读取数据的阻塞命令，其值为101。
#define CONSOLE_RD_BLOCK               1//表示阻塞模式，其值为1。
#define CONSOLE_RD_NONBLOCK            0//表示非阻塞模式，其值为0。
#define CONSOLE_SHELL_KEY_EVENT        0x112//表示shell键盘事件，其值为0x112。
#define CONSOLE_SHELL_EXITED           0x400//表示shell已退出，其值为0x400。
#define CONSOLE_CONTROL_RIGHTS_CAPTURE 201//表示控制权被捕获，其值为201。
#define CONSOLE_CONTROL_RIGHTS_RELEASE 202//表示控制权被释放，其值为202。
#define CONSOLE_CONTROL_CAPTURE_LINE   203//表示捕获行命令，其值为203。
#define CONSOLE_CONTROL_CAPTURE_CHAR   204//表示捕获字符命令，其值为204。
#define CONSOLE_FIFO_SIZE              1024//表示控制台FIFO（First In First Out）缓冲区大小，其值为1024。
#define CONSOLE_NUM                    2//表示控制台数量，其值为2。

typedef struct {
    Ringbuf ringbuf;           /* Ring buffer *///表示环形缓冲区，它可能是一个用于缓存数据的循环队列或者环形链表。
    EVENT_CB_S sendEvent;   /* Inform telnet send task *///表示向telnet发送任务发送事件的回调函数。
} RingbufSendCB;

typedef struct {
    UINT32 consoleID;//表示控制台的ID。
    UINT32 consoleType;//表示控制台的类型。
    UINT32 consoleSem;//表示用于同步的控制台信号量。
    UINT32 shellEntryId;//表示shell的入口ID。
    UINT32 consoleMask;//表示控制台的掩码。
    struct inode *devInode;//表示设备节点。
    CHAR *name;//表示控制台的名称。
    INT32 fd;//表示文件描述符。
    UINT32 refCount;//表示引用计数。
    BOOL isNonBlock;//表示是否为非阻塞模式。
#ifdef LOSCFG_SHELL
    VOID *shellHandle;//表示shell的句柄。
#endif
    UINT32 sendTaskID;//表示发送任务的ID。
    RingbufSendCB *ringbufSendCB;//表示环形缓冲区发送回调。
    UINT8 fifo[CONSOLE_FIFO_SIZE];//表示控制台的FIFO缓冲区。
    UINT32 fifoOut;//表示FIFO缓冲区的输出位置。
    UINT32 fifoIn;//表示FIFO缓冲区的输入位置。
    UINT32 currentLen;//表示当前长度。
    struct termios consoleTermios;//表示控制台的终端属性。
} CONSOLE_CB;

extern INT32 system_console_init(const CHAR *deviceName);//控制台初始化函数用于初始化控制台相关的资源和状态
extern INT32 system_console_deinit(const CHAR *deviceName);//控制台反初始化函数，用于释放控制台相关的资源和状态。
extern BOOL SetSerialNonBlock(const CONSOLE_CB *consoleCB);//设置串口为非阻塞模式。
extern BOOL SetSerialBlock(const CONSOLE_CB *consoleCB);//设置串口为阻塞模式。
extern BOOL SetTelnetNonBlock(const CONSOLE_CB *consoleCB);//设置Telnet连接为非阻塞模式。
extern BOOL SetTelnetBlock(const CONSOLE_CB *consoleCB);//设置Telnet连接为阻塞模式。
extern CONSOLE_CB *OsGetConsoleByID(INT32 consoleId);//根据控制台ID获取控制台的控制块（Control Block）。
extern CONSOLE_CB *OsGetConsoleByTaskID(UINT32 taskId);//根据任务ID获取关联的控制台的控制块。
extern UINT32 ConsoleTaskReg(INT32 consoleId, UINT32 taskId);//将任务与指定的控制台进行关联。
extern INT32 ConsoleUpdateFd(VOID);//更新控制台的文件描述符（File Descriptor）。
extern BOOL ConsoleEnable(VOID);//使能控制台功能。
extern BOOL is_nonblock(const CONSOLE_CB *consoleCB);//判断控制台是否为非阻塞模式。
extern BOOL IsConsoleOccupied(const CONSOLE_CB *consoleCB);//判断控制台是否已经被占用。
extern INT32 FilepOpen(struct file *filep, const struct file_operations_vfs *fops);//打开文件。
extern INT32 FilepClose(struct file *filep, const struct file_operations_vfs *fops);//关闭文件。
extern INT32 FilepRead(struct file *filep, const struct file_operations_vfs *fops, CHAR *buffer, size_t bufLen);//从文件中读取数据。
extern INT32 FilepWrite(struct file *filep, const struct file_operations_vfs *fops, const CHAR *buffer, size_t bufLen);//向文件中写入数据。
extern INT32 FilepPoll(struct file *filep, const struct file_operations_vfs *fops, poll_table *fds);//对文件进行轮询操作。
extern INT32 FilepIoctl(struct file *filep, const struct file_operations_vfs *fops, INT32 cmd, unsigned long arg);//对文件进行IO控制操作。
extern INT32 GetFilepOps(const struct file *filep, struct file **privFilep, const struct file_operations_vfs **fops);//获取文件的操作函数。
#else
STATIC INLINE INT32 ConsoleUpdateFd(VOID)//这是一个函数声明，声明了一个名为ConsoleUpdateFd的静态内联函数，返回类型为INT32（32位整数），参数为空。根据函数体的实现为return -1;，该函数的作用是更新控制台的文件描述符（File Descriptor），并返回-1。
{
    return -1;
}
#endif//这个宏表示结束了之前的条件编译指令#if。

#ifdef __cplusplus//这一组条件编译指令用于判断是否为C++编译环境。如果是C++编译环境，则将后面的代码块用extern "C"包裹起来，以保证C和C++之间的函数调用规则一致。
#if __cplusplus
}
#endif /* __cplusplus */
#endif /* __cplusplus */

#endif /* _CONSOLE_H */