原始版本

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);
+
+/**@}*/