doxygen: re-org module groups (#10197)

Match the organization of modules (groups) with
that of user guide.

Preliminary arrangement. This patch is just a
framework arrangement. Details need to be continued.

P.S., in this patch, adding numerical prefixes to
the files in documentation/0.doxygen is to meet the
need of displaying sorting in HTML pages.

Signed-off-by: Chen Wang <[email protected]>

Author: unicornx

documentation/0.doxygen/basicdef.h renamed to documentation/0.doxygen/0.basicdef.h

@@ -0,0 +1,142 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_kernel_core Kernel
+ *
+ * Core of RT-Thread, see @ref page_kernel_core for more details.
+ */
+
+/**
+ * @addtogroup group_kernel_core
+ * @{
+ */
+
+/**
+ * @defgroup group_KernelObject Kernel Object Management
+ * @brief See @ref section_kernel_object_model
+ *
+ * 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_Thread Thread Management
+ * @brief See @ref page_thread_management
+ */
+
+/**
+ * @defgroup group_Clock Clock and Timer Management
+ * @brief See @ref page_clock_management
+ */
+
+/**
+ * @defgroup group_IPC Inter-Thread Communication
+ * @brief See @ref page_thread_comm
+ */
+
+/**
+ * @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_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.
+ */
+
+/**
+ * @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();
+ */
+
+/**@}*/

documentation/0.doxygen/1.core.h

@@ -0,0 +1,75 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @defgroup group_kernel_components Components
+ *
+ * Components of RT-Thread, see @ref page_components for more details.
+ */
+
+/**
+ * @addtogroup group_kernel_components
+ * @{
+ */
+
+/**
+ * @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.
+ */
+
+/**
+ * @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_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).
+ */
+
+/**
+ * @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.
+ */
+
+/**@}*/

documentation/0.doxygen/2.components.h

@@ -6,4 +6,6 @@
  * @defgroup group_doxygen_example Doxygen Example
  *
  * @brief Introduce how to write doxygen documentation.
+ * 
+ * See @ref page_howto_doxygen for more details.
  */

documentation/0.doxygen/hardware.h renamed to documentation/0.doxygen/3.hardware.h

@@ -0,0 +1,27 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @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
+ */
+
+/**@}*/

documentation/0.doxygen/example/doxygen.h renamed to documentation/0.doxygen/4.doxygen.h

@@ -0,0 +1,19 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @addtogroup group_IPC
+ * @{
+ */
+
+/**
+ * @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.
+ */
+
+/**@}*/

documentation/0.doxygen/components/filesystem.h

@@ -0,0 +1,19 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @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);