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 <unicorn_wang@outlook.com>

documentation/0.doxygen/1.core.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/2.components.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/example/doxygen.h → documentation/0.doxygen/4.doxygen.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/components/filesystem.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/core/ipc.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/core/systeminit.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);

documentation/0.doxygen/filesystem.h

@@ -1,44 +0,0 @@
-/*
- * 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
- */
-
-/**@}*/

documentation/0.doxygen/finsh.h

@@ -1,19 +0,0 @@
-/*
- * 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).
- */

documentation/0.doxygen/kernel.h

@@ -1,169 +0,0 @@
-/*
- * 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.
- */
-
-/**@}*/

documentation/0.doxygen/module.h

@@ -1,14 +0,0 @@
-/*
- * 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.
- */

documentation/0.doxygen/systeminit.h

@@ -1,63 +0,0 @@
-/*
- * 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);

documentation/3.kernel/INDEX.md

@@ -1,4 +1,4 @@
-@page page_kernel Kenrel
+@page page_kernel_core Kenrel
 
 - @subpage page_kernel_basics
 - @subpage page_thread_management

documentation/3.kernel/basic/basic.md

@@ -295,7 +295,7 @@ The macro interface definitions used to implement the automatic initialization f
 
 Initialization function actively declares through these macro interfaces, such as `INIT_BOARD_EXPORT(rt_hw_usart_init)`, the linker will automatically collect all the declared initialization functions, placed in the RTI symbol segment, the symbol segment is located in the RO segment of the memory distribution. All functions in this RTI symbol segment are automatically called when the system is initialized.
 
-# RT-Thread Kernel Object Model
+@section section_kernel_object_model RT-Thread Kernel Object Model
 
 ## Static and Dynamic Objects
 

documentation/Doxyfile

@@ -2241,7 +2241,8 @@ PREDEFINED             = RT_USING_SEMAPHORE \
                          FINSH_USING_DESCRIPTION \
                          RT_USING_FINSH \
                          RT_USING_HEAP \
-                         RT_USING_MODULE
+                         RT_USING_MODULE \
+                         RT_USING_SIGNALS
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

documentation/INDEX.md

@@ -4,7 +4,7 @@
 
 @subpage page_quick_start
 
-@subpage page_kernel
+@subpage page_kernel_core
 
 - @ref page_kernel_basics
 - @ref page_thread_management

src/irq.c

@@ -59,7 +59,7 @@ void rt_interrupt_leave_sethook(void (*hook)(void))
 #endif /* RT_USING_HOOK */
 
 /**
- * @addtogroup group_Kernel
+ * @addtogroup group_kernel_core
  */
 
 /**@{*/