diff --git a/demos/LPC214x-GCC/main.c b/demos/LPC214x-GCC/main.c index a696b223f..c925671e9 100644 --- a/demos/LPC214x-GCC/main.c +++ b/demos/LPC214x-GCC/main.c @@ -23,7 +23,7 @@ #include "lpc214x_serial.h" #include "buzzer.h" -static BYTE8 waThread1[UserStackSize(16)]; +static BYTE8 waThread1[UserStackSize(32)]; static t_msg Thread1(void *arg) { @@ -40,7 +40,7 @@ static t_msg Thread1(void *arg) { return 0; } -static BYTE8 waThread2[UserStackSize(16)]; +static BYTE8 waThread2[UserStackSize(32)]; static t_msg Thread2(void *arg) { @@ -53,7 +53,7 @@ static t_msg Thread2(void *arg) { return 0; } -static BYTE8 waThread3[UserStackSize(16)]; +static BYTE8 waThread3[UserStackSize(32)]; static t_msg Thread3(void *arg) { diff --git a/docs/Doxyfile b/docs/Doxyfile index 6cc09c5d9..0bcdbdbf2 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -4,7 +4,7 @@ # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = ChibiOS/RT -PROJECT_NUMBER = "0.2.1 alpha" +PROJECT_NUMBER = "0.3.0 beta" OUTPUT_DIRECTORY = . CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English @@ -26,7 +26,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 MULTILINE_CPP_IS_BRIEF = NO @@ -34,7 +34,7 @@ DETAILS_AT_TOP = YES INHERIT_DOCS = NO SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 2 -ALIASES = +ALIASES = OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO BUILTIN_STL_SUPPORT = NO @@ -64,11 +64,11 @@ 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 -FILE_VERSION_FILTER = +FILE_VERSION_FILTER = #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- @@ -78,7 +78,7 @@ WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = +WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- @@ -115,15 +115,15 @@ FILE_PATTERNS = *.c \ *.py \ *.ddf RECURSIVE = YES -EXCLUDE = +EXCLUDE = EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXAMPLE_PATH = +EXCLUDE_PATTERNS = +EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = +IMAGE_PATH = ./img +INPUT_FILTER = +FILTER_PATTERNS = FILTER_SOURCE_FILES = NO #--------------------------------------------------------------------------- # configuration options related to source browsing @@ -141,20 +141,20 @@ 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 GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = +CHM_FILE = +HHC_LOCATION = GENERATE_CHI = NO BINARY_TOC = NO TOC_EXPAND = NO @@ -171,8 +171,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 = NO USE_PDFLATEX = NO LATEX_BATCHMODE = NO @@ -184,8 +184,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 #--------------------------------------------------------------------------- @@ -198,8 +198,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 @@ -211,16 +211,16 @@ 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 +# Configuration options related to the preprocessor #--------------------------------------------------------------------------- ENABLE_PREPROCESSING = YES MACRO_EXPANSION = NO EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = PREDEFINED = __JUST_STUBS__ \ __DOXIGEN__ \ CH_USE_VIRTUAL_TIMERS \ @@ -242,18 +242,18 @@ PREDEFINED = __JUST_STUBS__ \ CH_USE_MESSAGES \ CH_USE_MESSAGES_TIMEOUT \ CH_USE_MESSAGES_EVENT -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration::additions related to external references #--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = +TAGFILES = +GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = NO HIDE_UNDOC_RELATIONS = YES @@ -270,8 +270,8 @@ CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png -DOT_PATH = -DOTFILE_DIRS = +DOT_PATH = +DOTFILE_DIRS = MAX_DOT_GRAPH_WIDTH = 1024 MAX_DOT_GRAPH_HEIGHT = 1024 MAX_DOT_GRAPH_DEPTH = 1000 @@ -280,6 +280,6 @@ DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES DOT_CLEANUP = YES #--------------------------------------------------------------------------- -# Configuration::additions related to the search engine +# Configuration::additions related to the search engine #--------------------------------------------------------------------------- SEARCHENGINE = NO diff --git a/docs/ch.txt b/docs/ch.txt index c259357eb..38d6d589a 100644 --- a/docs/ch.txt +++ b/docs/ch.txt @@ -47,8 +47,77 @@ * memory image. *
  • Almost totally written in C with little ASM code required for ports.
    • * + * + * ChibiOS/RT architecture:

    + * @subpage Concepts */ +/** + * @page Concepts Concepts + * @{ + * @section naming Naming Conventions + * ChibiOS/RT APIs are all named following this convention: + * \a ch\\\(). + * The possible groups are: \a Sys, \a Sch, \a VT, \a Thd, \a Sem, \a Evt, + * \a Msg, \a IQ, \a OQ, \a HQ,\a FDD, \a HDD. + * The suffix is not present for normal APIs but can be one of + * the following: "I" for APIs meant to be invoked from an interrupt handler + * or within the system mutex zone but not from user code, "S" for APIs only + * useable from within the system mutex zone but not from interrupt handlers + * or user code. The APIs without suffix can be invoked only from the user + * code.
    + * Examples: \p chThdCreate(), \p chSemSignalI(), \p chIQGetTimeout(). + * + * @section scheduling Scheduling + * The strategy is very simple the currently ready thread with the highest + * priority is executed. If more than one thread with equal priority are + * eligible for execution then they are executed in a round-robin way, the + * CPU time slice constant is configurable. The ready list is a double linked + * list of threads ordered by priority. + * @image html readylist.png + * 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 warea Thread Working Area + * Each thread has its own stack, a Thread structure and a registers dump + * structure. 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.
    + + * @image html workspace.png + *
    + * Note that the registers dump is only present when the Thread is not + * running, the context switching is done by pushing the registers on the + * stack of the switched-out thread and popping the registers of the + * switched-in thread from its stack. + * + * @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, + * messages or events. + */ +/** @} */ + /** * @defgroup Kernel Kernel * @{ diff --git a/docs/img/readylist.png b/docs/img/readylist.png new file mode 100644 index 000000000..4d852388f Binary files /dev/null and b/docs/img/readylist.png differ diff --git a/docs/img/workspace.png b/docs/img/workspace.png new file mode 100644 index 000000000..03149b7bd Binary files /dev/null and b/docs/img/workspace.png differ diff --git a/readme.txt b/readme.txt index 07fc0c508..4508b2a21 100644 --- a/readme.txt +++ b/readme.txt @@ -32,6 +32,15 @@ LPC214x-GCC - ChibiOS/RT port for ARM7 LPC2148, the demo targets the *** Releases *** ***************************************************************************** +*** 0.3.0 *** +- ChibiOS/RT goes beta. +- Diet for the threads code, some simple APIs become macros. +- Thread Local Storage implemented as a single API: chThdLS(). + The API simply returns a pointer into the thread working area, see the + documentation on the web site. +- Moved some documentation and images from the web site into the Doxigen + generated HTMLs. + *** 0.2.1 *** - Optimizations in the RT semaphores subsystem. The support for this subsystem should still be considered experimental and further changes may diff --git a/src/chsleep.c b/src/chsleep.c index 9fedd0244..5814410f3 100644 --- a/src/chsleep.c +++ b/src/chsleep.c @@ -62,11 +62,11 @@ t_time chSysGetTime(void) { * option is enabled in \p chconf.h. */ void chThdSleepUntil(t_time time) { - VirtualTimer t; + VirtualTimer vt; chSysLock(); - chVTSetI(&t, (t_time)(time - stime), (t_vtfunc)chSchReadyI, currp); + chVTSetI(&vt, (t_time)(time - stime), (t_vtfunc)chSchReadyI, currp); chSchGoSleepI(PRSLEEP); chSysUnlock(); diff --git a/src/chthreads.c b/src/chthreads.c index 59c361116..a439eb5b4 100644 --- a/src/chthreads.c +++ b/src/chthreads.c @@ -129,17 +129,6 @@ Thread *chThdCreate(t_prio prio, t_tmode mode, void *workspace, return tp; } -/** - * Verifies if the specified thread is in the \p PREXIT state. - * @param tp the pointer to the thread - * @return \p TRUE if the thread is ended else \p FALSE. \p TRUE ensures that - * a subsequent call to \p chThdWait() would not block. - */ -BOOL chThdTerminated(Thread *tp) { - - return tp->p_state == PREXIT; -} - #ifdef CH_USE_RESUME /** * Resumes a thread created with the \p P_SUSPENDED option. @@ -176,17 +165,6 @@ void chThdTerminate(Thread *tp) { chSysUnlock(); } - -/** - * Verifies if the current thread has a termination request pending. - * @return \p TRUE if the termination was requested. The thread should terminate - * as soon it is ready to do so. - */ -BOOL chThdShouldTerminate(void) { - - return currp->p_flags & P_TERMINATE ? TRUE : FALSE; -} - #endif /** @@ -234,31 +212,4 @@ t_msg chThdWait(Thread *tp) { } #endif /* CH_USE_WAITEXIT */ -#ifdef CH_USE_EXIT_EVENT -/** - * Returns the exit event source for the specified thread. The source is - * signaled when the thread terminates. - * @param tp the pointer to the thread - * @note When registering on a thread termination make sure the thread - * is still alive, if you do that after the thread termination - * then you would miss the event. There are two ways to ensure - * this:
    - *
      - *
    • Create the thread suspended, register on the event source - * and then resume the thread (recommended).
      • - *
    • Create the thread with a lower priority then register on it. - * This does not work if the hardware is capable of multiple - * physical threads.
      • - *
    - * @note You dont need to unregister from a terminated thread because - * the event source becomes inactive. - * @note The function is available only if the \p CH_USE_EXIT_EVENT - * option is enabled in \p chconf.h. - */ -EventSource *chThdGetExitEventSource(Thread *tp) { - - return &tp->p_exitesource; -} -#endif /* CH_USE_EXIT_EVENT */ - /** @} */ diff --git a/src/include/threads.h b/src/include/threads.h index f170ce368..688ce579a 100644 --- a/src/include/threads.h +++ b/src/include/threads.h @@ -182,19 +182,55 @@ static INLINE void enqueue(Thread *tp, ThreadsQueue *tqp) { /* * Threads APIs. */ -#define chThdSelf() currp Thread *chThdCreate(t_prio prio, t_tmode mode, void *workspace, t_size wsize, t_tfunc pf, void *arg); void chThdResume(Thread *tp); -void chThdTerminate(Thread *tp); -BOOL chThdShouldTerminate(void); -BOOL chThdTerminated(Thread *tp); void chThdExit(t_msg msg); + +/** Returns the pointer to the \p Thread currently in execution.*/ +#define chThdSelf() currp + +/** Returns the pointer to the \p Thread local storage area, if any.*/ +#define chThdLS() (void *)(currp + 1) + +/** Verifies if the specified thread is in the \p PREXIT state.*/ +#define chThdTerminated(tp) ((tp)->p_state == PREXIT) + +#ifdef CH_USE_TERMINATE +/** + * Verifies if the current thread has a termination request pending. + */ +#define chThdShouldTerminate() (currp->p_flags & P_TERMINATE) + +void chThdTerminate(Thread *tp); +#endif + #ifdef CH_USE_WAITEXIT t_msg chThdWait(Thread *tp); #endif + #ifdef CH_USE_EXIT_EVENT -EventSource *chThdGetExitEventSource(Thread *tp); +/** + * Returns the exit event source for the specified thread. The source is + * signaled when the thread terminates. + * @param tp the pointer to the thread + * @note When registering on a thread termination make sure the thread + * is still alive, if you do that after the thread termination + * then you would miss the event. There are two ways to ensure + * this:
    + *
      + *
    • Create the thread suspended, register on the event source + * and then resume the thread (recommended).
      • + *
    • Create the thread with a lower priority then register on it. + * This does not work if the hardware is capable of multiple + * physical threads.
      • + *
    + * @note You dont need to unregister from a terminated thread because + * the event source becomes inactive. + * @note The function is available only if the \p CH_USE_EXIT_EVENT + * option is enabled in \p chconf.h. + */ +#define chThdGetExitEventSource(tp) (&(tp)->p_exitesource) #endif #endif /* _THREADS_H_ */ diff --git a/src/templates/chcore.c b/src/templates/chcore.c index 29a809378..e23cf1bfe 100644 --- a/src/templates/chcore.c +++ b/src/templates/chcore.c @@ -37,7 +37,7 @@ void chSysPause(void) {} /** - * Abonormal system termination handler. Invoked by the ChobiOS/RT when an + * Abonormal system termination handler. Invoked by the ChibiOS/RT when an * abnormal unrecoverable condition is met. */ void chSysHalt(void) {} diff --git a/src/templates/chcore.h b/src/templates/chcore.h index 895e2b685..bb901b1ec 100644 --- a/src/templates/chcore.h +++ b/src/templates/chcore.h @@ -39,7 +39,7 @@ struct stackregs { } /** - * Enters the ChobiOS/RT system mutual exclusion zone, the implementation is + * Enters the ChibiOS/RT system mutual exclusion zone, the implementation is * architecture dependent, on single core systems usually this function * just disables the interrupts. * @note The code in the system mutual exclusion zone must be as light and @@ -50,7 +50,7 @@ struct stackregs { #define chSysLock() /** - * Leaves the ChobiOS/RT system mutual exclusion zone, the implementation is + * Leaves the ChibiOS/RT system mutual exclusion zone, the implementation is * architecture dependent, on single core systems usually this function * just enables the interrupts. * @note The code in the system mutual exclusion zone must be as light and