Add doxygen script files.

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@2312 bbd45198-f89e-11dd-88c7-29a3b14d5316

8 files changed, 464 insertions, 0 deletions

diff --git a/documentation/doxygen/basicdef.h b/documentation/doxygen/basicdef.h
new file mode 100644
index 0000000000..ad766b4ebd
--- /dev/null
+++ b/documentation/doxygen/basicdef.h
@@ -0,0 +1,14 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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.

+ */

diff --git a/documentation/doxygen/filesystem.h b/documentation/doxygen/filesystem.h
new file mode 100644
index 0000000000..c56bb0faa6
--- /dev/null
+++ b/documentation/doxygen/filesystem.h
@@ -0,0 +1,44 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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 2: 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 DFS

+ */

+/*@{*/

+

+/**

+ * @defgroup Fd File Descriptor

+ *

+ */

+

+/**

+ * @defgroup FsApi File System API

+ */

+

+/**

+ * @defgroup FileApi File API

+ */

+

+/**

+ * @defgroup FsPosixApi File POSIX API

+ */

+

+/*@}*/

diff --git a/documentation/doxygen/finsh.h b/documentation/doxygen/finsh.h
new file mode 100644
index 0000000000..fd13c43379
--- /dev/null
+++ b/documentation/doxygen/finsh.h
@@ -0,0 +1,19 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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).

+ */

diff --git a/documentation/doxygen/hardware.h b/documentation/doxygen/hardware.h
new file mode 100644
index 0000000000..f46aed3e4b
--- /dev/null
+++ b/documentation/doxygen/hardware.h
@@ -0,0 +1,85 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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 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.

+ */

+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);

+

+/**

+ * This function will reset whole platform.

+ */

+void rt_hw_cpu_reset(void);

+

+/**

+ * This function will halt whole platform.

+ */

+void rt_hw_cpu_shutdown(void);

+

+/*@}*/

diff --git a/documentation/doxygen/kernel.h b/documentation/doxygen/kernel.h
new file mode 100644
index 0000000000..6270af6dba
--- /dev/null
+++ b/documentation/doxygen/kernel.h
@@ -0,0 +1,160 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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 Kernel
+ */

+/*@{*/
+

+/**

+ * @defgroup 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 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 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 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 thead 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 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 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 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 KernelService Other useful kernel service

+ * @brief other useful service in the kernel

+ */

+

+/**

+ * @defgroup 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. see @ref _rt_errno

+ */

+

+/*@}*/

diff --git a/documentation/doxygen/mainpage.h b/documentation/doxygen/mainpage.h
new file mode 100644
index 0000000000..94b525d563
--- /dev/null
+++ b/documentation/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.0.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 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 SystemInit

+ */

diff --git a/documentation/doxygen/module.h b/documentation/doxygen/module.h
new file mode 100644
index 0000000000..1b7ff4db90
--- /dev/null
+++ b/documentation/doxygen/module.h
@@ -0,0 +1,14 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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.

+ */

diff --git a/documentation/doxygen/systeminit.h b/documentation/doxygen/systeminit.h
new file mode 100644
index 0000000000..8508958c1d
--- /dev/null
+++ b/documentation/doxygen/systeminit.h
@@ -0,0 +1,79 @@
+/*

+ * This file is only used for doxygen document generation.

+ */

+

+/**

+ * @defgroup 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 system tick

+ * rt_system_tick_init();

+ *

+ * - initialize kernel object [deprecated]

+ * rt_system_object_init();

+ *

+ * - 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 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 SystemInit

+ *

+ * This function will initialize system heap memory.

+ *

+ * @param begin_addr the beginning address of system heap memory.

+ * @param end_addr the end address of system heap memory.

+ *

+ */

+void rt_system_heap_init(void* begin_addr, void* end_addr)

+{

+}