diff options
| -rw-r--r-- | demos/Win32-MinGW/chcore.h | 21 | ||||
| -rw-r--r-- | demos/Win32-MinGW/main.c | 2 | ||||
| -rw-r--r-- | docs/Doxyfile | 76 | ||||
| -rw-r--r-- | docs/ch.txt | 217 | ||||
| -rw-r--r-- | readme.txt | 4 | ||||
| -rw-r--r-- | src/chsys.c | 32 | ||||
| -rw-r--r-- | src/include/sys.h | 127 | ||||
| -rw-r--r-- | src/templates/chcore.c | 66 | ||||
| -rw-r--r-- | src/templates/chcore.h | 10 |
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
|