git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@621 35acf78f-673a-0410-8e92-d51de3d6d3f4

9 files changed, 317 insertions, 238 deletions

diff --git a/demos/Win32-MinGW/chcore.h b/demos/Win32-MinGW/chcore.h
index 70efa7edb..40555df63 100644
--- a/demos/Win32-MinGW/chcore.h
+++ b/demos/Win32-MinGW/chcore.h
@@ -144,6 +144,16 @@ typedef struct {
 #define SYS_IRQ_HANDLER

 

 /**

+ * Simulator initialization.

+ */

+#define sys_init() InitCore()

+

+/**

+ * Does nothing in this simulator.

+ */

+#define sys_disable_all()

+

+/**

  * Does nothing in this simulator.

  */

 #define sys_disable()

@@ -156,17 +166,22 @@ typedef struct {
 /**

  * Does nothing in this simulator.

  */

-#define sys_disable_from_isr()

+#define sys_lock()

 

 /**

  * Does nothing in this simulator.

  */

-#define sys_enable_from_isr()

+#define sys_unlock()

 

 /**

  * Does nothing in this simulator.

  */

-#define sys_disable_all()

+#define sys_lock_from_isr()

+

+/**

+ * Does nothing in this simulator.

+ */

+#define sys_unlock_from_isr()

 

 /**

  * In the simulator this does a polling pass on the simulated interrupt

diff --git a/demos/Win32-MinGW/main.c b/demos/Win32-MinGW/main.c
index eaf2504dd..a72d7b4da 100644
--- a/demos/Win32-MinGW/main.c
+++ b/demos/Win32-MinGW/main.c
@@ -279,8 +279,6 @@ static evhandler_t fhandlers[2] = {
 int main(void) {

   EventListener c1fel, c2fel;

 

-  InitCore();

-

   // Startup ChibiOS/RT.

   chSysInit();

 

diff --git a/docs/Doxyfile b/docs/Doxyfile
index 0c84e5c15..b76152c27 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -16,7 +16,7 @@ ALWAYS_DETAILED_SEC = NO
 INLINE_INHERITED_MEMB = NO
 FULL_PATH_NAMES = NO
 STRIP_FROM_PATH = "C:/Documents and Settings/Administrator/"
-STRIP_FROM_INC_PATH =
+STRIP_FROM_INC_PATH = 
 SHORT_NAMES = NO
 JAVADOC_AUTOBRIEF = YES
 QT_AUTOBRIEF = NO
@@ -24,7 +24,7 @@ MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS = NO
 SEPARATE_MEMBER_PAGES = NO
 TAB_SIZE = 2
-ALIASES =
+ALIASES = 
 OPTIMIZE_OUTPUT_FOR_C = YES
 OPTIMIZE_OUTPUT_JAVA = NO
 OPTIMIZE_FOR_FORTRAN = NO
@@ -63,14 +63,14 @@ GENERATE_TODOLIST = YES
 GENERATE_TESTLIST = YES
 GENERATE_BUGLIST = YES
 GENERATE_DEPRECATEDLIST = YES
-ENABLED_SECTIONS =
+ENABLED_SECTIONS = 
 MAX_INITIALIZER_LINES = 30
 SHOW_USED_FILES = NO
 SHOW_DIRECTORIES = NO
 SHOW_FILES = YES
 SHOW_NAMESPACES = YES
-FILE_VERSION_FILTER =
-LAYOUT_FILE =
+FILE_VERSION_FILTER = 
+LAYOUT_FILE = 
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
@@ -80,7 +80,7 @@ WARN_IF_UNDOCUMENTED = YES
 WARN_IF_DOC_ERROR = YES
 WARN_NO_PARAMDOC = YES
 WARN_FORMAT = "$file:$line: $text"
-WARN_LOGFILE =
+WARN_LOGFILE = 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
@@ -88,16 +88,16 @@ INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../src/lib
 INPUT_ENCODING = UTF-8
 FILE_PATTERNS = *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py *.ddf
 RECURSIVE = YES
-EXCLUDE =
+EXCLUDE = 
 EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS =
-EXAMPLE_PATH =
+EXCLUDE_PATTERNS = 
+EXCLUDE_SYMBOLS = 
+EXAMPLE_PATH = 
 EXAMPLE_PATTERNS = *
 EXAMPLE_RECURSIVE = NO
 IMAGE_PATH = ./img
-INPUT_FILTER =
-FILTER_PATTERNS =
+INPUT_FILTER = 
+FILTER_PATTERNS = 
 FILTER_SOURCE_FILES = NO
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
@@ -115,33 +115,33 @@ VERBATIM_HEADERS = NO
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX = NO
 COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
+IGNORE_PREFIX = 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML = YES
 HTML_OUTPUT = html
 HTML_FILE_EXTENSION = .html
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
+HTML_HEADER = 
+HTML_FOOTER = 
+HTML_STYLESHEET = 
 HTML_ALIGN_MEMBERS = YES
 HTML_DYNAMIC_SECTIONS = NO
 GENERATE_DOCSET = NO
 DOCSET_FEEDNAME = "Doxygen generated docs"
 DOCSET_BUNDLE_ID = org.doxygen.Project
 GENERATE_HTMLHELP = NO
-CHM_FILE =
-HHC_LOCATION =
+CHM_FILE = 
+HHC_LOCATION = 
 GENERATE_CHI = NO
-CHM_INDEX_ENCODING =
+CHM_INDEX_ENCODING = 
 BINARY_TOC = NO
 TOC_EXPAND = NO
 GENERATE_QHP = NO
-QCH_FILE =
+QCH_FILE = 
 QHP_NAMESPACE = org.doxygen.Project
 QHP_VIRTUAL_FOLDER = doc
-QHG_LOCATION =
+QHG_LOCATION = 
 DISABLE_INDEX = NO
 ENUM_VALUES_PER_LINE = 4
 GENERATE_TREEVIEW = YES
@@ -156,8 +156,8 @@ LATEX_CMD_NAME = latex
 MAKEINDEX_CMD_NAME = makeindex
 COMPACT_LATEX = NO
 PAPER_TYPE = a4wide
-EXTRA_PACKAGES =
-LATEX_HEADER =
+EXTRA_PACKAGES = 
+LATEX_HEADER = 
 PDF_HYPERLINKS = YES
 USE_PDFLATEX = YES
 LATEX_BATCHMODE = NO
@@ -169,8 +169,8 @@ GENERATE_RTF = NO
 RTF_OUTPUT = rtf
 COMPACT_RTF = NO
 RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
+RTF_STYLESHEET_FILE = 
+RTF_EXTENSIONS_FILE = 
 #---------------------------------------------------------------------------
 # configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -183,8 +183,8 @@ MAN_LINKS = NO
 #---------------------------------------------------------------------------
 GENERATE_XML = NO
 XML_OUTPUT = xml
-XML_SCHEMA =
-XML_DTD =
+XML_SCHEMA = 
+XML_DTD = 
 XML_PROGRAMLISTING = YES
 #---------------------------------------------------------------------------
 # configuration options for the AutoGen Definitions output
@@ -196,7 +196,7 @@ GENERATE_AUTOGEN_DEF = NO
 GENERATE_PERLMOD = NO
 PERLMOD_LATEX = NO
 PERLMOD_PRETTY = YES
-PERLMOD_MAKEVAR_PREFIX =
+PERLMOD_MAKEVAR_PREFIX = 
 #---------------------------------------------------------------------------
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
@@ -204,16 +204,16 @@ ENABLE_PREPROCESSING = YES
 MACRO_EXPANSION = NO
 EXPAND_ONLY_PREDEF = NO
 SEARCH_INCLUDES = YES
-INCLUDE_PATH =
-INCLUDE_FILE_PATTERNS =
-PREDEFINED = __JUST_STUBS__ __DOXIGEN__ CH_USE_WAITEXIT CH_USE_SEMAPHORES CH_USE_SEMSW CH_USE_SEMAPHORES_TIMEOUT CH_USE_MUTEXES CH_USE_CONDVARS CH_USE_CONDVARS_TIMEOUT CH_USE_EVENTS CH_USE_EVENTS_TIMEOUT CH_USE_EXIT_EVENT CH_USE_QUEUES CH_USE_QUEUES_TIMEOUT CH_USE_QUEUES_HALFDUPLEX CH_USE_SERIAL_FULLDUPLEX CH_USE_SERIAL_HALFDUPLEX CH_USE_HEAP CH_USE_MEMPOOLS CH_USE_MESSAGES CH_USE_MESSAGES_EVENT CH_USE_MESSAGES_PRIORITY CH_USE_DEBUG CH_USE_TRACE CH_USE_DYNAMIC CH_USE_ROUNDROBIN
-EXPAND_AS_DEFINED =
+INCLUDE_PATH = 
+INCLUDE_FILE_PATTERNS = 
+PREDEFINED = __DOXYGEN__ CH_USE_WAITEXIT CH_USE_SEMAPHORES CH_USE_SEMSW CH_USE_SEMAPHORES_TIMEOUT CH_USE_MUTEXES CH_USE_CONDVARS CH_USE_CONDVARS_TIMEOUT CH_USE_EVENTS CH_USE_EVENTS_TIMEOUT CH_USE_EXIT_EVENT CH_USE_QUEUES CH_USE_QUEUES_TIMEOUT CH_USE_QUEUES_HALFDUPLEX CH_USE_SERIAL_FULLDUPLEX CH_USE_SERIAL_HALFDUPLEX CH_USE_HEAP CH_USE_MEMPOOLS CH_USE_MESSAGES CH_USE_MESSAGES_EVENT CH_USE_MESSAGES_PRIORITY CH_USE_DEBUG CH_USE_TRACE CH_USE_DYNAMIC CH_USE_ROUNDROBIN 
+EXPAND_AS_DEFINED = 
 SKIP_FUNCTION_MACROS = YES
 #---------------------------------------------------------------------------
 # Configuration::additions related to external references
 #---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE =
+TAGFILES = 
+GENERATE_TAGFILE = 
 ALLEXTERNALS = NO
 EXTERNAL_GROUPS = YES
 PERL_PATH = /usr/bin/perl
@@ -221,12 +221,12 @@ PERL_PATH = /usr/bin/perl
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS = NO
-MSCGEN_PATH =
+MSCGEN_PATH = 
 HIDE_UNDOC_RELATIONS = YES
 HAVE_DOT = YES
 DOT_FONTNAME = FreeSans
 DOT_FONTSIZE = 8
-DOT_FONTPATH =
+DOT_FONTPATH = 
 CLASS_GRAPH = YES
 COLLABORATION_GRAPH = YES
 GROUP_GRAPHS = YES
@@ -239,8 +239,8 @@ CALLER_GRAPH = NO
 GRAPHICAL_HIERARCHY = YES
 DIRECTORY_GRAPH = NO
 DOT_IMAGE_FORMAT = png
-DOT_PATH =
-DOTFILE_DIRS =
+DOT_PATH = 
+DOTFILE_DIRS = 
 DOT_GRAPH_MAX_NODES = 20
 MAX_DOT_GRAPH_DEPTH = 3
 DOT_TRANSPARENT = YES
diff --git a/docs/ch.txt b/docs/ch.txt
index 151633ffc..c05df4761 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -62,17 +62,76 @@
  * @{

  * @section naming Naming Conventions

  * ChibiOS/RT APIs are all named following this convention:

- * \a ch\<group\>\<action\>\<suffix\>().

- * The possible groups are: \a Sys, \a Sch, \a VT, \a Thd, \a Sem, \a Mtx,

- * \a Evt, \a Msg, \a IQ, \a OQ, \a HQ,\a FDD, \a HDD, \a Dbg, \a Heap, \a Pool.

+ * @a ch\<group\>\<action\>\<suffix\>().

+ * The possible groups are: @a Sys, @a Sch, @a VT, @a Thd, @a Sem, @a Mtx,

+ * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg,

+ * @a Heap, @a Pool.

  * The suffix is not present for normal APIs but can be one of

- * the following: "I" for APIs meant to be invoked within the system mutex

- * zone, "S" for APIs only usable from within the system mutex zone but not

- * from interrupt handlers.<br>

- * The APIs without suffix can be invoked only from the user code outsize the

- * system mutex zone and not from interrupt handlers unless differently

- * specified.<br>

- * Examples: \p chThdCreateStatic(), \p chSemSignalI(), \p chIQGetTimeout().

+ * the following:

+ * - <b>"I"</b>, I-Class APIs are invokeable only from the I-Locked or S-Locked

+ *   states. See @ref system_states.

+ * - <b>"S"</b>, S-Class APIs are invokeable only from the S-Locked state. See

+ *   @ref system_states.

+ *

+ * The APIs without suffix can be invoked only from the user code in the Normal

+ * state unless differently specified.<br>

+ * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout().

+ *

+ * @section interrupts Interrupt Classes

+ * In ChibiOS/RT there are three logical interrupt classes:

+ * - <b>Regular Interrupts</b>. Maskable interrupt sources that cannot

+ *   preempt the kernel code and are thus able to invoke operating system APIs

+ *   from within their handlers. The interrupt handlers belonging to this class

+ *   must be written following some rules. See the @ref System APIs group.

+ * - <b>Fast Interrupts</b>. Maskable interrupt sources with the ability

+ *   to preempt the kernel code and thus have a lower latency. Such sources are

+ *   not supported on all the architectures.<br>

+ *   Fast interrupts are not allowed to invoke any operating system API from

+ *   within their handlers. Fast interrupt sources may however pend a lower

+ *   priority regular interrupt where access to the operating system is

+ *   possible.

+ * - <b>Non Maskable Interrupts</b>. Non maskable interrupt sources are

+ *   totally out of the operating system control and have the lowest latency.

+ *   Such sources are not supported on all the architectures.

+ *

+ * The mapping of the above logical classes into physical interrupts priorities

+ * is, of course, port dependent. See the documentation of the various ports

+ * for details.

+ *

+ * @section system_states System States

+ * When using ChibiOS/RT the system can be in one of the following logical

+ * operating states:

+ * - <b>Initialization</b>. When the system is in this state all the maskable

+ *   interrupt sources are disabled. In this state it is not possible to use

+ *   any system API except @p chSysInit(). This state is entered after a

+ *   physical reset.

+ * - <b>All Disabled</b>. When the system is in this state both the maskable

+ *   regular and fast interrupt sources are disabled. In this state it is not

+ *   possible to use any system API except @p chSysDisable() or chSysEnable().

+ *   This state is entered using @p chSysDisableAll().

+ * - <b>Disabled</b>. In this state the fast interrupt sources are enabled but

+ *   the regular interrupt sources are not. In this state it is not possible

+ *   to use any system API except @p chSysDisableAll() or chSysEnable().

+ * - <b>Normal</b>. All the interrupt sources are enabled and the system APIs

+ *   are accessible, threads are running.

+ * - <b>S-Locked</b>. Kernel locked and regular interrupt sources disabled.

+ *   Fast interrupt sources are enabled. I-Class and S-Class APIs are

+ *   invokeable in this state.

+ * - <b>I-Locked</b>. Kernel locked and regular interrupt sources disabled.

+ *   I-Class and APIs are invokeable from this state.

+ * - <b>Serving Regular Interrupt</b>. No system APIs are accessible but it is

+ *   possible to switch to the I-Locked state using @p chSysLockI() and then

+ *   invoke any I-Class API.

+ * - <b>Serving Fast Interrupt</b>. No system APIs are accessible.

+ * - <b>Serving Non-Maskable Interrupt</b>. No systemAPIs are accessible.

+ * - <b>Halted</b>. All interrupt sources disabled and system stopped into an

+ *   infinite loop. This state can be reached if the debug mode is activated

+ *   <b>and</b> an error is detected <b>or</b> after explicitly invoking

+ *   @p chSysHalt().

+ *

+ * Note that the above state are just <b>Logical States</b> that can have no

+ * real machine state associated. The following diagram shows the possible

+ * transitions between the states:

  *

  * @section scheduling Scheduling

  * The strategy is very simple the currently ready thread with the highest

@@ -84,18 +143,38 @@
  * Note that the currently running thread is not in the ready list, the list

  * only contains the threads ready to be executed but still actually waiting.

  *

- * @section states Threads States Diagram

+ * @section thread_states Threads States

  * The image shows how threads can change their state in ChibiOS/RT.<br>

  * @image html states.png

  *

+ * @section priority Priority Levels

+ * Priorities in ChibiOS/RT are a contiguous numerical range but the initial

+ * and final values are not enforced.<br>

+ * The following table describes the various priority boundaries (from lowest

+ *   to highest):

+ * - @p IDLEPRIO, this is the lowest priority level and is reserved for the

+ *   idle thread, no other threads should share this priority level. This is

+ *   the lowest numerical value of the priorities space.

+ * - @p LOWPRIO, the lowest priority level that can be assigned to an user

+ *   thread.

+ * - @p NORMALPRIO, this is the central priority level for user threads. It is

+ *   advisable to assign priorities to threads as values relative to

+ *   @p NORMALPRIO, as example NORMALPRIO-1 or NORMALPRIO+4, this ensures the

+ *   portability of code should the numerical range change in future

+ *   implementations.

+ * - @p HIGHPRIO, the highest priority level that can be assigned to an user

+ *   thread.

+ * - @p ABSPRO, absolute maximum software priority level, it can be higher than

+ *   @p HIGHPRIO but the numerical values above @p HIGHPRIO up to @p ABSPRIO

+ *   (inclusive) are reserved. This is the highest numerical value of the

+ *   priorities space.

+ *

  * @section warea Thread Working Area

  * Each thread has its own stack, a Thread structure and some preemption

  * areas. All the structures are allocated into a "Thread working area",

- * a thread private heap, usually allocated in a char array declared in your

- * code, there is not a central threads table or list, this means you can

- * have as many threads you want as long you have enough available RAM

- * memory. The threads do not use any memory outside the allocated working

- * area.<br><br>

+ * a thread private heap, usually allocated in an array declared in your

+ * code. Threads do not use any memory outside the allocated working area

+ * except when accessing static shared data.<br><br>

  * @image html workspace.png

  * <br>

  * Note that the preemption area is only present when the thread is not

@@ -109,28 +188,6 @@
  *

  * See the @ref Core documentation for details, the area may change on

  * the various ports and some structures may not be present (or be zero-sized).

- *

- * @section sysmutex System Mutex Zone

- * It is the code within the OS that cannot be preempted, this code is

- * everything between the \p chSysLock() and \p chSysUnlock() API calls.

- * The implementation of the APIs in most cases just enables/disables the

- * interrupts. Of course the code in the system mutex zone must be as short

- * and efficient possible as it affects the RT performance of the whole

- * system. The worst case response time is affected by the longest code

- * path in the system mutex zone or interrupt handler.

- * @code

- * // User code, not critical, preemption possible.

- * chSysLock();

- * ...

- * // System critical code, preemption delayed.

- * ...

- * chSysUnlock();

- * // User code, preemption possible again.

- * @endcode

- * Applications usually do not need to put code into the system mutex zone

- * unless you are implementing device drivers or special synchronization

- * primitives, everything else can be implemented by using semaphores,

- * mutexes, messages or events.

  */

 /** @} */

 

@@ -163,7 +220,7 @@
  * <p>

  * The ARM7 port makes some assumptions on the application code organization:

  * <ul>

- * <li>The \p main() function is invoked in system mode.</li>

+ * <li>The @p main() function is invoked in system mode.</li>

  * <li>Each thread has a private user/system stack, the system has a single

  *     interrupt stack where all the interrupts are processed.</li>

  * <li>The threads are started in system mode.</li>

@@ -186,7 +243,7 @@
  *     because in the ARM7 port all the OS interrupt handlers are declared

  *     naked).<br>

  *     Function-trashed registers (R0-R3,R12,LR,SR) are saved/restored by the

- *     system macros \p chSysIRQEnterI() and \p chSysIRQExitI().<br>

+ *     system macros @p chSysIRQEnterI() and @p chSysIRQExitI().<br>

  *     The easiest way to ensure this is to just invoke a function from within

  *     the interrupt handler, the function code will save all the required

  *     registers.<br>

@@ -280,7 +337,7 @@
  * The ARM Cortex-M3 port is organized as follow:

  * </p>

  * <ul>

- * <li>The \p main() function is invoked in thread-privileged mode.</li>

+ * <li>The @p main() function is invoked in thread-privileged mode.</li>

  * <li>Each thread has a private process stack, the system has a single main

  *     stack where all the interrupts and exceptions are processed.</li>

  * <li>Only the 4 MSb of the priority level are used, the 4 LSb are assumed

@@ -359,7 +416,7 @@
  * <ul>

  * <li>The AVR does not have a dedicated interrupt stack, make sure to reserve

  *     enough stack space for interrupts in each thread stack. This can be done

- *     by modifying the \p INT_REQUIRED_STACK macro into

+ *     by modifying the @p INT_REQUIRED_STACK macro into

  *     <b>./ports/AVR/chcore.h</b>.</li>

  * </ul>

  * @ingroup Ports

@@ -393,7 +450,7 @@
  * <ul>

  * <li>The MSP430 does not have a dedicated interrupt stack, make sure to reserve

  *     enough stack space for interrupts in each thread stack. This can be done

- *     by modifying the \p INT_REQUIRED_STACK macro into

+ *     by modifying the @p INT_REQUIRED_STACK macro into

  *     <b>./ports/MSP430/chcore.h</b>.</li>

  * </ul>

  * @ingroup Ports

@@ -421,13 +478,14 @@
 /**

  * @defgroup Kernel Kernel

  * @{

+ * @file ch.h ChibiOS/RT main include file, it includes everything else.

  */

 /** @} */

 

 /**

  * @defgroup Config Configuration

  * @{

- * In \p chconf.h are defined the required subsystems for your application.

+ * In @p chconf.h are defined the required subsystems for your application.

  * @ingroup Kernel

  * @file chconf.h ChibiOS/RT configuration file.

  */

@@ -453,21 +511,22 @@
 /** @} */

 

 /**

- * @defgroup Inline Inline

+ * @defgroup System System Management

  * @{

- * System inline-able code.

+ * Initialization, Locks, Interrupt Handling, Power Management, Abnormal

+ * Termination.

  * @ingroup Kernel

- * @file inline.h Inline versions of some critical system routines.

+ * @file sys.h System related macros and structures.

+ * @file chsys.c System related code.

  */

 /** @} */

 

 /**

- * @defgroup Initialization Initialization

+ * @defgroup Inline Inline

  * @{

- * Initialization APIs and procedures.

+ * System inline-able code.

  * @ingroup Kernel

- * @file ch.h ChibiOS/RT main include file, it includes everything else.

- * @file chinit.c ChibiOS/RT Initialization code.

+ * @file inline.h Inline versions of some critical system routines.

  */

 /** @} */

 

@@ -525,13 +584,13 @@
  * Heap Allocator related APIs.

  * <b>Operation mode</b><br><br>

  * The heap allocator implements a first-fit strategy and its APIs are

- * functionally equivalent to the usual \p malloc() and \p free(). The main

+ * functionally equivalent to the usual @p malloc() and @p free(). The main

  * difference is that the heap APIs are thread safe.<br>

- * By enabling the \p CH_USE_MALLOC_HEAP option the heap manager will use the

- * runtime-provided \p malloc() and \p free() as backend for the heap APIs

+ * By enabling the @p CH_USE_MALLOC_HEAP option the heap manager will use the

+ * runtime-provided @p malloc() and @p free() as backend for the heap APIs

  * instead of the system provided allocator.<br>

- * In order to use the heap APIs the \p CH_USE_HEAP option must be specified

- * in \p chconf.h.

+ * In order to use the heap APIs the @p CH_USE_HEAP option must be specified

+ * in @p chconf.h.

  * @file include/heap.h Heap macros and structures.

  * @file chheap.c Heap functions.

  */

@@ -544,8 +603,8 @@
  * <b>Operation mode</b><br><br>

  * The Memory Pools APIs allow to allocate/free fixed size objects in

  * <b>constant time</b> and reliably without memory fragmentation problems.<br>

- * In order to use the Time APIs the \p CH_USE_MEMPOOLS option must be

- * specified in \p chconf.h.

+ * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be

+ * specified in @p chconf.h.

  * @file include/mempools.h Memory Pools macros and structures.

  * @file chmempools.c Memory Pools functions.

  */

@@ -572,8 +631,8 @@
  * </ul>

  * Semaphores can be used as guards for mutual exclusion code zones but

  * also have other uses, queues guards and counters as example.<br>

- * In order to use the Semaphores APIs the \p CH_USE_SEMAPHORES

- * option must be specified in \p chconf.h.<br><br>

+ * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES

+ * option must be specified in @p chconf.h.<br><br>

  * @file semaphores.h Semaphores macros and structures.

  * @file chsem.c Semaphores code.

  */

@@ -596,8 +655,8 @@
  *     of the mutex.

  *   </li>

  * </ul>

- * In order to use the Event APIs the \p CH_USE_MUTEXES option must be

- * specified in \p chconf.h.<br>

+ * In order to use the Event APIs the @p CH_USE_MUTEXES option must be

+ * specified in @p chconf.h.<br>

  *

  * <b>Constraints</b><br><br>

  * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse

@@ -625,10 +684,10 @@
  * Conditional Variables and threads synchronization.

  * <b>Operation mode</b><br><br>

  * The condition variable is a synchronization object meant to be used inside

- * a zone protected by a \p Mutex. Mutexes and CondVars together can implement

+ * a zone protected by a @p Mutex. Mutexes and CondVars together can implement

  * a Monitor construct.<br>

- * In order to use the Conditional Variables APIs the \p CH_USE_CONDVARS

- * option must be specified in \p chconf.h.<br><br>

+ * In order to use the Conditional Variables APIs the @p CH_USE_CONDVARS

+ * option must be specified in @p chconf.h.<br><br>

  * @file condvars.h Conditional Variables macros and structures.

  * @file chcond.c Conditional Variables code.

  */

@@ -646,12 +705,12 @@
  * An unlimited number of Event Sources can exists in a system and each

  * thread can listen on an unlimited number of them.<br>

  * Note that the events can be asynchronously generated but are synchronously

- * served, a thread can serve event by calling a \p chEvtWaitXXX()

+ * served, a thread can serve event by calling a @p chEvtWaitXXX()

  * API. If an event is generated while a listening thread is not ready to

  * serve it then the event becomes "pending" and will be served as soon the

- * thread invokes a \p chEvtWaitXXX().<br>

- * In order to use the Event APIs the \p CH_USE_EVENTS option must be

- * specified in \p chconf.h.

+ * thread invokes a @p chEvtWaitXXX().<br>

+ * In order to use the Event APIs the @p CH_USE_EVENTS option must be

+ * specified in @p chconf.h.

  * @file events.h Events macros and structures.

  * @file chevents.c Events functions.

  */

@@ -669,12 +728,12 @@
  * efficient.<br>

  * Messages are usually processed in FIFO order but it is possible to process

  * them in priority order by specifying CH_USE_MESSAGES_PRIORITY

- * in \p chconf.h.<br>

+ * in @p chconf.h.<br>

  * Threads do not need to allocate space for message queues, the mechanism

- * just requires two extra pointers in the \p Thread structure (the message

+ * just requires two extra pointers in the @p Thread structure (the message

  * queue header).<br>

- * In order to use the Messages APIs the \p CH_USE_MESSAGES option must be

- * specified in \p chconf.h.

+ * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be

+ * specified in @p chconf.h.

  * @file messages.h	Messages macros and structures.

  * @file chmsg.c Messages functions.

  */

@@ -702,10 +761,10 @@
  *     operations can happen at the same time. Full duplex queues

  *     are implemented by pairing an input queue and an output queue together.

  * </ul>

- * In order to use the I/O queues the \p CH_USE_QUEUES option must

- * be specified in \p chconf.h.<br>

- * In order to use the half duplex queues the \p CH_USE_QUEUES_HALFDUPLEX

- * option must be specified in \p chconf.h.

+ * In order to use the I/O queues the @p CH_USE_QUEUES option must

+ * be specified in @p chconf.h.<br>

+ * In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX

+ * option must be specified in @p chconf.h.

  * @file queues.h I/O Queues macros and structures.

  * @file chqueues.c I/O Queues code.

  */

@@ -721,9 +780,9 @@
  * The  module also contains functions that make the implementation of the

  * interrupt service routines much easier.<br>

  * In order to use the serial full duplex driver the

- * \p CH_USE_SERIAL_FULLDUPLEX option must be specified in \p chconf.h.<br>

+ * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.<br>

  * In order to use the serial half duplex driver the

- * \p CH_USE_SERIAL_HALFDUPLEX option must be specified in \p chconf.h.

+ * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h.

  * @file serial.h Serial Drivers macros and structures.

  * @file chserial.c Serial Drivers code.

  */

diff --git a/readme.txt b/readme.txt
index 2b2f4010b..0b8cf3437 100644
--- a/readme.txt
+++ b/readme.txt
@@ -80,11 +80,13 @@ Win32-MinGW            - ChibiOS/RT simulator and demo into a WIN32 process,
   Port functions are no more directly exposed as APIs to the user code.

 - NEW: Added a configuration option to enable nested system locks/unlocks.

 - NEW: Improved the interrupt handlers related code. Now interrupts are

-  handled in a very similar way for every architecture.

+  handled in a very similar way in every architecture.

 - CHANGE: Renamed the macros chSysIRQEnter() and chSysIRQExit() in

   CH_IRQ_PROLOGUE() and CH_IRQ_EPILOGUE() in order to make very clear that

   those are not functions but inlined code. Also introduced a new macro

   CH_IRQ_HANDLER that should be used when declaring an interrupt handler.

+- Introduced the concept of interrupt classes, see the documentation.

+- Introduced the concept of system state, see the documentation.

 

 *** 1.0.0rc2 ***

 - FIX: Removed unused variable "retaddr" from the Cortex-M3 port.

diff --git a/src/chsys.c b/src/chsys.c
index 45ce8b0f8..2f4c796a8 100644
--- a/src/chsys.c
+++ b/src/chsys.c
@@ -52,6 +52,7 @@ static void idle_thread(void *p) {
 void chSysInit(void) {
   static Thread mainthread;
 
+  sys_init();
   chSchInit();
   chDbgInit();
   chVTInit();
@@ -94,37 +95,20 @@ void chSysTimerHandlerI(void) {
   chVTDoTickI();
 }
 
-#if !defined(CH_OPTIMIZE_SPEED)
-/**
- * Enters the ChibiOS/RT system mutual exclusion zone.
- * @note The use of system mutual exclusion zone is not recommended in
- *       the user code, it is a better idea to use the semaphores or mutexes
- *       instead.
- * @note The code of this API is may be inlined or not depending on the
- *       @p CH_OPTIMIZE_SPEED setting.
- * @see CH_USE_NESTED_LOCKS, chSysLockInline()
- */
+#if defined(CH_USE_NESTED_LOCKS) && !defined(CH_OPTIMIZE_SPEED)
 void chSysLock(void) {
 
-  chSysLockInline();
+  chDbgAssert(currp->p_locks >= 0, "chinit.c, chSysLock()");
+  if (currp->p_locks++ == 0)
+    sys_lock();
 }
 
-/**
- * Leaves the ChibiOS/RT system mutual exclusion zone.
- * @note The use of system mutual exclusion zone is not recommended in
- *       the user code, it is a better idea to use the semaphores or mutexes
- *       instead.
- * @note The code of this API is may be inlined or not depending on the
- *       @p CH_OPTIMIZE_SPEED setting.
- * @see CH_USE_NESTED_LOCKS, chSysUnlockInline()
- */
 void chSysUnlock(void) {
 
-#ifdef CH_USE_NESTED_LOCKS
   chDbgAssert(currp->p_locks > 0, "chinit.c, chSysUnlock()");
-#endif
-  chSysUnlockInline();
+  if (--currp->p_locks == 0)
+    sys_unlock();
 }
-#endif /* !CH_OPTIMIZE_SPEED */
+#endif /* defined(CH_USE_NESTED_LOCKS) && !defined(CH_OPTIMIZE_SPEED) */
 
 /** @} */
diff --git a/src/include/sys.h b/src/include/sys.h
index 5acc863f2..ae38a5639 100644
--- a/src/include/sys.h
+++ b/src/include/sys.h
@@ -50,36 +50,74 @@
 #define chSysSwitchI(otp, ntp) sys_switch(otp, ntp)

 

 /**

- * Lowers the system interrupt priority mask to user level.

- * @note The implementation is architecture dependent, it may just enable the

- *       interrupts.

- * @note This API is normally invoked only from within @p chSysInit().
- * @note The use of this API is <b>not</b> an alternative to @p chSysUnlock().

+ * Raises the system interrupt priority mask to the maximum level.

+ * All the maskable interrupt sources are disabled regardless their hardware

+ * priority.

+ * @note The implementation is architecture dependent, it may just disable the

+ *       interrupts or be exactly equivalent to @p chSysDisable().

+ * @note Do not invoke this API from within a kernel lock.

  */

-#define chSysEnable() sys_enable()

+#define chSysDisableAll() sys_disable_all()

 

 /**

  * Raises the system interrupt priority mask to system level.

+ * The interrupt sources that should not be able to preempt the kernel are

+ * disabled, interrupt sources with higher priority are still enabled.

  * @note The implementation is architecture dependent, it may just disable the

  *       interrupts.

- * @note This API should only be invoked from the main thread in order to stop

- *       ChibiOS/RT, hardware de/re-initialization should follow. It would then

- *       be possible to re-initialize ChibiOS/RT using @p chSysInit().

- * @note The use of this API is <b>not</b> an alternative to @p chSysLock().

+ * @note Do not invoke this API from within a kernel lock.

+ * @note This API is no replacement for @p chSysLock(), the @p chSysLock()

+ *       could do more than just disable the interrupts.

  */

 #define chSysDisable() sys_disable()

 

 /**

- * Raises the system interrupt priority mask to the maximum level thus disabling

- * any mask-able interrupt source..

- * @note The implementation is architecture dependent, it may just disable the

- *       interrupts or be exactly equivalent to @p chSysDisable().

+ * Lowers the system interrupt priority mask to user level.

+ * All the interrupt sources are enabled.

+ * @note The implementation is architecture dependent, it may just enable the

+ *       interrupts.

+ * @note Do not invoke this API from within a kernel lock.

+ * @note This API is no replacement for @p chSysUnlock(), the @p chSysUnlock()

+ *       could do more than just enable the interrupts.

  */

-#define chSysDisableAll() sys_disable_all()

+#define chSysEnable() sys_enable()

 

 /**

- * Enters the ChibiOS/RT system mutual exclusion zone from within an interrupt

- * handler.

+ * Enters the kernel lock mode.

+ * @note The use of kernel lock mode is not recommended in the user code, it is

+ *       a better idea to use the semaphores or mutexes instead.

+ * @see CH_USE_NESTED_LOCKS

+ */

+#if defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)

+#if defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)

+#define chSysLock() {                                                   \

+  if (currp->p_locks++ == 0)                                            \

+    sys_lock();                                                         \

+}

+#endif /* defined(CH_OPTIMIZE_SPEED) */

+#else /* !defined(CH_USE_NESTED_LOCKS) */

+#define chSysLock() sys_lock()

+#endif /* !defined(CH_USE_NESTED_LOCKS) */

+

+/**

+ * Leaves the kernel lock mode.

+ * @note The use of kernel lock mode is not recommended in the user code, it is

+ *       a better idea to use the semaphores or mutexes instead.

+ * @see CH_USE_NESTED_LOCKS

+ */

+#if defined(CH_USE_NESTED_LOCKS) || defined(__DOXYGEN__)

+#if defined(CH_OPTIMIZE_SPEED) || defined(__DOXYGEN__)

+#define chSysUnlock() {                                                 \

+  if (--currp->p_locks == 0)                                            \

+    sys_unlock();                                                       \

+}

+#endif /* defined(CH_OPTIMIZE_SPEED) */

+#else /* !defined(CH_USE_NESTED_LOCKS) */

+#define chSysUnlock() sys_unlock()

+#endif /* !defined(CH_USE_NESTED_LOCKS) */

+

+/**

+ * Enters the kernel lock mode from within an interrupt handler.

  * @note This API may do nothing on some architectures, it is required because

  *       on ports that support preemptable interrupt handlers it is required to

  *       raise the interrupt mask to the same level of the system mutual

@@ -88,11 +126,10 @@
  *       syscall from an interrupt handler.

  * @note This API must be invoked exclusively from interrupt handlers.

  */

-#define chSysLockI() sys_disable_from_isr()

+#define chSysLockI() sys_lock_from_isr()

 

 /**

- * Leaves the ChibiOS/RT system mutual exclusion zone from within an interrupt

- * handler.

+ * Leaves the kernel lock mode from within an interrupt handler.

  * @note This API may do nothing on some architectures, it is required because

  *       on ports that support preemptable interrupt handlers it is required to

  *       raise the interrupt mask to the same level of the system mutual

@@ -101,47 +138,7 @@
  *       syscall from an interrupt handler.

  * @note This API must be invoked exclusively from interrupt handlers.

  */

-#define chSysUnlockI() sys_enable_from_isr()

-

-#if defined(CH_USE_NESTED_LOCKS) || defined(_DOXYGEN_)

-/**

- * Enters the ChibiOS/RT system mutual exclusion zone.

- * @note The use of system mutual exclusion zone is not recommended in

- *       the user code, it is a better idea to use the semaphores or mutexes

- *       instead.

- * @note The code of this API is always inlined regardless the

- *       @p CH_OPTIMIZE_SPEED setting. This function is meant to be used in

- *       places where the performance is always preferred.

- * @see CH_USE_NESTED_LOCKS

- */

-#define chSysLockInline() {                                             \

-  if (currp->p_locks == 0) {                                            \

-    currp->p_locks++;                                                   \

-    sys_disable();                                                      \

-  }                                                                     \

-}

-

-/**

- * Leaves the ChibiOS/RT system mutual exclusion zone.

- * @note The use of system mutual exclusion zone is not recommended in

- *       the user code, it is a better idea to use the semaphores or mutexes

- *       instead.

- * @note The code of this API is always inlined regardless the

- *       @p CH_OPTIMIZE_SPEED setting. This function is meant to be used in

- *       places where the performance is always preferred.

- * @see CH_USE_NESTED_LOCKS

- */

-#define chSysUnlockInline() {                                           \

-  if (--currp->p_locks == 0)                                            \

-    sys_enable();                                                       \

-}

-

-#else /* defined(CH_USE_NESTED_LOCKS) || defined(_DOXYGEN_) */

-

-#define chSysLockInline() sys_disable()

-#define chSysUnlockInline() sys_enable()

-

-#endif /* !defined(CH_USE_NESTED_LOCKS) && !defined(_DOXYGEN_) */

+#define chSysUnlockI() sys_unlock_from_isr()

 

 /**

  * IRQ handler enter code.

@@ -163,14 +160,6 @@
  */

 #define CH_IRQ_HANDLER SYS_IRQ_HANDLER

 

-/*

- * Inlined code when CH_OPTIMIZE_SPEED is defined.
- */

-#if defined(CH_OPTIMIZE_SPEED)

-#define chSysLock() chSysLockInline()

-#define chSysUnlock() chSysUnlockInline()

-#endif /* defined(CH_OPTIMIZE_SPEED) */

-

 #ifdef __cplusplus

 extern "C" {

 #endif

diff --git a/src/templates/chcore.c b/src/templates/chcore.c
index 65d8e155d..84f0b7418 100644
--- a/src/templates/chcore.c
+++ b/src/templates/chcore.c
@@ -32,38 +32,32 @@
  */

 

 /**

- * Prints a message on the system console.
- * @param msg pointer to the message
+ * Port-related initialization code.

+ * @note This function is usually empty.
  */

-void sys_puts(char *msg) {

-}

-

-/**

- * Performs a context switch between two threads.

- * @param otp the thread to be switched out

- * @param ntp the thread to be switched in
- */

-void sys_switch(Thread *otp, Thread *ntp) {

+void sys_init(void){

 }

 

 /**

- * Kernel-unlock action. Usually this function just enables interrupts.
+ * Kernel-unlock action. Usually this function just disables interrupts but

+ * may perform more actions.
  */

-void sys_enable(void) {

+void sys_lock(void) {

 }

 

 /**

- * Kernel-lock action. Usually this function just disables interrupts.

+ * Kernel-unlock action. Usually this function just disables interrupts but

+ * may perform more actions.

  */

-void sys_disable(void) {

+void sys_unlock(void) {

 }

 

 /**

  * Kernel-lock action from an interrupt handler. This function is invoked

  * before invoking I-class APIs from interrupt handlers. The implementation

- * is architecture dependent, in its simplest form it is void.
+ * is architecture dependent, in its simplest form it is void.

  */

-void sys_disable_from_isr(void) {

+void sys_lock_from_isr(void) {

 }

 

 /**

@@ -71,7 +65,26 @@ void sys_disable_from_isr(void) {
  * after invoking I-class APIs from interrupt handlers. The implementation

  * is architecture dependent, in its simplest form it is void.

  */

-void sys_enable_from_isr(void) {

+void sys_unlock_from_isr(void) {

+}

+

+/**

+ * Disables all the interrupt sources.

+ * @note Of course non maskable interrupt sources are not included.
+ */

+void sys_disable_all() {

+}

+

+/**

+ * Disables the interrupt sources that are not supposed to preempt the kernel.
+ */

+void sys_disable(void) {

+}

+

+/**

+ * Enables all the interrupt sources.
+ */

+void sys_enable(void) {

 }

 

 /**

@@ -90,9 +103,24 @@ void sys_wait_for_interrupt(void) {
  */

 void sys_halt(void) {

 

-  sys_disable();

+  sys_disable_all();

   while (TRUE) {

   }

 }

 

+/**

+ * Performs a context switch between two threads.

+ * @param otp the thread to be switched out

+ * @param ntp the thread to be switched in

+ */

+void sys_switch(Thread *otp, Thread *ntp) {

+}

+

+/**

+ * Prints a message on the system console.

+ * @param msg pointer to the message

+ */

+void sys_puts(char *msg) {

+}

+

 /** @} */

diff --git a/src/templates/chcore.h b/src/templates/chcore.h
index d8d3614c8..dec2deee7 100644
--- a/src/templates/chcore.h
+++ b/src/templates/chcore.h
@@ -129,14 +129,18 @@ typedef struct {
 #ifdef __cplusplus

 extern "C" {

 #endif

-  void sys_puts(char *msg);

-  void sys_switch(Thread *otp, Thread *ntp);

-  void sys_enable(void);

+  void sys_init(void);

+  void sys_disable_all(void);

   void sys_disable(void);

+  void sys_enable(void);

+  void sys_lock(void);

+  void sys_unlock(void);

   void sys_disable_from_isr(void);

   void sys_enable_from_isr(void);

   void sys_wait_for_interrupt(void);

   void sys_halt(void);

+  void sys_switch(Thread *otp, Thread *ntp);

+  void sys_puts(char *msg);

 #ifdef __cplusplus

 }

 #endif