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

17 files changed, 66 insertions, 65 deletions

diff --git a/docs/src/articles.dox b/docs/src/articles.dox
index 9d3aee8d0..42d1606ae 100644
--- a/docs/src/articles.dox
+++ b/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

diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox
index 6ddc8035f..9c09041a7 100644
--- a/docs/src/concepts.dox
+++ b/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()"];

diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox
index 0774e0e7e..8bbd74a2d 100644
--- a/docs/src/createthread.dox
+++ b/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

- * be reused. Static threads are ideal for safety applications because there is

- * no risk of a memory allocation failure because progressive heap

+ * Note that the memory allocated to myThread() is statically defined and

+ * cannot be reused. Static threads are ideal for safety applications because

+ * 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. */

-                                   128,         /* Stack size.          */

-                                   NORMALPRIO,  /* Initial priority.    */

-                                   myThread,    /* Thread function.     */

-                                   NULL);       /* Thread parameter.    */

+  Thread *tp = chThdCreateFromHeap(NULL,            /* NULL = Default heap. */

+                                   THD_WA_SIZE(128),/* Stack size.          */

+                                   NORMALPRIO,      /* Initial priority.    */

+                                   myThread,        /* Thread function.     */

+                                   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. */

   

diff --git a/docs/src/debug.dox b/docs/src/debug.dox
index 46a67dfb2..341e852c6 100644
--- a/docs/src/debug.dox
+++ b/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

- *   time and test often, if you add too many things at once a small problem

- *   can become a debugging nightmare. Follow the cycle: think, implement,

- *   test, repeat.

+ * - Start your application from an existing demo, add things one at a

+ *   time and test often, if you add too many things at once then finding a

+ *   small problem can become a debugging nightmare. Follow the cycle: think,

+ *   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

diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox
index 6eec61e75..dd91d8cf8 100644
--- a/docs/src/integrationguide.dox
+++ b/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,

- * in that case you have the problem to integrate the OS source code into

- * your application.

+ * a different runtime framework or if you want to use a different build

+ * system, in that case you have the problem to integrate the OS source

+ * 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

- *   could be both C source files and assembler source files and that some

- *   architectures have an extra directories layer containing files required

- *   for a specific platform.

+ *   <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.

+ *   Note that those could be both C source files and assembler source files

+ *   and that some architectures have an extra directories layer containing

+ *   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

diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox
index 6ac74116e..759425b4e 100644
--- a/docs/src/jitter.dox
+++ b/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

- * to handle the bulk of the work.<br>

+ * An handler should just serve the interrupt and wakeup a dedicated thread in

+ * 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>

diff --git a/docs/src/lifecycle.dox b/docs/src/lifecycle.dox
index d96795b21..18875e7da 100644
--- a/docs/src/lifecycle.dox
+++ b/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

- *   the available allocators (see @ref heaps, @ref pools).

+ * - <b>Dynamic threads</b>. Dynamic threads are allocated at runtime from one

+ *   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

- * with a reference counter. The memory of a thread, if dynamic, is released

+ * 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 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

- * that another threads performs a @p chThdWait() on the dynamic thread.<br>

+ * As you can see the easiest way to ensure that the memory is released is

+ * 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

- * terminated ones.

+ * scans the threads through the @ref registry subsystem, scanning the registry

+ * has the side effect to release the zombies (detached and then terminated

+ * threads).

  */

diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox
index 7f0b90e21..260732e19 100644
--- a/docs/src/mutualexcl.dox
+++ b/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

- *   you don't want to enable the mutexes too because space constraints.

+ * - The semaphores code is "already there" if you use the I/O queues or

+ *   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

- * terminology to avoid confusion with counting semaphores), are the mechanism

- * intended as general solution for Mutual Exclusion.

+ * The mutexes are the mechanism intended as the most 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

diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox
index 3af53c4cf..170ca75a3 100644
--- a/docs/src/portguide.dox
+++ b/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.

  * .

diff --git a/docs/src/roundrobin.dox b/docs/src/roundrobin.dox
index 8158a5c03..df57ec971 100644
--- a/docs/src/roundrobin.dox
+++ b/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

- *   all the other threads at the same priority level.

+ *   (see @ref thread_states), when the thread is awakened it goes behind

+ *   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

- *   other threads at the same priority level.

+ *   thread is automatically reinserted in the ready list behind any

+ *   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.

diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox
index 87c404f7a..d87d183f6 100644
--- a/docs/src/stacks.dox
+++ b/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

- * leads to crashes or, worst scenario, hard to track instability.

+ * Assigning too much space to a stack is a waste of RAM, assigning too little

+ * 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

- *   end of your development cycle.

+ *   are really starved on RAM. Anyway, it is best to optimize stack space

+ *   at the very end of your development cycle.

  * .

  */

diff --git a/os/hal/include/mii.h b/os/hal/include/mii.h
index bc3b4ff6a..87612273a 100644
--- a/os/hal/include/mii.h
+++ b/os/hal/include/mii.h
@@ -183,7 +183,6 @@
 #define MII_AM79C875_ID   0x00225540

 #define MII_KS8721_ID     0x00221610

 

-

 #endif /* _MII_H_ */

 

 /*-* @} */

diff --git a/os/hal/platforms/LPC11xx/platform.dox b/os/hal/platforms/LPC11xx/platform.dox
index 3114d8732..e41fffa13 100644
--- a/os/hal/platforms/LPC11xx/platform.dox
+++ b/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.

diff --git a/os/hal/platforms/LPC13xx/platform.dox b/os/hal/platforms/LPC13xx/platform.dox
index cd7d0bdfd..8fc0cf389 100644
--- a/os/hal/platforms/LPC13xx/platform.dox
+++ b/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.

diff --git a/os/hal/platforms/STM32/platform.dox b/os/hal/platforms/STM32/platform.dox
index 8c699443e..8fe156035 100644
--- a/os/hal/platforms/STM32/platform.dox
+++ b/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

  */

diff --git a/os/various/memstreams.h b/os/various/memstreams.h
index ce1a8d69c..81b7127a7 100644
--- a/os/various/memstreams.h
+++ b/os/various/memstreams.h
@@ -18,7 +18,7 @@
 */

 

 /**

- * @file    memstreams.c

+ * @file    memstreams.h

  * @brief   Memory streams structures and macros.

  

  * @addtogroup memory_streams

diff --git a/readme.txt b/readme.txt
index 06cd0484d..f5111703d 100644
--- a/readme.txt
+++ b/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).