原始版本

RT_Thread/documentation/0.doxygen/INDEX.md

@@ -0,0 +1,116 @@
+@page page_howto_doxygen How to write doxygen documentation for RT-Thread
+
+RT-Thread Online Documentation is created based on doxygen and is available at: <https://rt-thread.github.io/rt-thread/>. It is consisted of two parts.
+
+One part is the detailed introduction of Kernel, which is written in markdown format and converted into HTML page by doxygen. It is displayed under "RT-Thread User Guide" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [subpage mechanism][2]. To define a page, we use `@page` command. The page name should be prefixed with a "page_", and the page name should be unique. Besides this, there are no special requirements for writing this part, so I will not go into details in this article.
+
+The other part is the description of API. RT-Thread uses [doxygen][1] to automate the generation of documentation from source code comments, parsing information about classes, functions, and variables to produce output in format of HTML. It is displayed under "Modules" in Treeview on the left side of the browser. Each sub-chapter is organized into a hierarchical structure by using doxygen's [topics mechanism][3]. The main content of this article is to describe how to write API with doxygen.
+
+# General Rules on writing API documentation
+
+@note The code comments and HTML content generated by doxygen in this guide, for the **structures**, **constants(macro definition)**, **enumeration values**, **union values**, **global functions**, **global variables** and other objects involved are all within the scope of the **RT-Thread kernel API**. The code of internal functions, variables (such as static functions etc.) are not belong to the API scope, how to write comment for these elements are not considered in this guide.
+
+By default, API documentation is written in header files, but there are exceptions, such as for **functions**.
+
+There are several ways to mark a comment block as a detailed description. We prefer JavaDoc-style (C-style) comment block with some additional markings to document the code, like this:
+
+```
+/**
+ * ... text ...
+ */
+```
+
+When you want to put documentation after members, we prefer a Qt style, like this:
+
+```
+int var; /**< Detailed description after the member */
+```
+
+When writing comments based on doxygen, several commands defined by doxygen are used. See <https://www.doxygen.nl/manual/commands.html> for more details about doxygen commands.
+
+More details refer to [Doxygen Docs: Documenting the code][4]
+
+# Detailed Rules on writing API documentation
+
+This article provide an <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/">example</a>. 
+
+Click @ref group_doxygen_example for the corresponding HTML documentation that is generated by Doxygen.
+
+The contents of Example are described in the following chapters:
+
+- @subpage page_howto_groups
+
+- @subpage page_howto_macro
+
+- @subpage page_howto_struct
+
+- @subpage page_howto_union
+
+- @subpage page_howto_enum
+
+- @subpage page_howto_typedef
+
+- @subpage page_howto_function
+
+# Build & Run
+
+## How to build & run doxygen html on Ubuntu
+
+The following steps are verified on Ubuntu 22.04：
+
+```shell
+$ lsb_release -a
+No LSB modules are available.
+Distributor ID:	Ubuntu
+Description:	Ubuntu 22.04.5 LTS
+Release:	22.04
+Codename:	jammy
+```
+
+The following packages (and dependents) need to be installed:
+
+```shell
+$ sudo apt update
+$ sudo apt install doxygen
+$ sudo apt install graphviz
+```
+
+Assume that the path of RT-Thead code tree is $RTT, execute the following command to build html.
+
+```shell
+$ cd $RTT/documentation
+$ rm -rf html
+$ doxygen
+```
+
+A new html directory will be created and all the html files will be placed in this directory.
+
+If you want to quickly browse HTML locally (in Ubuntu environment), you can enter the html directory and start a local HTML server through Python.
+
+```shell
+$ cd html
+$ python3 -m http.server
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+A bash script `run.sh` is provided to automatic upon operations.
+
+```shell
+$ cd $RTT/documentation
+$ ./run.sh
+```
+
+Then open the browser and enter `http://<IP>:8000/index.html` to access the created html web pages. If it is a local access, then `<IP>` should be replaced by `localhost`. If it is a remote access, then `<IP>` should be replaced by the actual accessible IP address of the machine where HTML is located.
+
+## How to build & run doxygen html with Doxywizard
+
+1. download from https://doxygen.nl/index.html
+2. open `Doxywizard`
+3. `File` -> `Open`
+4. Open the file ./Doxyfile 
+5.  To tab `Run` , Click `Run doxygen`
+
+[1]:https://www.doxygen.nl/
+[2]:https://www.doxygen.nl/manual/grouping.html#subpaging
+[3]:https://www.doxygen.nl/manual/grouping.html#topics
+[4]:https://www.doxygen.nl/manual/docblocks.html

RT_Thread/documentation/0.doxygen/basicdef.h

@@ -0,0 +1,14 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_BasicDef Basic Definitions
+ *
+ * @brief Basic data type in RT-Thread RTOS.
+ *
+ * These are the basic definitions which used in RT-Thread RTOS. In general,
+ * RT-Thread kernel uses its own definition of the basic data types, such as
+ * rt_uint32_t, rt_uint8_t, etc., which does not depend on the compiler or
+ * architecture.
+ */

RT_Thread/documentation/0.doxygen/doxygen.h

@@ -0,0 +1,9 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_doxygen_example Doxygen Example
+ *
+ * @brief Introduce how to write doxygen documentation.
+ */

RT_Thread/documentation/0.doxygen/example/include/enum.h

@@ -0,0 +1,37 @@
+#ifndef _DOXYGEN_EXAMPLE_ENUM_H_
+#define _DOXYGEN_EXAMPLE_ENUM_H_
+
+/**
+ * @page page_howto_enum How to write doxygen documentation for enumeration.
+ *
+ * A comment block before the enumeration definition is recommended to
+ * describe the general information of the enumeration type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * To describe the values of the enumeration, document is recommended
+ * to be put after each value.
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/enum.h">documentation/0.doxygen/example/include/enum.h</a>
+ * for example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description of this enumeration
+ */
+enum doxygen_example_enum
+{
+    V1, /**< description for value 1 */
+    V2, /**< description for value 2 */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_ENUM_H_ */

RT_Thread/documentation/0.doxygen/example/include/function.h

@@ -0,0 +1,7 @@
+#ifndef _DOXYGEN_EXAMPLE_FUNCTION_H_
+#define _DOXYGEN_EXAMPLE_FUNCTION_H_
+
+void doxygen_example_func_foo(int a, int b);
+int doxygen_example_func_bar(int a, int* b);
+
+#endif /* _DOXYGEN_EXAMPLE_FUNCTION_H_ */

RT_Thread/documentation/0.doxygen/example/include/groups.h

@@ -0,0 +1,74 @@
+#ifndef _DOXYGEN_EXAMPLE_GROUPS_H_
+#define _DOXYGEN_EXAMPLE_GROUPS_H_
+
+/**
+ * @page page_howto_groups How to use groups in doxygen documentation.
+ *
+ * Doxygen has three mechanisms to group things together. For RT-Thread
+ * API documentation, we use 'topics' to create new page for each group.
+ * On HTML browser, the topics pages are shown under the "Modules" in the
+ * treeview on the left.
+ *
+ * To define a group, we use `@defgroup` command. The group name should be
+ * prefixed with a "group_", and the group name should be unique. We can
+ * define a group anywhere, not necessarily in the same file as the members
+ * of the group. Generally, we define a group in a header file.
+ *
+ * To make an entity (structure, function etc. or another group) a member of
+ * a speicific group, we can use `@ingroup` command and put the `@ingroup`
+ * command inside its documentation block.
+ *
+ * To avoid putting `@ingroup` commands in the documentation for each member
+ * you can use `@addtogroup` and group members together by the open marker
+ * `@{` before the group and the closing marker `@}` after the group.
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/groups.h">documentation/0.doxygen/example/include/groups.h</a>
+ * for example.
+ *
+ * More information can be found in the Doxygen manual:
+ * <a href="https://www.doxygen.nl/manual/grouping.html">Grouping</a>.
+ */
+
+/**
+ * @defgroup group_doxygen_example_sub Sub Group of Doxygen Example
+ *
+ * All members of this group will be displayed in one HTML page.
+ *
+ * @ingroup group_doxygen_example
+ *
+ * @brief Define a sub group of Doxygen Example.
+ */
+
+/**
+ * @brief Brief description of this enumeration
+ *
+ * We use `@ingroup` to add this enum to the group_doxygen_example_sub separately.
+ *
+ * @ingroup group_doxygen_example_sub
+ */
+enum doxygen_example_enum_2
+{
+    V1, /**< description for value 1 */
+    V2, /**< description for value 2 */
+};
+
+// This entity is not a member of any group.
+#define DOXYGEN_EXAMPLE_CONST_E 300 /**< Description of macro const D */
+
+/**
+ * @addtogroup group_doxygen_example_sub
+ */
+
+/** @{ */
+
+/*
+ * DOXYGEN_EXAMPLE_CONST_C & DOXYGEN_EXAMPLE_CONST_D are close together, so
+ * we can use `@addtogroup`, `@{` and `@}` to group them together.
+ */
+#define DOXYGEN_EXAMPLE_CONST_C 100 /**< Description of macro const C */
+#define DOXYGEN_EXAMPLE_CONST_D 200 /**< Description of macro const D */
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_GROUPS_H_ */

RT_Thread/documentation/0.doxygen/example/include/macro.h

@@ -0,0 +1,44 @@
+#ifndef _DOXYGEN_EXAMPLE_MACRO_H_
+#define _DOXYGEN_EXAMPLE_MACRO_H_
+
+/**
+ * @page page_howto_macro How to write doxygen documentation for macro.
+ *
+ * There are two typical types of macro definitions.
+ *
+ * - One is to define constant macros. For this type of macro, we
+ *   recommend putting documentation after members. See `DOXYGEN_EXAMPLE_CONST_A`
+ *   and `DOXYGEN_EXAMPLE_CONST_B` in
+ *   <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/macro.h">documentation/0.doxygen/example/include/macro.h</a>
+ *   for exmaple.
+ *
+ * - The other is to define macros with parameters. For this type of
+ *   macro, we recommend using a method similar to documenting for
+ *   functions, that is, writing comment block before the macro definition.
+ *   More details please see @ref page_howto_function
+ *   See `DOXYGEN_EXAMPLE_ABS` in
+ *   <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/macro.h">documentation/0.doxygen/example/include/macro.h</a>
+ *   for example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+#define DOXYGEN_EXAMPLE_CONST_A 100 /**< Description of macro const A */
+#define DOXYGEN_EXAMPLE_CONST_B 200 /**< Description of macro const B */
+
+/**
+ * @brief Computes the absolute value of its argument @a x.
+ *
+ * @param[in] x input value.
+ *
+ * @return absolute value of @a x.
+ */
+#define DOXYGEN_EXAMPLE_ABS(x) (((x)>0)?(x):-(x))
+
+/** @} */
+
+#endif

RT_Thread/documentation/0.doxygen/example/include/struct.h

@@ -0,0 +1,78 @@
+#ifndef _DOXYGEN_EXAMPLE_STRUCT_H_
+#define _DOXYGEN_EXAMPLE_STRUCT_H_
+
+/**
+ * @page page_howto_struct How to write doxygen documentation for structure.
+ *
+ * We recommend the following approach:
+ *
+ * A comment block before the structure definition is recommended to
+ * describe the general information of the structure type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * If you feel that the description of `@brief` is not enough, you
+ * can add a detailed description part, which is also optional.
+ *
+ * Put member comments inside the structure definition and after every member.
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/struct.h">documentation/0.doxygen/example/include/struct.h</a>
+ * for example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description this structure
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+struct dogygen_example_struct
+{
+    int m1; /**< Some documentation for member 'm1'...
+             * Multiple lines ... Note the "multi-line" here refers
+             * to the code. Whether it is displayed in multiple lines
+             * on the specific HTML page depends on the browser rendering.
+             *
+             * @note We can also embed note for member 'm1'...
+             */
+    int m2; /**< Some documentation for member 'm2'... */
+    int m3; /**< Some documentation for member 'm3'... */
+    int m4; /**< Some documentation for member 'm4'... */
+    int m5; /**< Some documentation for member 'm5'... */
+};
+
+/**
+ * @brief Brief description this structure
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+struct dogygen_example_struct_another
+{
+    int m1; /**< Some documentation for member 'm1'...
+             * Multiple lines ... Note the "multi-line" here refers
+             * to the code. Whether it is displayed in multiple lines
+             * on the specific HTML page depends on the browser rendering.
+             *
+             * @note We can also embed note for member 'm1'...
+             */
+    int m2; /**< Some documentation for member 'm2'... */
+    int m3; /**< Some documentation for member 'm3'... */
+    int m4; /**< Some documentation for member 'm4'... */
+    int m5; /**< Some documentation for member 'm5'... */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_STRUCT_H_ */

RT_Thread/documentation/0.doxygen/example/include/typedef.h

@@ -0,0 +1,59 @@
+#ifndef _DOXYGEN_EXAMPLE_TYPEDEF_H_
+#define _DOXYGEN_EXAMPLE_TYPEDEF_H_
+
+/**
+ * @page page_howto_typedef How to write doxygen documentation for typedef.
+ *
+ * It is recommended to use separate typedef statements rather
+ * than a combination. That is:
+ *
+ * Recommended:
+ *
+ * ```c
+ * struct S { ... };
+ * typedef struct S S_t;
+ * ```
+ *
+ * Not recommended:
+ *
+ * ```c
+ * typedef struct S { ... } S_t;
+ * ```
+ *
+ * The reason is we found that the former is more readable, and when we
+ * write comment block with `@typedef`, the latter may
+ * cause unexpceted behaviour for doxygen (as of version 1.9.1).
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/typedef.h">documentation/0.doxygen/example/include/typedef.h</a>
+ * for example.
+ */
+
+#include "struct.h"
+#include "enum.h"
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @typedef dogygen_example_struct_t
+ * Alias of `struct dogygen_example_struct`.
+ *
+ * @typedef dogygen_example_struct_another_t
+ * Alias of `struct dogygen_example_struct_another`.
+ */
+typedef struct dogygen_example_struct dogygen_example_struct_t;
+typedef struct dogygen_example_struct_another dogygen_example_struct_another_t;
+
+/**
+ * @typedef doxygen_example_enum
+ * Alias of `enum doxygen_example_enum`.
+ */
+typedef enum doxygen_example_enum doxygen_example_enum_t;
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_TYPEDEF_H_ */

RT_Thread/documentation/0.doxygen/example/include/union.h

@@ -0,0 +1,37 @@
+#ifndef _DOXYGEN_EXAMPLE_UNION_H_
+#define _DOXYGEN_EXAMPLE_UNION_H_
+
+/**
+ * @page page_howto_union How to write doxygen documentation for union.
+ *
+ * A comment block before the union definition is recommended to
+ * describe the general information of the union type. In the
+ * comment block, a `@brief` is required, other commands (such as `@note`)
+ * are optional.
+ *
+ * To describe the values of the union, document is recommended
+ * to be put after each value.
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/union.h">documentation/0.doxygen/example/include/union.h</a>
+ * for example.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description of this union
+ */
+union doxygen_example_union
+{
+    int    v1; /**< description for v1 */
+    double v2; /**< description for v2 */
+};
+
+/** @} */
+
+#endif /* _DOXYGEN_EXAMPLE_UNION_H_ */

RT_Thread/documentation/0.doxygen/example/src/function.c

@@ -0,0 +1,95 @@
+/**
+ * @page page_howto_function How to write doxygen documentation for function.
+ *
+ * Function comments can be placed in the header file (before the
+ * function declaration) OR in the source file (before the function
+ * definition).
+ *
+ * The advantage of placing it in the header file is that we generally
+ * think that the header file is the place to declare the API, but the
+ * problem is that when a module has many API extern functions, if the
+ * comments are placed in the header file, the header file will be very
+ * long. You can imagine that for a module with many APIs and many
+ * comments, the header file will be full of large green comments, and
+ * the function declaration part is mixed in the middle and difficult
+ * to distinguish. And if you want to fully understand which extern
+ * functions this module exports, you need to scroll a long file for a
+ * long time to get a general idea. Especially for RTT, see `include/rtthread.h`
+ * as an example.
+ *
+ * Putting the comment in the source file can avoid the above problems.
+ * For developers, it is also convenient to read the comments together with
+ * the code implementation. The disadvantage is that it would be different
+ * from the function side, from other types, such as structures, i.e. the API
+ * comments of functions need to be read in the source file instead of directly
+ * in the header file.
+ *
+ * Comprehensive consideration can be combined with the actual situation.
+ * For example, if there are too many API functions in a header file, it is
+ * recommended to put the function comments in the source file.
+ *
+ * So, it is **strongly recommended** to put comments in the source file when
+ * writing new functions or annotating functions.
+ *
+ * To documenting for functions, a comment block before the function
+ * declaraion/definition is recommended to describe the general information
+ * of the function. In the comment block, a `@brief` is required, a `@return`
+ * is also required no matter if the function return values or not. `@param` is
+ * required if any, and if it is provided, direction [in]/[out]/[in,out] should
+ * be provide together. Other commands (such as `@note`) are optional.
+ *
+ * If you feel that the description of `@brief` is not enough, you
+ * can add a detailed description part, which is also optional.
+ *
+ * See
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/src/function.c">documentation/0.doxygen/example/src/function.c</a>
+ * for example.
+ *
+ * <a href="https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/src/function.h">documentation/0.doxygen/example/src/function.h</a> is an example of the header file where we just declare the API without doxygen documentation.
+ */
+
+/**
+ * @addtogroup group_doxygen_example
+ */
+
+/** @{ */
+
+/**
+ * @brief Brief description for the function
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @param[in] a Description of param a
+ *
+ * @param[in] b Description of param b
+ *
+ * @return void
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+void doxygen_example_func_foo(int a, int b)
+{
+    return;
+}
+
+/**
+ * @brief Brief description for the function
+ *
+ * Detailed description starts here, one line or multiple lines.
+ * Blah blah blah...
+ *
+ * @param[in] a Description of param a
+ *
+ * @param[out] b Description of param b
+ *
+ * @return the return value, 0 for success, -1 for failure
+ *
+ * @note This is a note for this structure, blah blah blah...
+ */
+int doxygen_example_func_bar(int a, int* b)
+{
+    return 0;
+}
+
+/** @} */

RT_Thread/documentation/0.doxygen/filesystem.h

@@ -0,0 +1,44 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_DFS Device Virtual File System
+ *
+ * @brief DFS is a virtual file system in RT-Thread RTOS.
+ *
+ * The DFS (Device Virtual File System) is a vfs file system of RT-Thread RTOS,
+ * which is focused on embedded device. VFS is an abstraction layer on top of a
+ * more concrete file system. The purpose of a VFS is to allow client applications
+ * to access different types of concrete file systems in a uniform way.
+ *
+ * @image html dfs.png "Figure 4: Device Virtual File System Architecture"
+ *
+ * The DFS specifies an interface between the kernel and a concrete file system.
+ * Therefore, it is easy to add support for new file system types to the kernel
+ * simply by fulfilling the interface.
+ */
+
+/**
+ * @addtogroup group_DFS
+ * @{
+ */
+
+/**
+ * @defgroup group_Fd File Descriptor
+ *
+ */
+
+/**
+ * @defgroup group_FsApi File System API
+ */
+
+/**
+ * @defgroup group_FileApi File API
+ */
+
+/**
+ * @defgroup group_FsPosixApi File POSIX API
+ */
+
+/**@}*/

RT_Thread/documentation/0.doxygen/finsh.h

@@ -0,0 +1,19 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_finsh finsh shell
+ *
+ * @brief finsh shell is a user command shell in RT-Thread RTOS.
+ *
+ * finsh shell is a user command shell in RT-Thread RTOS, which is a shell can
+ * accept C-expression like syntax in command. From finsh shell, user can access
+ * system area, such as memory, variables and function by input C-expression in
+ * command.
+ *
+ * @image html finsh.png "Figure 3: finsh shell architecture"
+ * There is a shell thread, which named as "tshell", in the finsh shell, it read
+ * user command from console device, and then invokes system function or access
+ * system variable to output result (by rt_kprintf).
+ */

RT_Thread/documentation/0.doxygen/hardware.h

@@ -0,0 +1,77 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_bsp Hardware Related Package
+ *
+ * @brief Hardware Related Package includes board support package(BSP) and CSP(Chip
+ * Support Package).
+ *
+ * Board Support Package(BSP) is the hardware related wrapper, for example, peripherals
+ * in board, the pinmux setting etc. In RT-Thread RTOS, the bsp is placed under bsp
+ * directory.
+ *
+ * Chip Support Package(CSP) is a software set that contains chip specific software.
+ * A CSP usually includes operating system porting and peripheral device drivers inside
+ * chip. In RT-Thread RTOS, the csp is placed under libcpu directory.
+ */
+
+/**
+ * @addtogroup group_bsp
+ * @{
+ */
+
+/**
+ * This function will return current system interrupt status and disable system
+ * interrupt.
+ *
+ * @return the current system interrupt status.
+ */
+rt_base_t rt_hw_interrupt_disable(void);
+
+/**
+ * This function will set the specified interrupt status, which shall saved by
+ * rt_hw_intterrupt_disable function. If the saved interrupt status is interrupt
+ * opened, this function will open system interrupt status.
+ *
+ * @param level the interrupt status to be set.
+ */
+void rt_hw_interrupt_enable(rt_base_t level);
+
+/**
+ * This function initializes interrupt.
+ */
+void rt_hw_interrupt_init(void);
+
+/**
+ * This function masks the specified interrupt.
+ *
+ * @param vector the interrupt number to be masked.
+ *
+ * @note not all of platform provide this function.
+ */
+void rt_hw_interrupt_mask(int vector);
+
+/**
+ * This function umasks the specified interrupt.
+ *
+ * @param vector the interrupt number to be unmasked.
+ *
+ * @note not all of platform provide this function.
+ */
+void rt_hw_interrupt_umask(int vector);
+
+/**
+ * This function will install specified interrupt handler.
+ *
+ * @param vector the interrupt number to be installed.
+ * @param new_handler the new interrupt handler.
+ * @param old_handler the old interrupt handler. This parameter can be RT_NULL.
+ *
+ * @note not all of platform provide this function.
+ */
+void rt_hw_interrupt_install(int vector, rt_isr_handler_t new_handler,
+                            rt_isr_handler_t *old_handler);
+
+/**@}*/

RT_Thread/documentation/0.doxygen/kernel.h

@@ -0,0 +1,169 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_Kernel RT-Thread Kernel API
+ *
+ * The Kernel APIs are the core APIs of RT-Thread, which supports the following
+ * features:
+ * - Multi-thread management
+ * - Synchronization mechanisms
+ * - Inter-thread communication
+ * - Memory management
+ * - Asynchronous timer
+ */
+
+/**
+ * @addtogroup group_Kernel
+ * @{
+ */
+
+/**
+ * @defgroup group_Thread Thread Management
+ * @brief the thread management
+ *
+ * RT-Thread operating system supports multitask systems, which are based on thread
+ * scheduling.
+ * - The scheduling is a full preemptive priority-based scheduling algorithm.
+ * - 8/32/256 priority levels are supported, in which 0 is the highest and 7/31/255 the lowest.
+ * The 7/31/255th priority is used for idle thread.
+ * - Threads running at same priority level are supported. The shared time-slice
+ * round-robin scheduling is used for this case.
+ * - The time of scheduler to choose the next highest ready thread is determinant.
+ * - There are four status in thread management
+ *  -# Initialization
+ *  -# Running/Ready
+ *  -# Blocked
+ *  -# Closed
+ * - The number of threads in the system is unlimited, only related with RAM.
+ */
+
+/**
+ * @defgroup group_Clock Clock and Timer Management
+ * @brief clock and system timer management
+ *
+ * RT-Thread uses clock tick to implement shared time-slice scheduling.
+ *
+ * The timing sensitivity of thread is implemented by timers. The timer can be set as
+ * one-shot or periodic timeout.
+ */
+
+/**
+ * @defgroup group_KernelObject Kernel Object Management
+ * @brief kernel object management
+ *
+ * The Kernel object system can access and manage all of the kernel objects.
+ *
+ * Kernel objects include most of the facilities in the kernel:
+ * - thread
+ * - semaphore and mutex
+ * - event/fast event, mailbox, messagequeue
+ * - memory pool
+ * - timer
+ * @image html Kernel_Object.png "Figure 2: Kernel Object"
+ * @image rtf  Kernel_Object.png "Figure 2: Kernel Object"
+ *
+ * Kernel objects can be static objects, whose memory is allocated in compiling.
+ * It can be dynamic objects as well, whose memory is allocated from system heaps
+ * in runtime.
+ */
+
+/**
+ * @defgroup group_IPC Inter-Thread Communication
+ * @brief inter-thread communication
+ *
+ * RT-Thread operating system supports the traditional semaphore and mutex.
+ * - Mutex objects use inherited priority to prevent priority reversion.
+ * - The semaphore release action is safe for interrupt service routine.
+ *
+ * Moreover, the blocked queue for thread to obtain semaphore or mutex can be sorted
+ * by priority or FIFO. There are two flags to indicate this mechanism.
+ * - RT_IPC_FLAG_FIFO
+ *   when the resource is available, thread pended on this resource at first would get
+ *   the resource.
+ * - RT_IPC_FLAG_PRIO
+ *   when the resource is available, thread pended on this resource who had the most high
+ *   priority would get the resource.
+ *
+ * RT-Thread operating systems supports event/fast event, mail box and message queue.
+ * - The event mechanism is used to awake a thread by setting one or more corresponding
+ * bit of a binary number when an event ocurs.
+ * - The fast event supports event thread queue. Once a one bit event occurs, the corresponding
+ * blocked thread can be found out timing accurately, then will be waked up.
+ * - In mailbox, the mail length is fixed to 4 byte, which is more effective than message queue.
+ * - The send action for communication facilities is also safe for interrupt service routine.
+ */
+
+/**
+ * @defgroup group_Signal Signal
+ * @brief signal is used for thread kill etc.
+ *
+ * A signal (also known as a soft interrupt signal), from a software perspective,
+ * is a simulation of interrupt mechanism. When it comes to its principle,
+ * thread receiving a signal is similar to processor receiving an interrupt request.
+ */
+
+/**
+ * @defgroup group_MM Memory Management
+ * @brief memory management for memory pool and heap memory
+ *
+ * RT-Thread operating system supports two types memory management:
+ * - Static memory pool management
+ * - Dynamic memory heap management.
+ *
+ * The time to allocate a memory block from the memory pool is determinant. When
+ * the memory pool is empty, the allocated thread can be blocked (or immediately return,
+ * or waiting for sometime to return, which are determined by a timeout parameter).
+ * When other thread releases memory blocks to this memory pool, the blocked thread is
+ * wake up.
+ *
+ * There are two methods in dynamic memory heap management, one is used for small memory,
+ * such as less than 1MB.  Another is a SLAB like memory management, which is suitable
+ * for large memory system. All of them has no real-time character.
+ */
+
+/**
+ * @defgroup group_Device Device System
+ * @brief device I/O subsystem
+ *
+ * The Device System is designed as simple and minimum layer to help communication between
+ * applications and drivers.
+ *
+ * The Device System provide five interfaces to driver:
+ * - open, open a device
+ * - close, close a device
+ * - read, read some data from a device
+ * - write, write some data to a device
+ * - control, send some control command to a device
+ */
+
+/**
+ * @defgroup group_Hook Runtime Trace and Record
+ * @brief the hook function set in runtime
+ *
+ * In order to trace and record RT-Thread activity in runtime, a hook mechanism
+ * is introduced.
+ *
+ * The hooks are a series of routines, which are invoked in some special checkpoints.
+ * The hook routines include:
+ * - object hook, invoked at object created, deleted, taken and put etc.
+ * - scheduler hook, invoked at thread switch and idle thread loop.
+ * - memory hook, invoked when allocate or free memory block.
+ * - timer hook, invoked when timer is timeout.
+ */
+
+/**
+ * @defgroup group_KernelService Other useful kernel service
+ * @brief other useful service in the kernel
+ */
+
+/**
+ * @defgroup group_Error Error Code
+ * @brief error code
+ *
+ * The error code is defined to identify which kind of error occurs. When some
+ * bad things happen, the current thread's errno will be set.
+ */
+
+/**@}*/

RT_Thread/documentation/0.doxygen/mainpage.h

@@ -0,0 +1,49 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @mainpage Introduction
+ * @author RT-Thread Development Team
+ * @version 1.2.0
+ *
+ * RT-Thread RTOS is an open source embedded real-time operating system and is
+ * designed specifically for small memory footprint platforms. The real-time and
+ * embedded characters are the most significant advantages of RT-Thread.
+ *
+ * - Real-Time Character
+ *
+ * RT-Thread has a real-time operating system kernel, with fully preempted
+ * multi-thread scheduler, inter-thread communication with timing sensitivity
+ * and transparent interrupt handling.
+ *
+ * - Embedded Character
+ *
+ * RT-Thread is suitable for embedded systems for small footprint characters.
+ * The kernel is implemented as a simple C library. The simplest application
+ * costs less than 1 Kbytes RAM on the ARM Cortex-M platform.
+ *
+ * @section kernel_arch RT-Thread Architecture
+ *
+ * RT-Thread system architecture is like:
+ * @image html System_Arch.png "Figure 1: RT-Thread Architecture"
+ *
+ * @section kernel_service Kernel API
+ *
+ * The Kernel APIs are the core APIs of RT-Thread, which supports the following
+ * features:
+ * - Multi-thread management and scheduler
+ * - Synchronization mechanisms, semaphore, recursive mutex and event set
+ * - Inter-thread communication, mailbox and message queue
+ * - Memory management, memory pool and dynamic heap memory management
+ * - Asynchronous timer
+ *
+ * For more details, please refer to @ref group_Kernel
+ *
+ * @section system_init System Initialization
+ *
+ * Once RT-Thread operating system starts up, the facility in system must be initialized
+ * firstly.
+ *
+ * For more details, please refer to @ref group_SystemInit
+ */

RT_Thread/documentation/0.doxygen/module.h

@@ -0,0 +1,14 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_Module Application Module
+ *
+ * @brief Application Module is a feature let user to execute application in RT-Thread RTOS.
+ *
+ * Application Module is implemented as dynamic object loader, but it can handle
+ * the dependences relationship between application and dynamic library, moreover,
+ * it also can handle the kernel object destroy and memory release issue when application
+ * (abnormally) exit.
+ */

RT_Thread/documentation/0.doxygen/systeminit.h

@@ -0,0 +1,63 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_SystemInit System Initialization
+ *
+ * @brief System initialization procedure.
+ *
+ * When RT-Thread operating system starts up, the basic operating system facility
+ * initialization routines must be invoked.
+ *
+ * The suggested initialization sequence is:
+ *
+ * - initialize device hardware
+ * rt_hw_board_init();
+ *
+ * User can put the low level hardware initialization in this function, such as
+ * DDR memory setting, pinmux setting, console device setting etc.
+ *
+ * - show version
+ * rt_show_version();
+ *
+ * - initialize timer system
+ * rt_system_timer_init();
+ *
+ * - initialize system heap memory
+ * rt_system_heap_init(__bss_end, __end_of_memory);
+ *
+ * - initialize module system
+ * rt_system_module_init();
+ *
+ * - initialize scheduler system
+ * rt_system_scheduler_init();
+ *
+ * - initialize application
+ * rt_application_init();
+ *
+ * - initialize system timer thread
+ * rt_system_timer_thread_init();
+ *
+ * - initialize idle thread
+ * rt_thread_idle_init();
+ *
+ * - start scheduler
+ * rt_system_scheduler_start();
+ */
+
+/**
+ * @ingroup group_SystemInit
+ *
+ * This function will initialize user application.
+ *
+ * This function will be invoked when system initialization and system scheduler
+ * has not started. User can allocate memory, create thread, semaphore etc. However,
+ * user shall not suspend 'current' thread.
+ */
+void rt_application_init();
+
+/**
+ * @ingroup group_SystemInit
+ */
+void rt_system_heap_init(void* begin_addr, void* end_addr);

RT_Thread/documentation/0.doxygen/thread.h

@@ -0,0 +1,89 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @addtogroup group_Thread
+ * @{
+ */
+
+/**
+ * @brief This function will handle IPI interrupt and do a scheduling in system.
+ *
+ * @param vector is the number of IPI interrupt for system scheduling.
+ *
+ * @param param is not used, and can be set to RT_NULL.
+ *
+ * @note this function should be invoke or register as ISR in BSP.
+ *
+ * @note this function is only implemented in scheduler_mp.c.
+ */
+void rt_scheduler_ipi_handler(int vector, void *param);
+
+/**
+ * @brief This function will perform one scheduling. It will select one thread
+ *        with the highest priority level in global ready queue or local ready queue,
+ *        then switch to it.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule(void);
+
+/**
+ * @brief This function checks whether a scheduling is needed after an IRQ context switching. If yes,
+ *        it will select one thread with the highest priority level, and then switch
+ *        to it.
+ *
+ * @param context is the context to be switched to.
+ *
+ * @note this function is only implemented in scheduler_mp.c.
+ */
+void rt_scheduler_do_irq_switch(void *context);
+
+/**
+ * @brief This function will insert a thread to the system ready queue. The state of
+ *        thread will be set as READY and the thread will be removed from suspend queue.
+ *
+ * @param thread is the thread to be inserted.
+ *
+ * @note  Please do not invoke this function in user application.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule_insert_thread(struct rt_thread *thread);
+
+/**
+ * @brief This function will remove a thread from system ready queue.
+ *
+ * @param thread is the thread to be removed.
+ *
+ * @note  Please do not invoke this function in user application.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule_remove_thread(struct rt_thread *thread);
+
+/**
+ * @brief This function will lock the thread scheduler.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_enter_critical(void);
+
+/**
+ * @brief This function will unlock the thread scheduler.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_exit_critical(void);
+
+/**
+ * @brief Get the scheduler lock level.
+ *
+ * @return the level of the scheduler lock. 0 means unlocked.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+rt_uint16_t rt_critical_level(void);
+
+/**@}*/

RT_Thread/documentation/1.introduction/introduction.md

@@ -0,0 +1,37 @@
+@page page_introduction Introduction
+
+As a beginner of Real-time Operating Systems (RTOS), you might be new to RT-Thread. However, with a better understanding of it over time, you will gradually discover the charm of RT-Thread and its advantages over other RTOSs of the same type. RT-Thread is an RTOS. With over 16 years of experience accumulated, along with the rise of the Internet of Things (IoT), it is evolving into a powerful, component-rich IoT operating system.  
+
+# RT-Thread Overview
+
+RT-Thread, short for Real Time-Thread, is an embedded real-time multi-threaded operating system. One of its main purposes is to support multi-tasking. Allowing multiple tasks to run simultaneously does not mean that the processor actually performs multiple tasks at the same time - a processor core can only run one task at a time. Every task is executed quickly, and through the task scheduler which determines the sequence according to priority, the tasks are switched rapidly, giving the illusion that multiple tasks are running at the same time. In the RT-Thread system, tasks are implemented by threads, and scheduled by the task scheduler.
+
+RT-Thread is mainly written in the C programming language, making it easy to understand and port. It applies object-oriented programming methods to real-time system design, making the code elegant, structured, modular, and very customizable. RT-Thread comes in a few varieties - the NANO version is a minimal kernel that requires only 3KB of flash and 1.2KB of RAM, which can be tailored with easy-to-use tools. For resource-rich IoT devices, RT-Thread can use an online software package management tool, together with system configuration tools, to achieve an intuitive and rapid modular design, while being able to seamlessly import rich software featurepacks. Through this, complex functions like Android's graphical interface, touch sliding effects, smart voice control and more can be easily created.
+
+Compared with the Linux operating system, RT-Thread is small in size, low in cost, low in power consumption and fast in startup. In addition, RT-Thread is highly responsible, with low resource usage, which is ideally suitable for various resource constraints such as cost, power consumption, etc. Although the 32-bit MCU is its main operating platform, other CPUs, such as ones with MMU, ones based on ARM9, ARM11 and even the Cortex-A series CPUs are suitable for RT-Thread in specific applications.
+
+# License Agreement
+
+The RT-Thread system is a completely open source system, which follows the Apache License 2.0 open source license agreement. The RT-Thread system can be used free of charge in commercial products and does not require opening private code up to the public.
+
+# RT-Thread Frame
+
+In recent years, the concept of the Internet of Things has become widely known, and the IoT market has developed rapidly. The networking of embedded devices is the trend of the times. Terminal networking has greatly increased the complexity of software, and traditional RTOS kernels can hardly meet the needs of the market. For this reason, the concept of the Internet of Things Operating System (IoT OS) came into being. **IoT operating system refers to the software platform that is based on operating system kernel (like RTOS, Linux, etc.) and includes relatively complete middleware components such as a file system, graphics library, etc. It has low overhead and high security, abides by the Communication Protocol and is capable of connecting to the cloud.** RT-Thread is an IoT OS. 
+
+One of the main differences between RT-Thread and many other RTOSs such as FreeRTOS and uC/OS is that it is not only a real-time kernel, but also has a rich middle-tier component, as shown in the following figure.
+
+![RT-Thread Software Framework](figures/02Software_framework_diagram.png)
+
+It includes: 
+
+- Kernel layer: RT-Thread kernel, the core part of RT-Thread, includes the implementation of objects in the kernel system, such as multi-threading and its scheduling, semaphore, mailbox, message queue, memory management, timer, etc.; libcpu/BSP (Chip Migration Related Files/Board Support Package) is closely related to hardware and consists of peripheral drivers and CPU transport. 
+- Components and Service Layer: Components are based on upper-level software on top of the RT-Thread kernel, such as virtual file systems, FinSH command-line interfaces, network frameworks, device frameworks, and more. Its modular design allows for high internal cohesion within the assembly and low coupling between components.
+- RT-Thread software package: A general-purpose software component running on the RT-Thread IoT operating system platform for different application areas, consisting of description information, source code or library files. RT-Thread provides an open package platform with officially available or developer-supplied packages that provide developers with a choice of reusable packages that are an important part of the RT-Thread ecosystem. The package ecosystem is critical to the choice of an operating system because these packages are highly reusable and modular, making it easy for application developers to build the system they want in the shortest amount of time.  RT-Thread supports more than 60 software packages, listed below: 
+
+1. Internet of Things related software packages: Paho MQTT, WebClient, mongoose, WebTerminal, etc.
+2. Scripting language related software packages: JerryScript and MicroPython are currently supported.
+3. Multimedia related software packages: Openmv, mupdf.
+4. Tools packages: CmBacktrace, EasyFlash, EasyLogger, SystemView.
+5. System related software packages: RTGUI, Persimmon UI, lwext4, partition, SQLite, etc.
+6. Peripheral library and driver software packages: RealTek RTL8710BN SDK.
+7. Others.

RT_Thread/documentation/2.quick-start/keil-installation/keil-installation.md

@@ -0,0 +1,36 @@
+@page page_quickstart_keil Keil MDK Installation
+
+Before running the RT-Thread operating system, we need to install MDK-ARM 5.24 (either official or evaluation version, version 5.14 and above), this version is also a relatively new version. This version can provide relatively complete debugging functions. Here, we are using evaluation version 5.24 of 16k compiled code limit. If you want to remove the 16k compiled code limit, please purchase the official MDK-ARM.
+
+Firstly, download the MDK-ARM evaluation version from the official website of www.keil.com:
+[http://www.keil.com/download/](http://www.keil.com/download/)
+
+When downloading, you need to fill in some basic information, please fill in the corresponding complete information, and then start downloading. After it is downloaded, double-click the mouse to start the installation, you will see the software installation as shown:
+
+![First Step](./figures/1.png)
+
+This is the MDK-ARM installation instructions, click “Next>>” to enter the next step, as shown.
+
+![Second Step](./figures/2.png)
+
+Click "√"  in the box next to "I agree to all the terms of the preceding License Agreement" and click "Next >>" to proceed to the next step of installation, as shown:
+
+![Third Step](./figures/3.png)
+
+Click "Browse..." to select the installation directory of MDK-ARM or directly input installation path in the "Destination Folder" box. Here, we default to "C:/Keil_v5", then click "Next>>" to proceed to the next step of installation, as shown:
+
+![Fourth Step](./figures/4.png)
+
+Input your name after "First Name", input your last name after "Last Name", input your company name after "Company Name", input your email address after "E-mail", and then click "Next>> " for the installation. Wait for a while for the installation to finish and you will see the following:
+
+![Fifth Step](./figures/12.png)
+
+The default selection does not need to be changed, just click “Next” to enter the next step as shown.
+
+![MDK-ARM Installment Complete](./figures/13.png)
+
+Here, you can click "Finish" to complete the installation of the entire MDK-ARM software.
+
+With a useful took like MDK-ARM, you can start the RT-Thread operating system easily and explore real-time operating systems.
+
+>Note: There is a charge for Official version of MDK-ARM. If you want to be able to compile larger binaries, please purchase the official version of MDK-ARM. RT-Thread operating system also supports GNU GCC compiler by Free Software Foundation which is an open source compiler. For more information on how to use GNU related tools, please refer to the related documentation on RT-Thread website.

RT_Thread/documentation/2.quick-start/quick-start.md

@@ -0,0 +1,150 @@
+@page page_quick_start Start Guide
+
+Because of its particularity, the embedded operating system is often closely related to the hardware platform, and specific embedded operating systems can only run on specific hardware. For those who might not have an RT-Thread compatible hardware module, or want to test out their ideas, a complete RT-Thread system can be developed in the simulation environment MDK-ARM.
+
+MDK-ARM (Microcontroller Development Kit - ARM) is a complete integrated development environment (IDE) from ARM. It includes an efficient C/C++ compiler for ARM chips (ARM7, ARM9, Cortex-M series, Cortex-R series, etc.), a project wizard and project management for various ARM devices and evaluation boards and a simulator for simulating hardware platforms in software. It supports debuggers connected to simulators debugging the target board, such as the commonly available ST-Link, J-Link, etc. The simulator software in MDK-ARM uses a complete software simulation to interpret and execute machine instructions from ARM and implement some peripheral logic to form a complete virtual hardware environment, enabling users to execute the corresponding target program on the computer without using a real hardware platform.
+
+Because of its full STM32F103 software simulation environment, the MDK-ARM integrated development environment gives us the opportunity to run object code directly on the computer without using a real hardware environment. This simulator platform can completely virtualize the various operating modes and peripherals of the ARM Cortex-M3, such as exceptions, interrupts, clock timers, serial ports, etc., which is almost identical to the real hardware environment. RT-Thread can run on both the simulated environment and on real hardware.
+
+What will follow is a demonstration of RT-Thread running on a simulated STM32F103 microcontroller through MDK-ARM.
+
+# Preparation
+
+MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is a relatively new version, which can provide relatively complete debugging functions. An installation guide can be found here: @subpage page_quickstart_keil.
+
+# First acquaintance with RT-Thread
+
+To see the code size of RT-Thread we first need to get an example of RT-Thread that is suited for this environment, which can be obtained from the following link:
+
+[RT-Thread Simulator Sample](./rtthread_simulator_v0.1.0.zip)
+
+This example is a zip file, unzip it. The directory structure after decompression is as shown below:
+
+![rtthread_simulator_v0.1.0 Code Directory ](./figures/7.png)
+
+Descriptions of the file types contained in each directory are shown in the following table:
+
+Directory Name      | Description
+---         |   ---
+applications| RT-Thread application.
+rt-thread   | Source file for RT-Thread.
+- components| Respective component directories of RT-Thread.
+- include   | Header file for RT-Thread kernel.
+- libcpu    | Porting code for various types of chips, including porting files of STM32.
+- src       | Source file for RT-Thread kernel.
+- tools     | Script file of RT-Thread commanding building tool.
+drivers     | Driver of RT-Thread, implementations of bottom driver of different platforms.
+Libraries   | ST's STM32 firmware library file.
+kernel-sample-0.1.0    | Kernel sample for RT-Thread.
+
+In the directory, there is a file with the name "project.uvprojx", which is an MDK5 project file in the sample referenced in this manual. Double-click "project.uvprojx" icon to open the project file:
+
+![Open the project](./figures/5.png)
+
+Under the "Project" column on the left side of the main window of the project, you can see the file list of the project. These files are stored in the following groups, respectively:
+
+| Directory Group | Description                                                  |
+| :-------------- | ------------------------------------------------------------ |
+| Applications    | The corresponding directory is rtthread_simulator_v0.1.0/applications, used to store user application code. |
+| Drivers         | The corresponding directory is rtthread_simulator_v0.1.0/drivers, used to store the bottom driver code for RT-Thread. |
+| STM32_HAL       | The corresponding directory is rtthread_simulator_v0.1.0/Libraries/CMSIS/Device/ST/STM32F1xx, used to store the firmware library files of STM32. |
+| kernel-sample   | The corresponding directory is rtthread_simulator_v0.1.0/kernel-sample-0.1.0, used to store kernel samples of RT-Thread. |
+| Kernel          | The corresponding directory is rtthread_simulator_v0.1.0/src, used to store RT-Thread kernel core code. |
+| CORTEX-M3       | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/libcpu, used to store ARM Cortex-M3 porting code. |
+| DeviceDrivers   | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/drivers, used to store driver framework source code of RT-Thread. |
+| finsh           | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/finsh, used to store command line of RT-Thread finsh command line component. |
+
+Now click the button from the toolbar on the top the window, ![img](./figures/compile.jpg), to compile the project as shown:
+
+![compiling](./figures/9.png)
+
+The result of the compilation is displayed in the "Build Output" bar at the bottom of the window. If nothing else, it will say "0 Error(s), * Warning(s)." on the last line, that is, there are no errors or warnings.
+
+After compiling RT-Thread/STM32, we can simulate running RT-Thread through the MDK-ARM simulator. Click ![img](./figures/debug.jpg) at the top right of the window or directly hit Ctrl+F5 to enter the simulation interface and hit F5 to start, then click the button in the toolbar shown in the screen shot or select “View→Serial Windows→UART#1” in the menu bar to open the serial port 1 window. You can see that the output of the serial port only shows the logo of RT-Thread. This is because the user code is empty and the result of its simulation is as shown:
+
+![simulate RT-Thread1](./figures/10.png)
+
+>We can output all the commands supported by the current system by inputting the Tab key or `help + enter` , as shown in the following figure.
+
+![simulate RT-Thread2](./figures/6.png)
+
+
+# User Entry Code
+
+The above startup code is related to the RT-Thread system, so how do users add initialization code for their own applications? RT-Thread uses main function as the user code entry, all you need to do is just add your own code to the main function.
+
+```c
+int main(void)
+{
+  /* user app entry */
+  return 0;
+}
+```
+
+>Note: In order to complete the initialization for the system functions before entering the main program, you can use the `$sub$$` and `$super$$` function identifiers to call another sample before entering the main program, this was, users can ignore the initialization operations before the main() function. See [ARM® Compiler v5.06 for µVision® armlink User Guide](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0377g/pge1362065967698.html) for details.
+
+# Example of a Marquee
+
+For technical engineers working on electronics, marquee is probably the simplest example, the equivalent of Hello World in every programming language programmers learn. So we will start with a marquee in the following example, to make it periodically update (turn on or off) the LED.
+
+Under UART#1, input msh command: led and then click Enter to run it, as shown:
+
+![run led](./figures/11.png)
+
+**Example of a Marquee**
+
+```c
+/*
+ * Manifest of programs: Marquee sample
+ *
+ * marquee is probably the simplest example, it is like the first program
+ * Hello World in every programming language that programmers learned. So we will start with a marquee in the following example, start a thread to make it periodically
+ * update (turn on or off) the LED.
+ */
+
+int led(void)
+{
+    rt_uint8_t count;
+
+    rt_pin_mode(LED_PIN, PIN_MODE_OUTPUT);
+
+    for(count = 0 ; count < 10 ;count++)
+    {
+        rt_pin_write(LED_PIN, PIN_HIGH);
+        rt_kprintf("led on, count : %d\r\n", count);
+        rt_thread_mdelay(500);
+
+        rt_pin_write(LED_PIN, PIN_LOW);
+        rt_kprintf("led off\r\n");
+        rt_thread_mdelay(500);
+    }
+    return 0;
+}
+MSH_CMD_EXPORT(led, RT-Thread first led sample);
+```
+
+# Other Examples
+
+Additional kernel examples can be found in the kernel-sample-0.1.0 directory.
+
+![more kernel samples](./figures/14.png)
+
+# Frequently Asked Question
+
+* Compilation error occurred as following:
+
+```
+rt-thread\src\kservice.c(823): error: #929: incorrect use of vaarg fieldwidth = aarg(args, int);
+rt-thread\src\kservice.c(842): error: #929: incorrect use of vaarg precision = aarg(args, int);
+………
+```
+
+Cause: This type of problem is usually caused by installation of ADS, when ADS and keil coexist, the header file of va_start points to the ADS folder.
+
+Solution:
+
+- Delete ADS environment variables
+- Uninstall ADS and Keil, restart the computer, reload Keil
+
+
+

RT_Thread/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_linux.md

@@ -0,0 +1,203 @@
+# Getting Started of QEMU (Ubuntu)
+
+The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board.
+
+## 1 Install dependency libraries
+
+We need to type commands as following in the terminal:
+
+```shell
+sudo apt install gcc
+sudo apt install python3
+sudo apt install python3-pip
+sudo apt install gcc-arm-none-eabi
+sudo apt install gdb-arm-none-eabi
+sudo apt install binutils-arm-none-eabi
+sudo apt install scons
+sudo apt install libncurses5-dev
+sudo apt install qemu
+sudo apt install qemu-system-arm
+sudo apt install git
+```
+
+## 2 Get RT-Thread source code
+
+Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git`
+
+You can directly ignore the following steps, this is used for setting GCC compiler manually. Usually, you don't need to set this.
+
+> - Install the compiler. If the compiler version installed with `apt-get` command is too old, it will cause compilation errors. You can download and install the new version using the following command in turn. The download link and the decompression folder name will vary according to the download version. The following Compression Packet will unzip to the `/opt` folder.
+>
+>   - `wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-rm/6-2016q4/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2`
+>   - `cd /opt`
+>   - `sudo tar xf ~/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2`
+>
+>
+> - After the compiler is installed, it is necessary to modify the `rtconfig.py` file under `rt-thread/bsp/qemu-vexpress-a9` BSP, modify the corresponding path to the bin directory corresponding to the compiler decompressed into the opt directory. Referring to the following figure, the directory name varies according to the downloaded version of the compiler:
+>
+> ![edit EXEC_PATH in rtconfig.py](figures/ubuntu-rtconfig-py.png)
+>
+
+
+
+## 3 Build QEMU Project
+
+### 3.1 Move into QEMU folder
+
+```
+cd rt-thread/bsp/qemu-vexpress-a9/
+```
+
+### 3.2 Configure the environment of Env tool
+
+#### 3.2.1 Remap python command
+
+We need to remap `python` command as python3 by default.
+
+Using `whereis` command to identify your python3's version:
+
+![python3-version](figures/python3-version.png)
+
+For instance, as you can see, in my computer, the python3's version is python 3.9. You need to identify python3's version in your computer. Then, we remap the `python` command as python3 by default:
+
+```shell
+sudo rm -rf /usr/bin/python3
+sudo rm -rf /usr/bin/python
+sudo ln -s /usr/bin/python3.9 /usr/bin/python3
+sudo ln -s /usr/bin/python3.9 /usr/bin/python
+```
+
+### 3.3 Install Env and Configure BSP
+
+Type following the command under  `bsp/qemu-vexpress-a9` folder:
+
+```
+scons --menuconfig
+```
+
+The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP:
+
+![install env tool](figures/ubuntu-menuconfig.png)
+
+![enter the configuration interface](figures/ubuntu-env-menu.png)
+
+You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and press `Esc Esc` to exit the current directory.
+
+> Notice: Please make sure that the terminal size is larger than 80x24 character size.
+
+### 3.4 Configure the QEMU BSP and acquisition of software packages
+
+```
+source ~/.env/env.sh
+scons --menuconfig
+pkgs --update
+```
+
+The `env.sh` file is a file that needs to be executed. It configures the environment variables so that we can update the package with the pkgs command and execute it with the `source ~/.env/env.sh` command.
+
+Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages by this time.
+
+![commands of acquisition of pkgs](figures/ubuntu-pkg-menuconfig.png)
+
+![add pkg menu](figures/ubuntu-pkgs-add-to-menu.png)
+
+For example, select the kernel sample package: semphore sample.
+
+![select a package](figures/ubuntu-select-pkg.png)
+
+Exit and save the configuration.
+
+![save the configuration](figures/ubuntu-save.png)
+
+If you have selected an online package, you can download the package to the packages folder in the BSP directory using the `pkgs --update` command (Git needs to be installed):
+
+![download the package](figures/ubuntu-update-pkg.png)
+
+#### 4.1 Tips
+
+Before you use the `pkgs` command, you need to type command `source ~/.env/env.sh`. This is a annoying work. We can attach this command as a new line at the end of `~/.bashrc`, which can let you to to use `pkgs` command directly.
+
+### 3.5 Compile the QEMU project
+
+```
+scons
+```
+
+Using the `scons` command to compile the BSP.
+
+![compile the BSP](figures/ubuntu-scons.png)
+
+## 4 Introduction of QEMU BSP Catalogue
+
+The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the `bsp` directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
+
+![qemu-vexpress-a9 folder](figures/ubuntu-qemu-bsp.png)
+
+The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
+
+| Fles/Directories | Description                                 |
+| ---------------- | ------------------------------------------- |
+| applications     | User application code directory             |
+| drivers          | The underlying driver provided by RT-Thread |
+| qemu.bat         | Script files running on Windows platform    |
+| qemu.sh          | Script files running on Linux platform      |
+| qemu-dbg.bat     | Debugging script files on Windows platform  |
+| qemu-dbg.sh      | Debugging script files on Linux platform    |
+| README.md        | Description document of BSP                 |
+| rtconfig.h       | A header file of BSP                        |
+
+## 5 Compile and Run
+
+### 5.1 Use the *scons* Command to Compile the Project
+
+Switch to the QEMU BSP directory and enter the `scons` command to compile the project. If the compilation is correct, the `rtthread.elf`  file will be generated in the BSP directory, which is a target file required for QEMU to run.
+
+![compile the project](figures/ubuntu-scons.png)
+
+### 5.2 Use the *./qemu.sh* Command to Run the Project 
+
+After compiling, type `./qemu.sh` to start the virtual machine and BSP project. `qemu.sh` is a Linux batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
+
+![run the project](figures/ubuntu-qume-sh.png)
+
+### 5.3 Run the Finsh Console
+
+RT-Thread supports Finsh, and users can use command operations in command line mode.
+
+Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
+
+![view all supported commands](figures/ubuntu-msh-help.png)
+
+For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
+
+![threads and timers](figures/ubuntu-thread-timer.png)
+
+### 5.4 Run the File System
+
+Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
+
+> For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
+
+![format the SD card](figures/ubuntu-mkfs-sd0.png)
+
+The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `./qemu.sh` on the command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
+
+![commands of file system](figures/ubuntu-filesys.png)
+
+- ls: Display the file and directory information
+- cd: Switch to the specified directory
+- rm: Delete files or directories
+- echo: Writes the specified content to the target file
+- cat: Displays the details of a file
+- mkdir: Create folders
+
+Please enter `help` to see more commands.
+
+## 6 More Functions
+
+You can configure more functions in the menuconfig's configuration interface. use `scons --menuconfig` to config the BSP. After the configuration is completed, save the configuration first, and then exit the configuration interface, then:
+
+1. If you choose a package, you need to use the command `pkgs --update` to download the package.
+2. Compile with `scons`.
+3. Then enter `./qemu.sh` to run QEMU.
+4. Use `help` to view all commands of the BSP. And then use the commands.

RT_Thread/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_macos.md

@@ -0,0 +1,181 @@
+# Getting Started of QEMU (macOS)
+
+The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board. This document details the steps to run RT-Thread with QEMU on a macOS machine with an Intel processor.
+
+## 1 Install dependency libraries
+
+### 1.1 Install Python and SCons
+
+Download the latest Python installer from the [official Python website](https://www.python.org/downloads/). Click on the installer and follow the steps to install.
+
+Then install SCons with
+
+```shell
+python3 -m pip install scons
+```
+
+### 1.2 Use Homebrew to install QEMU
+
+First install Homebrew with
+
+```shell
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Then use Homebrew to install QEMU
+
+```shell
+brew install qemu
+```
+
+### 1.3 Install compiler toolchain
+
+Download the latest ARM GNU toolchain from [armDeveloper website](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads). Download the `.tar.xz` file under macOS (x86_64) hosted cross toolchains, AArch32 bare-metal target (arm-none-eabi)
+
+![gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi.tar.xz](figures/gnu-arm.png)
+
+Move the file to an appropriate location. The following steps assume the file is moved to the home directory
+
+Decompress the file
+
+```shell
+tar xf ~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi.tar.xz
+```
+
+Add the following line to `~/.bash_profile`
+
+```shell
+export PATH="$PATH:~/gcc-arm-11.2-2022.02-darwin-x86_64-arm-none-eabi/bin"
+```
+
+Run the following command. This is only needed once after `~/.bash_profile` is modified
+
+```shell
+source ~/.bash_profile
+```
+
+Check the installed tools can be detected
+
+```
+$ arm-none-eabi-gcc --version
+arm-none-eabi-gcc (GNU Toolchain for the Arm Architecture 11.2-2022.02 (arm-11.14)) 11.2.1 20220111
+Copyright (C) 2021 Free Software Foundation, Inc.
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+```
+
+## 2 Get RT-Thread source code
+
+Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git`
+
+## 3 Build QEMU Project
+
+### 3.1 Move into QEMU folder
+
+```
+cd rt-thread/bsp/qemu-vexpress-a9/
+```
+
+### 3.2 Install Env and Configure BSP
+
+Type following the command under  `bsp/qemu-vexpress-a9` folder:
+
+```
+scons --menuconfig
+```
+
+The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP:
+
+![enter the configuration interface](figures/macos-env-menu.png)
+
+You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and press `Esc Esc` to exit the current directory.
+
+### 3.3 Acquire software packages
+
+```
+source ~/.env/env.sh
+scons --menuconfig
+pkgs --update
+```
+
+The `env.sh` file  configures the environment variables so that you can update the package with the `pkgs` command. You need to run `source ~/.env/env.sh` every time before you use the `pkgs` command in a new terminal. To avoid doing this you can add this command to the end of `~/.bash_profile`, which can let you to use `pkgs` command directly.
+
+Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages at this time.
+
+![add pkg menu](figures/macos-pkgs-add-to-menu.png)
+
+For example, select the system packages, POSIX extension functions, xxtension string functions `<strings.h>`
+
+![select a package](figures/macos-select-pkg.png)
+
+Exit and save the configuration.
+
+![save the configuration](figures/macos-save.png)
+
+If you have selected an online package, you can download the package to the packages folder in the BSP directory using the `pkgs --update` command (Git needs to be installed):
+
+![download the package](figures/macos-update-pkg.png)
+
+### 3.4 Compile the QEMU project
+
+Run the `scons` command to compile the BSP. If the compilation is successful, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run.
+
+## 4 Introduction of QEMU BSP Catalogue
+
+The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the `bsp` directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
+
+![qemu-vexpress-a9 folder](figures/macos-qemu-bsp.png)
+
+The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
+
+| Fles/Directories | Description                                 |
+| ---------------- | ------------------------------------------- |
+| applications     | User application code directory             |
+| drivers          | The underlying driver provided by RT-Thread |
+| qemu.bat         | Script files running on Windows platform    |
+| qemu.sh          | Script files running on Linux platform      |
+| qemu-dbg.bat     | Debugging script files on Windows platform  |
+| qemu-dbg.sh      | Debugging script files on Linux platform    |
+| README.md        | Description document of BSP                 |
+| rtconfig.h       | A header file of BSP                        |
+
+## 5 Run the QEMU project
+
+### 5.1 Use the *./qemu.sh* Command to Run the Project 
+
+After compiling, type `./qemu.sh` to start the virtual machine and BSP project. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
+
+![run the project](figures/macos-qemu-sh.png)
+
+### 5.2 Run the Finsh Console
+
+RT-Thread supports Finsh, and users can use command operations in command line mode.
+
+Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
+
+![view all supported commands](figures/macos-msh-help.png)
+
+For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
+
+![threads and timers](figures/macos-thread-timer.png)
+
+### 5.3 Run the File System
+
+Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
+
+> For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
+
+![format the SD card](figures/macos-mkfs-sd0.png)
+
+The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `./qemu_nographic.sh` on the command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
+
+![commands of file system](figures/macos-filesys.png)
+
+- ls: Display the file and directory information
+- cd: Switch to the specified directory
+- rm: Delete files or directories
+- echo: Writes the specified content to the target file
+- cat: Displays the details of a file
+- mkdir: Create folders
+
+Please enter `help` to see more commands.

RT_Thread/documentation/2.quick-start/quick_start_qemu/quick_start_qemu_windows.md

@@ -0,0 +1,117 @@
+# Getting Started of QEMU (Windows)
+
+The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board.
+
+## Preparations
+
+- [Download RT-Thread source code](https://github.com/RT-Thread/rt-thread)
+- [Download annd install Env tool](../../env/env.md)
+
+
+## Introduction of QEMU BSP Catalogue
+
+The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `bsp/qemu-vexpress-a9` folder under the BSP directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure.
+
+![qemu-vexpress-a9 folder](figures/qemubsp.png)
+
+The main files and directories of `qemu-vexpress-a9` BSP are described as follows:
+
+| Fles/Directories | Description                                 |
+| ---------------- | ------------------------------------------- |
+| .vscode          | configuration file of vscode                |
+| applications     | User application code directory             |
+| drivers          | The underlying driver provided by RT-Thread |
+| qemu.bat         | Script files running on Windows platform    |
+| qemu.sh          | Script files running on Linux platform      |
+| qemu-dbg.bat     | Debugging script files on Windows platform  |
+| qemu-dbg.sh      | Debugging script files on Linux platform    |
+| README.md        | Description document of BSP                 |
+| rtconfig.h       | A header file of BSP                        |
+
+## Compile and Run
+
+### Configuration
+
+Type the `menuconfig` command in the Env terminal to enter the configuration interface, and then configure the BSP:
+
+![menuconfig command](figures/win-menuconfig.png)
+
+![enter the configuration interface](figures/env_menu.png)
+
+You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and use the `Esc` key to exit the current directory.
+
+### Acquisition of software packages
+
+If a package is selected in menuconfig, download the package using the `pkgs --update` command. 
+
+The alternative and recommended way is by using `menuconfig -s` to select the `Auto update pkgs config` feature, so that when users exit the menuconfig, Env will automatically download and update software packages.
+
+### Compile
+
+Compile using the `scons` command, or `scons -j12` means 12 CPU cores compiling.
+
+#### Step 1. Use the *scons* Command to Compile the Project
+
+Open the Env folder and double-click the `env.exe` file to open the Env console:
+
+![Env folder](figures/env.png)
+
+Switch to the QEMU BSP directory and enter the `scons` or `scons -j12` command to compile the project. If the compilation is correct, the `rtthread.elf`  file will be generated in the BSP directory, which is a target file required for QEMU to run.
+
+![compile the project](figures/scons.png)
+
+#### Step 2. Use the *qemu.bat* Command to Run the Project
+
+After compiling, type `qemu.bat` to start the virtual machine and BSP project. `qemu.bat` is a Windows batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture:
+
+![run the project](figures/qemu.bat.png)
+
+![QEMU virtual machine](figures/qemu.png)
+
+### Run the Finsh Console
+
+RT-Thread supports Finsh, and users can use command operations in command line mode.
+
+Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right.
+
+![view all supported commands](figures/finsh-cmd.png)
+
+For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers.
+
+![threads and timers](figures/finsh-thread.png)
+
+### Run the File System
+
+Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability.
+
+For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html)
+
+![format the SD card ](figures/mkfs-sd0.png)
+
+The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `qemu.bat` on the Env command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread:
+
+![commands of file system](figures/echo-cat.png)
+
+- ls: Display file and directory information
+- cd: Switch to the specified directory
+- rm: Delete files or directories
+- echo: Writes the specified content to the target file
+- cat: Displays the details of a file
+- mkdir: Create folders
+
+Please enter `help` to see more commands.
+
+## More Functions
+
+Open the Env tool in the BSP directory and enter the `menuconfig` command:
+
+![menuconfig](figures/menuconfig.png)
+
+You can configure more functions in the configuration interface. After the configuration is completed, save the configuration first, and then exit the configuration interface:
+
+![menuconfig interface](figures/menuconfig_menu.png)
+
+1. If you choose a package, you need to use the command `pkgs --update` to download the package.
+2. Compile with `scons` or `scons -j12`.
+3. Then enter `qemu.bat` to run.
+4. Use `help` to view all commands of the BSP. And then use the commands.

RT_Thread/documentation/3.kernel/INDEX.md

@@ -0,0 +1,10 @@
+@page page_kernel Kenrel
+
+- @subpage page_kernel_basics
+- @subpage page_thread_management
+- @subpage page_clock_management
+- @subpage page_thread_sync
+- @subpage page_thread_comm
+- @subpage page_memory_management
+- @subpage page_interrupt_management
+- @subpage page_kernel_porting

RT_Thread/documentation/4.tool/INDEX.md

@@ -0,0 +1,5 @@
+@page page_tool Tool
+
+- @subpage page_env
+
+- @subpage page_scons

RT_Thread/documentation/5.device/INDEX.md

@@ -0,0 +1,14 @@
+@page page_device Device
+
+- @subpage page_device_framework
+- @subpage page_device_pin
+- @subpage page_device_uart
+- @subpage page_device_adc
+- @subpage page_device_i2c
+- @subpage page_device_spi
+- @subpage page_device_pwm
+- @subpage page_device_rtc
+- @subpage page_device_hwtimer
+- @subpage page_device_watchdog
+- @subpage page_device_wlan
+- @subpage page_device_sensor

RT_Thread/documentation/6.components/INDEX.md

@@ -0,0 +1,12 @@
+@page page_components Components
+
+- @subpage page_component_finsh
+- @subpage page_component_vfs
+- @subpage page_component_utest
+- @subpage page_component_dlmodule
+- @subpage page_component_sal
+- @subpage page_component_at
+- @subpage page_component_posix
+- @subpage page_component_ulog
+- @subpage page_component_pm
+- @subpage page_component_network

RT_Thread/documentation/7.contribution/INDEX.md

@@ -0,0 +1,11 @@
+@page page_code_contribution Contribution
+
+# Contribution Guide
+
+We sincerely thank you for your contribution, and welcome to submit the code through GitHub's fork and Pull Request processes. RT-Thread 3.1.0 version and its earlier versions follow the GPL V2 open source license agreement. Versions from the 3.1.0 version onwards follow the Apache License 2.0 open source license agreement.
+
+All the real-time operating system kernel and open source components can be used free of charge for commercial products, there is no potential commercial risk and you will not being request to publish application source.
+
+@subpage page_rtt_code_style_en
+
+@subpage page_howto_doxygen

RT_Thread/documentation/INDEX.md

@@ -0,0 +1,52 @@
+@mainpage RT-Thread User Guide
+
+@subpage page_introduction
+
+@subpage page_quick_start
+
+@subpage page_kernel
+
+- @ref page_kernel_basics
+- @ref page_thread_management
+- @ref page_clock_management
+- @ref page_thread_sync
+- @ref page_thread_comm
+- @ref page_memory_management
+- @ref page_interrupt_management
+- @ref page_kernel_porting
+
+@subpage page_tool
+
+- @ref page_env
+- @ref page_scons
+
+@subpage page_device
+
+- @ref page_device_framework
+- @ref page_device_pin
+- @ref page_device_uart
+- @ref page_device_adc
+- @ref page_device_i2c
+- @ref page_device_spi
+- @ref page_device_pwm
+- @ref page_device_rtc
+- @ref page_device_hwtimer
+- @ref page_device_watchdog
+- @ref page_device_wlan
+- @ref page_device_sensor
+
+@subpage page_components
+
+- @ref page_component_finsh
+- @ref page_component_vfs
+- @ref page_component_utest
+- @ref page_component_dlmodule
+- @ref page_component_sal
+- @ref page_component_at
+- @ref page_component_posix
+- @ref page_component_ulog
+- @ref page_component_pm
+- @ref page_component_network
+
+@subpage page_code_contribution
+