kernel.h.svn-base

RT-Thread是发展中的下一代微内核嵌入式实时操作系统

/*
 * 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
 *
 * RT-Thread operating system supports multi-task systems, which are based on thread 
 * scheduling. 
 * - The scheduling is a full preemptive priority-based scheduling algorithm. 
 * - 256 priority levels are supported, in which 0 is the highest and 255 the lowest. 
 * The 255th priority is used for idle thread. 
 * - Threads running at same priority level are supports. The shared time-slice 
 * round-robin scheduling is used for this case. 
 * - The time of scheduler to determine the next highest ready thread is determinant. 
 * - There are three status in thread management
 *	-# Runnning
 *	-# Ready
 *	-# Blocked
 * - The number of threads in the system is unlimited, only related with RAM.
 */
 
/**
 * @defgroup Clock Clock and 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
 * 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
 * @dot
 * digraph G
 * {
 *  graph [
 *  ];
 * 	node [
 * 		fontname="Times New Roman"
 * 		shape=rect
 * 		fillcolor=transparent
 * 	];
 * 	edge [
 * 	];
 * 
 * 	"ko" [
 * 		label="Object"
 * 		style=filled
 * 		fillcolor=aliceblue
 * 	];
 * 	"sem" [
 * 		label="semaphore"
 * 	];
 * 	"mtx" [
 * 		label="mutex"
 * 	];
 * 	"mb" [
 * 		label="mailbox"
 * 	];
 * 	"e" [
 * 		label="event"
 * 	];
 * 	"mq" [
 * 		label="message\nqueue"
 * 	];
 * 	"tm" [
 * 		label="timer"
 * 	];
 * 
 * 	sem -> ko;
 * 	mtx -> ko;
 * 	mb	-> ko;
 * 	e		-> ko;
 * 	mq	-> ko;
 * 	tm	-> ko;
 * } 
 * @enddot
 * 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
 * 
 * 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
 *
 * 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 and 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.
 */

/**
 * @defgroup Hook Runtime Trace and Record
 *
 * 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
 */

/**
 * @defgroup Error Error Code
 *
 * The error code is defined to identify what's happen. When some bad things happen, 
 * the current thread's errno will be set.
 */

/*@}*/