git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1931 35acf78f-673a-0410-8e92-d51de3d6d3f4
This commit is contained in:
gdisirio
parent
b5b34a5b9b
commit
88d93ba5bf
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()"];
|
||||
|
|
|
|||
|
|
@ -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,16 +93,16 @@ 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. */
|
||||
THD_WA_SIZE(128),/* Stack size. */
|
||||
NORMALPRIO, /* Initial priority. */
|
||||
myThread, /* Thread function. */
|
||||
NULL); /* Thread parameter. */
|
||||
|
|
@ -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. */
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* .
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* .
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -183,7 +183,6 @@
|
|||
#define MII_AM79C875_ID 0x00225540
|
||||
#define MII_KS8721_ID 0x00221610
|
||||
|
||||
|
||||
#endif /* _MII_H_ */
|
||||
|
||||
/*-* @} */
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@
|
|||
*/
|
||||
|
||||
/**
|
||||
* @file memstreams.c
|
||||
* @file memstreams.h
|
||||
* @brief Memory streams structures and macros.
|
||||
|
||||
* @addtogroup memory_streams
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in New Issue