From 88d93ba5bf533bfd49df40ba7998b747d1fbadc2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 17 May 2010 15:02:27 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1931 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 2 +- docs/src/concepts.dox | 2 +- docs/src/createthread.dox | 21 +++++++++++---------- docs/src/debug.dox | 8 ++++---- docs/src/integrationguide.dox | 18 +++++++++--------- docs/src/jitter.dox | 4 ++-- docs/src/lifecycle.dox | 19 ++++++++++--------- docs/src/mutualexcl.dox | 14 +++++++------- docs/src/portguide.dox | 10 +++++----- docs/src/roundrobin.dox | 14 +++++++------- docs/src/stacks.dox | 10 +++++----- os/hal/include/mii.h | 1 - os/hal/platforms/LPC11xx/platform.dox | 1 - os/hal/platforms/LPC13xx/platform.dox | 1 - os/hal/platforms/STM32/platform.dox | 2 +- os/various/memstreams.h | 2 +- readme.txt | 2 ++ 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.
* 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. * *

Creating a dynamic thread using the heap allocator

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

What this guide does not cover

* 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 - * ./os/@/@. 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. + * ./os/ports/@/@. + * 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 ./os/kernel/include. * - The port layer headers - * ./os/@/@. + * ./os/ports/@/@. * . * @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 ./os/hal/src. + * - The portable HAL headers ./os/hal/include. * - The platform layer headers * ./os/hal/platforms/@. * - 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.
* 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.
+ * An handler should just serve the interrupt and wakeup a dedicated thread in + * order to handle the bulk of the work.
* 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.
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 + * - Static threads. 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). + * - Dynamic threads. 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.
* 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.
* The following diagram explains the mechanism: @@ -57,11 +57,12 @@ } * @enddot *
- * 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.
+ * 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.
* 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.
* The semaphores can, however, be used as simple mutexes by initializing - * counter to one. + * the semaphore counter to one. * *

Advantages

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

Mutual exclusion by Mutexes

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

Advantages

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

Disadvantages

* - 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: - * ./projects/@ + * ./projects/@ * -# 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.
* If this is your case proceed as follow: - * -# Create a new directory under @p ./os/io/platforms and + * -# Create a new directory under @p ./os/io/platforms and * name it with the microcontroller name (or family name).
* In case of the ARM-based microcontroller you also need to create a * equally named directory under - * @p ./os/ports/@/@ and + * @p ./os/ports/@/@ 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 ./os/io/templates. + * @p ./os/io/templates. * -# Work out the differences in the drivers or implement them if you started * from the templates. - * -# Edit/create the documentation file @p platform.dox, this + * -# Edit/create the documentation file @p platform.dox, 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 aggressive * round-robin strategy.
* The strategy is defined as aggressive because any scheduling event - * can cause the round-robin threads to rotate.
+ * causes the round-robin threads to rotate.
* 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 does not 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. *

The stacks

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

Assigning the correct size

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