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

docs/src/articles.dox

@@ -19,7 +19,7 @@
 
 /**
  * @page articles Articles and Code Samples
- * ChibiOS/RT Articles and Code Examples:
+ * ChibiOS/RT Articles and Code Samples:
  * - @subpage page_general
  * - @subpage page_kb
  * - @subpage page_howtos

docs/src/concepts.dox

@@ -229,7 +229,7 @@
       start -> suspend [label="chThdInit()", constraint=false];
       start -> run [label="chThdCreate()"];
       start -> ready [label="chThdCreate()"];
-      run -> ready [label="Reschedulation", dir="both"];
+      run -> ready [label="Reschedule", dir="both"];
       suspend -> run [label="chThdResume()"];
       suspend -> ready [label="chThdResume()"];
       run -> sleep [label="chSchGoSleepS()"];

docs/src/createthread.dox

@@ -55,7 +55,7 @@ static WORKING_AREA(myThreadWorkingArea, 128);
                                  myThread,      /* Thread function.     */
                                  NULL);         /* Thread parameter.    */
  * @endcode
- * Tre variable tp receives the pointer to the thread object, it is taken
+ * The variable tp receives the pointer to the thread object, it is taken
  * by other APIs as parameter.<br>
  * Now a complete example:
  * @code
@@ -93,19 +93,19 @@ int main(int argc, char *argv[]) {
   .
 }
  * @endcode
- * Note that is memory allocated to myThread() is statically defined and cannot
+ * Note that the memory allocated to myThread() is statically defined and
- * be reused. Static threads are ideal for safety applications because there is
+ * cannot be reused. Static threads are ideal for safety applications because
- * no risk of a memory allocation failure because progressive heap
+ * there is no risk of a memory allocation failure because progressive heap
  * fragmentation.
  *
  * <h2>Creating a dynamic thread using the heap allocator</h2>
  * In order to create a thread from a memory heap is very easy:
  * @code
-  Thread *tp = chThdCreateFromHeap(NULL,        /* NULL = Default heap. */
+  Thread *tp = chThdCreateFromHeap(NULL,            /* NULL = Default heap. */
-                                   128,         /* Stack size.          */
+                                   THD_WA_SIZE(128),/* Stack size.          */
-                                   NORMALPRIO,  /* Initial priority.    */
+                                   NORMALPRIO,      /* Initial priority.    */
-                                   myThread,    /* Thread function.     */
+                                   myThread,        /* Thread function.     */
-                                   NULL);       /* Thread parameter.    */
+                                   NULL);           /* Thread parameter.    */
  * @endcode
  * The memory is allocated from the spawned heap and the thread is started.
  * Note that the memory is not freed when the thread terminates but when the
@@ -127,7 +127,8 @@ static msg_t myThread(void *arg) {
 
 int main(int argc, char *argv[]) {
 
-  Thread *tp = chThdCreateFromHeap(NULL, 128, NORMALPRIO+1, myThread, NULL);
+  Thread *tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(128), NORMALPRIO+1,
+                                   myThread, NULL);
   if (tp == NULL)
     chSysHalt();    /* Memory exausted. */
   

docs/src/debug.dox

@@ -125,10 +125,10 @@
  *   common RTOS related tasks, under "./testhal" there are examples
  *   regarding the various device drivers, the various demos contain
  *   good code samples too).
- * - Start your application from an existing demos, add things one piece at
+ * - Start your application from an existing demo, add things one at a
- *   time and test often, if you add too many things at once a small problem
+ *   time and test often, if you add too many things at once then finding a
- *   can become a debugging nightmare. Follow the cycle: think, implement,
+ *   small problem can become a debugging nightmare. Follow the cycle: think,
- *   test, repeat.
+ *   implement, test, repeat.
  * - If you are stuck for too much time then consider asking for advice.
  * - Report bugs and problems, bugs can be fixed, problems can become new
  *   articles in the documentation (this and other documentation articles

docs/src/integrationguide.dox

@@ -24,9 +24,9 @@
  * integration effort, you are simply using the existing makefiles, the
  * default startup files etc, minimal effort.<br>
  * The matter is very different if you are going to integrate the OS into
- * a different runtime framework or want to use a different build system,
+ * a different runtime framework or if you want to use a different build
- * in that case you have the problem to integrate the OS source code into
+ * system, in that case you have the problem to integrate the OS source
- * your application.
+ * code into your application.
  *
  * <h2>What this guide does not cover</h2>
  * This guide has a limited scope, the following topics are handled elsewhere:
@@ -55,16 +55,16 @@
  *   subsystems. Unused subsystems can be excluded from the kernel
  *   configuration file @p chconf.h.
  * - All the source files contained under
- *   <tt>./os/<i>@<compiler@></i>/<i>@<architecture@></i></tt>. Note that those
+ *   <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
- *   could be both C source files and assembler source files and that some
+ *   Note that those could be both C source files and assembler source files
- *   architectures have an extra directories layer containing files required
+ *   and that some architectures have an extra directories layer containing
- *   for a specific platform.
+ *   files required for a specific platform.
  * .
  * You also need to add to the compiler options the following paths for
  * searching header files:
  * - The portable kernel headers <tt>./os/kernel/include</tt>.
  * - The port layer headers
- *   <tt>./os/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
+ *   <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
  * .
  * @section integrationguide_hal Integrating the HAL
  * If, in addition to the kernel as described in the previous section, you also
@@ -86,7 +86,7 @@
  * .
  * You also need to add to the compiler options the following paths for
  * searching header files:
- * - The portable HAL headers <tt>./os/hal/src</tt>.
+ * - The portable HAL headers <tt>./os/hal/include</tt>.
  * - The platform layer headers
  *   <tt>./os/hal/platforms/<i>@<platform@></i></tt>.
  * - The board description headers

docs/src/jitter.dox

@@ -101,8 +101,8 @@
  * An obvious mitigation action is to optimize the interrupt handler code as
  * much as possible for speed.<br>
  * Complex actions should never be performed in interrupt handlers.
- * An handler should serve the interrupt and wakeup a dedicated thread in order
+ * An handler should just serve the interrupt and wakeup a dedicated thread in
- * to handle the bulk of the work.<br>
+ * order to handle the bulk of the work.<br>
  * Another possible mitigation action is to evaluate if a specific interrupt
  * handler really needs to interact with the OS, if the handler uses full
  * stand-alone code then it is possible to remove the OS related overhead.<br>

docs/src/lifecycle.dox

@@ -20,17 +20,17 @@
 /**
  * @page article_lifecycle Threads Lifecycle
  * In ChibiOS/RT threads are divided in two categories:
- * - Static threads. The memory used for static threads is allocated at
+ * - <b>Static threads</b>. The memory used for static threads is allocated at
  *   compile time so static threads are always there, there is no management
  *   to be done.
- * - Dynamic threads. Dynamic threads are allocated at runtime from one of
+ * - <b>Dynamic threads</b>. Dynamic threads are allocated at runtime from one
- *   the available allocators (see @ref heaps, @ref pools).
+ *   of the available allocators (see @ref heaps, @ref pools).
  * .
  * Dynamic threads create the problem of who is responsible of releasing
  * their memory because a thread cannot dispose its own memory.<br>
  * This is handled in ChibiOS/RT through the mechanism of "thread references",
- * When the @p CH_USE_DYNAMIC option is enabled the threads becomes objects
+ * When the @p CH_USE_DYNAMIC option is enabled the threads become objects
- * with a reference counter. The memory of a thread, if dynamic, is released
+ * with a reference counter. The memory of a thread, if dynamic, is freed
  * when the last reference to the thread is released while the thread is in
  * its @p THD_STATE_FINAL state.<br>
  * The following diagram explains the mechanism:
@@ -57,11 +57,12 @@
   }
  * @enddot
  * <br>
- * As you can see the simplest way to ensure that the memory is released is
+ * As you can see the easiest way to ensure that the memory is released is
- * that another threads performs a @p chThdWait() on the dynamic thread.<br>
+ * to make another thread perform a @p chThdWait() on the dynamic thread.<br>
  * If all the references to the threads are released while the thread is
  * still alive then the thread goes in a "detached" state and its memory
  * cannot be recovered unless there is a dedicated task in the system that
- * scans the threads through the @ref registry subsystem and frees the
+ * scans the threads through the @ref registry subsystem, scanning the registry
- * terminated ones.
+ * has the side effect to release the zombies (detached and then terminated
+ * threads).
  */

docs/src/mutualexcl.dox

@@ -77,11 +77,12 @@
  * running at thread level. Usually a thread waits on a semaphore that is
  * signaled asynchronously by an interrupt handler.<br>
  * The semaphores can, however, be used as simple mutexes by initializing
- * counter to one.
+ * the semaphore counter to one.
  *
  * <h3>Advantages</h3>
- * - The semaphores code is "already there" if you use the I/O queues and
+ * - The semaphores code is "already there" if you use the I/O queues or
- *   you don't want to enable the mutexes too because space constraints.
+ *   mailboxes and you don't want to enable the mutexes too in order to save
+ *   space.
  * - Semaphores are lighter than mutexes because their queues are FIFO
  *   ordered and do not have any overhead caused by the priority inheritance
  *   algorithm.
@@ -112,14 +113,13 @@
  * @endcode
  *
  * <h2>Mutual exclusion by Mutexes</h2>
- * The mutexes, also known as binary semaphores (we choose to not use this
+ * The mutexes are the mechanism intended as the most general solution for
- * terminology to avoid confusion with counting semaphores), are the mechanism
+ * Mutual Exclusion.
- * intended as general solution for Mutual Exclusion.
  *
  * <h3>Advantages</h3>
  * - Mutexes implement the Priority Inheritance algorithm that is an important
  *   tool in reducing jitter and improve overall system response time (it is
- *   not a magic solution, just a tool for the system designer).
+ *   not a magic solution, just another tool for the system designer).
  * .
  * <h3>Disadvantages</h3>
  * - Heaviest among all the possible choices. The Priority Inheritance method

docs/src/portguide.dox

@@ -51,7 +51,7 @@
  *     some hardware specific initialization code then put it here.
  *   .
  * -# Create a new directory under the ChibiOS/RT installation directory:
- *    <code>./projects/<i>@<my_app_name@></i></code>
+ *    <tt>./projects/<i>@<my_app_name@></i></tt>
  * -# Copy an existing demo code under the newly created directory.
  * -# Customize the demo:
  *   - @p Makefile You may edit this file in order to remove the test related
@@ -78,19 +78,19 @@
  * core (a common example: ARM7) of a supported microcontroller but has
  * differences in the internal peripherals.<br>
  * If this is your case proceed as follow:
- * -# Create a new directory under @p <code>./os/io/platforms</code> and
+ * -# Create a new directory under @p <tt>./os/io/platforms</tt> and
  *    name it with the microcontroller name (or family name).<br>
  *    In case of the ARM-based microcontroller you also need to create a
  *    equally named directory under
- *    @p <code>./os/ports/<i>@<compiler@></i>/<i>@<arch@></i></code> and
+ *    @p <tt>./os/ports/<i>@<compiler@></i>/<i>@<arch@></i></tt> and
  *    put there the microcontroller related files such as the vectors table,
  *    see the existing ports as example.
  * -# Copy into the newly created directory the most closely related existing
  *    chip port or the naked template files from
- *    @p <code>./os/io/templates</code>.
+ *    @p <tt>./os/io/templates</tt>.
  * -# Work out the differences in the drivers or implement them if you started
  *    from the templates.
- * -# Edit/create the documentation file @p <code>platform.dox</code>, this
+ * -# Edit/create the documentation file @p <tt>platform.dox</tt>, this
  *    is required if you want to regenerate this documentation including
  *    your work.
  * .

docs/src/roundrobin.dox

@@ -23,27 +23,27 @@
  * same priority level and schedules them using an <i>aggressive</i>
  * round-robin strategy.<br>
  * The strategy is defined as aggressive because any scheduling event
- * can cause the round-robin threads to rotate.<br>
+ * causes the round-robin threads to rotate.<br>
  * A round-robin rotation can happen because of the following events:
  * - The currently executed thread voluntarily invokes the @p chThdYield()
  *   API in order to allow the execution of another thread at the same
  *   priority level, if any.
  * - The currently executed thread voluntarily goes into a sleep state
- *   (see @ref thread_states), when the thread is waken it goes behind
+ *   (see @ref thread_states), when the thread is awakened it goes behind
- *   all the other threads at the same priority level.
+ *   any other thread at the same priority level.
  * - The currently executed thread is preempted by an higher priority
  *   thread, the thread is reinserted in the ready list (see @ref scheduling)
- *   behind all the other threads at the same priority level.
+ *   behind any other thread at the same priority level.
  * - If the @p CH_TIME_QUANTUM configuration constant is set to a value
  *   greater than zero and if the specified time quantum expired and if
  *   a thread with equal priority is ready then the currently executing
- *   thread is automatically reinserted in the ready list behind all the
+ *   thread is automatically reinserted in the ready list behind any
- *   other threads at the same priority level.
+ *   other thread at the same priority level.
  * .
  * As you can see the @p CH_TIME_QUANTUM setting is really useful only if
  * there are threads at the same priority level that can run not preempted
  * for long periods of time and that do not explicitly yield using
- * @p chThdYield(). Because of this you should consider to set
+ * @p chThdYield(). Because of this you should consider setting
  * @p CH_TIME_QUANTUM to zero in your configuration file, this makes the
  * kernel much faster and smaller and <b>does not</b> forbid the use of
  * multiple threads at the same priority level.

docs/src/stacks.dox

@@ -19,7 +19,7 @@
 
 /**
  * @page article_stacks Stacks and stack sizes
- * In a RTOS like ChibiOS/RT there are several dedicated stacks, each stack
+ * In an RTOS like ChibiOS/RT there are several dedicated stacks, each stack
  * has a dedicated RAM space that must have a correctly sized assigned area.
  * <h2>The stacks</h2>
  * There are several stacks in the systems, some are always present, some
@@ -43,8 +43,8 @@
  * The most critical thing when writing an embedded multithreaded application
  * is to determine the correct stack size for main, threads and, when present,
  * interrupts.<br>
- * Assign too much space to a stack wastes RAM, assign too little space
+ * Assigning too much space to a stack is a waste of RAM, assigning too little
- * leads to crashes or, worst scenario, hard to track instability.
+ * space leads to crashes or, worst scenario, hard to track instability.
  *
  * <h2>Assigning the correct size</h2>
  * You may try to examine the asm listings in order to calculate the exact
@@ -101,7 +101,7 @@
  *   to this value. Resizing of the global interrupt stack may be required
  *   instead.
  * - Often is a good idea to have some extra space in stacks unless you
- *   are really starved on RAM. Anyway optimize stack space at the very
+ *   are really starved on RAM. Anyway, it is best to optimize stack space
- *   end of your development cycle.
+ *   at the very end of your development cycle.
  * .
  */

os/hal/include/mii.h

@@ -183,7 +183,6 @@
 #define MII_AM79C875_ID   0x00225540
 #define MII_KS8721_ID     0x00221610
 
-
 #endif /* _MII_H_ */
 
 /*-* @} */

os/hal/platforms/LPC11xx/platform.dox

@@ -50,7 +50,6 @@
  * - @p PAL_MODE_RESET.
  * - @p PAL_MODE_UNCONNECTED.
  * - @p PAL_MODE_INPUT.
- * - @p PAL_MODE_INPUT_ANALOG.
  * - @p PAL_MODE_OUTPUT_PUSHPULL.
  * .
  * Any attempt to setup an invalid mode is ignored.

os/hal/platforms/LPC13xx/platform.dox

@@ -50,7 +50,6 @@
  * - @p PAL_MODE_RESET.
  * - @p PAL_MODE_UNCONNECTED.
  * - @p PAL_MODE_INPUT.
- * - @p PAL_MODE_INPUT_ANALOG.
  * - @p PAL_MODE_OUTPUT_PUSHPULL.
  * .
  * Any attempt to setup an invalid mode is ignored.

os/hal/platforms/STM32/platform.dox

@@ -94,7 +94,7 @@
  * @defgroup STM32_DMA STM32 DMA Support
  * @brief DMA support.
  * @details The DMA helper driver allows to stop the DMA clock when no other
- *          drivers require its services.
+ *          driver requires its services.
  *
  * @ingroup STM32
  */

os/various/memstreams.h

@@ -18,7 +18,7 @@
 */
 
 /**
- * @file    memstreams.c
+ * @file    memstreams.h
  * @brief   Memory streams structures and macros.
  
  * @addtogroup memory_streams

readme.txt

@@ -79,6 +79,8 @@
   the new compiler shows a general performance regression except in one
   test case.
 - Added credits page to the documentation.
+- Performed another documentation revision cycle, fixed more bad English and
+  few errors.
 
 *** 1.5.6 ***
 - FIX: Fixed centralized ARM makefile (bug 2992747)(backported in 1.4.3).