From 0810f1daac3c33d194d573d82ec436021e3e7255 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 19 Jan 2009 13:31:37 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@643 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 50 +++++++++++++++++++++++++++++++++++++++ docs/src/saveram.dox | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 docs/src/atomic.dox create mode 100644 docs/src/saveram.dox (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox new file mode 100644 index 000000000..0f678448b --- /dev/null +++ b/docs/src/atomic.dox @@ -0,0 +1,50 @@ +/** + * @page article_atomic Invoking multiple primitives as a single atomic operation + * @{ + * It is often necessary to invoke multiple operations involving a + * reschedulation as a single atomic operation.
+ * ChibiOS/RT already implements APIs that perform complex operations, as + * example the API @p chSemSignalWait() performs two operations atomically.
+ * If more complex operations are required in your application then it is + * possible to build macro-operations, see the following example: + * @code + chSysLock(); + + chSemSignalI(&sem1); + chSemSignalI(&sem2); + if (tp != NULL) { + chThdResumeI(tp); + tp = NULL; + } + chSchRescheduleS(); + + chSysUnlock(); + * @endcode + * The above example performs a signal operation on two semaphores, optionally + * resumes a thread, and performs a final reschedulation. The three operations + * are performed atomically.
+ * An hypotetical @p chSemSignalSignalWait() operation could be implemented as + * follow: + * @code + chSysLock(); + + chSemSignalI(&sem1); + chSemSignalI(&sem2); + /* + * The "if" is required because the chSemWaitS() does not always internally + * reschedule. + */ + if (chSemGetCounter(&sem3) <= 0) + chSemWaitS(&Sem3); + else { + chSemFastWaitS(&sem3); + chSchRescheduleS(); + } + + chSysUnlock(); + * @endcode + * In general multiple I-Class APIs can be included and the block is terminated + * by an S-Class API that performs a reschedulation. Optionally a + * @p chSchRescheduleS() is present at the very end of the block. + */ +/** @} */ diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox new file mode 100644 index 000000000..fec810c81 --- /dev/null +++ b/docs/src/saveram.dox @@ -0,0 +1,66 @@ +/** + * @page article_saveram Saving RAM by declaring thread functions "noreturn" + * @{ + * One of the problems, when writing embedded multi-threaded applications, + * is that the thread functions do save the registers in the function + * entry code even if the system does not require it, exiting such + * a function would terminate the thread so there is no need to preserve + * the register values. This can waste tens of bytes for each thread.
+ * Consider the following code: + * @code +#include + +static WORKING_AREA(waMyThread, 64); + +static t_msg MyThread(void *arg) { + + while (!chThdShoudTerminate()) { + /* Do thread inner work */ + } + return 1; +} + +main() { + chSysInit(); + ... + chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL); + ... + chSysPause(); +} + * @endcode + * The resulting ASM code for the thread function would be something like this: + * @code +MyThread: + stmfd sp!, {r4, r5, r6, lr} + ... + ldmfd sp!, {r4, r5, r6, pc} + * @endcode + * Being that function a thread there is no need to save those registers, in + * embedded applications often the RAM is a scarce resource. That space can be + * saved by modifying the code as follow, using some advanced GCC extensions: + * @code +#include + +static BYTE8 waMyThread[UserStackSize(64)]; + +__attribute__((noreturn)) void MyThread(void *arg) { + + while (!chThdShoudTerminate()) { + /* Do thread inner work */ + } + chThdExit(1); +} + +main() { + chSysInit(); + ... + chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL); + ... + chSysPause(); +} + * @endcode + * This will make GCC believe that the function cannot return and there is no + * need to save registers. The code will be a bit less readable and less + * portable on other compilers however. + */ +/** @} */ -- cgit v1.2.3 From 79089d6352e01e1e7c6c3f0a88266abbc9af6abb Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 19 Jan 2009 15:10:41 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@644 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 12 ++---------- docs/src/interrupts.dox | 34 ++++++++++++++++++++++++++++++++++ docs/src/saveram.dox | 25 +++++++++++-------------- 3 files changed, 47 insertions(+), 24 deletions(-) create mode 100644 docs/src/interrupts.dox (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 0f678448b..22601d8d9 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -30,16 +30,8 @@ chSemSignalI(&sem1); chSemSignalI(&sem2); - /* - * The "if" is required because the chSemWaitS() does not always internally - * reschedule. - */ - if (chSemGetCounter(&sem3) <= 0) - chSemWaitS(&Sem3); - else { - chSemFastWaitS(&sem3); - chSchRescheduleS(); - } + chSemWaitS(&Sem3); + chSchRescheduleS(); /* Because chSemWaitS() might not reschedule internally.*/ chSysUnlock(); * @endcode diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox new file mode 100644 index 000000000..8c61eaa6e --- /dev/null +++ b/docs/src/interrupts.dox @@ -0,0 +1,34 @@ +/** + * @page article_interrupts Writing interrupt handlers under ChibiOS/RT + * @{ + * Since version 1.1.0 ChbiOS/RT offers a cross-platform system for writing + * interrupt handlers. Port-related and compiler-related details are + * encapsulated within standard system macros.
+ * An interrupt handler assumes the following general form: + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // IRQ handling code, preemptable if the architecture supports it. + + chSysLockI(); + // Invocation of some I-Class system API, never preemptable. + chSysUnlockI(). + + // More IRQ handling code, again preemptable. + + CH_IRQ_EPILOGUE(); +} + * @endcode + * Note that only interrupt handlers that have to invoke system I-Class APIs + * must be written in this form, handlers unrelated to the OS activity can + * omit the macros. + * Another note about the handler name "myIRQ", in some ports it must be a + * vector number rather than a function name, it could also be a name from + * within a predefined set, see the notes about the various ports. + *

Important Notes

+ * - There is an important application note about ARM7 interrupt handlers, + * please read about it in the ARM7 port section: @ref ARM7_IH + */ +/** @} */ + \ No newline at end of file diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox index fec810c81..324bdb9a3 100644 --- a/docs/src/saveram.dox +++ b/docs/src/saveram.dox @@ -9,23 +9,21 @@ * Consider the following code: * @code #include - + static WORKING_AREA(waMyThread, 64); - + static t_msg MyThread(void *arg) { - while (!chThdShoudTerminate()) { /* Do thread inner work */ } return 1; } - + main() { chSysInit(); ... - chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL); + chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL); ... - chSysPause(); } * @endcode * The resulting ASM code for the thread function would be something like this: @@ -40,23 +38,22 @@ MyThread: * saved by modifying the code as follow, using some advanced GCC extensions: * @code #include - -static BYTE8 waMyThread[UserStackSize(64)]; - -__attribute__((noreturn)) void MyThread(void *arg) { - + +static WORKING_AREA(waMyThread, 64); + +__attribute__((noreturn)) +static void MyThread(void *arg) { while (!chThdShoudTerminate()) { /* Do thread inner work */ } chThdExit(1); } - + main() { chSysInit(); ... - chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL); + chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL); ... - chSysPause(); } * @endcode * This will make GCC believe that the function cannot return and there is no -- cgit v1.2.3 From 3f200660f67fa674ef388ed3b507e29f71a2c462 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 19 Jan 2009 15:28:34 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@645 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/interrupts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 8c61eaa6e..2a14bd6aa 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -12,7 +12,7 @@ CH_IRQ_HANDLER(myIRQ) { // IRQ handling code, preemptable if the architecture supports it. chSysLockI(); - // Invocation of some I-Class system API, never preemptable. + // Invocation of some I-Class system APIs, never preemptable. chSysUnlockI(). // More IRQ handling code, again preemptable. -- cgit v1.2.3 From 22fe505a817d26c5b88dae4f602b658498a8a18e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 21 Jan 2009 11:32:31 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@655 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 10 +++------- docs/src/timing.dox | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 7 deletions(-) create mode 100644 docs/src/timing.dox (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 22601d8d9..144d6bca0 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -12,17 +12,13 @@ chSemSignalI(&sem1); chSemSignalI(&sem2); - if (tp != NULL) { - chThdResumeI(tp); - tp = NULL; - } chSchRescheduleS(); chSysUnlock(); * @endcode - * The above example performs a signal operation on two semaphores, optionally - * resumes a thread, and performs a final reschedulation. The three operations - * are performed atomically.
+ * The above example performs a signal operation on two semaphores and + * performs a final reschedulation. The two operations are performed + * atomically.
* An hypotetical @p chSemSignalSignalWait() operation could be implemented as * follow: * @code diff --git a/docs/src/timing.dox b/docs/src/timing.dox new file mode 100644 index 000000000..e38fcb74c --- /dev/null +++ b/docs/src/timing.dox @@ -0,0 +1,42 @@ +/** + * @page article_timing Reliable timings using Threads + * @{ + * One common task is to have threads do something at regular, scheduled, + * intervals. + * An obvious solution is to write something like this: + * @code +msg_t my_thread(void *param) { + + while (TRUE) { + do_something(); + chThdSleepMilliseconds(1000); /* Fixed interval */ + } +} + * @endcode + * This example works well assuming that @p do_something() execution time is + * well below the system tick period and that @p my_thread() is not preempted + * by other threads inserting long intervals.
+ * If the above conditions are not satisfied you may have @p do_something() + * executed at irregular intevals, as example:

+ * T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.

+ * Also note that the error increases over time and this kind of behavior can + * lead anomalies really hard to debug. + *

A better solution

+ * It is possible to rewrite the above code using absolute deadlines rather + * than fixed intervals: + * @code +msg_t my_thread(void *param) { + + systick_t time = chSysGetTime(); /* T0 */ + while (TRUE) { + time += MS2ST(1000); /* Next deadline */ + do_something(); + chThdSleepUntil(time); + } +} + * @endcode + * Using this code @p do_something() will always be executed at an absolute + * deadline time and the error will not accumulate over time regardless of + * the execution time and delays inserted by other threads. + */ +/** @} */ -- cgit v1.2.3 From 34d36884a75954eaae35604ce1a20e115d17d42c Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 21 Jan 2009 14:39:47 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@656 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 18 +++++++------ docs/src/jitter.dox | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 8 deletions(-) create mode 100644 docs/src/jitter.dox (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 144d6bca0..7eeaa27f3 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -12,13 +12,14 @@ chSemSignalI(&sem1); chSemSignalI(&sem2); + chMtxUnlock(); chSchRescheduleS(); chSysUnlock(); * @endcode - * The above example performs a signal operation on two semaphores and - * performs a final reschedulation. The two operations are performed - * atomically.
+ * The above example performs a signal operation on two semaphores, unlocks the + * last aquired mutex and finally performs a reschedulation. All the operations + * are performed atomically.
* An hypotetical @p chSemSignalSignalWait() operation could be implemented as * follow: * @code @@ -26,13 +27,14 @@ chSemSignalI(&sem1); chSemSignalI(&sem2); - chSemWaitS(&Sem3); - chSchRescheduleS(); /* Because chSemWaitS() might not reschedule internally.*/ + chSemWaitS(&Sem3); /* May reschedule or not. */ + chSchRescheduleS(); /* This one reschedules if necessary. */ chSysUnlock(); * @endcode - * In general multiple I-Class APIs can be included and the block is terminated - * by an S-Class API that performs a reschedulation. Optionally a - * @p chSchRescheduleS() is present at the very end of the block. + * In general multiple I-Class and (non rescheduling) S-Class APIs can be + * included and the block is terminated by a rescheduling S-Class API. + * An extra @p chSchRescheduleS() can be present at the very end of the block, + * it only reschedules if a reschedulation is still required. */ /** @} */ diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox new file mode 100644 index 000000000..64351c5d3 --- /dev/null +++ b/docs/src/jitter.dox @@ -0,0 +1,77 @@ +/** + * @page article_jitter Minimizing Jitter + * @{ + * Response time jitter is one of the more sneaky source of problems when + * designing a real time system. When using a RTOS like ChibiOS/RT one must + * be aware of what Jitter is and how it can affect the performance of the + * system.
+ * A good place to start is this + * Wikipedia article. + *

Jitter sources under ChibiOS/RT

+ * Under ChibiOS/RT (or any other similar RTOS) there are several jitter + * possible sources: + * -# Hardware interrupt latency. + * -# Interrupt service time. + * -# Kernel lock zones. + * -# Higher priority threads activity. + * + *

Jitter mitigation countermeasures

+ * For each of the previously described jitter source there are possible + * mitigation actions. + * + *

Hardware interrupt latency

+ * This parameter is pretty much fixed and a characteristic of the system. + * Possible actions include higher clock speeds or switch to an hardware + * architecture more efficient at interrupt handling, as example, the + * ARM Cortex-M3 core present in the STM32 family is very efficient at + * interrupt handling. + * + *

Interrupt service time

+ * This is the execution time of interrupt handlers, this time includes: + * - Fixed handler overhead, as example registers stacking/unstacking. + * - Interrupt specific service time, as example, in a serial driver, this is + * the time used by the handler to transfer data from/to the UART. + * - OS overhead. Any operating system requires to run some extra code + * in interrupt handlers in order to handle correct preemption and Context + * Switching. + * + * 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.
+ * Another possible mitigation action is to evaluate if a specific interrupt + * handler really need to "speak" with the OS, if the handler uses full + * stand-alone code then it is possible to remove the OS related overhead.
+ * On some architecture it is also possible to give to interrupt sources a + * greater hardware priority than the kernel and not be affected by the + * jitter introduced by OS itself (see next subsection).
+ * As example, in the ARM port, FIQ sources are not affected by the + * kernel-generated jitter. The Cortex-M3 port is even better thanks to its + * hardware-assisted interrupt architecture allowing handlers preemption, + * late switch, tail chaining etc. See the notes about the various @ref Ports. + * + *

Kernel lock zones

+ * The OS kernel protects some critical internal data structure by disabling + * (fully in simple architecture, to some extent in more advanced + * microcontrollers) the interrupt sources. Because of this the kernel itself + * is a jitter source, a good OS design minimizes the jitter generated by the + * kernel by both using adequate data structure, algorithms and good coding + * practices.
+ * A good OS design is not the whole story, some OS primitives may generate + * more or less jitter depending on the system state, as example the maximum + * number of threads on a certain queue, the maximum number of nested mutexes + * and so on. Some algorithms employed internally can have constant execution + * time but others may have linear execution time or be even more complex. + * + *

Higher priority threads activity

+ * At thread level the response time is affected by the interrupt-related + * jitter as seen in the previous subsections but also by the activity of the + * higher priority threads and contention on protected resources.
+ * It is possible to improve the system overall response time and reduce jitter + * by carefully assigning priorities to the various threads and carefully + * designing mutual exclusion zones.
+ * The use of the proper synchronization mechanism (semaphores, mutexes, events, + * messages and so on) also helps to improve the system performance. + */ +/** @} */ -- cgit v1.2.3 From 03bba9ac46dc3a710efcb761a1d6e6ac34f81f86 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 21 Jan 2009 17:19:25 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@657 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/jitter.dox | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/src') diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 64351c5d3..733e30ef6 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -1,17 +1,18 @@ /** - * @page article_jitter Minimizing Jitter + * @page article_jitter Response Time and Jitter * @{ - * Response time jitter is one of the more sneaky source of problems when + * Response time jitter is one of the most sneaky source of problems when * designing a real time system. When using a RTOS like ChibiOS/RT one must * be aware of what Jitter is and how it can affect the performance of the * system.
* A good place to start is this * Wikipedia article. - *

Jitter sources under ChibiOS/RT

+ * + *

Jitter Sources

* Under ChibiOS/RT (or any other similar RTOS) there are several jitter * possible sources: - * -# Hardware interrupt latency. - * -# Interrupt service time. + * -# Hardware interrupts latency. + * -# Interrupts service time and priority. * -# Kernel lock zones. * -# Higher priority threads activity. * @@ -19,14 +20,13 @@ * For each of the previously described jitter source there are possible * mitigation actions. * - *

Hardware interrupt latency

+ *

Hardware interrupts latency

* This parameter is pretty much fixed and a characteristic of the system. * Possible actions include higher clock speeds or switch to an hardware * architecture more efficient at interrupt handling, as example, the - * ARM Cortex-M3 core present in the STM32 family is very efficient at - * interrupt handling. + * ARM Cortex-M3 core present in the STM32 family is very efficient at that. * - *

Interrupt service time

+ *

Interrupts service time and priority

* This is the execution time of interrupt handlers, this time includes: * - Fixed handler overhead, as example registers stacking/unstacking. * - Interrupt specific service time, as example, in a serial driver, this is -- cgit v1.2.3 From bae98eb8d8e752aa084a2438aa99d5f72e3f1247 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 22 Jan 2009 15:37:29 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@666 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/jitter.dox | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs/src') diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 733e30ef6..4bbedd7b7 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -3,21 +3,21 @@ * @{ * Response time jitter is one of the most sneaky source of problems when * designing a real time system. When using a RTOS like ChibiOS/RT one must - * be aware of what Jitter is and how it can affect the performance of the + * be aware of what the jitter is and how it can affect the performance of the * system.
* A good place to start is this * Wikipedia article. * *

Jitter Sources

- * Under ChibiOS/RT (or any other similar RTOS) there are several jitter - * possible sources: + * Under ChibiOS/RT (or any other similar RTOS) there are several possible + * jitter sources: * -# Hardware interrupts latency. * -# Interrupts service time and priority. * -# Kernel lock zones. * -# Higher priority threads activity. * *

Jitter mitigation countermeasures

- * For each of the previously described jitter source there are possible + * For each of the previously described jitter sources there are possible * mitigation actions. * *

Hardware interrupts latency

@@ -49,13 +49,14 @@ * As example, in the ARM port, FIQ sources are not affected by the * kernel-generated jitter. The Cortex-M3 port is even better thanks to its * hardware-assisted interrupt architecture allowing handlers preemption, - * late switch, tail chaining etc. See the notes about the various @ref Ports. + * late arriving, tail chaining etc. See the notes about the various + * @ref Ports. * *

Kernel lock zones

* The OS kernel protects some critical internal data structure by disabling * (fully in simple architecture, to some extent in more advanced * microcontrollers) the interrupt sources. Because of this the kernel itself - * is a jitter source, a good OS design minimizes the jitter generated by the + * is a jitter cause, a good OS design minimizes the jitter generated by the * kernel by both using adequate data structure, algorithms and good coding * practices.
* A good OS design is not the whole story, some OS primitives may generate @@ -72,6 +73,6 @@ * by carefully assigning priorities to the various threads and carefully * designing mutual exclusion zones.
* The use of the proper synchronization mechanism (semaphores, mutexes, events, - * messages and so on) also helps to improve the system performance. + * messages and so on) also helps to improve the overall system performance. */ /** @} */ -- cgit v1.2.3 From 819c02b8391e3cadcbe814c84c5c5f366ae41e03 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 23 Jan 2009 16:18:13 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@669 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/jitter.dox | 81 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 61 insertions(+), 20 deletions(-) (limited to 'docs/src') diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 4bbedd7b7..1b4220dd4 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -8,15 +8,61 @@ * A good place to start is this * Wikipedia article. * - *

Jitter Sources

- * Under ChibiOS/RT (or any other similar RTOS) there are several possible - * jitter sources: - * -# Hardware interrupts latency. - * -# Interrupts service time and priority. - * -# Kernel lock zones. - * -# Higher priority threads activity. + *

Interrupt Response Time

+ * This is the time from an interrupt event and the execution of the handler + * code. * - *

Jitter mitigation countermeasures

+ * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + int [label="Interrupt"]; + busy [label="Busy"]; + served [label="Interrupt\nServed"]; + int -> served [label="Not Busy"]; + int -> busy [label="Not Ready"]; + busy -> busy [label="Still Busy\n(jitter)"]; + busy -> served [label="Finally Ready"]; + * @enddot + * + *

Jitter Sources

+ * In this scenario the jitter (busy state) is represented by the sum of: + * - Higher or equal priority interrupt sources execution time combined. + * This time can go from zero to the maximum randomly. This value can be + * guaranteed to be zero only if the interrupt has the highest priority in + * the system. + * - Highest execution time among lower priority sources. This value is zero + * on those architectures (Cortex-M3 as example) where interrupt handlers + * can be preempted by higher priority sources. + * - Longest time in a kernel lock zone that can delay interrupt servicing. + * This value is zero for fast interrupt sources, see @ref system_states. + * + *

Threads Flyback Time

+ * This is the time from an event, as example an interrupt, and the execution + * of a thread supposed to handle the event. Imagine the following graph as the + * continuation of the previous one. + * + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + served [label="Interrupt\nServed"]; + busy [label="Busy"]; + thread [label="Thread\nAwakened"]; + served -> busy [label="Not Highest Priority"]; + busy -> busy [label="Other Threads\n(jitter)"]; + busy -> thread [label="Highest Priority"]; + served -> thread [label="Highest Priority"]; + * @enddot + * + *

Jitter Sources

+ * In this scenario all the jitter sources previously discussed are also + * present and there is the added jitter caused by the activity of the + * higher priority threads. + * + *

Jitter Mitigation

* For each of the previously described jitter sources there are possible * mitigation actions. * @@ -26,7 +72,7 @@ * architecture more efficient at interrupt handling, as example, the * ARM Cortex-M3 core present in the STM32 family is very efficient at that. * - *

Interrupts service time and priority

+ *

Interrupts service time

* This is the execution time of interrupt handlers, this time includes: * - Fixed handler overhead, as example registers stacking/unstacking. * - Interrupt specific service time, as example, in a serial driver, this is @@ -41,16 +87,8 @@ * An handler should 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 need to "speak" with the OS, if the handler uses full + * handler really needs to "speak" with the OS, if the handler uses full * stand-alone code then it is possible to remove the OS related overhead.
- * On some architecture it is also possible to give to interrupt sources a - * greater hardware priority than the kernel and not be affected by the - * jitter introduced by OS itself (see next subsection).
- * As example, in the ARM port, FIQ sources are not affected by the - * kernel-generated jitter. The Cortex-M3 port is even better thanks to its - * hardware-assisted interrupt architecture allowing handlers preemption, - * late arriving, tail chaining etc. See the notes about the various - * @ref Ports. * *

Kernel lock zones

* The OS kernel protects some critical internal data structure by disabling @@ -67,12 +105,15 @@ * *

Higher priority threads activity

* At thread level the response time is affected by the interrupt-related - * jitter as seen in the previous subsections but also by the activity of the - * higher priority threads and contention on protected resources.
+ * jitter, as seen in the previous subsections, but also by the activity of + * the higher priority threads and contention on protected resources.
* It is possible to improve the system overall response time and reduce jitter * by carefully assigning priorities to the various threads and carefully * designing mutual exclusion zones.
* The use of the proper synchronization mechanism (semaphores, mutexes, events, * messages and so on) also helps to improve the overall system performance. + * The use of the Priority Inheritance algorithm implemented in the mutexes + * subsystem can improve the overall response time and reduce jitter but it is + * not a magic wand, a proper system design comes first. */ /** @} */ -- cgit v1.2.3 From 672fb83fa475643b6cbd4f3cdd0b799aa17e8b32 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 23 Jan 2009 19:25:13 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@670 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/jitter.dox | 68 +++++++++++++++++++++++++---------------------------- 1 file changed, 32 insertions(+), 36 deletions(-) (limited to 'docs/src') diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 1b4220dd4..da3251369 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -4,13 +4,25 @@ * Response time jitter is one of the most sneaky source of problems when * designing a real time system. When using a RTOS like ChibiOS/RT one must * be aware of what the jitter is and how it can affect the performance of the - * system.
- * A good place to start is this + * system. A good place to start is this * Wikipedia article. * + *

Interrupt handlers execution time

+ * The total execution time of an interrupt handler includes: + * - Hardware interrupts latency, this parameter is pretty much fixed and + * characteristic of the system. + * - Fixed handler overhead, as example registers stacking/unstacking. + * - Interrupt specific handler code execution time, as example, in a serial + * driver, this is the time used by the handler to transfer data from/to + * the UART. + * - OS overhead. Any operating system requires to run some extra code + * in interrupt handlers in order to handle correct preemption and Context + * Switching. + * *

Interrupt Response Time

- * This is the time from an interrupt event and the execution of the handler - * code. + * The Interrupt Response Time is the time from an interrupt event and the + * execution of the handler code. Unfortunately this time is not constant + * in most cases, see the following graph: * * @dot digraph example { @@ -20,28 +32,27 @@ int [label="Interrupt"]; busy [label="Busy"]; served [label="Interrupt\nServed"]; - int -> served [label="Not Busy"]; + int -> served [label="Not Busy (minimum latency)"]; int -> busy [label="Not Ready"]; - busy -> busy [label="Still Busy\n(jitter)"]; + busy -> busy [label="Still Busy\n(added latency)"]; busy -> served [label="Finally Ready"]; * @enddot * - *

Jitter Sources

* In this scenario the jitter (busy state) is represented by the sum of: - * - Higher or equal priority interrupt sources execution time combined. + * - Higher or equal priority interrupt handlers execution time combined. * This time can go from zero to the maximum randomly. This value can be * guaranteed to be zero only if the interrupt has the highest priority in * the system. - * - Highest execution time among lower priority sources. This value is zero + * - Highest execution time among lower priority handlers. This value is zero * on those architectures (Cortex-M3 as example) where interrupt handlers * can be preempted by higher priority sources. * - Longest time in a kernel lock zone that can delay interrupt servicing. * This value is zero for fast interrupt sources, see @ref system_states. * *

Threads Flyback Time

- * This is the time from an event, as example an interrupt, and the execution - * of a thread supposed to handle the event. Imagine the following graph as the - * continuation of the previous one. + * This is the time between an event, as example an interrupt, and the + * execution of the thread that will process it. Imagine the following + * graph as the continuation of the previous one. * * @dot digraph example { @@ -51,13 +62,12 @@ served [label="Interrupt\nServed"]; busy [label="Busy"]; thread [label="Thread\nAwakened"]; - served -> busy [label="Not Highest Priority"]; - busy -> busy [label="Other Threads\n(jitter)"]; + served -> busy [label="Not highest Priority"]; + busy -> busy [label="Higher priority Threads\n(added latency)"]; busy -> thread [label="Highest Priority"]; - served -> thread [label="Highest Priority"]; + served -> thread [label="Highest Priority (minimum latency)"]; * @enddot * - *

Jitter Sources

* In this scenario all the jitter sources previously discussed are also * present and there is the added jitter caused by the activity of the * higher priority threads. @@ -66,28 +76,14 @@ * For each of the previously described jitter sources there are possible * mitigation actions. * - *

Hardware interrupts latency

- * This parameter is pretty much fixed and a characteristic of the system. - * Possible actions include higher clock speeds or switch to an hardware - * architecture more efficient at interrupt handling, as example, the - * ARM Cortex-M3 core present in the STM32 family is very efficient at that. - * - *

Interrupts service time

- * This is the execution time of interrupt handlers, this time includes: - * - Fixed handler overhead, as example registers stacking/unstacking. - * - Interrupt specific service time, as example, in a serial driver, this is - * the time used by the handler to transfer data from/to the UART. - * - OS overhead. Any operating system requires to run some extra code - * in interrupt handlers in order to handle correct preemption and Context - * Switching. - * + *

Interrupt handlers optimization

* 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.
* Another possible mitigation action is to evaluate if a specific interrupt - * handler really needs to "speak" with the OS, if the handler uses full + * 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.
* *

Kernel lock zones

@@ -95,7 +91,7 @@ * (fully in simple architecture, to some extent in more advanced * microcontrollers) the interrupt sources. Because of this the kernel itself * is a jitter cause, a good OS design minimizes the jitter generated by the - * kernel by both using adequate data structure, algorithms and good coding + * kernel by using adequate data structures, algorithms and coding * practices.
* A good OS design is not the whole story, some OS primitives may generate * more or less jitter depending on the system state, as example the maximum @@ -104,9 +100,9 @@ * time but others may have linear execution time or be even more complex. * *

Higher priority threads activity

- * At thread level the response time is affected by the interrupt-related - * jitter, as seen in the previous subsections, but also by the activity of - * the higher priority threads and contention on protected resources.
+ * At thread level, the response time is affected by the interrupt-related + * jitter but mainly by the activity of the higher priority threads and + * contention on protected resources.
* It is possible to improve the system overall response time and reduce jitter * by carefully assigning priorities to the various threads and carefully * designing mutual exclusion zones.
-- cgit v1.2.3 From 3df52d3f899e9dbb9f257a148764b4165a19ba10 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 24 Jan 2009 11:06:58 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@672 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 7eeaa27f3..31f141ce1 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -12,7 +12,7 @@ chSemSignalI(&sem1); chSemSignalI(&sem2); - chMtxUnlock(); + chMtxUnlockS(); chSchRescheduleS(); chSysUnlock(); -- cgit v1.2.3 From 8fa109243e5d626a941db8e7d6dc30bb64f9bc9f Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 24 Jan 2009 17:59:51 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@675 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/interrupts.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 2a14bd6aa..3ba5d2b9a 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -11,9 +11,9 @@ CH_IRQ_HANDLER(myIRQ) { // IRQ handling code, preemptable if the architecture supports it. - chSysLockI(); + chSysLockFromIsr(); // Invocation of some I-Class system APIs, never preemptable. - chSysUnlockI(). + chSysUnlockFromIsr(). // More IRQ handling code, again preemptable. -- cgit v1.2.3 From 5282822dfe4d55da2f73b79c94a25b0484887167 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 25 Jan 2009 08:33:20 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@678 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 19 +++++++++++++++++++ docs/src/interrupts.dox | 19 +++++++++++++++++++ docs/src/jitter.dox | 19 +++++++++++++++++++ docs/src/saveram.dox | 19 +++++++++++++++++++ docs/src/timing.dox | 19 +++++++++++++++++++ 5 files changed, 95 insertions(+) (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 31f141ce1..64084ff30 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -1,3 +1,22 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + /** * @page article_atomic Invoking multiple primitives as a single atomic operation * @{ diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 3ba5d2b9a..fe74d90e9 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -1,3 +1,22 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + /** * @page article_interrupts Writing interrupt handlers under ChibiOS/RT * @{ diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index da3251369..3e2ec1cb4 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -1,3 +1,22 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + /** * @page article_jitter Response Time and Jitter * @{ diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox index 324bdb9a3..e237da909 100644 --- a/docs/src/saveram.dox +++ b/docs/src/saveram.dox @@ -1,3 +1,22 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + /** * @page article_saveram Saving RAM by declaring thread functions "noreturn" * @{ diff --git a/docs/src/timing.dox b/docs/src/timing.dox index e38fcb74c..c1a33ae19 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -1,3 +1,22 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + /** * @page article_timing Reliable timings using Threads * @{ -- cgit v1.2.3 From c1ef5c1ac7c65f7d9ffbafea09c0516e7ec632f3 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 29 Jan 2009 18:43:42 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@681 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 30 +++++++ docs/src/concepts.dox | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 270 insertions(+) create mode 100644 docs/src/articles.dox create mode 100644 docs/src/concepts.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox new file mode 100644 index 000000000..a152d7c44 --- /dev/null +++ b/docs/src/articles.dox @@ -0,0 +1,30 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page Articles Articles + * @{ + * ChibiOS/RT Articles and Code Examples: + * - @subpage article_atomic + * - @subpage article_saveram + * - @subpage article_interrupts + * - @subpage article_jitter + * - @subpage article_timing + */ +/** @} */ diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox new file mode 100644 index 000000000..cfa5bfbc3 --- /dev/null +++ b/docs/src/concepts.dox @@ -0,0 +1,240 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page Concepts Concepts + * @{ + * @brief ChibiOS/RT Concepts and Architecture + * @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 Mtx, + * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg, + * @a Heap, @a Pool. + * + * @section api_suffixes API Names Suffixes + * The suffix can be one of the following: + * - None, APIs without any suffix can be invoked only from the user + * code in the Normal state unless differently specified. See + * @ref system_states. + * - "I", I-Class APIs are invokable only from the I-Locked or + * S-Locked states. See @ref system_states. + * - "S", S-Class APIs are invokable only from the S-Locked + * state. See @ref system_states. + * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). + * + * @section interrupt_classes Interrupt Classes + * In ChibiOS/RT there are three logical interrupt classes: + * - Regular Interrupts. Maskable interrupt sources that cannot + * preempt the kernel code and are thus able to invoke operating system APIs + * from within their handlers. The interrupt handlers belonging to this class + * must be written following some rules. See the @ref System APIs group and + * @ref article_interrupts. + * - Fast Interrupts. Maskable interrupt sources with the ability + * to preempt the kernel code and thus have a lower latency and are less + * subject to jitter, see @ref article_jitter. Such sources are not + * supported on all the architectures.
+ * Fast interrupts are not allowed to invoke any operating system API from + * within their handlers. Fast interrupt sources may however pend a lower + * priority regular interrupt where access to the operating system is + * possible. + * - Non Maskable Interrupts. Non maskable interrupt sources are + * totally out of the operating system control and have the lowest latency. + * Such sources are not supported on all the architectures. + * + * The mapping of the above logical classes into physical interrupts priorities + * is, of course, port dependent. See the documentation of the various ports + * for details. + * + * @section system_states System States + * When using ChibiOS/RT the system can be in one of the following logical + * operating states: + * - Init. When the system is in this state all the maskable + * interrupt sources are disabled. In this state it is not possible to use + * any system API except @p chSysInit(). This state is entered after a + * physical reset. + * - Normal. All the interrupt sources are enabled and the system APIs + * are accessible, threads are running. + * - Suspended. In this state the fast interrupt sources are enabled but + * the regular interrupt sources are not. In this state it is not possible + * to use any system API except @p chSysDisable() or @p chSysEnable() in + * order to change state. + * - Disabled. When the system is in this state both the maskable + * regular and fast interrupt sources are disabled. In this state it is not + * possible to use any system API except @p chSysSuspend() or + * @p chSysEnable() in order to change state. + * - Sleep. Architecture-dependent low power mode, the idle thread + * goes in this state and waits for interrupts, after servicing the interrupt + * the Normal state is restored and the scheduler has a chance to reschedule. + * - S-Locked. Kernel locked and regular interrupt sources disabled. + * Fast interrupt sources are enabled. S-Class and I-Class APIs are + * invokable in this state. + * - I-Locked. Kernel locked and regular interrupt sources disabled. + * I-Class APIs are invokable from this state. + * - Serving Regular Interrupt. No system APIs are accessible but it is + * possible to switch to the I-Locked state using @p chSysLockFromIsr() and + * then invoke any I-Class API. Interrupt handlers can be preemptable on some + * architectures thus is important to switch to I-Locked state before + * invoking system APIs. + * - Serving Fast Interrupt. System APIs are not accessible. + * - Serving Non-Maskable Interrupt. System APIs are not accessible. + * - Halted. All interrupt sources are disabled and system stopped into + * an infinite loop. This state can be reached if the debug mode is activated + * and an error is detected or after explicitly invoking + * @p chSysHalt(). + * + * Note that the above state are just Logical States that may have no + * real associated machine state on some architectures. The following diagram + * shows the possible transitions between the states: + * + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + init [label="Init", style="bold"]; + norm [label="Normal", shape=doublecircle]; + susp [label="Suspended"]; + disab [label="Disabled"]; + slock [label="S-Locked"]; + ilock [label="I-Locked"]; + slock [label="S-Locked"]; + sleep [label="Sleep"]; + sri [label="SRI"]; + init -> norm [label="chSysInit()"]; + norm -> slock [label="chSysLock()", constraint=false]; + slock -> norm [label="chSysUnlock()"]; + norm -> susp [label="chSysSuspend()"]; + susp -> disab [label="chSysDisable()"]; + norm -> disab [label="chSysDisable()"]; + susp -> norm [label="chSysEnable()"]; + disab -> norm [label="chSysEnable()"]; + slock -> ilock [label="Context Switch", dir="both"]; + norm -> sri [label="Regular IRQ", style="dotted"]; + sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8]; + sri -> ilock [label="chSysLockFromIsr()", constraint=false]; + ilock -> sri [label="chSysUnlockFromIsr()", fontsize=8]; + norm -> sleep [label="Idle Thread"]; + sleep -> sri [label="Regular IRQ", style="dotted"]; + } + * @enddot + * Note, the SFI, Halted and SNMI states were not shown + * because those are reachable from most states: + * + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + any1 [label="Any State\nexcept *"]; + any2 [label="Any State"]; + sfi [label="SFI"]; + halt [label="Halted"]; + SNMI [label="SNMI"]; + any1 -> sfi [style="dotted", label="Fast IRQ"]; + sfi -> any1 [label="Fast IRQ return"]; + any2 -> halt [label="chSysHalt()"]; + any2 -> SNMI [label="Synchronous NMI"]; + any2 -> SNMI [label="Asynchronous NMI", style="dotted"]; + SNMI -> any2 [label="NMI return"]; + halt -> SNMI [label="Asynchronous NMI", style="dotted"]; + SNMI -> halt [label="NMI return"]; + } + * @enddot + * @attention * except: Init, Halt, SNMI, Disabled. + * + * @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 thread_states Threads States + * The image shows how threads can change their state in ChibiOS/RT.
+ * @dot + digraph example { + /*rankdir="LR";*/ + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + start [label="Start", style="bold"]; + run [label="Running"]; + ready [label="Ready"]; + suspend [label="Suspended"]; + sleep [label="Sleeping"]; + stop [label="Stop", style="bold"]; + start -> suspend [label="chThdInit()", constraint=false]; + start -> run [label="chThdCreate()"]; + start -> ready [label="chThdCreate()"]; + run -> ready [label="Reschedulation", dir="both"]; + suspend -> run [label="chThdResume()"]; + suspend -> ready [label="chThdResume()"]; + run -> sleep [label="chSchGoSleepS()"]; + sleep -> run [label="chSchWakepS()"]; + sleep -> ready [label="chSchWakepS()"]; + run -> stop [label="chThdExit()"]; + } + * @enddot + * + * @section priority Priority Levels + * Priorities in ChibiOS/RT are a contiguous numerical range but the initial + * and final values are not enforced.
+ * The following table describes the various priority boundaries (from lowest + * to highest): + * - @p IDLEPRIO, this is the lowest priority level and is reserved for the + * idle thread, no other threads should share this priority level. This is + * the lowest numerical value of the priorities space. + * - @p LOWPRIO, the lowest priority level that can be assigned to an user + * thread. + * - @p NORMALPRIO, this is the central priority level for user threads. It is + * advisable to assign priorities to threads as values relative to + * @p NORMALPRIO, as example NORMALPRIO-1 or NORMALPRIO+4, this ensures the + * portability of code should the numerical range change in future + * implementations. + * - @p HIGHPRIO, the highest priority level that can be assigned to an user + * thread. + * - @p ABSPRO, absolute maximum software priority level, it can be higher than + * @p HIGHPRIO but the numerical values above @p HIGHPRIO up to @p ABSPRIO + * (inclusive) are reserved. This is the highest numerical value of the + * priorities space. + * + * @section warea Thread Working Area + * Each thread has its own stack, a Thread structure and some preemption + * areas. All the structures are allocated into a "Thread Working Area", + * a thread private heap, usually statically declared in your code. + * Threads do not use any memory outside the allocated working area + * except when accessing static shared data.

+ * @image html workspace.png + *
+ * Note that the preemption area is only present when the thread is not + * running (switched out), 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. + * The preemption area can be divided in up to three structures: + * - External Context. + * - Interrupt Stack. + * - Internal Context. + * + * See the @ref Core documentation for details, the area may change on + * the various ports and some structures may not be present (or be zero-sized). + */ +/** @} */ -- cgit v1.2.3 From 41eeaff123f182af8ba629570d684207ee8bf12a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 31 Jan 2009 10:30:16 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@701 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 2 +- docs/src/concepts.dox | 2 +- docs/src/licfaq.dox | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 docs/src/licfaq.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index a152d7c44..59350b732 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -18,7 +18,7 @@ */ /** - * @page Articles Articles + * @page articles Articles * @{ * ChibiOS/RT Articles and Code Examples: * - @subpage article_atomic diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index cfa5bfbc3..531340560 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -18,7 +18,7 @@ */ /** - * @page Concepts Concepts + * @page concepts Concepts * @{ * @brief ChibiOS/RT Concepts and Architecture * @section naming Naming Conventions diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox new file mode 100644 index 000000000..a666a6aa0 --- /dev/null +++ b/docs/src/licfaq.dox @@ -0,0 +1,89 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page lic_faq License and F.A.Q. + * @{ + * ChibiOS/RT is a + * GPL3-licensed product but it offers a linking exception in its stable + * releases.
+ * This article contains some answers about the exception. + * + * @section faq Frequently Asked Questions + * - Is ChibiOS/RT free ?
+ * Yes, free as both in free beer and freedom. + * - Can I use it in my commercial embedded product?
+ * Yes, you just have to advertise that you are using ChibiOS/RT by putting + * a link to the project somewhere on your web site or documentation. + * - Am I forced to release the source code of my product?
+ * The exception to the GPL allows you to use ChibiOS/RT in your commercial + * application without have to release your source code under certains + * conditions. See the exception text under "Approved Interfaces" for + * details. + * - I don't want to be bound by any of the above restriction, is this + * possible?
+ * You may contact us about a commercial license. + * + * @section exception_text GPL Exception Text + +
GPL Exception Text
+ + In addition, as a special exception, the copyright holder of ChibiOS/RT, +gives You the additional right to link the unmodified code of this Program with +code not covered under the GNU General Public License ("Non-GPL Code") and to +distribute linked combinations including the two, subject to the limitations +in this paragraph. + + -# Non-GPL Code permitted under this exception must only link to the + unmodified code of this Program through those well defined interfaces + identified as "Approved Interfaces". + -# Every copy of the combined work is accompanied by a written statement + that details to the recipient the version of ChibiOS/RT used and an + offer by yourself to provide the ChibiOS/RT source code should the + recipient request it. + -# The combined work is not itself an RTOS, scheduler, kernel or related + product. + -# The combined work is not itself a library intended for linking into + other software applications. + +
The Approved Interfaces
+ + -# The files of Non-GPL Code may include the unmodified ChibiOS/RT + distribution header files contained in ./src/include and ./src/lib + without causing the resulting work to be covered by the GNU General + Public License. + -# The files of Non-GPL Code may link to the unmodified ChibiOS/RT + distribution files contained under ./src and ./src/lib without + causing the resulting work to be covered by the GNU General Public + License. + -# The files of Non-GPL Code may link to, or include, the modified or + unmodified ChibiOS/RT distribution files contained under ./src/templates + and ./ports and ./demos without causing the resulting work to be + covered by the GNU General Public License. + + Only the copyright holder of ChibiOS/RT may make changes or additions to the +list of Approved Interfaces. + + You must obey the GNU General Public License in all respects for all of the +Program code and other code used in conjunction with the Program except the +Non-GPL Code covered by this exception. + * + */ +/** @} */ + \ No newline at end of file -- cgit v1.2.3 From 528e9fea357b8b24069d99657230ba28968f5d0c Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 2 Feb 2009 21:07:27 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@713 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 8 ++++---- docs/src/concepts.dox | 16 ++++++++-------- docs/src/interrupts.dox | 4 ++-- docs/src/licfaq.dox | 4 ++++ docs/src/timing.dox | 2 +- 5 files changed, 19 insertions(+), 15 deletions(-) (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 64084ff30..5fb0bc628 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -51,9 +51,9 @@ chSysUnlock(); * @endcode - * In general multiple I-Class and (non rescheduling) S-Class APIs can be - * included and the block is terminated by a rescheduling S-Class API. - * An extra @p chSchRescheduleS() can be present at the very end of the block, - * it only reschedules if a reschedulation is still required. + * In general multiple @ref I-Class and (non rescheduling) @ref S-Class APIs + * can be included and the block is terminated by a rescheduling @ref S-Class + * API. An extra @p chSchRescheduleS() can be present at the very end of the + * block, it only reschedules if a reschedulation is still required. */ /** @} */ diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 531340560..9c0a1d9c2 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -33,10 +33,10 @@ * - None, APIs without any suffix can be invoked only from the user * code in the Normal state unless differently specified. See * @ref system_states. - * - "I", I-Class APIs are invokable only from the I-Locked or - * S-Locked states. See @ref system_states. - * - "S", S-Class APIs are invokable only from the S-Locked - * state. See @ref system_states. + * - @anchor I-Class "I", I-Class APIs are invokable only from the + * I-Locked or S-Locked states. See @ref system_states. + * - @anchor S-Class "S", S-Class APIs are invokable only from the + * S-Locked state. See @ref system_states. * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). * * @section interrupt_classes Interrupt Classes @@ -83,14 +83,14 @@ * goes in this state and waits for interrupts, after servicing the interrupt * the Normal state is restored and the scheduler has a chance to reschedule. * - S-Locked. Kernel locked and regular interrupt sources disabled. - * Fast interrupt sources are enabled. S-Class and I-Class APIs are + * Fast interrupt sources are enabled. @ref S-Class and @ref I-Class APIs are * invokable in this state. * - I-Locked. Kernel locked and regular interrupt sources disabled. - * I-Class APIs are invokable from this state. + * @ref I-Class APIs are invokable from this state. * - Serving Regular Interrupt. No system APIs are accessible but it is * possible to switch to the I-Locked state using @p chSysLockFromIsr() and - * then invoke any I-Class API. Interrupt handlers can be preemptable on some - * architectures thus is important to switch to I-Locked state before + * then invoke any @ref I-Class API. Interrupt handlers can be preemptable on + * some architectures thus is important to switch to I-Locked state before * invoking system APIs. * - Serving Fast Interrupt. System APIs are not accessible. * - Serving Non-Maskable Interrupt. System APIs are not accessible. diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index fe74d90e9..1b3932078 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -39,8 +39,8 @@ CH_IRQ_HANDLER(myIRQ) { CH_IRQ_EPILOGUE(); } * @endcode - * Note that only interrupt handlers that have to invoke system I-Class APIs - * must be written in this form, handlers unrelated to the OS activity can + * Note that only interrupt handlers that have to invoke system @ref I-Class + * APIs must be written in this form, handlers unrelated to the OS activity can * omit the macros. * Another note about the handler name "myIRQ", in some ports it must be a * vector number rather than a function name, it could also be a name from diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index a666a6aa0..afe0fa687 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -36,6 +36,10 @@ * application without have to release your source code under certains * conditions. See the exception text under "Approved Interfaces" for * details. + * - Is the exception applicable to any ChibiOS/RT version ?
+ * The exception is valid only for ChibiOS/RT releases marked as @e stable. + * Beta or unstable versions are covered by the GPL3 alone because are meant + * for testing only. * - I don't want to be bound by any of the above restriction, is this * possible?
* You may contact us about a commercial license. diff --git a/docs/src/timing.dox b/docs/src/timing.dox index c1a33ae19..9fd19545d 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -36,7 +36,7 @@ msg_t my_thread(void *param) { * well below the system tick period and that @p my_thread() is not preempted * by other threads inserting long intervals.
* If the above conditions are not satisfied you may have @p do_something() - * executed at irregular intevals, as example:

+ * executed at irregular intervals, as example:

* T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.

* Also note that the error increases over time and this kind of behavior can * lead anomalies really hard to debug. -- cgit v1.2.3 From e4245075bef0e790f228d47c4dfb0380f878cf4f Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 4 Feb 2009 15:18:37 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@715 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/portguide.dox | 114 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 docs/src/portguide.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 59350b732..61080f196 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -21,6 +21,7 @@ * @page articles Articles * @{ * ChibiOS/RT Articles and Code Examples: + * - @subpage article_portguide * - @subpage article_atomic * - @subpage article_saveram * - @subpage article_interrupts diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox new file mode 100644 index 000000000..57216885d --- /dev/null +++ b/docs/src/portguide.dox @@ -0,0 +1,114 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_portguide Porting ChibiOS/RT for Dummies + * @{ + * Porting the operating system on a new platform is one of the most common + * tasks. The difficulty can range from easy to very difficult depending + * on several factors.
+ * We can divide in problem in several classes of progressively increasing + * difficulty: + * - @ref port_board + * - @ref port_family + * - @ref port_chip + * - @ref port_core + * . + * Another kind of port type is porting to another compiler and this is an + * added complexity level on the above classes. The kernel itself is portable + * but the port-specific code usually contains compiler specific extensions to + * the C language and the asm files syntax is almost never compatible. + * + * @section port_board Porting the OS to a new board + * This is the easiest port type, the scenario is that the specific + * microcontroller is already supported and a demo exists. This scenario also + * applies when porting the OS on a custom hardware using a supported + * microcontroller. This task can be easily performed with the following + * steps: + * -# Create a new directory under the ChibiOS/RT installation directory: + * ./projects/@ + * -# Copy the microcontroller demo code under the newly created directory. + * -# Customize the demo. Usually there are only four files that need to + * be modified: + * - @p board.h This file contains the I/O pins setup for the uC, it + * may also contain other board-dependent settings, as example, clock and + * PLL settings. Customize this file depending on your target hardware. + * - @p board.c This file contains the initialization code, it is possible + * you just need to customize @p board.h and not this file. If you have + * some hardware specific initialization code then put it here. + * - @p Makefile You may edit this file in order to remove the test related + * sources and/or add you application source files. + * - @p main.c It contains the demo simple code, clean it and write your + * own @p main() function here, use this file just as a template. + * -# Compile your application and debug. + * . + * @section port_family Porting the OS to a closely related microcontroller + * In this scenario all the above steps are required but an analysis must + * be performed to evaluate the differences between from the supported micro + * and the target micro. Often the micros just differ for the memory area + * sizes and a change to the linker script is enough (the file is usually + * named @p ch.ld). Chips having more or less peripherals, everything else + * being the same or compatible are not a problem also as long the timer and + * the serial peripherals used by the port do not change.
+ * If there are differences in the internal peripherals, as example non + * compatible interrupt controllers (this happens in the LPC2000 family) + * or differences in UARTS, timers etc then the port falls in the following + * category. + * + * @section port_chip Porting the OS to another microcontroller using the same core + * This kind of port is required when a target microcontroller has the same + * 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 ./ports and name it as follow: + * @-@[-@] + * The compiler part can be omitted if the port uses GCC (our default). + * Examples: @p ARM7-LPC236x or @p ARMCM3-STM32F103-IAR + * -# Copy into the newly created directory the most closely related existing + * chip port. + * -# Rename the files in order to reflect the name of the new chip. + * -# Work out the differences in the drivers. + * -# Edit the documentation file @p port.dox, this is required if you want + * to regenerate this documentation including your work. + * . + * Usually this kind of port just requires a serial driver (and those are very + * similar each other) and some code for the interrupt controller (this one + * can be part of the core port, as example the Cortex-M3 has this as standard + * part of the core).
+ * When the chip port is completed created your application as seen in the + * previous sections. + * + * @section port_core Porting the OS to a whole new architecture + * This is the hardest scenario, the time required by core ports depends + * strongly by the target architecture complexity and the level of support you + * need for the architecture specific features.
+ * As a reference, the MSP430 port took me 2 hours and it worked at the first + * run, it can be a reference for simple architectures, the ARM Cortex-M3 was + * painful instead, the architecture enforces you to implement things in a very + * specific way and I spent 2 week to go through all the documentation and + * figure out the correct way to implement the port (you can see that the + * preemption context switch is done in a very peculiar way because the + * exceptions architecture).
+ * One thing is sure, port an OS to a new architecture is not an easy task and + * if you have the required experience for such an effort then probably you + * don't need any advice from me. Just follow the directory patterns and fill + * the OS template files, the hardest part is decide the correct and efficient + * way to implement the context switching. + */ +/** @} */ -- cgit v1.2.3 From 9869b77a9a8af56192e4bcf65b70757bb12ca514 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 5 Feb 2009 21:26:18 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@723 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/concepts.dox | 9 +++++---- docs/src/interrupts.dox | 1 + docs/src/jitter.dox | 4 ++-- docs/src/licfaq.dox | 2 +- 5 files changed, 10 insertions(+), 7 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 61080f196..a14a7285b 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -27,5 +27,6 @@ * - @subpage article_interrupts * - @subpage article_jitter * - @subpage article_timing + * . */ /** @} */ diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 9c0a1d9c2..360e5f4f2 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -37,6 +37,7 @@ * I-Locked or S-Locked states. See @ref system_states. * - @anchor S-Class "S", S-Class APIs are invokable only from the * S-Locked state. See @ref system_states. + * . * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). * * @section interrupt_classes Interrupt Classes @@ -57,7 +58,7 @@ * - Non Maskable Interrupts. Non maskable interrupt sources are * totally out of the operating system control and have the lowest latency. * Such sources are not supported on all the architectures. - * + * . * The mapping of the above logical classes into physical interrupts priorities * is, of course, port dependent. See the documentation of the various ports * for details. @@ -98,7 +99,7 @@ * an infinite loop. This state can be reached if the debug mode is activated * and an error is detected or after explicitly invoking * @p chSysHalt(). - * + * . * Note that the above state are just Logical States that may have no * real associated machine state on some architectures. The following diagram * shows the possible transitions between the states: @@ -216,7 +217,7 @@ * @p HIGHPRIO but the numerical values above @p HIGHPRIO up to @p ABSPRIO * (inclusive) are reserved. This is the highest numerical value of the * priorities space. - * + * . * @section warea Thread Working Area * Each thread has its own stack, a Thread structure and some preemption * areas. All the structures are allocated into a "Thread Working Area", @@ -233,7 +234,7 @@ * - External Context. * - Interrupt Stack. * - Internal Context. - * + * . * See the @ref Core documentation for details, the area may change on * the various ports and some structures may not be present (or be zero-sized). */ diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 1b3932078..679eb8884 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -48,6 +48,7 @@ CH_IRQ_HANDLER(myIRQ) { *

Important Notes

* - There is an important application note about ARM7 interrupt handlers, * please read about it in the ARM7 port section: @ref ARM7_IH + * . */ /** @} */ \ No newline at end of file diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 3e2ec1cb4..d0215abb2 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -37,7 +37,7 @@ * - OS overhead. Any operating system requires to run some extra code * in interrupt handlers in order to handle correct preemption and Context * Switching. - * + * . *

Interrupt Response Time

* The Interrupt Response Time is the time from an interrupt event and the * execution of the handler code. Unfortunately this time is not constant @@ -67,7 +67,7 @@ * can be preempted by higher priority sources. * - Longest time in a kernel lock zone that can delay interrupt servicing. * This value is zero for fast interrupt sources, see @ref system_states. - * + * . *

Threads Flyback Time

* This is the time between an event, as example an interrupt, and the * execution of the thread that will process it. Imagine the following diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index afe0fa687..f3bf3c3a1 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -43,7 +43,7 @@ * - I don't want to be bound by any of the above restriction, is this * possible?
* You may contact us about a commercial license. - * + * . * @section exception_text GPL Exception Text
GPL Exception Text
-- cgit v1.2.3 From 50bebb29768a76567c9540c9f236d8ad22c86d60 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 11 Feb 2009 19:37:57 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@752 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 3 +- docs/src/goals.dox | 88 ++++++++++++++++++++ docs/src/mutualexcl.dox | 213 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 303 insertions(+), 1 deletion(-) create mode 100644 docs/src/goals.dox create mode 100644 docs/src/mutualexcl.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index a14a7285b..590efdda7 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -21,12 +21,13 @@ * @page articles Articles * @{ * ChibiOS/RT Articles and Code Examples: - * - @subpage article_portguide + * - @subpage article_mutual_exclusion * - @subpage article_atomic * - @subpage article_saveram * - @subpage article_interrupts * - @subpage article_jitter * - @subpage article_timing + * - @subpage article_portguide * . */ /** @} */ diff --git a/docs/src/goals.dox b/docs/src/goals.dox new file mode 100644 index 000000000..4df7eaba7 --- /dev/null +++ b/docs/src/goals.dox @@ -0,0 +1,88 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page goals Project Goals + * @{ + *

Another RTOS?

+ * The first question to be answered is: there was really the need for YET + * ANOTHER RTOS?
+ * My answer is yes because various reasons: + * - The ChibiOS/RT ancestor was created more than 15 years ago and while it + * had far less features than the current product it was complete and + * functioning. ChibiOS/RT is just a new (and silly) name given to + * something created when there were not many free RTOSes around (actually + * none, at least none in my knowledge, there was no widespread Internet + * at that time). + * - When, after a while, I needed a RTOS again, none of the existing FOSS + * projects met my expectations or my ideas of how a RTOS should be, not + * even close (see below). I decided that work on that old project was + * a better idea that contribute to, or fork, something else. + * - I wanted another toy. + * . + *

Why is it different?

+ * In itself it implements ideas already seen in other projects but never + * all together in a single FOSS project. There are some basic choices in + * ChibiOS/RT (mostly derived by its ancestor): + * + *

Static design

+ * Everything in the kernel is static, nowhere memory is allocated or freed, + * there are two allocator subsystems but those are options and not part of + * core OS. Safety is something you design in, not something you can add later. + * + *

No fixed size tables or structures

+ * No tables to configure, no arrays that can be filled and overflow at + * runtime. Everything without practical upper bounds (except for resource + * limits and numerical upper bounds of course). + * + *

No error conditions and no error checks

+ * All the API should not have error conditions, all the previous points are + * finalized to this objective. Everything you can invoke in the kernel is + * designed to not fail unless you pass garbage as parameters, stray pointers + * or such. Also the APIs are not slowed down by error checks, error checks + * exists but only when the debug switch is activated.
+ * All the static core APIs always succeed if correct parameters are passed. + * + *

Very simple APIs

+ * Every API should have the parameters you would expect for that function, no + * more no less. Each API should do a single thing with no options. + * + *

Damn fast and compact

+ * Note first "fast" then "compact", the focus is on speed and execution + * efficiency rather than code size. This does not mean it is large, the OS + * with all the subsystems activated is well below 8KiB (32bit ARM code, the + * least space efficient) and can shrink down below 2KiB. It would be + * possible to make something smaller but: + * -# It would be pointless, it @a is already small. + * -# I would not sacrifice efficiency or features in order to save few bytes. + * . + * About the "fast" part, it is able to start/wait/exit more than 200,000 + * threads per second on a 72MHz STM32 (Cortex-M3). The Context Switch just + * takes 2.3 microseconds on the same STM32. The numbers are not + * pulled out of thin air, it is the output of the included test suite. + * + *

Tests and metrics

+ * I think it is nice to know how an OS is tested and how it performs before + * committing to use it. Test results on all the supported platforms and + * performance metrics are included in each ChibiOS/RT release. The test + * code is released as well, all the included demos are capable of executing + * the test suite and the OS benchmarks. + */ +/** @} */ + \ No newline at end of file diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox new file mode 100644 index 000000000..367618d5d --- /dev/null +++ b/docs/src/mutualexcl.dox @@ -0,0 +1,213 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_mutual_exclusion Mutual Exclusion guide + * @{ + * The most common problem when writing multithreaded code is the + * synchronization on the shared resources/services.
+ * ChibiOS/RT offers a rich variety of mechanisms that apparently solve the + * same problem. I wrote apparently because each mechanism has its pro and + * cons. + * This article will introduce the various mechanisms and the explain the + * right scenarios for each one. + * + *

Basics

+ * Some of the concepts mentioned in this article can be found in the + * following Wikipedia articles: + * - + * Mutual Exclusion + * - + * Priority Inversion + * - Priority Inheritance + * - + * Priority Ceiling + * . + *

Mutual exclusion by System Locks

+ * This is the lowest level mechanism, the system is locked by invoking the + * @p chSysLock() API and then unlocked by invoking @p chSysUnlock().
+ * The implementation is architecture dependent but it is guaranteed to, at + * least, disable the interrupt sources with hardware priority below or equal + * the kernel level. + * + *

Advantages

+ * - It is the lightest as execution time, often a lock or unlock becomes just a + * single inlined assembler instruction. + * - It ensures mutual exclusion among threads but also interrupt handling code. + * - The implementation would ensure mutual exclusion even on multicore + * architectures where multiple hardware threads are present. + * . + *

Disadvantages

+ * - Disabling interrupts for a long period of time can deteriorate the overall + * system response time and/or introduce jitter. + * . + *

When use Locks

+ * - When mutual exclusion with interrupt handlers is required. + * - When the operation within the lock zone is very simple and has finite + * time. + * . + *

Example

+ * @code + * ... + * chSysLock(); + * /* Protected code */ + * chSysUnlock(); + * ... + * @endcode + * + *

Mutual exclusion by Semaphores

+ * In ChibiOS/RT the counting semaphores are mainly meant as a + * synchronization mechanism between interrupt handlers and high level code + * 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. + * + *

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. + * - Semaphores are lighter than mutexes because their queues are FIFO + * ordered and do not have any overhead caused by the priority inheritance + * algorithm. + * - A semaphore takes less RAM than a mutex (12 vs 16 bytes on 32 bit + * architectures). + * . + *

Disadvantages

+ * - Semaphore queues are FIFO ordered by default, an option exist to make + * them priority ordered but this can impact I/O performance because + * semaphores are used in I/O queues. + * - Semaphores do not implement the priority inheritance algorithm so the + * priority inversion problem is not mitigated. + * . + *

When use Semaphores

+ * - When you don't need queuing by priority nor the priority inheritance + * algorithm. + * - When RAM/ROM space is scarce. + * . + *

Example

+ * @code + * static Semaphore sem; /* Semaphore declaration */ + * ... + * chSemInit(&sem, 1); /* Semaphore initialization before use */ + * ... + * chSemWait(&sem); + * /* Protected code */ + * chSemSignal(&sem); + * ... + * @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 the mutual exclusion problem. + * + *

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

Disadvantages

+ * - Heaviest among all the possible choices. The Priority Inheritance method + * is efficiently implemented but nothing is more efficient than no code at + * all. + * . + *

When use Mutexes

+ * - When you are designing a very complex system with hard realtime + * requirements. + * . + *

Example

+ * @code + * static Mutex mtx; /* Mutex declaration */ + * ... + * chMtxInit(&mtx); /* Mutex initialization before use */ + * ... + * chMtxLock(&mtx); + * /* Protected code */ + * chMtxUnlock(); + * ... + * @endcode + * + *

Mutual exclusion by priority boost

+ * Another way to implement mutual exclusion is to boost the thread priority + * to a level higher than all of the threads competing for a certain resource. + * This solution effectively implements an Immediate Priority Ceiling + * algorithm. + * + *

Advantages

+ * - Almost free as code size, you need no semaphores nor mutexes. + * - No RAM overhead. + * - Fast execution, priority change is a quick operation under ChibiOS/RT. + * - The priority ceiling protocol that can help mitigate the Priority + * Inversion problem. + * . + *

Disadvantages

+ * - Makes the design more complicated because priorities must be assigned to + * not just threads but also assigned to the resources to be protected. + * - Locking a resource affects all the threads with lower priority even if + * not interested to the resource. + * - All the threads that can access the resource must have lower priority + * than the resource itself. + * - The mechanism is not easy to understand in the code unless it is clearly + * documented. + * - This method does not work in on multicore architectures where multiple + * hardware threads are present. + * - Only useful in very simple applications. + * . + *

Example

+ * @code + * /* Priority assigned to the resource, threads must have lower + * priority than this.*/ + * #define AAA_RESOURCE_PRIORITY NORMALPRIO+10 + * ... + * /* Locks the resources AAA.*/ + * tprio_t aaa_old_prio = chThdSetPriority(AAA_RESOURCE_PRIORITY); + * /* Accessing resource AAA */ + * chThdSetPriority(aaa_old_prio); /* Unlocks AAA.*/ + * ... + * @endcode + * + *

Mutual exclusion by message passing

+ * Another method is to make a single dedicated thread execute the critical + * code and make it work as a messages server. The other threads can request + * the service to the server by sending a properly formatted message and + * then wait for the answer with the result.
+ * This method is very useful when integrating into the system components not + * designed to be reentrant or to be executed in a multithreaded environment, + * as example a 3rd part file system or a networking protocol stack. + * + *

Advantages

+ * - It is possible to encapsulate very complex logic without worry about + * about concurrent accesses. + * - If the encapsulate code uses a large stack area only the server thread + * have to allocate enough RAM, the client threads save RAM by just + * requesting the service to the server. + * - Clean system architecture. + * - This method also implements a form of Priority Ceiling. The ceiling is + * the priority of the server thread itself. + * . + *

Disadvantages

+ * - More complex implementation, a protocol must be created between clients + * and server. + * - Two context switches are required for each request to the server (but + * ChibiOSRT is very efficient at that). + * - Requires a dedicated thread. + * . + */ +/** @} */ -- cgit v1.2.3 From 8486b10c8ff5989c37f92ad028dc7e3ffb9846a1 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 11 Feb 2009 21:05:12 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@753 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 43 +++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 20 deletions(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index 4df7eaba7..f0de70da7 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -23,7 +23,7 @@ *

Another RTOS?

* The first question to be answered is: there was really the need for YET * ANOTHER RTOS?
- * My answer is yes because various reasons: + * There are several reasons: * - The ChibiOS/RT ancestor was created more than 15 years ago and while it * had far less features than the current product it was complete and * functioning. ChibiOS/RT is just a new (and silly) name given to @@ -37,45 +37,48 @@ * - I wanted another toy. * . *

Why is it different?

- * In itself it implements ideas already seen in other projects but never - * all together in a single FOSS project. There are some basic choices in - * ChibiOS/RT (mostly derived by its ancestor): + * Well, there are some design choices that should be explained and contribute + * to make ChibiOS/RT a peculiar design. Nothing really new by itself but + * the whole is interesting: * *

Static design

* Everything in the kernel is static, nowhere memory is allocated or freed, * there are two allocator subsystems but those are options and not part of * core OS. Safety is something you design in, not something you can add later. * - *

No fixed size tables or structures

- * No tables to configure, no arrays that can be filled and overflow at - * runtime. Everything without practical upper bounds (except for resource - * limits and numerical upper bounds of course). + *

No tables or other fixed structures

+ * The kernel has no internal tables, there is nothing that must be configured + * at design time or that can overflow at run time. No upper bounds, the + * internal structures are all dynamic even if all the objects are statically + * allocated. Things that are not there cannot go wrong and take no space. * *

No error conditions and no error checks

- * All the API should not have error conditions, all the previous points are + * All the system APIs have no error conditions, all the previous points are * finalized to this objective. Everything you can invoke in the kernel is * designed to not fail unless you pass garbage as parameters, stray pointers - * or such. Also the APIs are not slowed down by error checks, error checks - * exists but only when the debug switch is activated.
+ * as examples. The APIs are not slowed down by parameter checks, + * parameter checks (and consistency checks) do exists but only when the + * debug switch is activated.
* All the static core APIs always succeed if correct parameters are passed. * *

Very simple APIs

* Every API should have the parameters you would expect for that function, no - * more no less. Each API should do a single thing with no options. + * more no less. Each API does a single thing with no options. * - *

Damn fast and compact

+ *

Fast and compact

* Note first "fast" then "compact", the focus is on speed and execution * efficiency rather than code size. This does not mean it is large, the OS - * with all the subsystems activated is well below 8KiB (32bit ARM code, the - * least space efficient) and can shrink down below 2KiB. It would be + * size with all the subsystems activated is well below 8KiB (32bit ARM code, + * the least space efficient) and can shrink down below 2KiB. It would be * possible to make something smaller but: - * -# It would be pointless, it @a is already small. + * -# It would be pointless, it is already @a really small. * -# I would not sacrifice efficiency or features in order to save few bytes. * . - * About the "fast" part, it is able to start/wait/exit more than 200,000 - * threads per second on a 72MHz STM32 (Cortex-M3). The Context Switch just - * takes 2.3 microseconds on the same STM32. The numbers are not - * pulled out of thin air, it is the output of the included test suite. + * About the "fast" part, the kernel is able to start/exit more than + * 200,000 threads per second on a 72MHz STM32 (Cortex-M3). + * The Context Switch just takes 2.3 microseconds on the same STM32. + * The numbers are not pulled out of thin air, it is the output of the + * included test suite. * *

Tests and metrics

* I think it is nice to know how an OS is tested and how it performs before -- cgit v1.2.3 From ea63ddb71973bf7e4d46acde3bfd9037da159a3e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 11 Feb 2009 21:26:09 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@754 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index f0de70da7..d19c7d70a 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -48,7 +48,7 @@ * *

No tables or other fixed structures

* The kernel has no internal tables, there is nothing that must be configured - * at design time or that can overflow at run time. No upper bounds, the + * at compile time or that can overflow at run time. No upper bounds, the * internal structures are all dynamic even if all the objects are statically * allocated. Things that are not there cannot go wrong and take no space. * -- cgit v1.2.3 From af4eb6b7901f0871d46b4de27486f47266f24e99 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 12 Feb 2009 21:29:43 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@755 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 27 +++++++++++++-------------- docs/src/mutualexcl.dox | 13 ++++++------- 2 files changed, 19 insertions(+), 21 deletions(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index d19c7d70a..3a2209f0c 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -38,7 +38,7 @@ * . *

Why is it different?

* Well, there are some design choices that should be explained and contribute - * to make ChibiOS/RT a peculiar design. Nothing really new by itself but + * to make ChibiOS/RT a peculiar design. Nothing really new in itself but * the whole is interesting: * *

Static design

@@ -46,11 +46,11 @@ * there are two allocator subsystems but those are options and not part of * core OS. Safety is something you design in, not something you can add later. * - *

No tables or other fixed structures

+ *

No tables, arrays or other fixed structures

* The kernel has no internal tables, there is nothing that must be configured * at compile time or that can overflow at run time. No upper bounds, the * internal structures are all dynamic even if all the objects are statically - * allocated. Things that are not there cannot go wrong and take no space. + * allocated. * *

No error conditions and no error checks

* All the system APIs have no error conditions, all the previous points are @@ -60,25 +60,25 @@ * parameter checks (and consistency checks) do exists but only when the * debug switch is activated.
* All the static core APIs always succeed if correct parameters are passed. + * Exception to this are the optional allocators APIs that, of course, + * can report memory exhausted. * *

Very simple APIs

* Every API should have the parameters you would expect for that function, no * more no less. Each API does a single thing with no options. * *

Fast and compact

- * Note first "fast" then "compact", the focus is on speed and execution - * efficiency rather than code size. This does not mean it is large, the OS - * size with all the subsystems activated is well below 8KiB (32bit ARM code, - * the least space efficient) and can shrink down below 2KiB. It would be - * possible to make something smaller but: + * Note, first "fast" then "compact", the focus is on speed and execution + * efficiency and then on code size. This does not mean that the OS is large, + * the kernel size with all the subsystems activated is around 5.3KiB + * and can shrink down around to 1.2Kib in a minimal configuration + * (STM32, Cortex-M3). It would be possible to make something even smaller but: * -# It would be pointless, it is already @a really small. - * -# I would not sacrifice efficiency or features in order to save few bytes. + * -# I would not trade efficiency or features in order to save few bytes. * . * About the "fast" part, the kernel is able to start/exit more than - * 200,000 threads per second on a 72MHz STM32 (Cortex-M3). - * The Context Switch just takes 2.3 microseconds on the same STM32. - * The numbers are not pulled out of thin air, it is the output of the - * included test suite. + * 200,000 threads per second on a 72MHz STM32. + * The Context Switch takes 2.3 microseconds on the same STM32. * *

Tests and metrics

* I think it is nice to know how an OS is tested and how it performs before @@ -88,4 +88,3 @@ * the test suite and the OS benchmarks. */ /** @} */ - \ No newline at end of file diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox index 367618d5d..ae6f57c0a 100644 --- a/docs/src/mutualexcl.dox +++ b/docs/src/mutualexcl.dox @@ -93,11 +93,10 @@ * - Semaphore queues are FIFO ordered by default, an option exist to make * them priority ordered but this can impact I/O performance because * semaphores are used in I/O queues. - * - Semaphores do not implement the priority inheritance algorithm so the - * priority inversion problem is not mitigated. + * - Semaphores do not implement the Priority Inheritance algorithm. * . *

When use Semaphores

- * - When you don't need queuing by priority nor the priority inheritance + * - When you don't need queuing by priority nor the Priority Inheritance * algorithm. * - When RAM/ROM space is scarce. * . @@ -116,7 +115,7 @@ *

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 the mutual exclusion problem. + * intended as general solution for Mutual Exclusion. * *

Advantages

* - Mutexes implement the Priority Inheritance algorithm that is an important @@ -154,8 +153,8 @@ * - Almost free as code size, you need no semaphores nor mutexes. * - No RAM overhead. * - Fast execution, priority change is a quick operation under ChibiOS/RT. - * - The priority ceiling protocol that can help mitigate the Priority - * Inversion problem. + * - The Priority Ceiling protocol can help mitigate potential Priority + * Inversion problems. * . *

Disadvantages

* - Makes the design more complicated because priorities must be assigned to @@ -207,7 +206,7 @@ * and server. * - Two context switches are required for each request to the server (but * ChibiOSRT is very efficient at that). - * - Requires a dedicated thread. + * - Requires a dedicated thread as server. * . */ /** @} */ -- cgit v1.2.3 From a200e0aaff1eb04789057603f528510c1da1c4d2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 13 Feb 2009 16:04:20 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@756 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 4 ++-- docs/src/jitter.dox | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index 3a2209f0c..13e764802 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -64,8 +64,8 @@ * can report memory exhausted. * *

Very simple APIs

- * Every API should have the parameters you would expect for that function, no - * more no less. Each API does a single thing with no options. + * Each API should have the parameters you would expect for that function and + * do just one thing with no options. * *

Fast and compact

* Note, first "fast" then "compact", the focus is on speed and execution diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index d0215abb2..bff39bed6 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -55,6 +55,7 @@ int -> busy [label="Not Ready"]; busy -> busy [label="Still Busy\n(added latency)"]; busy -> served [label="Finally Ready"]; + } * @enddot * * In this scenario the jitter (busy state) is represented by the sum of: @@ -85,6 +86,7 @@ busy -> busy [label="Higher priority Threads\n(added latency)"]; busy -> thread [label="Highest Priority"]; served -> thread [label="Highest Priority (minimum latency)"]; + } * @enddot * * In this scenario all the jitter sources previously discussed are also -- cgit v1.2.3 From ad0dd210e7fbb030b10e1cb076b833bd7ae6470d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 13 Feb 2009 20:34:09 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@757 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/jitter.dox | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index bff39bed6..747a07a7e 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -24,7 +24,8 @@ * designing a real time system. When using a RTOS like ChibiOS/RT one must * be aware of what the jitter is and how it can affect the performance of the * system. A good place to start is this - * Wikipedia article. + * Wikipedia + * article. * *

Interrupt handlers execution time

* The total execution time of an interrupt handler includes: -- cgit v1.2.3 From e9274448e9058df5a32e43212ee9858006fe1c4d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 24 Feb 2009 16:07:42 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@802 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/stacks.dox | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/src/stacks.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 590efdda7..a0426f41c 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -21,6 +21,7 @@ * @page articles Articles * @{ * ChibiOS/RT Articles and Code Examples: + * - @subpage article_stacks * - @subpage article_mutual_exclusion * - @subpage article_atomic * - @subpage article_saveram diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox new file mode 100644 index 000000000..e824ea04a --- /dev/null +++ b/docs/src/stacks.dox @@ -0,0 +1,106 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_stacks Stacks and stack sizes + * @{ + * In a 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 + * others are present only in some architectures: + * - Main stack, this stack is used by the @p main() function and the + * thread that execute it. It is not a normal thread stack because it is + * initialized in the startup code and its size is defined in a port + * dependent way. Details are in the various ports documentation. + * - Interrupt Stack, some architectures have a dedicated interrupt + * stack. This is an important feature in a multithreaded environment, + * without a dedicated interrupt stack each thread has to reserve + * enough space, for interrupts servicing, within its own stack. This space, + * multiplied by the total threads number, can be a significant RAM waste. + * - Thread Stack, each thread has a dedicated stack for its own + * execution and context switch. + * - Other Stacks, some architectures (ARM) can have other stacks but + * the OS does not directly use any of them. + * . + *

Risks

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

Assign the correct size

+ * You may try to examine the asm listings in order to calculate the exact + * stack requirements but this requires much time, experience and patience.
+ * An alternative way is to use an interactive method. Follow this procedure + * for each thread in the system: + * - Enable the following debug options in the kernel: + * - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any + * context switch. This option halts the system in @p chSysHalt() just + * before a stack overflow happens. + * - @p CH_DBG_FILL_THREADS, this option fills the threads working area + * with an easily recognizable pattern (0x55). + * - Assign a large and safe size to the thread stack, as example 256 bytes + * on 32 MCUs, 128 bytes on 8/16 bit MCUs. This is almost always too much + * for simple threads. + * - Run the application, if the application crashes or halts then increase + * the stack size and repeat (you know how to use the debugger right?). + * - Let the application run and make sure to trigger the thread in a way to + * make it follow most or all its code paths. If the application crashes or + * halts then increase the stack size and repeat. + * - Stop the application using the debugger and examine the thread working + * area (you know what a map file is, right?). You can see that the thread + * stack overwrote the fill pattern (0x55) from the top of the working area + * downward. You can estimate the excess stack by counting the untouched + * locations. + * - Trim down the stack size and repeat until the application still runs + * correctly and you have a decent margin in the stack. + * - Repeat for all the thread classes in the system. + * - Turn off the debug options. + * - Done. + * . + *

Final Notes

+ * Some useful info: + * - Stack overflows are the most common source of problems during development, + * when in trouble with crashes or anomalous behaviors always first verify + * stack sizes. + * - The required stack size can, and very often does change when changing + * compiler vendor, compiler version, compiler options, code type (ARM + * or THUMB as example). + * - Code compiled in THUMB mode uses more stack space compared to the + * same code compiled in ARM mode. In GCC this is related to lack of tail + * calls optimizations in THUMB mode, this is probably true also in other + * compilers. + * - Speed optimized code often requires less stack space compared to space + * optimized code. Be careful when changing optimizations. + * - The interrupts space overhead on the thread stacks (@p INT_REQUIRED_STACK + * defined in @p chcore.h) is included in the total working area size + * by the system macros @p THD_WA_SIZE() and @p WORKING_AREA().
+ * The correct way to reserve space into the thread stacks for interrupts + * processing is to override the @p INT_REQUIRED_STACK default value. + * Architectures with a dedicated interrupt stack do not require changes + * 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. + * . + */ +/** @} */ -- cgit v1.2.3 From eb75c053eb46cbeb4ad9c0b7b179ba1acb20eba4 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 28 Feb 2009 09:39:02 +0000 Subject: Added new benchmarks about semaphores and mutexes to the test suite. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@804 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/stacks.dox | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox index e824ea04a..a27c2e1b9 100644 --- a/docs/src/stacks.dox +++ b/docs/src/stacks.dox @@ -33,7 +33,8 @@ * stack. This is an important feature in a multithreaded environment, * without a dedicated interrupt stack each thread has to reserve * enough space, for interrupts servicing, within its own stack. This space, - * multiplied by the total threads number, can be a significant RAM waste. + * multiplied by the total threads number, can amount to a significant RAM + * overhead. * - Thread Stack, each thread has a dedicated stack for its own * execution and context switch. * - Other Stacks, some architectures (ARM) can have other stacks but @@ -46,7 +47,7 @@ * Assign too much space to a stack wastes RAM, assign too little space * leads to crashes or, worst scenario, hard to track instability. * - *

Assign the correct size

+ *

Assigning the correct size

* You may try to examine the asm listings in order to calculate the exact * stack requirements but this requires much time, experience and patience.
* An alternative way is to use an interactive method. Follow this procedure @@ -78,7 +79,7 @@ * . *

Final Notes

* Some useful info: - * - Stack overflows are the most common source of problems during development, + * - Stack overflows are the most common problems source during development, * when in trouble with crashes or anomalous behaviors always first verify * stack sizes. * - The required stack size can, and very often does change when changing -- cgit v1.2.3 From 75813bcef30adf76c54ab1f7f02203896320b8c5 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 7 Mar 2009 10:07:12 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@809 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 407 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 407 insertions(+) create mode 100644 docs/src/main.dox (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox new file mode 100644 index 000000000..58a96870d --- /dev/null +++ b/docs/src/main.dox @@ -0,0 +1,407 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @mainpage ChibiOS/RT + * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net). + * + *

Chibi ?

+ * I didn't want a serious name for this project. It is the Japanese word for + * small as in small child. So ChibiOS/RT + * @htmlonly (ちびOS/RT) @endhtmlonly + * means small Real Time Operating System. + * Source Wikipedia. + * + *

Features

+ * - Free software, GPL3 licensed. Stable releases include a exception clause + * to the GPL. + * - Designed for realtime applications. + * - Easily portable. + * - Preemptive scheduling. + * - 128 priority levels. Multiple threads at the same priority level allowed. + * - Round robin scheduling for threads at the same priority level. + * - Offers threads, virtual timers, semaphores, mutexes, condvars, + * event flags, messages, I/O queues. + * - No static setup at compile time, there is no need to configure a maximum + * number of all the above objects. + * - PC simulator target included, the development can be done on the PC + * using MinGW.
+ * Timers, I/O channels and other HW resources are simulated in a + * Win32 process and the application code does not need to be aware of it. + * MinGW demo available. + * - No *need* for a memory allocator, all the kernel structures are static + * and declaratively allocated. + * - Optional, thread safe, Heap Allocator subsystem. + * - Optional, thread safe, Memory Pools Allocator subsystem. + * - Blocking and non blocking I/O channels with timeout and events generation + * capability. + * - Minimal system requirements: about 8KiB ROM with all options enabled and + * speed optimizations on. The size can shrink under 2KiB by disabling the + * the unused subsystems and optimizing for size. + * - Almost totally written in C with little ASM code required for ports. + * . + *

Related pages

+ * - @subpage lic_faq + * - @subpage goals + * - @subpage concepts + * - @subpage articles + * . + */ + +/** + * @defgroup Ports Ports + * @{ + * This section describes the technical details for the various supported + * ChibiOS/RT ports. + */ +/** @} */ + +/** + * @defgroup Kernel Kernel + * @{ + */ +/** @} */ + +/** + * @defgroup Config Configuration + * @{ + * In @p chconf.h are defined the required subsystems for your application. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Core Generic Port Code Templates + * @{ + * Non portable code templates. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Types Types + * @{ + * System types and macros. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup System System Management + * @{ + * Initialization, Locks, Interrupt Handling, Power Management, Abnormal + * Termination. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Inline Inline + * @{ + * System inline-able code. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Debug Debug + * @{ + * Debug APIs and procedures. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Scheduler Scheduler + * @{ + * ChibiOS/RT scheduler. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup ThreadLists Thread Lists and Queues + * @{ + * ChibiOS/RT thread lists and queues utilities. + * @ingroup Kernel + */ +/** @} */ + +/** + * @defgroup Threads Threads + * @{ + * Threads creation and termination APIs. + */ +/** @} */ + +/** + * @defgroup Time Time and Virtual Timers + * @{ + * Time and Virtual Timers related APIs. + */ +/** @} */ + +/** + * @defgroup Heap Heap + * @{ + * Heap Allocator related APIs. + *

Operation mode

+ * The heap allocator implements a first-fit strategy and its APIs are + * functionally equivalent to the usual @p malloc() and @p free(). The main + * difference is that the heap APIs are thread safe.
+ * By enabling the @p CH_USE_MALLOC_HEAP option the heap manager will use the + * runtime-provided @p malloc() and @p free() as backend for the heap APIs + * instead of the system provided allocator.
+ * In order to use the heap APIs the @p CH_USE_HEAP option must be specified + * in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup MemoryPools Memory Pools + * @{ + * Memory Pools related APIs. + *

Operation mode

+ * The Memory Pools APIs allow to allocate/free fixed size objects in + * constant time and reliably without memory fragmentation problems.
+ * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be + * specified in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup Semaphores Semaphores + * @{ + * Semaphores and threads synchronization. + *

Operation mode

+ * A semaphore is a threads synchronization object, some operations + * are defined on semaphores: + * - Signal: The semaphore counter is increased and if the result + * is non-positive then a waiting thread is removed from the semaphore + * queue and made ready for execution. + * - Wait: The semaphore counter is decreased and if the result + * becomes negative the thread is queued in the semaphore and suspended. + * - Reset: The semaphore counter is reset to a non-negative value + * and all the threads in the queue are released. + * . + * Semaphores can be used as guards for mutual exclusion code zones (note that + * mutexes are recommended for this kind of use) but also have other uses, + * queues guards and counters as example.
+ * Semaphores usually use FIFO queues but it is possible to make them + * order threads by priority by specifying CH_USE_SEMAPHORES_PRIORITY in + * @p chconf.h.
+ * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES + * option must be specified in @p chconf.h.

+ */ +/** @} */ + +/** + * @defgroup Mutexes Mutexes + * @{ + * Mutexes and threads synchronization. + *

Operation mode

+ * A mutex is a threads synchronization object, some operations are defined + * on mutexes: + * - Lock: The mutex is checked, if the mutex is not owned by some + * other thread then it is locked else the current thread is queued on the + * mutex in a list ordered by priority. + * - Unlock: The mutex is released by the owner and the highest + * priority thread waiting in the queue, if any, is resumed and made owner + * of the mutex. + * . + * In order to use the Event APIs the @p CH_USE_MUTEXES option must be + * specified in @p chconf.h.
+ * + *

Constraints

+ * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse + * order. The Unlock API does not even have a parameter, the mutex to unlock + * is taken from an internal stack of owned mutexes. + * This both improves the performance and is required by the priority + * inheritance mechanism. + * + *

The priority inversion problem

+ * The mutexes in ChibiOS/RT implements the full priority + * inheritance mechanism in order handle the priority inversion problem.
+ * When a thread is queued on a mutex, any thread, directly or indirectly, + * holding the mutex gains the same priority of the waiting thread (if their + * priority was not already equal or higher). The mechanism works with any + * number of nested mutexes and any number of involved threads. The algorithm + * complexity (worst case) is N with N equal to the number of nested mutexes. + */ +/** @} */ + +/** + * @defgroup CondVars Condition Variables + * @{ + * Condition Variables and threads synchronization. + *

Operation mode

+ * The condition variable is a synchronization object meant to be used inside + * a zone protected by a @p Mutex. Mutexes and CondVars together can implement + * a Monitor construct.
+ * In order to use the Condition Variables APIs the @p CH_USE_CONDVARS + * option must be specified in @p chconf.h.

+ */ +/** @} */ + +/** + * @defgroup Events Events + * @{ + * Event Sources and Event Listeners. + *

Operation mode

+ * An Event Source is a special object that can be signaled by a thread or + * an interrupt service routine. Signaling an Event Source has the effect + * that all the threads registered on the Event Source will receive + * and serve the event.
+ * An unlimited number of Event Sources can exists in a system and each + * thread can listen on an unlimited number of them.
+ * Note that the events can be asynchronously generated but are synchronously + * served, a thread can serve event by calling a @p chEvtWaitXXX() + * API. If an event is generated while a listening thread is not ready to + * serve it then the event becomes "pending" and will be served as soon the + * thread invokes a @p chEvtWaitXXX().
+ * In order to use the Event APIs the @p CH_USE_EVENTS option must be + * specified in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup Messages Synchronous Messages + * @{ + * Synchronous inter-thread messages. + *

Operation Mode

+ * Synchronoud messages are an easy to use and fast IPC mechanism, threads + * can both serve messages and send messages to other threads, the mechanism + * allows data to be carried in both directions. Data is not copied between + * the client and server threads but just a pointer passed so the exchange + * is very time efficient.
+ * Messages are usually processed in FIFO order but it is possible to process + * them in priority order by specifying CH_USE_MESSAGES_PRIORITY + * in @p chconf.h.
+ * Threads do not need to allocate space for message queues, the mechanism + * just requires two extra pointers in the @p Thread structure (the message + * queue header).
+ * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be + * specified in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup Mailboxes Mailboxes + * @{ + * Asynchronous messages. + *

Operation mode

+ * A mailbox is an asynchronous communication mechanism.
+ * The following operations are possible on a mailbox: + * - Post: Posts a message on the mailbox in FIFO order. + * - Post Ahead: Posts a message on the mailbox with high priority. + * - Fetch: A message is fetched from the mailbox and removed from + * the queue. + * - Reset: The mailbox is emptied and all the stored messages lost. + * . + * A message is a variable of type msg_t that is guaranteed to have the + * same size of and be compatible with pointers (an explicit cast is needed). + * If larger messages need to be exchanged then a pointer to a structure can + * be posted in the mailbox but the posting side has no predefined way to + * know when the message has been processed. A possible approach is to + * allocate memory (from a memory pool as example) from the posting side and + * free it on the fetching side. Another approach is to set a "done" flag into + * the structure pointed by the message. + */ +/** @} */ + +/** + * @defgroup IOQueues I/O Queues + * @{ + * ChibiOS/RT supports several kinds of queues. The queues are mostly used + * in serial-like device drivers. The device drivers are usually designed to + * have a lower side (lower driver, it is usually an interrupt service + * routine) and an upper side (upper driver, accessed by the application + * threads).
+ * There are several kind of queues:
+ * - Input queue, unidirectional queue where the writer is the + * lower side and the reader is the upper side. + * - Output queue, unidirectional queue where the writer is the + * upper side and the reader is the lower side. + * - Half duplex queue, bidirectional queue where the buffer is shared + * between a receive and a transmit queues. This means that concurrent + * buffered input and output operations are not possible, this is perfectly + * acceptable for a lot of applications however, as example an RS485 driver. + * - Full duplex queue, bidirectional queue where read and write + * operations can happen at the same time. Full duplex queues + * are implemented by pairing an input queue and an output queue together. + * . + * In order to use the I/O queues the @p CH_USE_QUEUES option must + * be specified in @p chconf.h.
+ * In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX + * option must be specified in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup Serial Serial Drivers + * @{ + * This module implements a generic full duplex serial driver and a generic + * half duplex serial driver. It uses the I/O Queues for communication between + * the upper and the lower driver and events to notify the application about + * incoming data, outcoming data and other I/O events. + * The module also contains functions that make the implementation of the + * interrupt service routines much easier.
+ * In order to use the serial full duplex driver the + * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
+ * In order to use the serial half duplex driver the + * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h. + */ +/** @} */ + +/** + * @defgroup utilities_library Utilities Library + * @{ + * @brief Utilities Library. + * @details This is a collection of useful library code that is not part of + * the base kernel services. + *

Notes

+ * The library code does not follow the same naming convention of the + * system APIs in order to make very clear that it is not "core" code.
+ * The main difference is that library code is not formally tested in the + * test suite but through usage in the various demo applications. + */ +/** @} */ + +/** + * @defgroup CPlusPlusLibrary C++ Wrapper + * @{ + * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities + * from C++ as classes and objects rather the traditional "C" APIs. + * + * @ingroup utilities_library + */ +/** @} */ + +/** + * @defgroup event_timer Events Generator Timer + * @{ + * @brief Event Generator Timer. + * @details This timer generates an event at regular intervals. The + * listening threads can use the event to perform time related activities. + * Multiple threads can listen to the same timer. + * + * @ingroup utilities_library + */ +/** @} */ + -- cgit v1.2.3 From 5a176878c4e9ab7adcdab0e28455b22ffde253a2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 8 Mar 2009 09:16:19 +0000 Subject: Updated test reports. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@817 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 58a96870d..a17c4e008 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -37,7 +37,7 @@ * - 128 priority levels. Multiple threads at the same priority level allowed. * - Round robin scheduling for threads at the same priority level. * - Offers threads, virtual timers, semaphores, mutexes, condvars, - * event flags, messages, I/O queues. + * event flags, messages, mailboxes, I/O queues. * - No static setup at compile time, there is no need to configure a maximum * number of all the above objects. * - PC simulator target included, the development can be done on the PC -- cgit v1.2.3 From 773f580e37e9248096bc25eb0e64af292a5f53bd Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 8 Mar 2009 15:58:28 +0000 Subject: Added architecture diagram to the concepts page. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@820 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 360e5f4f2..d8d874bac 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -18,9 +18,19 @@ */ /** - * @page concepts Concepts + * @page concepts Concepts and Architecture * @{ * @brief ChibiOS/RT Concepts and Architecture + * - @ref naming + * - @ref api_suffixes + * - @ref interrupt_classes + * - @ref system_states + * - @ref scheduling + * - @ref thread_states + * - @ref priority + * - @ref warea + * - @ref architecture + * . * @section naming Naming Conventions * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). @@ -218,7 +228,7 @@ * (inclusive) are reserved. This is the highest numerical value of the * priorities space. * . - * @section warea Thread Working Area + * @section warea Threads Working Area * Each thread has its own stack, a Thread structure and some preemption * areas. All the structures are allocated into a "Thread Working Area", * a thread private heap, usually statically declared in your code. @@ -237,5 +247,18 @@ * . * See the @ref Core documentation for details, the area may change on * the various ports and some structures may not be present (or be zero-sized). + * + * @section architecture Architectural Diagram + * The following diagram shows the relationships among the hardware, the + * various ChibiOS/RT subsystems and the application code. + *

+ * @image html arch.png + *
+ * In this diagram the device drivers are at the same level of the application + * code because both have access to the system services and can directly + * access the hardware.
+ * Of course it is possible to create in the application architecture several + * extra layers, this is just not part of the kernel architecture but part of + * the overall system design. */ /** @} */ -- cgit v1.2.3 From da4f9beaee8f1f8f344012b4d9a122462a6c802e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 10 Mar 2009 15:31:58 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@827 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 6 +++--- docs/src/timing.dox | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index d8d874bac..8ef626c01 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,9 +34,9 @@ * @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 Mtx, - * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg, - * @a Heap, @a Pool. + * The possible groups are: @a Sys, @a Sch, @a Time @a VT, @a Thd, @a Sem, + * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, + * @a Dbg, @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes * The suffix can be one of the following: diff --git a/docs/src/timing.dox b/docs/src/timing.dox index 9fd19545d..7732bef0b 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -46,7 +46,7 @@ msg_t my_thread(void *param) { * @code msg_t my_thread(void *param) { - systick_t time = chSysGetTime(); /* T0 */ + systick_t time = chTimeNow(); /* T0 */ while (TRUE) { time += MS2ST(1000); /* Next deadline */ do_something(); -- cgit v1.2.3 From 89788b3234417d8aea3d5e34d78bf24c4e1da444 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 11 Mar 2009 14:24:02 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@831 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/design.dox | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 docs/src/design.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index a0426f41c..66268f9d7 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -29,6 +29,7 @@ * - @subpage article_jitter * - @subpage article_timing * - @subpage article_portguide + * - @subpage article_design * . */ /** @} */ diff --git a/docs/src/design.dox b/docs/src/design.dox new file mode 100644 index 000000000..4b6780a7a --- /dev/null +++ b/docs/src/design.dox @@ -0,0 +1,112 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_design Designing an embedded application + * @{ + * ChibiOS/RT offers a variety of mechanisms and primitives, often it is + * better to focus on a single approach for the system design and use only + * part of the available subsystems.
+ * When designing your application you may choose among several design + * alternatives: + * - @ref nothreads + * - @ref messpass + * - @ref thdshared + * - @ref thdmixed + * . + * @section nothreads Single threaded superloop + * Correct, single thread, it is not mandatory to use the multithreading + * features of the OS. You may choose to implements everything as a complex + * state machine handled in the main thread alone. In this scenario the OS + * still offers a variety of useful mechanisms: + * - Interrupt handling. + * - Virtual Timers, very useful in state machines in order to handle time + * triggered state transitions. + * - Power management. + * - Event Flags and/or Semaphores as communication mechanism between + * interrupt handlers and the main. + * - I/O queues. + * - Memory allocation. + * - System time. + * . + * In this configuration the kernel size is really minimal, everything else + * is disabled and takes no space. You always have the option to use more + * threads at a later time in order to perform separate tasks. + * + * @section messpass Message Passing + * In this scenario there are multiple threads in the system that never + * share data, everything is done by exchanging messages. Each thread + * represents a service, the other threads can request the service by sending + * a message.
+ * In this scenario the following subsystems can be used: + * - Synchronous Messages. + * - Mailboxes (asynchronous message queues). + * . + * The advantage of this approach is to not have to deal with mutual exclusion, + * each functionality is encapsulated into a server thread that sequentially + * serves all the requests. As example, you can have the following scenario: + * - A buffers allocator server. + * - A disk driver server. + * - A file system server. + * - One or more client threads. + * . + * Example: + *

+ * @dot + digraph example { + rankdir="RL"; + node [shape=rectangle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="1.2", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + disk [label="Server Thread\nDisk Driver"]; + buf [label="Server Thread\nBuffers Allocator"]; + fs [label="Client&Server Thread\nFile System"]; + cl1 [label="Client Thread"]; + cl2 [label="Client Thread"]; + cl3 [label="Client Thread"]; + fs -> disk [label="I/O request", constraint=false]; + disk -> fs [label="status", style="dotted", constraint=false]; + fs -> buf [label="buffer request"]; + buf -> fs [label="buffer", style="dotted"]; + cl1 -> fs [label="FS transaction"]; + fs -> cl1 [label="result", style="dotted"]; + cl2 -> fs [label="FS transaction"]; + fs -> cl2 [label="result", style="dotted"]; + cl3 -> fs [label="FS transaction"]; + fs -> cl3 [label="result", style="dotted"]; + } + * @enddot + *

+ * Note that the threads should not exchange complex messages but just + * pointers to data structures in order to optimize the performance. + * Also note that a thread can be both client and server at the same + * time, the FS service in the previous scenario as example. + * + * @section thdshared Threads sharing data + * This is the most common scenario, several threads have access to both their + * private data and shared data. Synchronization happens with one of the + * mechanisms described in the @ref article_mutual_exclusion article.
+ * + * @section thdmixed Mixed + * All the above approaches can be freely mixed in a single application but + * usually I prefer to choose a way and consistently design the system around + * it. The OS is a toolbox that offers a lot of tools but you don't have + * to use them all necessarily. + */ +/** @} */ -- cgit v1.2.3 From 07e6ae3a59c7191facaaada4b4549587ae5ed0fa Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 18 Mar 2009 19:53:33 +0000 Subject: Fixed bug 2692510 and some other small documentation errors. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@852 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 8ef626c01..cc768052e 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -62,7 +62,7 @@ * subject to jitter, see @ref article_jitter. Such sources are not * supported on all the architectures.
* Fast interrupts are not allowed to invoke any operating system API from - * within their handlers. Fast interrupt sources may however pend a lower + * within their handlers. Fast interrupt sources may, however, pend a lower * priority regular interrupt where access to the operating system is * possible. * - Non Maskable Interrupts. Non maskable interrupt sources are @@ -110,7 +110,7 @@ * and an error is detected or after explicitly invoking * @p chSysHalt(). * . - * Note that the above state are just Logical States that may have no + * Note that the above states are just Logical States that may have no * real associated machine state on some architectures. The following diagram * shows the possible transitions between the states: * -- cgit v1.2.3 From fad3a0802ac7f43da5f7dcf68e369dc735de3ed2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 2 Apr 2009 13:41:54 +0000 Subject: Documentation fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@864 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- docs/src/interrupts.dox | 2 +- docs/src/saveram.dox | 3 ++- docs/src/timing.dox | 2 +- 4 files changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index cc768052e..725be9b52 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,7 +34,7 @@ * @section naming Naming Conventions * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). - * The possible groups are: @a Sys, @a Sch, @a Time @a VT, @a Thd, @a Sem, + * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, * @a Dbg, @a Heap, @a Pool. * diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 679eb8884..d2dfb70b5 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -20,7 +20,7 @@ /** * @page article_interrupts Writing interrupt handlers under ChibiOS/RT * @{ - * Since version 1.1.0 ChbiOS/RT offers a cross-platform system for writing + * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing * interrupt handlers. Port-related and compiler-related details are * encapsulated within standard system macros.
* An interrupt handler assumes the following general form: diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox index e237da909..7a1f6f662 100644 --- a/docs/src/saveram.dox +++ b/docs/src/saveram.dox @@ -71,7 +71,8 @@ static void MyThread(void *arg) { main() { chSysInit(); ... - chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL); + chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, + (tfunc_t)MyThread, NULL); ... } * @endcode diff --git a/docs/src/timing.dox b/docs/src/timing.dox index 7732bef0b..9e013c412 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -39,7 +39,7 @@ msg_t my_thread(void *param) { * executed at irregular intervals, as example:

* T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.

* Also note that the error increases over time and this kind of behavior can - * lead anomalies really hard to debug. + * lead to anomalies really hard to debug. *

A better solution

* It is possible to rewrite the above code using absolute deadlines rather * than fixed intervals: -- cgit v1.2.3 From 34728efb1629b43e72d5f8ac22093abb3b90db13 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 28 Apr 2009 20:31:05 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@924 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index 13e764802..46c092086 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -57,7 +57,7 @@ * finalized to this objective. Everything you can invoke in the kernel is * designed to not fail unless you pass garbage as parameters, stray pointers * as examples. The APIs are not slowed down by parameter checks, - * parameter checks (and consistency checks) do exists but only when the + * parameter checks (and consistency checks) do exist but only when the * debug switch is activated.
* All the static core APIs always succeed if correct parameters are passed. * Exception to this are the optional allocators APIs that, of course, -- cgit v1.2.3 From c989a8967cdcbd54109d686678936a3581fd2c70 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 1 May 2009 13:11:26 +0000 Subject: Removed the CH_USE_SERIAL_HALFDUPLEX, CH_USE_QUEUES_TIMEOUT and CH_USE_QUEUES_HALFDUPLEX configuration options. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@927 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index a17c4e008..f5870a276 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -338,18 +338,12 @@ * lower side and the reader is the upper side. * - Output queue, unidirectional queue where the writer is the * upper side and the reader is the lower side. - * - Half duplex queue, bidirectional queue where the buffer is shared - * between a receive and a transmit queues. This means that concurrent - * buffered input and output operations are not possible, this is perfectly - * acceptable for a lot of applications however, as example an RS485 driver. * - Full duplex queue, bidirectional queue where read and write * operations can happen at the same time. Full duplex queues * are implemented by pairing an input queue and an output queue together. * . * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
- * In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX - * option must be specified in @p chconf.h. */ /** @} */ -- cgit v1.2.3 From 8cfd8aefb69f582c8d658995b6ce7b3f8b024c7e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 2 May 2009 10:13:20 +0000 Subject: Initial documentation for channels. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@932 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 69 ++++++++++++++----------------------------------------- 1 file changed, 17 insertions(+), 52 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index f5870a276..ea30d420f 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -66,100 +66,76 @@ /** * @defgroup Ports Ports - * @{ * This section describes the technical details for the various supported * ChibiOS/RT ports. */ -/** @} */ /** * @defgroup Kernel Kernel - * @{ + * Kernel related subsystems, */ -/** @} */ /** * @defgroup Config Configuration - * @{ * In @p chconf.h are defined the required subsystems for your application. * @ingroup Kernel */ -/** @} */ /** * @defgroup Core Generic Port Code Templates - * @{ * Non portable code templates. * @ingroup Kernel */ -/** @} */ /** * @defgroup Types Types - * @{ * System types and macros. * @ingroup Kernel */ -/** @} */ /** * @defgroup System System Management - * @{ * Initialization, Locks, Interrupt Handling, Power Management, Abnormal * Termination. * @ingroup Kernel */ -/** @} */ /** * @defgroup Inline Inline - * @{ * System inline-able code. * @ingroup Kernel */ -/** @} */ /** * @defgroup Debug Debug - * @{ * Debug APIs and procedures. * @ingroup Kernel */ -/** @} */ /** * @defgroup Scheduler Scheduler - * @{ * ChibiOS/RT scheduler. * @ingroup Kernel */ -/** @} */ /** * @defgroup ThreadLists Thread Lists and Queues - * @{ * ChibiOS/RT thread lists and queues utilities. * @ingroup Kernel */ -/** @} */ /** * @defgroup Threads Threads - * @{ * Threads creation and termination APIs. */ -/** @} */ /** * @defgroup Time Time and Virtual Timers - * @{ * Time and Virtual Timers related APIs. */ -/** @} */ /** * @defgroup Heap Heap - * @{ * Heap Allocator related APIs. *

Operation mode

* The heap allocator implements a first-fit strategy and its APIs are @@ -171,11 +147,9 @@ * In order to use the heap APIs the @p CH_USE_HEAP option must be specified * in @p chconf.h. */ -/** @} */ /** * @defgroup MemoryPools Memory Pools - * @{ * Memory Pools related APIs. *

Operation mode

* The Memory Pools APIs allow to allocate/free fixed size objects in @@ -183,11 +157,9 @@ * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be * specified in @p chconf.h. */ -/** @} */ /** * @defgroup Semaphores Semaphores - * @{ * Semaphores and threads synchronization. *

Operation mode

* A semaphore is a threads synchronization object, some operations @@ -209,11 +181,9 @@ * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES * option must be specified in @p chconf.h.

*/ -/** @} */ /** * @defgroup Mutexes Mutexes - * @{ * Mutexes and threads synchronization. *

Operation mode

* A mutex is a threads synchronization object, some operations are defined @@ -244,11 +214,9 @@ * number of nested mutexes and any number of involved threads. The algorithm * complexity (worst case) is N with N equal to the number of nested mutexes. */ -/** @} */ /** * @defgroup CondVars Condition Variables - * @{ * Condition Variables and threads synchronization. *

Operation mode

* The condition variable is a synchronization object meant to be used inside @@ -257,11 +225,9 @@ * In order to use the Condition Variables APIs the @p CH_USE_CONDVARS * option must be specified in @p chconf.h.

*/ -/** @} */ /** * @defgroup Events Events - * @{ * Event Sources and Event Listeners. *

Operation mode

* An Event Source is a special object that can be signaled by a thread or @@ -278,11 +244,9 @@ * In order to use the Event APIs the @p CH_USE_EVENTS option must be * specified in @p chconf.h. */ -/** @} */ /** * @defgroup Messages Synchronous Messages - * @{ * Synchronous inter-thread messages. *

Operation Mode

* Synchronoud messages are an easy to use and fast IPC mechanism, threads @@ -299,11 +263,9 @@ * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be * specified in @p chconf.h. */ -/** @} */ /** * @defgroup Mailboxes Mailboxes - * @{ * Asynchronous messages. *

Operation mode

* A mailbox is an asynchronous communication mechanism.
@@ -323,11 +285,9 @@ * free it on the fetching side. Another approach is to set a "done" flag into * the structure pointed by the message. */ -/** @} */ /** - * @defgroup IOQueues I/O Queues - * @{ + * @defgroup IOQueues Physical I/O Queues * ChibiOS/RT supports several kinds of queues. The queues are mostly used * in serial-like device drivers. The device drivers are usually designed to * have a lower side (lower driver, it is usually an interrupt service @@ -345,11 +305,22 @@ * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
*/ -/** @} */ +/** + * @defgroup Channels Abstract I/O Channels + * This module defines an abstract interface for I/O channels. Note that + * no code is present, I/O channels are just abstract classes-like structures, + * you should look at the systems as to a set of abstract C++ classes (even if + * implemented in C). Specific device drivers can use/extend the interfaces + * and implement them.
+ * This system has the advantage to make the access to the device drivers + * independent from the implementation logic. As example, an I/O channel + * interface can hide the access to a serial driver, to a networking socket + * and so on. + */ + /** * @defgroup Serial Serial Drivers - * @{ * This module implements a generic full duplex serial driver and a generic * half duplex serial driver. It uses the I/O Queues for communication between * the upper and the lower driver and events to notify the application about @@ -361,11 +332,9 @@ * In order to use the serial half duplex driver the * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h. */ -/** @} */ /** * @defgroup utilities_library Utilities Library - * @{ * @brief Utilities Library. * @details This is a collection of useful library code that is not part of * the base kernel services. @@ -375,21 +344,18 @@ * The main difference is that library code is not formally tested in the * test suite but through usage in the various demo applications. */ -/** @} */ /** * @defgroup CPlusPlusLibrary C++ Wrapper - * @{ - * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities + * @brief C++ wrapper module. + * @details This module allows to use the ChibiOS/RT functionalities * from C++ as classes and objects rather the traditional "C" APIs. * * @ingroup utilities_library */ -/** @} */ /** * @defgroup event_timer Events Generator Timer - * @{ * @brief Event Generator Timer. * @details This timer generates an event at regular intervals. The * listening threads can use the event to perform time related activities. @@ -397,5 +363,4 @@ * * @ingroup utilities_library */ -/** @} */ -- cgit v1.2.3 From 62a6638eb544f2c3d9022bcb34cae181aa8f7aae Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 3 May 2009 09:51:01 +0000 Subject: Added I/O queue checks to the channels, added notes in the readme, improved the FullDuplexDriver. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@940 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 4 ++-- docs/src/main.dox | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 725be9b52..ed37ed349 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -35,8 +35,8 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, - * @a Dbg, @a Heap, @a Pool. + * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a IO, @a FDD, @a Dbg, + * @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes * The suffix can be one of the following: diff --git a/docs/src/main.dox b/docs/src/main.dox index ea30d420f..2e76e0a75 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -313,7 +313,7 @@ * you should look at the systems as to a set of abstract C++ classes (even if * implemented in C). Specific device drivers can use/extend the interfaces * and implement them.
- * This system has the advantage to make the access to the device drivers + * This system has the advantage to make the access to channels * independent from the implementation logic. As example, an I/O channel * interface can hide the access to a serial driver, to a networking socket * and so on. -- cgit v1.2.3 From aea323e12179301b00e7766fc97dc3d3b51576d9 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 7 May 2009 15:24:47 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@949 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 2 -- docs/src/atomic.dox | 2 -- docs/src/concepts.dox | 2 -- docs/src/design.dox | 2 -- docs/src/goals.dox | 2 -- docs/src/interrupts.dox | 2 -- docs/src/jitter.dox | 2 -- docs/src/licfaq.dox | 2 -- docs/src/main.dox | 21 +++++++++++++++++++++ docs/src/mutualexcl.dox | 2 -- docs/src/portguide.dox | 2 -- docs/src/saveram.dox | 2 -- docs/src/stacks.dox | 2 -- docs/src/timing.dox | 2 -- 14 files changed, 21 insertions(+), 26 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 66268f9d7..e9849782c 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -19,7 +19,6 @@ /** * @page articles Articles - * @{ * ChibiOS/RT Articles and Code Examples: * - @subpage article_stacks * - @subpage article_mutual_exclusion @@ -32,4 +31,3 @@ * - @subpage article_design * . */ -/** @} */ diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 5fb0bc628..5e2fb58cd 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -19,7 +19,6 @@ /** * @page article_atomic Invoking multiple primitives as a single atomic operation - * @{ * It is often necessary to invoke multiple operations involving a * reschedulation as a single atomic operation.
* ChibiOS/RT already implements APIs that perform complex operations, as @@ -56,4 +55,3 @@ * API. An extra @p chSchRescheduleS() can be present at the very end of the * block, it only reschedules if a reschedulation is still required. */ -/** @} */ diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index ed37ed349..8a7418b53 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -19,7 +19,6 @@ /** * @page concepts Concepts and Architecture - * @{ * @brief ChibiOS/RT Concepts and Architecture * - @ref naming * - @ref api_suffixes @@ -261,4 +260,3 @@ * extra layers, this is just not part of the kernel architecture but part of * the overall system design. */ -/** @} */ diff --git a/docs/src/design.dox b/docs/src/design.dox index 4b6780a7a..bc88edf6f 100644 --- a/docs/src/design.dox +++ b/docs/src/design.dox @@ -19,7 +19,6 @@ /** * @page article_design Designing an embedded application - * @{ * ChibiOS/RT offers a variety of mechanisms and primitives, often it is * better to focus on a single approach for the system design and use only * part of the available subsystems.
@@ -109,4 +108,3 @@ * it. The OS is a toolbox that offers a lot of tools but you don't have * to use them all necessarily. */ -/** @} */ diff --git a/docs/src/goals.dox b/docs/src/goals.dox index 46c092086..e7a26fb3f 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -19,7 +19,6 @@ /** * @page goals Project Goals - * @{ *

Another RTOS?

* The first question to be answered is: there was really the need for YET * ANOTHER RTOS?
@@ -87,4 +86,3 @@ * code is released as well, all the included demos are capable of executing * the test suite and the OS benchmarks. */ -/** @} */ diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index d2dfb70b5..95bd6c281 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -19,7 +19,6 @@ /** * @page article_interrupts Writing interrupt handlers under ChibiOS/RT - * @{ * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing * interrupt handlers. Port-related and compiler-related details are * encapsulated within standard system macros.
@@ -50,5 +49,4 @@ CH_IRQ_HANDLER(myIRQ) { * please read about it in the ARM7 port section: @ref ARM7_IH * . */ -/** @} */ \ No newline at end of file diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 747a07a7e..5f4e7ff5e 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -19,7 +19,6 @@ /** * @page article_jitter Response Time and Jitter - * @{ * Response time jitter is one of the most sneaky source of problems when * designing a real time system. When using a RTOS like ChibiOS/RT one must * be aware of what the jitter is and how it can affect the performance of the @@ -134,4 +133,3 @@ * subsystem can improve the overall response time and reduce jitter but it is * not a magic wand, a proper system design comes first. */ -/** @} */ diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index f3bf3c3a1..58e99a2bb 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -19,7 +19,6 @@ /** * @page lic_faq License and F.A.Q. - * @{ * ChibiOS/RT is a * GPL3-licensed product but it offers a linking exception in its stable * releases.
@@ -89,5 +88,4 @@ Program code and other code used in conjunction with the Program except the Non-GPL Code covered by this exception. * */ -/** @} */ \ No newline at end of file diff --git a/docs/src/main.dox b/docs/src/main.dox index 2e76e0a75..bf6eecd54 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -64,6 +64,27 @@ * . */ +/** + * @page TEST_SUITE Tests Description + *

Descriptions

+ * Most of the ChibiOS/RT demos link a set of software modules (test suite) in + * order to verify the proper working of the kernel, the port and the demo + * itself.
+ * Each Test Module performs a series of tests on a specified subbsystem or + * subsystems and can report a failure/success status and/or a performance + * index as the test suite output.
+ * The test suite is usually activated in the demo applications by pressing a + * button on the target board, see the readme into the various demos + * directories. The test suite output is usually sent through a serial port and + * can be examined by using a terminal emulator program. + * + *

Test Modules

+ * - @subpage test_threads + * - @subpage test_queues + * - @subpage test_serial + * . + */ + /** * @defgroup Ports Ports * This section describes the technical details for the various supported diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox index ae6f57c0a..69eb65dc8 100644 --- a/docs/src/mutualexcl.dox +++ b/docs/src/mutualexcl.dox @@ -19,7 +19,6 @@ /** * @page article_mutual_exclusion Mutual Exclusion guide - * @{ * The most common problem when writing multithreaded code is the * synchronization on the shared resources/services.
* ChibiOS/RT offers a rich variety of mechanisms that apparently solve the @@ -209,4 +208,3 @@ * - Requires a dedicated thread as server. * . */ -/** @} */ diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index 57216885d..14a3c2eca 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -19,7 +19,6 @@ /** * @page article_portguide Porting ChibiOS/RT for Dummies - * @{ * Porting the operating system on a new platform is one of the most common * tasks. The difficulty can range from easy to very difficult depending * on several factors.
@@ -111,4 +110,3 @@ * the OS template files, the hardest part is decide the correct and efficient * way to implement the context switching. */ -/** @} */ diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox index 7a1f6f662..6682fe0fe 100644 --- a/docs/src/saveram.dox +++ b/docs/src/saveram.dox @@ -19,7 +19,6 @@ /** * @page article_saveram Saving RAM by declaring thread functions "noreturn" - * @{ * One of the problems, when writing embedded multi-threaded applications, * is that the thread functions do save the registers in the function * entry code even if the system does not require it, exiting such @@ -80,4 +79,3 @@ main() { * need to save registers. The code will be a bit less readable and less * portable on other compilers however. */ -/** @} */ diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox index a27c2e1b9..6035e1277 100644 --- a/docs/src/stacks.dox +++ b/docs/src/stacks.dox @@ -19,7 +19,6 @@ /** * @page article_stacks Stacks and stack sizes - * @{ * In a 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

@@ -104,4 +103,3 @@ * end of your development cycle. * . */ -/** @} */ diff --git a/docs/src/timing.dox b/docs/src/timing.dox index 9e013c412..a09db8575 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -19,7 +19,6 @@ /** * @page article_timing Reliable timings using Threads - * @{ * One common task is to have threads do something at regular, scheduled, * intervals. * An obvious solution is to write something like this: @@ -58,4 +57,3 @@ msg_t my_thread(void *param) { * deadline time and the error will not accumulate over time regardless of * the execution time and delays inserted by other threads. */ -/** @} */ -- cgit v1.2.3 From b37209d196026ba07f687c487d53dcbeef1f9223 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 7 May 2009 20:36:26 +0000 Subject: Started adding documentation tags to the test suite. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@950 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index bf6eecd54..59b9f3f6d 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -61,16 +61,17 @@ * - @subpage goals * - @subpage concepts * - @subpage articles + * - @subpage testsuite * . */ /** - * @page TEST_SUITE Tests Description - *

Descriptions

+ * @page testsuite Tests Suite + *

Description

* Most of the ChibiOS/RT demos link a set of software modules (test suite) in * order to verify the proper working of the kernel, the port and the demo * itself.
- * Each Test Module performs a series of tests on a specified subbsystem or + * Each Test Module performs a series of tests on a specified subsystem or * subsystems and can report a failure/success status and/or a performance * index as the test suite output.
* The test suite is usually activated in the demo applications by pressing a @@ -82,6 +83,7 @@ * - @subpage test_threads * - @subpage test_queues * - @subpage test_serial + * - @subpage test_benchmarks * . */ -- cgit v1.2.3 From 3d2fd8eb545182334b672c52acd7b8a06193bedf Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 8 May 2009 14:06:45 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@951 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 59b9f3f6d..184bfab11 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -81,8 +81,13 @@ * *

Test Modules

* - @subpage test_threads + * - @subpage test_dynamic + * - @subpage test_msg + * - @subpage test_events + * - @subpage test_mbox * - @subpage test_queues * - @subpage test_serial + * - @subpage test_heap * - @subpage test_benchmarks * . */ -- cgit v1.2.3 From 824e30be80c79d866ac444b4eed7f4df0cf154c1 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 9 May 2009 13:06:30 +0000 Subject: Fixed bugs 2789377 and 2789383. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@956 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 184bfab11..f4e638ca7 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -83,6 +83,7 @@ * - @subpage test_threads * - @subpage test_dynamic * - @subpage test_msg + * - @subpage test_mtx * - @subpage test_events * - @subpage test_mbox * - @subpage test_queues @@ -230,8 +231,8 @@ * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse * order. The Unlock API does not even have a parameter, the mutex to unlock * is taken from an internal stack of owned mutexes. - * This both improves the performance and is required by the priority - * inheritance mechanism. + * This both improves the performance and is required by an efficient + * implementation of the priority inheritance mechanism. * *

The priority inversion problem

* The mutexes in ChibiOS/RT implements the full priority -- cgit v1.2.3 From f3ca042618b9b1f5fa877b68e89ec31fe66497eb Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 9 May 2009 14:42:26 +0000 Subject: Added more documentation to the test suite. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@957 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index f4e638ca7..d7366acdc 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -66,7 +66,7 @@ */ /** - * @page testsuite Tests Suite + * @page testsuite Test Suite *

Description

* Most of the ChibiOS/RT demos link a set of software modules (test suite) in * order to verify the proper working of the kernel, the port and the demo -- cgit v1.2.3 From 83d50f08219d05f65b55f686e74e5cb4e7352092 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 9 May 2009 16:46:49 +0000 Subject: Finished adding tests documentation to the general documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@963 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index d7366acdc..288cda4c7 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -83,12 +83,14 @@ * - @subpage test_threads * - @subpage test_dynamic * - @subpage test_msg + * - @subpage test_sem * - @subpage test_mtx * - @subpage test_events * - @subpage test_mbox * - @subpage test_queues * - @subpage test_serial * - @subpage test_heap + * - @subpage test_pools * - @subpage test_benchmarks * . */ -- cgit v1.2.3 From 1508b4c564d1a34a3b06699a212b1faa27607fae Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 14:59:30 +0000 Subject: Removed empty "inline" section from the documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@995 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 288cda4c7..377427d0a 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -131,12 +131,6 @@ * @ingroup Kernel */ -/** - * @defgroup Inline Inline - * System inline-able code. - * @ingroup Kernel - */ - /** * @defgroup Debug Debug * Debug APIs and procedures. -- cgit v1.2.3 From b863d01c132a22f752761baa4d4209c17a7fba93 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 15:20:25 +0000 Subject: Documentation sections reorganizations, fixed bug 2799507. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@996 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 47 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 8 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 377427d0a..0013737df 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -113,8 +113,11 @@ */ /** - * @defgroup Core Generic Port Code Templates - * Non portable code templates. + * @defgroup Core Port Code Templates + * Non portable code templates. The function and the macros defined under this + * section are the non portable part of the kernel. + * @note The port code is not an API, the applications should not invoke it + * directly, use the equivalent system API instead. * @ingroup Kernel */ @@ -132,14 +135,14 @@ */ /** - * @defgroup Debug Debug + * @defgroup Debug Debug Support * Debug APIs and procedures. * @ingroup Kernel */ /** - * @defgroup Scheduler Scheduler - * ChibiOS/RT scheduler. + * @defgroup Scheduler Low Level Scheduler + * ChibiOS/RT scheduler APIs and macros. * @ingroup Kernel */ @@ -151,12 +154,19 @@ /** * @defgroup Threads Threads - * Threads creation and termination APIs. + * Threads related APIs. + * @ingroup Kernel */ /** * @defgroup Time Time and Virtual Timers * Time and Virtual Timers related APIs. + * @ingroup Kernel + */ + +/** + * @defgroup Memory Memory Management + * Memory Management services. */ /** @@ -171,6 +181,7 @@ * instead of the system provided allocator.
* In order to use the heap APIs the @p CH_USE_HEAP option must be specified * in @p chconf.h. + * @ingroup Memory */ /** @@ -181,6 +192,12 @@ * constant time and reliably without memory fragmentation problems.
* In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be * specified in @p chconf.h. + * @ingroup Memory + */ + +/** + * @defgroup Synchronization Synchronization + * Synchronization services. */ /** @@ -205,6 +222,7 @@ * @p chconf.h.
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES * option must be specified in @p chconf.h.

+ * @ingroup Synchronization */ /** @@ -238,6 +256,7 @@ * priority was not already equal or higher). The mechanism works with any * number of nested mutexes and any number of involved threads. The algorithm * complexity (worst case) is N with N equal to the number of nested mutexes. + * @ingroup Synchronization */ /** @@ -249,6 +268,7 @@ * a Monitor construct.
* In order to use the Condition Variables APIs the @p CH_USE_CONDVARS * option must be specified in @p chconf.h.

+ * @ingroup Synchronization */ /** @@ -268,6 +288,7 @@ * thread invokes a @p chEvtWaitXXX().
* In order to use the Event APIs the @p CH_USE_EVENTS option must be * specified in @p chconf.h. + * @ingroup Synchronization */ /** @@ -287,6 +308,7 @@ * queue header).
* In order to use the Messages APIs the @p CH_USE_MESSAGES option must be * specified in @p chconf.h. + * @ingroup Synchronization */ /** @@ -309,6 +331,12 @@ * allocate memory (from a memory pool as example) from the posting side and * free it on the fetching side. Another approach is to set a "done" flag into * the structure pointed by the message. + * @ingroup Synchronization + */ + +/** + * @defgroup IO I/O Support + * I/O related services. */ /** @@ -329,6 +357,7 @@ * . * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
+ * @ingroup IO */ /** @@ -342,6 +371,7 @@ * independent from the implementation logic. As example, an I/O channel * interface can hide the access to a serial driver, to a networking socket * and so on. + * @ingroup IO */ /** @@ -356,6 +386,7 @@ * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
* In order to use the serial half duplex driver the * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h. + * @ingroup IO */ /** @@ -380,8 +411,8 @@ */ /** - * @defgroup event_timer Events Generator Timer - * @brief Event Generator Timer. + * @defgroup event_timer Periodic Events Timer + * @brief Periodic Event Timer. * @details This timer generates an event at regular intervals. The * listening threads can use the event to perform time related activities. * Multiple threads can listen to the same timer. -- cgit v1.2.3 From 67f44fadd6eeac97843259481aaa4bc286496785 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 15:47:29 +0000 Subject: Improved event flags documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@997 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 0013737df..e1852342e 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -272,20 +272,30 @@ */ /** - * @defgroup Events Events - * Event Sources and Event Listeners. + * @defgroup Events Event Flags + * @brief Event Flags, Event Sources and Event Listeners. *

Operation mode

- * An Event Source is a special object that can be signaled by a thread or - * an interrupt service routine. Signaling an Event Source has the effect - * that all the threads registered on the Event Source will receive - * and serve the event.
+ * Each thread has a mask of pending event flags inside its Thread structure. + * Several operations are defined: + * - Wait, the invoking thread goes to sleep until a certain AND/OR + * combination of event flags becomes pending. + * - Clear, a mask of event flags is cleared from the pending events + * mask, the cleared event flags mask is returned (only the flags that were + actually pending and then cleared). + * - Signal, an event mask is directly ORed to the mask of the signaled + * thread. + * - Broadcast, each thread registered on an Event Source is signaled + * with the event flags specified in its Event Listener. + * - Dispatch, an events mask is scanned and for each bit set to one + * an associated handler function is invoked. Bit masks are scanned from bit + * zero upward. + * . + * An Event Source is a special object that can be "broadcasted" by a thread or + * an interrupt service routine. Broadcasting an Event Source has the effect + * that all the threads registered on the Event Source will be signaled with + * and events mask.
* An unlimited number of Event Sources can exists in a system and each - * thread can listen on an unlimited number of them.
- * Note that the events can be asynchronously generated but are synchronously - * served, a thread can serve event by calling a @p chEvtWaitXXX() - * API. If an event is generated while a listening thread is not ready to - * serve it then the event becomes "pending" and will be served as soon the - * thread invokes a @p chEvtWaitXXX().
+ * thread can listen on an unlimited number of them.

* In order to use the Event APIs the @p CH_USE_EVENTS option must be * specified in @p chconf.h. * @ingroup Synchronization @@ -295,7 +305,7 @@ * @defgroup Messages Synchronous Messages * Synchronous inter-thread messages. *

Operation Mode

- * Synchronoud messages are an easy to use and fast IPC mechanism, threads + * Synchronous messages are an easy to use and fast IPC mechanism, threads * can both serve messages and send messages to other threads, the mechanism * allows data to be carried in both directions. Data is not copied between * the client and server threads but just a pointer passed so the exchange -- cgit v1.2.3 From 120ed882b18dd550d9776dacff49d37783742c9b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 16:01:41 +0000 Subject: Improvements to the I/O section documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@998 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index e1852342e..289e7ab55 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -350,10 +350,11 @@ */ /** - * @defgroup IOQueues Physical I/O Queues - * ChibiOS/RT supports several kinds of queues. The queues are mostly used - * in serial-like device drivers. The device drivers are usually designed to - * have a lower side (lower driver, it is usually an interrupt service + * @defgroup IOQueues I/O Queues + * @brief I/O queues. + * @details ChibiOS/RT supports several kinds of queues. The queues are mostly + * used in serial-like device drivers. The device drivers are usually designed + * to have a lower side (lower driver, it is usually an interrupt service * routine) and an upper side (upper driver, accessed by the application * threads).
* There are several kind of queues:
@@ -372,11 +373,12 @@ /** * @defgroup Channels Abstract I/O Channels - * This module defines an abstract interface for I/O channels. Note that - * no code is present, I/O channels are just abstract classes-like structures, - * you should look at the systems as to a set of abstract C++ classes (even if - * implemented in C). Specific device drivers can use/extend the interfaces - * and implement them.
+ * @brief Abstract I/O Channels. + * @details This module defines an abstract interface for I/O channels. Note + * that no code is present, I/O channels are just abstract classes-like + * structures, you should look at the systems as to a set of abstract C++ + * classes (even if implemented in C). Specific device drivers can use/extend + * the interfaces and implement them.
* This system has the advantage to make the access to channels * independent from the implementation logic. As example, an I/O channel * interface can hide the access to a serial driver, to a networking socket @@ -386,10 +388,12 @@ /** * @defgroup Serial Serial Drivers - * This module implements a generic full duplex serial driver and a generic - * half duplex serial driver. It uses the I/O Queues for communication between - * the upper and the lower driver and events to notify the application about - * incoming data, outcoming data and other I/O events. + * @brief Generic Serial Drivers. + * @details This module implements a generic full duplex serial driver. The + * driver implements a @p FullDuplexDriver interface and uses I/O Queues for + * communication between the upper and the lower driver. Event flags are used + * to notify the application about incoming data, outgoing data and other I/O + * events.
* The module also contains functions that make the implementation of the * interrupt service routines much easier.
* In order to use the serial full duplex driver the -- cgit v1.2.3 From 811227694ff5fdbdb2ee60c083e8e1fcac34e4e9 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 16:02:22 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@999 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 289e7ab55..a3b9a453b 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -399,8 +399,6 @@ * In order to use the serial full duplex driver the * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
* In order to use the serial half duplex driver the - * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h. - * @ingroup IO */ /** -- cgit v1.2.3 From 38c77daa8b81bc55fc391d5ebcf320d5cd3aba18 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 16:04:06 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1000 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index a3b9a453b..2cc656107 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -397,8 +397,7 @@ * The module also contains functions that make the implementation of the * interrupt service routines much easier.
* In order to use the serial full duplex driver the - * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
- * In order to use the serial half duplex driver the + * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h. */ /** -- cgit v1.2.3 From c94601bac37911295d3945cdd4041c52d42e0e80 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 16:11:08 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1001 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 2cc656107..2c9b63d21 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -346,7 +346,12 @@ /** * @defgroup IO I/O Support - * I/O related services. + * @brief I/O related services. + * @details This section contains the I/O related services. Note that no + * specific drivers are documented here, all the listed modules are abstract + * interfaces or kernel APIs that the device drivers should implement/use.
+ * The use of common I/O interfaces allow for a certain degree of portability + * for the ChibiOS/RT application among very different MCUs. */ /** @@ -398,6 +403,7 @@ * interrupt service routines much easier.
* In order to use the serial full duplex driver the * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h. + * @ingroup IO */ /** -- cgit v1.2.3 From a83063db261921df93594ae43bd9d568298f3361 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 16:13:15 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1002 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 2c9b63d21..0bcd4969f 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -382,7 +382,7 @@ * @details This module defines an abstract interface for I/O channels. Note * that no code is present, I/O channels are just abstract classes-like * structures, you should look at the systems as to a set of abstract C++ - * classes (even if implemented in C). Specific device drivers can use/extend + * classes (even if written in C). Specific device drivers can use/extend * the interfaces and implement them.
* This system has the advantage to make the access to channels * independent from the implementation logic. As example, an I/O channel -- cgit v1.2.3 From 0da4e6e067db019f455b43a3391a1510f517d2cf Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 17:52:34 +0000 Subject: Added abstract I/O ports driver header file and documentation. Implementations are missing. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1003 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 80 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 15 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 0bcd4969f..a969854f4 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -354,6 +354,69 @@ * for the ChibiOS/RT application among very different MCUs. */ +/** + * @defgroup IOPorts Abstract I/O Ports + * @brief Abstract digital I/O ports. + * @details This module defines an abstract interface for digital I/O ports. + * Note that no code is present, I/O ports are just a set of macros that must + * be implemented by a low level I/O port driver.
+ * Currently the I/O ports interface does not handle physical port programming + * like direction, pull up/down resistors etc. The interface only allows input + * and output operations but this may change in future releases. + * This system has the advantage to make the access to I/O ports platform + * independent from the implementation logic. + * + *

Implementation Rules

+ * In implementing an I/O port low level driver there are some rules that + * should be respected. + * + *

Write on input pads

+ * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The written value is not actually output but latched, should the pads + * be reprogrammed as outputs the value would be in effect. + * -# The write operation is ignored. + * -# The write operation has side effects, as example disabling/enabling + * pull up/down resistors or changing the pad direction. This scenario is + * discouraged, please try to avoid this scenario. + * . + *

Read from output pads

+ * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The actual pads states are read (not the output latch). + * -# The output latch value is read (regardless of the actual pads states). + * -# Unspecified, please try to avoid this scenario. + * . + *

Writing unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading from unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading or writing on pins associated to other functionalities

+ * The behavior is not specified. + * + * @ingroup IO + */ + +/** + * @defgroup Channels Abstract I/O Channels + * @brief Abstract I/O Channels. + * @details This module defines an abstract interface for I/O channels. Note + * that no code is present, I/O channels are just abstract classes-like + * structures, you should look at the systems as to a set of abstract C++ + * classes (even if written in C). Specific device drivers can use/extend + * the interfaces and implement them.
+ * This system has the advantage to make the access to channels + * independent from the implementation logic. As example, an I/O channel + * interface can hide the access to a serial driver, to a networking socket + * and so on. + * + * @ingroup IO + */ + /** * @defgroup IOQueues I/O Queues * @brief I/O queues. @@ -373,24 +436,10 @@ * . * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
+ * * @ingroup IO */ -/** - * @defgroup Channels Abstract I/O Channels - * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels. Note - * that no code is present, I/O channels are just abstract classes-like - * structures, you should look at the systems as to a set of abstract C++ - * classes (even if written in C). Specific device drivers can use/extend - * the interfaces and implement them.
- * This system has the advantage to make the access to channels - * independent from the implementation logic. As example, an I/O channel - * interface can hide the access to a serial driver, to a networking socket - * and so on. - * @ingroup IO - */ - /** * @defgroup Serial Serial Drivers * @brief Generic Serial Drivers. @@ -403,6 +452,7 @@ * interrupt service routines much easier.
* In order to use the serial full duplex driver the * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h. + * * @ingroup IO */ -- cgit v1.2.3 From 080e6abe804c5404c4d81614cf130b4ce332efcd Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 18:35:07 +0000 Subject: Added I/O ports low level driver template. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1006 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index a969854f4..d62ebda3e 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -401,6 +401,15 @@ * @ingroup IO */ +/** + * @defgroup IOPortsLLD I/O Ports Low Level Driver + * @brief Digital I/O ports low level driver template. + * @details This file is a template for an I/O port low level driver. This + * file implements the prysical layer of an I/O port driver. + * + * @ingroup IOPorts + */ + /** * @defgroup Channels Abstract I/O Channels * @brief Abstract I/O Channels. -- cgit v1.2.3 From 6d9146901cd9503180ec272f5b3af12e08553277 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 19:50:42 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1007 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index d62ebda3e..f38920462 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -359,7 +359,7 @@ * @brief Abstract digital I/O ports. * @details This module defines an abstract interface for digital I/O ports. * Note that no code is present, I/O ports are just a set of macros that must - * be implemented by a low level I/O port driver.
+ * be implemented by an @ref IOPortsLLD.
* Currently the I/O ports interface does not handle physical port programming * like direction, pull up/down resistors etc. The interface only allows input * and output operations but this may change in future releases. @@ -367,10 +367,10 @@ * independent from the implementation logic. * *

Implementation Rules

- * In implementing an I/O port low level driver there are some rules that + * In implementing an @ref IOPortsLLD there are some rules/behaviors that * should be respected. * - *

Write on input pads

+ *

Writing on input pads

* The behavior is not specified but there are implementations better than * others, this is the list of possible implementations, preferred options * are on top: @@ -381,7 +381,7 @@ * pull up/down resistors or changing the pad direction. This scenario is * discouraged, please try to avoid this scenario. * . - *

Read from output pads

+ *

Reading from output pads

* The behavior is not specified but there are implementations better than * others, this is the list of possible implementations, preferred options * are on top: -- cgit v1.2.3 From 4a4940c5b1a87c2b9541a6015dc121f27cef72b4 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 20:54:39 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1008 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index f38920462..6eda34beb 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -360,11 +360,14 @@ * @details This module defines an abstract interface for digital I/O ports. * Note that no code is present, I/O ports are just a set of macros that must * be implemented by an @ref IOPortsLLD.
+ * This system has the advantage to make the access to I/O ports platform + * independent from the implementation logic.
* Currently the I/O ports interface does not handle physical port programming * like direction, pull up/down resistors etc. The interface only allows input - * and output operations but this may change in future releases. - * This system has the advantage to make the access to I/O ports platform - * independent from the implementation logic. + * and output operations but this may change in future releases.
+ * Note that the @ref IOPortsLLD may also offer non standard macro and + * functions in order to support specific features but, of course, the use of + * such interfaces would not be portable. * *

Implementation Rules

* In implementing an @ref IOPortsLLD there are some rules/behaviors that -- cgit v1.2.3 From 8ada44e092e20e825b78c3d25ee016861cf886a9 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 2 Jun 2009 09:33:11 +0000 Subject: Modified the STM32 demo to use the new I/O port driver. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1010 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 6eda34beb..fee2af8e5 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -401,6 +401,11 @@ *

Reading or writing on pins associated to other functionalities

* The behavior is not specified. * + *

Usage

+ * The use of I/O ports requires the inclusion of the header file @p ioports.h, + * this file is not automatically included @o ch.h like the other header + * files. + * * @ingroup IO */ -- cgit v1.2.3 From 10ff25a6d35e23728ebb5f42788975452d8978a4 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 2 Jun 2009 09:54:57 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1013 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index fee2af8e5..bfe6f036c 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -403,7 +403,7 @@ * *

Usage

* The use of I/O ports requires the inclusion of the header file @p ioports.h, - * this file is not automatically included @o ch.h like the other header + * this file is not automatically included @p ch.h like the other header * files. * * @ingroup IO -- cgit v1.2.3 From 9148fd36b23a5ffcdd2f358627370a697fb49cef Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 3 Jun 2009 20:32:28 +0000 Subject: Added default implementations for I/O ports functions in ioports.h. Adjusted the documentation accordingly. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1017 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index bfe6f036c..c92192fff 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -358,10 +358,14 @@ * @defgroup IOPorts Abstract I/O Ports * @brief Abstract digital I/O ports. * @details This module defines an abstract interface for digital I/O ports. - * Note that no code is present, I/O ports are just a set of macros that must - * be implemented by an @ref IOPortsLLD.
- * This system has the advantage to make the access to I/O ports platform - * independent from the implementation logic.
+ * Note that I/O ports functions are just a set of macros. The macros + * have default software implementation that can be redefined by an + * @ref IOPortsLLD if the target hardware supports special features like, as + * example, atomic bit set/reset/masking. Please refer to the documentation + * of the low level drivers for each port.
+ * This abstraction system has the advantage to make the access to the I/O + * ports platform independent and still be optimized for the specific + * architecture.
* Currently the I/O ports interface does not handle physical port programming * like direction, pull up/down resistors etc. The interface only allows input * and output operations but this may change in future releases.
-- cgit v1.2.3 From 4fc5b696fad6b10620dcd49149bf64b829e38f77 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 7 Jun 2009 10:27:48 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1019 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index c92192fff..24d7acda1 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -355,26 +355,25 @@ */ /** - * @defgroup IOPorts Abstract I/O Ports - * @brief Abstract digital I/O ports. + * @defgroup PAL I/O Ports Abstraction Layer (PAL) + * @brief I/O Ports Abstraction Layer * @details This module defines an abstract interface for digital I/O ports. * Note that I/O ports functions are just a set of macros. The macros - * have default software implementation that can be redefined by an - * @ref IOPortsLLD if the target hardware supports special features like, as - * example, atomic bit set/reset/masking. Please refer to the documentation - * of the low level drivers for each port.
- * This abstraction system has the advantage to make the access to the I/O - * ports platform independent and still be optimized for the specific - * architecture.
+ * have default software implementations that can be redefined in a + * @ref PAL_LLD if the target hardware supports special features like, as + * example, atomic bit set/reset/masking. Please refer to the ports specific + * documentation for details.
+ * The @ref PAL has the advantage to make the access to the I/O ports platform + * independent and still be optimized for the specific architectures.
* Currently the I/O ports interface does not handle physical port programming * like direction, pull up/down resistors etc. The interface only allows input * and output operations but this may change in future releases.
- * Note that the @ref IOPortsLLD may also offer non standard macro and - * functions in order to support specific features but, of course, the use of - * such interfaces would not be portable. + * Note that the @ref PAL_LLD may also offer non standard macro and functions + * in order to support specific features but, of course, the use of such + * interfaces would not be portable. * *

Implementation Rules

- * In implementing an @ref IOPortsLLD there are some rules/behaviors that + * In implementing an @ref PAL_LLD there are some rules/behaviors that * should be respected. * *

Writing on input pads

@@ -406,7 +405,7 @@ * The behavior is not specified. * *

Usage

- * The use of I/O ports requires the inclusion of the header file @p ioports.h, + * The use of I/O ports requires the inclusion of the header file @p pal.h, * this file is not automatically included @p ch.h like the other header * files. * @@ -414,12 +413,12 @@ */ /** - * @defgroup IOPortsLLD I/O Ports Low Level Driver - * @brief Digital I/O ports low level driver template. + * @defgroup PAL_LLD PAL Low Level Driver + * @brief @ref PAL low level driver template. * @details This file is a template for an I/O port low level driver. This - * file implements the prysical layer of an I/O port driver. + * file implements the physical layer of an I/O port driver. * - * @ingroup IOPorts + * @ingroup PAL */ /** -- cgit v1.2.3 From a5df28e309adbccff162d67cfb9f55c653c73f7b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 7 Jun 2009 15:44:03 +0000 Subject: Revised port abstraction layer (PAL), STM32 support adjusted. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1023 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 24d7acda1..3a38d7115 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -358,7 +358,7 @@ * @defgroup PAL I/O Ports Abstraction Layer (PAL) * @brief I/O Ports Abstraction Layer * @details This module defines an abstract interface for digital I/O ports. - * Note that I/O ports functions are just a set of macros. The macros + * Note that most I/O ports functions are just macros. The macros * have default software implementations that can be redefined in a * @ref PAL_LLD if the target hardware supports special features like, as * example, atomic bit set/reset/masking. Please refer to the ports specific -- cgit v1.2.3 From be1e6b03d4a49b6fa16c3368435089f8706fb566 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 7 Jun 2009 17:53:23 +0000 Subject: Adjusted PAL support for LPC214x. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1026 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 62 +++++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 3a38d7115..fecca64f9 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -164,37 +164,6 @@ * @ingroup Kernel */ -/** - * @defgroup Memory Memory Management - * Memory Management services. - */ - -/** - * @defgroup Heap Heap - * Heap Allocator related APIs. - *

Operation mode

- * The heap allocator implements a first-fit strategy and its APIs are - * functionally equivalent to the usual @p malloc() and @p free(). The main - * difference is that the heap APIs are thread safe.
- * By enabling the @p CH_USE_MALLOC_HEAP option the heap manager will use the - * runtime-provided @p malloc() and @p free() as backend for the heap APIs - * instead of the system provided allocator.
- * In order to use the heap APIs the @p CH_USE_HEAP option must be specified - * in @p chconf.h. - * @ingroup Memory - */ - -/** - * @defgroup MemoryPools Memory Pools - * Memory Pools related APIs. - *

Operation mode

- * The Memory Pools APIs allow to allocate/free fixed size objects in - * constant time and reliably without memory fragmentation problems.
- * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be - * specified in @p chconf.h. - * @ingroup Memory - */ - /** * @defgroup Synchronization Synchronization * Synchronization services. @@ -344,6 +313,37 @@ * @ingroup Synchronization */ +/** + * @defgroup Memory Memory Management + * Memory Management services. + */ + +/** + * @defgroup Heap Heap + * Heap Allocator related APIs. + *

Operation mode

+ * The heap allocator implements a first-fit strategy and its APIs are + * functionally equivalent to the usual @p malloc() and @p free(). The main + * difference is that the heap APIs are thread safe.
+ * By enabling the @p CH_USE_MALLOC_HEAP option the heap manager will use the + * runtime-provided @p malloc() and @p free() as backend for the heap APIs + * instead of the system provided allocator.
+ * In order to use the heap APIs the @p CH_USE_HEAP option must be specified + * in @p chconf.h. + * @ingroup Memory + */ + +/** + * @defgroup MemoryPools Memory Pools + * Memory Pools related APIs. + *

Operation mode

+ * The Memory Pools APIs allow to allocate/free fixed size objects in + * constant time and reliably without memory fragmentation problems.
+ * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be + * specified in @p chconf.h. + * @ingroup Memory + */ + /** * @defgroup IO I/O Support * @brief I/O related services. -- cgit v1.2.3 From c33d090881ca0a6fc4dc4eaa8c5e8bd8ea4ab7fa Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 21 Jun 2009 10:01:35 +0000 Subject: Doxygen related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1044 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index fecca64f9..3d6c605c5 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -365,12 +365,10 @@ * documentation for details.
* The @ref PAL has the advantage to make the access to the I/O ports platform * independent and still be optimized for the specific architectures.
- * Currently the I/O ports interface does not handle physical port programming - * like direction, pull up/down resistors etc. The interface only allows input - * and output operations but this may change in future releases.
* Note that the @ref PAL_LLD may also offer non standard macro and functions * in order to support specific features but, of course, the use of such - * interfaces would not be portable. + * interfaces would not be portable. Such interfaces shall be marked with + * the architecture name inside the function names. * *

Implementation Rules

* In implementing an @ref PAL_LLD there are some rules/behaviors that -- cgit v1.2.3 From 8ce831d013cd306b24c3e6eca4c1efec28469f5b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 20 Aug 2009 11:15:24 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1087 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 50 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 12 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 3d6c605c5..56fcd252a 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -88,7 +88,6 @@ * - @subpage test_events * - @subpage test_mbox * - @subpage test_queues - * - @subpage test_serial * - @subpage test_heap * - @subpage test_pools * - @subpage test_benchmarks @@ -347,11 +346,33 @@ /** * @defgroup IO I/O Support * @brief I/O related services. - * @details This section contains the I/O related services. Note that no - * specific drivers are documented here, all the listed modules are abstract - * interfaces or kernel APIs that the device drivers should implement/use.
- * The use of common I/O interfaces allow for a certain degree of portability - * for the ChibiOS/RT application among very different MCUs. + * @details This section contains the I/O related services. + * + * The I/O subsystem is a collection of device driver poertable interfaces and + * platform dependent implementations.
+ * Under ChibiOS/RT a device driver is split in two layers: + * - High Level Device Driver (HLD). This layer contains the definitions + * of the driver's APIs and the platform independent part of the driver.
+ * An HLD is composed by two files: + * - @.c, the high level implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @.h, the high level header file. This file must be included + * by the application code in order to access the driver's APIs. + * . + * - Low Level Device Driver (LLD). This layer contains the platform + * dependent part of the driver.
+ * A LLD is composed by two files: + * - @_lld.c, the low level implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @_lld.h, the high level header file. This file is implicitly + * included by the HLD header file. + * . + * . + *

Available Device Drivers

+ * The I/O subsystem currently includes support for: + * - @ref PAL. + * - @ref SERIAL. + * . */ /** @@ -413,8 +434,7 @@ /** * @defgroup PAL_LLD PAL Low Level Driver * @brief @ref PAL low level driver template. - * @details This file is a template for an I/O port low level driver. This - * file implements the physical layer of an I/O port driver. + * @details This file is a template for an I/O port low level driver. * * @ingroup PAL */ @@ -459,21 +479,27 @@ */ /** - * @defgroup Serial Serial Drivers + * @defgroup SERIAL Serial Driver * @brief Generic Serial Drivers. * @details This module implements a generic full duplex serial driver. The - * driver implements a @p FullDuplexDriver interface and uses I/O Queues for + * driver implements a @p SerialDriver interface and uses I/O Queues for * communication between the upper and the lower driver. Event flags are used * to notify the application about incoming data, outgoing data and other I/O * events.
* The module also contains functions that make the implementation of the * interrupt service routines much easier.
- * In order to use the serial full duplex driver the - * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h. * * @ingroup IO */ +/** + * @defgroup SERIAL_LLD Serial Low Level Driver + * @brief @ref SERIAL low level driver template. + * @details This file is a template for a serial low level driver. + * + * @ingroup SERIAL + */ + /** * @defgroup utilities_library Utilities Library * @brief Utilities Library. -- cgit v1.2.3 From 1421a2fd6ca461a96c4be653ea7b925834963433 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 28 Aug 2009 17:43:57 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1118 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 78 +++++++++++++++++++++++++++---------------------------- 1 file changed, 39 insertions(+), 39 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 56fcd252a..d1cba5773 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -375,6 +375,45 @@ * . */ +/** + * @defgroup Channels I/O Abstract Channels + * @brief Abstract I/O Channels. + * @details This module defines an abstract interface for I/O channels. Note + * that no code is present, I/O channels are just abstract classes-like + * structures, you should look at the systems as to a set of abstract C++ + * classes (even if written in C). Specific device drivers can use/extend + * the interfaces and implement them.
+ * This system has the advantage to make the access to channels + * independent from the implementation logic. As example, an I/O channel + * interface can hide the access to a serial driver, to a networking socket + * and so on. + * + * @ingroup IO + */ + +/** + * @defgroup IOQueues I/O Queues + * @brief I/O queues. + * @details ChibiOS/RT supports several kinds of queues. The queues are mostly + * used in serial-like device drivers. The device drivers are usually designed + * to have a lower side (lower driver, it is usually an interrupt service + * routine) and an upper side (upper driver, accessed by the application + * threads).
+ * There are several kind of queues:
+ * - Input queue, unidirectional queue where the writer is the + * lower side and the reader is the upper side. + * - Output queue, unidirectional queue where the writer is the + * upper side and the reader is the lower side. + * - Full duplex queue, bidirectional queue where read and write + * operations can happen at the same time. Full duplex queues + * are implemented by pairing an input queue and an output queue together. + * . + * In order to use the I/O queues the @p CH_USE_QUEUES option must + * be specified in @p chconf.h.
+ * + * @ingroup IO + */ + /** * @defgroup PAL I/O Ports Abstraction Layer (PAL) * @brief I/O Ports Abstraction Layer @@ -439,45 +478,6 @@ * @ingroup PAL */ -/** - * @defgroup Channels Abstract I/O Channels - * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels. Note - * that no code is present, I/O channels are just abstract classes-like - * structures, you should look at the systems as to a set of abstract C++ - * classes (even if written in C). Specific device drivers can use/extend - * the interfaces and implement them.
- * This system has the advantage to make the access to channels - * independent from the implementation logic. As example, an I/O channel - * interface can hide the access to a serial driver, to a networking socket - * and so on. - * - * @ingroup IO - */ - -/** - * @defgroup IOQueues I/O Queues - * @brief I/O queues. - * @details ChibiOS/RT supports several kinds of queues. The queues are mostly - * used in serial-like device drivers. The device drivers are usually designed - * to have a lower side (lower driver, it is usually an interrupt service - * routine) and an upper side (upper driver, accessed by the application - * threads).
- * There are several kind of queues:
- * - Input queue, unidirectional queue where the writer is the - * lower side and the reader is the upper side. - * - Output queue, unidirectional queue where the writer is the - * upper side and the reader is the lower side. - * - Full duplex queue, bidirectional queue where read and write - * operations can happen at the same time. Full duplex queues - * are implemented by pairing an input queue and an output queue together. - * . - * In order to use the I/O queues the @p CH_USE_QUEUES option must - * be specified in @p chconf.h.
- * - * @ingroup IO - */ - /** * @defgroup SERIAL Serial Driver * @brief Generic Serial Drivers. -- cgit v1.2.3 From 397ccffac55ffd139d0e3e82add83e51413c1347 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 06:59:43 +0000 Subject: Documentation reorganization. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1133 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 4 +- docs/src/main.dox | 282 -------------------------------------------------- 2 files changed, 2 insertions(+), 284 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 8a7418b53..8add4464c 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -54,7 +54,7 @@ * - Regular Interrupts. Maskable interrupt sources that cannot * preempt the kernel code and are thus able to invoke operating system APIs * from within their handlers. The interrupt handlers belonging to this class - * must be written following some rules. See the @ref System APIs group and + * must be written following some rules. See the @ref system APIs group and * @ref article_interrupts. * - Fast Interrupts. Maskable interrupt sources with the ability * to preempt the kernel code and thus have a lower latency and are less @@ -244,7 +244,7 @@ * - Interrupt Stack. * - Internal Context. * . - * See the @ref Core documentation for details, the area may change on + * See the @ref core documentation for details, the area may change on * the various ports and some structures may not be present (or be zero-sized). * * @section architecture Architectural Diagram diff --git a/docs/src/main.dox b/docs/src/main.dox index d1cba5773..58e1b4e6a 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -100,249 +100,6 @@ * ChibiOS/RT ports. */ -/** - * @defgroup Kernel Kernel - * Kernel related subsystems, - */ - -/** - * @defgroup Config Configuration - * In @p chconf.h are defined the required subsystems for your application. - * @ingroup Kernel - */ - -/** - * @defgroup Core Port Code Templates - * Non portable code templates. The function and the macros defined under this - * section are the non portable part of the kernel. - * @note The port code is not an API, the applications should not invoke it - * directly, use the equivalent system API instead. - * @ingroup Kernel - */ - -/** - * @defgroup Types Types - * System types and macros. - * @ingroup Kernel - */ - -/** - * @defgroup System System Management - * Initialization, Locks, Interrupt Handling, Power Management, Abnormal - * Termination. - * @ingroup Kernel - */ - -/** - * @defgroup Debug Debug Support - * Debug APIs and procedures. - * @ingroup Kernel - */ - -/** - * @defgroup Scheduler Low Level Scheduler - * ChibiOS/RT scheduler APIs and macros. - * @ingroup Kernel - */ - -/** - * @defgroup ThreadLists Thread Lists and Queues - * ChibiOS/RT thread lists and queues utilities. - * @ingroup Kernel - */ - -/** - * @defgroup Threads Threads - * Threads related APIs. - * @ingroup Kernel - */ - -/** - * @defgroup Time Time and Virtual Timers - * Time and Virtual Timers related APIs. - * @ingroup Kernel - */ - -/** - * @defgroup Synchronization Synchronization - * Synchronization services. - */ - -/** - * @defgroup Semaphores Semaphores - * Semaphores and threads synchronization. - *

Operation mode

- * A semaphore is a threads synchronization object, some operations - * are defined on semaphores: - * - Signal: The semaphore counter is increased and if the result - * is non-positive then a waiting thread is removed from the semaphore - * queue and made ready for execution. - * - Wait: The semaphore counter is decreased and if the result - * becomes negative the thread is queued in the semaphore and suspended. - * - Reset: The semaphore counter is reset to a non-negative value - * and all the threads in the queue are released. - * . - * Semaphores can be used as guards for mutual exclusion code zones (note that - * mutexes are recommended for this kind of use) but also have other uses, - * queues guards and counters as example.
- * Semaphores usually use FIFO queues but it is possible to make them - * order threads by priority by specifying CH_USE_SEMAPHORES_PRIORITY in - * @p chconf.h.
- * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES - * option must be specified in @p chconf.h.

- * @ingroup Synchronization - */ - -/** - * @defgroup Mutexes Mutexes - * Mutexes and threads synchronization. - *

Operation mode

- * A mutex is a threads synchronization object, some operations are defined - * on mutexes: - * - Lock: The mutex is checked, if the mutex is not owned by some - * other thread then it is locked else the current thread is queued on the - * mutex in a list ordered by priority. - * - Unlock: The mutex is released by the owner and the highest - * priority thread waiting in the queue, if any, is resumed and made owner - * of the mutex. - * . - * In order to use the Event APIs the @p CH_USE_MUTEXES option must be - * specified in @p chconf.h.
- * - *

Constraints

- * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse - * order. The Unlock API does not even have a parameter, the mutex to unlock - * is taken from an internal stack of owned mutexes. - * This both improves the performance and is required by an efficient - * implementation of the priority inheritance mechanism. - * - *

The priority inversion problem

- * The mutexes in ChibiOS/RT implements the full priority - * inheritance mechanism in order handle the priority inversion problem.
- * When a thread is queued on a mutex, any thread, directly or indirectly, - * holding the mutex gains the same priority of the waiting thread (if their - * priority was not already equal or higher). The mechanism works with any - * number of nested mutexes and any number of involved threads. The algorithm - * complexity (worst case) is N with N equal to the number of nested mutexes. - * @ingroup Synchronization - */ - -/** - * @defgroup CondVars Condition Variables - * Condition Variables and threads synchronization. - *

Operation mode

- * The condition variable is a synchronization object meant to be used inside - * a zone protected by a @p Mutex. Mutexes and CondVars together can implement - * a Monitor construct.
- * In order to use the Condition Variables APIs the @p CH_USE_CONDVARS - * option must be specified in @p chconf.h.

- * @ingroup Synchronization - */ - -/** - * @defgroup Events Event Flags - * @brief Event Flags, Event Sources and Event Listeners. - *

Operation mode

- * Each thread has a mask of pending event flags inside its Thread structure. - * Several operations are defined: - * - Wait, the invoking thread goes to sleep until a certain AND/OR - * combination of event flags becomes pending. - * - Clear, a mask of event flags is cleared from the pending events - * mask, the cleared event flags mask is returned (only the flags that were - actually pending and then cleared). - * - Signal, an event mask is directly ORed to the mask of the signaled - * thread. - * - Broadcast, each thread registered on an Event Source is signaled - * with the event flags specified in its Event Listener. - * - Dispatch, an events mask is scanned and for each bit set to one - * an associated handler function is invoked. Bit masks are scanned from bit - * zero upward. - * . - * An Event Source is a special object that can be "broadcasted" by a thread or - * an interrupt service routine. Broadcasting an Event Source has the effect - * that all the threads registered on the Event Source will be signaled with - * and events mask.
- * An unlimited number of Event Sources can exists in a system and each - * thread can listen on an unlimited number of them.

- * In order to use the Event APIs the @p CH_USE_EVENTS option must be - * specified in @p chconf.h. - * @ingroup Synchronization - */ - -/** - * @defgroup Messages Synchronous Messages - * Synchronous inter-thread messages. - *

Operation Mode

- * Synchronous messages are an easy to use and fast IPC mechanism, threads - * can both serve messages and send messages to other threads, the mechanism - * allows data to be carried in both directions. Data is not copied between - * the client and server threads but just a pointer passed so the exchange - * is very time efficient.
- * Messages are usually processed in FIFO order but it is possible to process - * them in priority order by specifying CH_USE_MESSAGES_PRIORITY - * in @p chconf.h.
- * Threads do not need to allocate space for message queues, the mechanism - * just requires two extra pointers in the @p Thread structure (the message - * queue header).
- * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be - * specified in @p chconf.h. - * @ingroup Synchronization - */ - -/** - * @defgroup Mailboxes Mailboxes - * Asynchronous messages. - *

Operation mode

- * A mailbox is an asynchronous communication mechanism.
- * The following operations are possible on a mailbox: - * - Post: Posts a message on the mailbox in FIFO order. - * - Post Ahead: Posts a message on the mailbox with high priority. - * - Fetch: A message is fetched from the mailbox and removed from - * the queue. - * - Reset: The mailbox is emptied and all the stored messages lost. - * . - * A message is a variable of type msg_t that is guaranteed to have the - * same size of and be compatible with pointers (an explicit cast is needed). - * If larger messages need to be exchanged then a pointer to a structure can - * be posted in the mailbox but the posting side has no predefined way to - * know when the message has been processed. A possible approach is to - * allocate memory (from a memory pool as example) from the posting side and - * free it on the fetching side. Another approach is to set a "done" flag into - * the structure pointed by the message. - * @ingroup Synchronization - */ - -/** - * @defgroup Memory Memory Management - * Memory Management services. - */ - -/** - * @defgroup Heap Heap - * Heap Allocator related APIs. - *

Operation mode

- * The heap allocator implements a first-fit strategy and its APIs are - * functionally equivalent to the usual @p malloc() and @p free(). The main - * difference is that the heap APIs are thread safe.
- * By enabling the @p CH_USE_MALLOC_HEAP option the heap manager will use the - * runtime-provided @p malloc() and @p free() as backend for the heap APIs - * instead of the system provided allocator.
- * In order to use the heap APIs the @p CH_USE_HEAP option must be specified - * in @p chconf.h. - * @ingroup Memory - */ - -/** - * @defgroup MemoryPools Memory Pools - * Memory Pools related APIs. - *

Operation mode

- * The Memory Pools APIs allow to allocate/free fixed size objects in - * constant time and reliably without memory fragmentation problems.
- * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be - * specified in @p chconf.h. - * @ingroup Memory - */ - /** * @defgroup IO I/O Support * @brief I/O related services. @@ -375,45 +132,6 @@ * . */ -/** - * @defgroup Channels I/O Abstract Channels - * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels. Note - * that no code is present, I/O channels are just abstract classes-like - * structures, you should look at the systems as to a set of abstract C++ - * classes (even if written in C). Specific device drivers can use/extend - * the interfaces and implement them.
- * This system has the advantage to make the access to channels - * independent from the implementation logic. As example, an I/O channel - * interface can hide the access to a serial driver, to a networking socket - * and so on. - * - * @ingroup IO - */ - -/** - * @defgroup IOQueues I/O Queues - * @brief I/O queues. - * @details ChibiOS/RT supports several kinds of queues. The queues are mostly - * used in serial-like device drivers. The device drivers are usually designed - * to have a lower side (lower driver, it is usually an interrupt service - * routine) and an upper side (upper driver, accessed by the application - * threads).
- * There are several kind of queues:
- * - Input queue, unidirectional queue where the writer is the - * lower side and the reader is the upper side. - * - Output queue, unidirectional queue where the writer is the - * upper side and the reader is the lower side. - * - Full duplex queue, bidirectional queue where read and write - * operations can happen at the same time. Full duplex queues - * are implemented by pairing an input queue and an output queue together. - * . - * In order to use the I/O queues the @p CH_USE_QUEUES option must - * be specified in @p chconf.h.
- * - * @ingroup IO - */ - /** * @defgroup PAL I/O Ports Abstraction Layer (PAL) * @brief I/O Ports Abstraction Layer -- cgit v1.2.3 From c7b1157dc9f3ae577d592ab3207a84e64140eabe Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 07:17:22 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1134 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 38 -------------------------------------- 1 file changed, 38 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 58e1b4e6a..59cb75e2c 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -94,12 +94,6 @@ * . */ -/** - * @defgroup Ports Ports - * This section describes the technical details for the various supported - * ChibiOS/RT ports. - */ - /** * @defgroup IO I/O Support * @brief I/O related services. @@ -217,35 +211,3 @@ * * @ingroup SERIAL */ - -/** - * @defgroup utilities_library Utilities Library - * @brief Utilities Library. - * @details This is a collection of useful library code that is not part of - * the base kernel services. - *

Notes

- * The library code does not follow the same naming convention of the - * system APIs in order to make very clear that it is not "core" code.
- * The main difference is that library code is not formally tested in the - * test suite but through usage in the various demo applications. - */ - -/** - * @defgroup CPlusPlusLibrary C++ Wrapper - * @brief C++ wrapper module. - * @details This module allows to use the ChibiOS/RT functionalities - * from C++ as classes and objects rather the traditional "C" APIs. - * - * @ingroup utilities_library - */ - -/** - * @defgroup event_timer Periodic Events Timer - * @brief Periodic Event Timer. - * @details This timer generates an event at regular intervals. The - * listening threads can use the event to perform time related activities. - * Multiple threads can listen to the same timer. - * - * @ingroup utilities_library - */ - -- cgit v1.2.3 From 49c40ba106e8fbea8e67157591eab7bf0c9e9a01 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 08:49:10 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1136 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 147 ------------------------------------------------------ 1 file changed, 147 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 59cb75e2c..ee1a2654c 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -64,150 +64,3 @@ * - @subpage testsuite * . */ - -/** - * @page testsuite Test Suite - *

Description

- * Most of the ChibiOS/RT demos link a set of software modules (test suite) in - * order to verify the proper working of the kernel, the port and the demo - * itself.
- * Each Test Module performs a series of tests on a specified subsystem or - * subsystems and can report a failure/success status and/or a performance - * index as the test suite output.
- * The test suite is usually activated in the demo applications by pressing a - * button on the target board, see the readme into the various demos - * directories. The test suite output is usually sent through a serial port and - * can be examined by using a terminal emulator program. - * - *

Test Modules

- * - @subpage test_threads - * - @subpage test_dynamic - * - @subpage test_msg - * - @subpage test_sem - * - @subpage test_mtx - * - @subpage test_events - * - @subpage test_mbox - * - @subpage test_queues - * - @subpage test_heap - * - @subpage test_pools - * - @subpage test_benchmarks - * . - */ - -/** - * @defgroup IO I/O Support - * @brief I/O related services. - * @details This section contains the I/O related services. - * - * The I/O subsystem is a collection of device driver poertable interfaces and - * platform dependent implementations.
- * Under ChibiOS/RT a device driver is split in two layers: - * - High Level Device Driver (HLD). This layer contains the definitions - * of the driver's APIs and the platform independent part of the driver.
- * An HLD is composed by two files: - * - @.c, the high level implementation file. This file must be - * included in the Makefile in order to use the driver. - * - @.h, the high level header file. This file must be included - * by the application code in order to access the driver's APIs. - * . - * - Low Level Device Driver (LLD). This layer contains the platform - * dependent part of the driver.
- * A LLD is composed by two files: - * - @_lld.c, the low level implementation file. This file must be - * included in the Makefile in order to use the driver. - * - @_lld.h, the high level header file. This file is implicitly - * included by the HLD header file. - * . - * . - *

Available Device Drivers

- * The I/O subsystem currently includes support for: - * - @ref PAL. - * - @ref SERIAL. - * . - */ - -/** - * @defgroup PAL I/O Ports Abstraction Layer (PAL) - * @brief I/O Ports Abstraction Layer - * @details This module defines an abstract interface for digital I/O ports. - * Note that most I/O ports functions are just macros. The macros - * have default software implementations that can be redefined in a - * @ref PAL_LLD if the target hardware supports special features like, as - * example, atomic bit set/reset/masking. Please refer to the ports specific - * documentation for details.
- * The @ref PAL has the advantage to make the access to the I/O ports platform - * independent and still be optimized for the specific architectures.
- * Note that the @ref PAL_LLD may also offer non standard macro and functions - * in order to support specific features but, of course, the use of such - * interfaces would not be portable. Such interfaces shall be marked with - * the architecture name inside the function names. - * - *

Implementation Rules

- * In implementing an @ref PAL_LLD there are some rules/behaviors that - * should be respected. - * - *

Writing on input pads

- * The behavior is not specified but there are implementations better than - * others, this is the list of possible implementations, preferred options - * are on top: - * -# The written value is not actually output but latched, should the pads - * be reprogrammed as outputs the value would be in effect. - * -# The write operation is ignored. - * -# The write operation has side effects, as example disabling/enabling - * pull up/down resistors or changing the pad direction. This scenario is - * discouraged, please try to avoid this scenario. - * . - *

Reading from output pads

- * The behavior is not specified but there are implementations better than - * others, this is the list of possible implementations, preferred options - * are on top: - * -# The actual pads states are read (not the output latch). - * -# The output latch value is read (regardless of the actual pads states). - * -# Unspecified, please try to avoid this scenario. - * . - *

Writing unused or unimplemented port bits

- * The behavior is not specified. - * - *

Reading from unused or unimplemented port bits

- * The behavior is not specified. - * - *

Reading or writing on pins associated to other functionalities

- * The behavior is not specified. - * - *

Usage

- * The use of I/O ports requires the inclusion of the header file @p pal.h, - * this file is not automatically included @p ch.h like the other header - * files. - * - * @ingroup IO - */ - -/** - * @defgroup PAL_LLD PAL Low Level Driver - * @brief @ref PAL low level driver template. - * @details This file is a template for an I/O port low level driver. - * - * @ingroup PAL - */ - -/** - * @defgroup SERIAL Serial Driver - * @brief Generic Serial Drivers. - * @details This module implements a generic full duplex serial driver. The - * driver implements a @p SerialDriver interface and uses I/O Queues for - * communication between the upper and the lower driver. Event flags are used - * to notify the application about incoming data, outgoing data and other I/O - * events.
- * The module also contains functions that make the implementation of the - * interrupt service routines much easier.
- * - * @ingroup IO - */ - -/** - * @defgroup SERIAL_LLD Serial Low Level Driver - * @brief @ref SERIAL low level driver template. - * @details This file is a template for a serial low level driver. - * - * @ingroup SERIAL - */ -- cgit v1.2.3 From ccd53468b81e03732a5d3c6da3eb0c541aca738b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 16:35:39 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1143 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 8add4464c..67b01f8b3 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,7 +34,7 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a IO, @a FDD, @a Dbg, + * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a IO, @a Dbg, * @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes -- cgit v1.2.3 From 8b4030cdc9edbdcb9948893387b713b2cb4311c7 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 19 Sep 2009 19:53:40 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1171 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/goals.dox | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/goals.dox b/docs/src/goals.dox index e7a26fb3f..bcce60922 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -69,15 +69,15 @@ *

Fast and compact

* Note, first "fast" then "compact", the focus is on speed and execution * efficiency and then on code size. This does not mean that the OS is large, - * the kernel size with all the subsystems activated is around 5.3KiB + * the kernel size with all the subsystems activated is around 5.2KiB * and can shrink down around to 1.2Kib in a minimal configuration * (STM32, Cortex-M3). It would be possible to make something even smaller but: * -# It would be pointless, it is already @a really small. * -# I would not trade efficiency or features in order to save few bytes. * . * About the "fast" part, the kernel is able to start/exit more than - * 200,000 threads per second on a 72MHz STM32. - * The Context Switch takes 2.3 microseconds on the same STM32. + * 220,000 threads per second on a 72MHz STM32. + * The Context Switch takes 1.41 microseconds on the same STM32. * *

Tests and metrics

* I think it is nice to know how an OS is tested and how it performs before -- cgit v1.2.3 From fb616e61013b58eaf5973db0ceefd14ef49d9b50 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 20 Sep 2009 06:30:25 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1172 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/portguide.dox | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) (limited to 'docs/src') diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index 14a3c2eca..fe5870732 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -75,16 +75,21 @@ * 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 ./ports and name it as follow: - * @-@[-@] - * The compiler part can be omitted if the port uses GCC (our default). - * Examples: @p ARM7-LPC236x or @p ARMCM3-STM32F103-IAR + * -# 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 + * 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. - * -# Rename the files in order to reflect the name of the new chip. - * -# Work out the differences in the drivers. - * -# Edit the documentation file @p port.dox, this is required if you want - * to regenerate this documentation including your work. + * chip port or the naked template files from + * @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 + * is required if you want to regenerate this documentation including + * your work. * . * Usually this kind of port just requires a serial driver (and those are very * similar each other) and some code for the interrupt controller (this one -- cgit v1.2.3 From 34fd822f84d409fa649934251fae01994de7888b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 17 Oct 2009 09:21:59 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1226 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 67b01f8b3..bab26d064 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -35,7 +35,7 @@ * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a IO, @a Dbg, - * @a Heap, @a Pool. + * @a Core, @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes * The suffix can be one of the following: -- cgit v1.2.3 From 2c41c0d442aa3cea412fba318d4fe0a7cfd276d6 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 19 Oct 2009 18:33:53 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1241 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 3 +- docs/src/createthread.dox | 186 ++++++++++++++++++++++++++++++++++++++++++++++ docs/src/stacks.dox | 4 +- 3 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 docs/src/createthread.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index e9849782c..ac534a0c9 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -18,7 +18,7 @@ */ /** - * @page articles Articles + * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: * - @subpage article_stacks * - @subpage article_mutual_exclusion @@ -29,5 +29,6 @@ * - @subpage article_timing * - @subpage article_portguide * - @subpage article_design + * - @subpage article_create_thread * . */ diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox new file mode 100644 index 000000000..6ef1a61c5 --- /dev/null +++ b/docs/src/createthread.dox @@ -0,0 +1,186 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_create_thread How to create a thread + * At the system startup there are already two active threads: + * - Idle thread. This thread has the lowest priority in the system so + * it runs only when the other threads in the system are sleeping. This + * threads usually switches the system in a low power mode and does nothing + * else. + * - Main thread. This thread executes your @p main() function at + * startup. The main thread is created at the @p NORMALPRIO level but it + * can change its own priority if required. It is from the main thread + * that the other threads are usually created. + * . + * There are two kind of threads in ChibiOS/RT: + * - Static Threads. This kind of threads are statically allocated in + * memory. The memory used by the thread cannot reused except for restarting + * the threads. + * - Dynamic Threads. Threads created by allocating memory from a memory + * heap or a memory pool. + * . + *

Creating a static thread

+ * In order to create a static thread a working area must be declared using + * the macro @p WORKING_AREA as shown: + * @code +static WORKING_AREA(myThreadWorkingArea, 128); + * @endcode + * This macro reserves 128 bytes of stack for the thread and space for all + * the required thread related structures. The total size and the alignment + * problems are handled inside the macro, you only need to specify the pure + * stack size.
+ * A thread can be started by invoking @p chThdCreateStatic() as shown in this + * example: + * @code + Thread *tp = chThdCreateStatic(myThreadWorkingArea, + sizeof(myThreadWorkingArea), + NORMALPRIO, /* Initial priority. */ + myThread, /* Thread function. */ + NULL); /* Thread parameter. */ + * @endcode + * Tre variable tp receives the pointer to the thread object, it is taken + * by other APIs as parameter.
+ * Now a complete example: + * @code +/* +* * My simple application. + */ + +#include + +/* +* * Working area for the LED flashing thread. + */ +static WORKING_AREA(myThreadWorkingArea, 128); + +/* +* * LED flashing thread. + */ +static msg_t myThread(void *arg) { + + while (TRUE) { + LED_ON(); + chThdSleepMilliseconds(500); + LED_OFF(); + chThdSleepMilliseconds(500); + } +} + +int main(int argc, char *argv[]) { + + /* Starting the flashing LEDs thread.*/ + (void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea), + NORMALPRIO, myThread, NULL); + . + . + . +} + * @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 + * 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. */ + * @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 + * thread final status (its return value) is collected by the spawning thread. + * As example: + * @code +static msg_t myThread(void *arg) { + + unsigned i = 10; + while (i > 0) { + LED_ON(); + chThdSleepMilliseconds(500); + LED_OFF(); + chThdSleepMilliseconds(500); + i--; + } + return (msg_t)i; +} + +int main(int argc, char *argv[]) { + + Thread *tp = chThdCreateFromHeap(NULL, 128, NORMALPRIO+1, myThread, NULL); + if (tp == NULL) + chSysHalt(); /* Memory exausted. */ + + /* The main thread continues its normal execution.*/ + . + . + /* +* * Now waits for the spawned thread to terminate (if it has not terminated +* * already) then gets the thread exit message (msg) and returns the +* * terminated thread memory to the heap (default system heap in this +* * example). + */ + msg_t msg = chThdWait(tp); + . + . +} + * @endcode + * + *

Creating a dynamic thread using the heap allocator

+ * A pool is a collection of equally sized memory blocks, creating a thread from + * a memry pool is very similar to the previous example but the memory of + * terminated threads is returned to the memory pool rather than to a heap: + * @code +static msg_t myThread(void *arg) { + + unsigned i = 10; + while (i > 0) { + LED_ON(); + chThdSleepMilliseconds(500); + LED_OFF(); + chThdSleepMilliseconds(500); + i--; + } + return (msg_t)i; +} + +int main(int argc, char *argv[]) { + + Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL); + if (tp == NULL) + chSysHalt(); /* Pool empty. */ + + /* The main thread continues its normal execution.*/ + . + . + /* +* * Now waits for the spawned thread to terminate (if it has not terminated +* * already) then gets the thread exit message (msg) and returns the +* * terminated thread memory to the original memory pool. + */ + msg_t msg = chThdWait(tp); + . + . +} + * @endcode + */ diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox index 6035e1277..ddb416596 100644 --- a/docs/src/stacks.dox +++ b/docs/src/stacks.dox @@ -54,7 +54,9 @@ * - Enable the following debug options in the kernel: * - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any * context switch. This option halts the system in @p chSysHalt() just - * before a stack overflow happens. + * before a stack overflow happens. The halt condition is caused by + * a stack overflow when the global variable @p panic_msg is set to + * @p NULL, normally it would point to a panic message. * - @p CH_DBG_FILL_THREADS, this option fills the threads working area * with an easily recognizable pattern (0x55). * - Assign a large and safe size to the thread stack, as example 256 bytes -- cgit v1.2.3 From 7d689a5fae4f0950c8cb8e291744465ea5d2ca93 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 20 Oct 2009 17:26:27 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1242 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 5 +++-- docs/src/interrupts.dox | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index ac534a0c9..ca35c3f14 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,15 +20,16 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: + * - @subpage article_interrupts + * - @subpage article_create_thread + * - @subpage article_manage_memory * - @subpage article_stacks * - @subpage article_mutual_exclusion * - @subpage article_atomic * - @subpage article_saveram - * - @subpage article_interrupts * - @subpage article_jitter * - @subpage article_timing * - @subpage article_portguide * - @subpage article_design - * - @subpage article_create_thread * . */ diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 95bd6c281..b85db6efd 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -18,7 +18,7 @@ */ /** - * @page article_interrupts Writing interrupt handlers under ChibiOS/RT + * @page article_interrupts How to write interrupt handlers * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing * interrupt handlers. Port-related and compiler-related details are * encapsulated within standard system macros.
-- cgit v1.2.3 From 8c10c8f576a67087a22b249bef43681227369a80 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 20 Oct 2009 18:12:30 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1245 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/memory.dox | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/src/memory.dox (limited to 'docs/src') diff --git a/docs/src/memory.dox b/docs/src/memory.dox new file mode 100644 index 000000000..727a95b2b --- /dev/null +++ b/docs/src/memory.dox @@ -0,0 +1,138 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_manage_memory How to manage memory + * ChibiOS/RT is a static kernel so you don't need to manage memory at all + * if your application doesn't really require it. This doesn't mean that + * the OS is unable to manage memory but just that memory management is an + * optional part of the whole.
+ * The OS offers three distinct ways to manage memory, each one with its + * weaknesses and strengths: + * - Core Memory Manager. See @ref memcore. + * - Heap Allocator. See @ref heaps. + * - Memory Pools. See @ref pools. + * . + * The three mechanisms are able to coexist and are well integrated, as example + * the heap allocator uses the core memory manager in order to get more + * memory blocks, memory pools can optionally do the same thing. + * + *

The three subsystems

+ * This is a small comparison table regarding the three subsystems, C-runtime + * and static objects are thrown there for comparison:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
+ * Subsystem + * + * Free capable + * + * Constant time + * + * Safe + * + * From IRQ + * + * Notes + *
+ * Static Objects + * N/AN/AYESYES + * Preferred solution for safety applications. + *
+ * Core Memory Manager + * NOYESYESYES + * Fast and safe but unable to free allocated memory. + *
+ * Heap Allocator + * YESNONONO + * Unsafe because fragmentation and not constant time, cannot be used + * from IRQ handlers. + *
+ * Memory Pools + * YESYESYESYES + * Fast and safe but it can handle fixed size objects only, you may have + * multiple memory pools however. + *
+ * C-Runtime + * YESNONONO + * Unsafe because fragmentation, not constant time, cannot be used + * from IRQ handlers and not thread safe. The C runtime must also be + * modified in order to work with the other allocators. + *
+ *
+ * When designing a system it is recommended to proceed as follow: + * -# Use static objects and initializers whenever possible. + * -# Where dynamic allocation is required without have to free the allocated + * memory then use the Core Memory Manager allocation APIs. + * -# Where dynamic allocation is required evaluate if one or more memory + * pools can be used. + * -# If all the above points do not satisfy your requirements then use the + * heap allocator. + * -# Consider the C-runtime allocator only for legacy code. + * . + */ + \ No newline at end of file -- cgit v1.2.3 From 453515ab5cc9139ca123151c29d2ddc3ef1e4a44 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 21 Dec 2009 08:55:31 +0000 Subject: Updated GPL exception text in the documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1452 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/licfaq.dox | 50 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 11 deletions(-) (limited to 'docs/src') diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index 58e99a2bb..33f9de5e2 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -33,8 +33,18 @@ * - Am I forced to release the source code of my product?
* The exception to the GPL allows you to use ChibiOS/RT in your commercial * application without have to release your source code under certains - * conditions. See the exception text under "Approved Interfaces" for + * conditions. See the @ref exception_text under "Approved Interfaces" for * details. + * - What I have to contribute back?
+ * In general you have to offer changes done on existing files (where + * allowed) or new developments done using the OS template files. As example: + * - Ports to new architectures because a new port uses copyrighted OS + * template files. + * - New, HAL-style, device drivers because device drivers use copyrighted + * template files. + * - Improvements on modifiable OS code as described in the + * "approved interfaces" section of the @ref exception_text. + * . * - Is the exception applicable to any ChibiOS/RT version ?
* The exception is valid only for ChibiOS/RT releases marked as @e stable. * Beta or unstable versions are covered by the GPL3 alone because are meant @@ -45,7 +55,7 @@ * . * @section exception_text GPL Exception Text -
GPL Exception Text
+
GPL Exception Text for ChibiOS/RT 1.4.x
In addition, as a special exception, the copyright holder of ChibiOS/RT, gives You the additional right to link the unmodified code of this Program with @@ -62,23 +72,41 @@ in this paragraph. recipient request it. -# The combined work is not itself an RTOS, scheduler, kernel or related product. - -# The combined work is not itself a library intended for linking into - other software applications. + -# The combined work is not itself a binary library intended for linking + into other software applications. + .
The Approved Interfaces
-# The files of Non-GPL Code may include the unmodified ChibiOS/RT - distribution header files contained in ./src/include and ./src/lib + distribution header files contained under: + - ./os/kernel/include + - ./os/hal/include + - ./os/hal/platforms + - ./os/various + . without causing the resulting work to be covered by the GNU General Public License. -# The files of Non-GPL Code may link to the unmodified ChibiOS/RT - distribution files contained under ./src and ./src/lib without - causing the resulting work to be covered by the GNU General Public - License. + distribution files contained under: + - ./os/kernel/src + - ./os/hal/sec + - ./os/hal/platforms + - ./os/various + . + without causing the resulting work to be covered by the GNU General + Public License. -# The files of Non-GPL Code may link to, or include, the modified or - unmodified ChibiOS/RT distribution files contained under ./src/templates - and ./ports and ./demos without causing the resulting work to be - covered by the GNU General Public License. + unmodified ChibiOS/RT distribution files contained under: + - ./os/kernel/templates + - ./os/hal/templates + - ./os/ports + - ./boards + - ./demos + . + without causing the resulting work to be covered by the GNU General + Public License. + . Only the copyright holder of ChibiOS/RT may make changes or additions to the list of Approved Interfaces. -- cgit v1.2.3 From 320a3f140e693a0d8647fd05ec6d2d4cb10c523a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 30 Dec 2009 13:28:10 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1484 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index ee1a2654c..4ce9b64b1 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -40,21 +40,22 @@ * event flags, messages, mailboxes, I/O queues. * - No static setup at compile time, there is no need to configure a maximum * number of all the above objects. - * - PC simulator target included, the development can be done on the PC - * using MinGW.
+ * - PC simulator target included, the development can be done on a PC + * under Linux or Windows.
* Timers, I/O channels and other HW resources are simulated in a * Win32 process and the application code does not need to be aware of it. - * MinGW demo available. * - No *need* for a memory allocator, all the kernel structures are static * and declaratively allocated. * - Optional, thread safe, Heap Allocator subsystem. * - Optional, thread safe, Memory Pools Allocator subsystem. * - Blocking and non blocking I/O channels with timeout and events generation * capability. - * - Minimal system requirements: about 8KiB ROM with all options enabled and + * - Minimal system requirements: about 6KiB ROM with all options enabled and * speed optimizations on. The size can shrink under 2KiB by disabling the * the unused subsystems and optimizing for size. * - Almost totally written in C with little ASM code required for ports. + * - Optional Hardware Abstraction Layer (HAL) with support for many device + * driver models and device driver implementations. * . *

Related pages

* - @subpage lic_faq -- cgit v1.2.3 From 855fe2391d07c5dab27129ad626541482fe8d782 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 5 Jan 2010 17:14:09 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1501 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index bab26d064..d6364513b 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,7 +34,7 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a IO, @a Dbg, + * @a Mtx, @a Cond, @a Evt, @a Msg, @a Stream, @a IO, @a IQ, @a OQ, @a Dbg, * @a Core, @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes -- cgit v1.2.3 From 1eebe078ffbb85c3fb8a14db4d241502b27145bf Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 7 Jan 2010 15:23:38 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1509 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 3 +- docs/src/concepts.dox | 4 +- docs/src/goals.dox | 4 +- docs/src/main.dox | 4 +- docs/src/memory.dox | 2 +- docs/src/wakeup.dox | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 157 insertions(+), 8 deletions(-) create mode 100644 docs/src/wakeup.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index ca35c3f14..caf332d32 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,8 +20,9 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: - * - @subpage article_interrupts * - @subpage article_create_thread + * - @subpage article_interrupts + * - @subpage article_wakeup * - @subpage article_manage_memory * - @subpage article_stacks * - @subpage article_mutual_exclusion diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index d6364513b..49c96b2c8 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,8 +34,8 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a Stream, @a IO, @a IQ, @a OQ, @a Dbg, - * @a Core, @a Heap, @a Pool. + * @a Mtx, @a Cond, @a Evt, @a Msg, @a SequentialStream, @a IO, @a IQ, @a OQ, + * @a Dbg, @a Core, @a Heap, @a Pool. * * @section api_suffixes API Names Suffixes * The suffix can be one of the following: diff --git a/docs/src/goals.dox b/docs/src/goals.dox index bcce60922..e312b526a 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -42,7 +42,7 @@ * *

Static design

* Everything in the kernel is static, nowhere memory is allocated or freed, - * there are two allocator subsystems but those are options and not part of + * there are three allocator subsystems but those are options and not part of * core OS. Safety is something you design in, not something you can add later. * *

No tables, arrays or other fixed structures

@@ -84,5 +84,5 @@ * committing to use it. Test results on all the supported platforms and * performance metrics are included in each ChibiOS/RT release. The test * code is released as well, all the included demos are capable of executing - * the test suite and the OS benchmarks. + * the test suite and the OS benchmarks, see @ref testsuite. */ diff --git a/docs/src/main.dox b/docs/src/main.dox index 4ce9b64b1..ddf608c3f 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -42,8 +42,8 @@ * number of all the above objects. * - PC simulator target included, the development can be done on a PC * under Linux or Windows.
- * Timers, I/O channels and other HW resources are simulated in a - * Win32 process and the application code does not need to be aware of it. + * Timers, I/O channels and other HW resources are simulated in a guest OS + * process and the application code does not need to be aware of it. * - No *need* for a memory allocator, all the kernel structures are static * and declaratively allocated. * - Optional, thread safe, Heap Allocator subsystem. diff --git a/docs/src/memory.dox b/docs/src/memory.dox index 727a95b2b..cf8495bcc 100644 --- a/docs/src/memory.dox +++ b/docs/src/memory.dox @@ -35,7 +35,7 @@ * *

The three subsystems

* This is a small comparison table regarding the three subsystems, C-runtime - * and static objects are thrown there for comparison:

+ * and static objects are thrown in there for comparison:

* * diff --git a/docs/src/wakeup.dox b/docs/src/wakeup.dox new file mode 100644 index 000000000..82766932b --- /dev/null +++ b/docs/src/wakeup.dox @@ -0,0 +1,148 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_wakeup How to wake up a thread from an interrupt handler + * Waking up a thread after an hardware event is one of the most common tasks + * that an RTOS must be able to perform efficiently. In ChibiOS/RT there are + * several mechanisms that can be used, often each mechanism is best suited + * in a specific scenario. + * + *

Synchronously waking up a specific thread

+ * A common situation is to have to synchronously wake up a specific thread. + * This can be accomplished without the use of any specific synchronization + * primitive, it uses the very efficient low level scheduler APIs, note that + * you can also optionally send a simple message from the IRQ handler to + * the thread. + * @code +static Thread *tp = NULL; + +void mythread(void *p) { + + while (TRUE) { + msg_t msg; + + // Waiting for the IRQ to happen. + chSysLock(); + tp = chThdSelf(); + chSchGoSleepS(PRSUSPENDED); + msg = chThdSelf()->p_rdymsg; // Retrieving the message, optional + chSysUnlock(); + // Perform processing here. + } +} + +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up the thread. + chSysLockFromIsr(); + if (tp != NULL) { + tp->p_rdymsg = (msg_t)55; // Sending the message, optional + chSchReadyI(tp); + tp = NULL; + } + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Synchronously waking up one of the waiting threads

+ * Lets assume you have a queue of waiting threads, you want to wake up + * the threads one by one in FIFO order, if there are no waiting threads + * then nothing happens.
+ * This can be accomplished using a @p Semaphore object initialized to zero: + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // If there is at least one waiting thread then signal it. + chSysLockFromIsr(); + if (chSemGetCounterI(&mysem) < 0) + chSemSignalI(&mysem); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Synchronously waking up all the waiting threads

+ * In this scenario you want to synchronously wake up all the waiting threads, + * if there are no waiting threads then nothing happens.
+ * This can be accomplished using a @p Semaphore object initialized to zero: + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up all the threads waiting on the semaphore. + chSysLockFromIsr(); + chSemResetI(&mysem); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Asynchronously waking up a specific thread

+ * If you have to asynchronously wake up a specific thread then a simple + * event flags can be used. + * @code +static Thread *tp; + +void mythread(void *p) { + + tp = chThdSelf(); + while (TRUE) { + // Checks if an IRQ happened else wait. + chEvtWaitAny((eventmask_t)1); + // Perform processing here. + } +} + +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Wakes up the thread. + chSysLockFromIsr(); + chEvtSignalI(tp, (eventmask_t)1); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + * + *

Asynchronously waking up one or more threads

+ * By using event sources it is possible to asynchronously wake up one or more + * listener threads. The mechanism requires a single initialized + * @p EventSource object, all the threads registered as listeners on the + * event source will be broadcasted. + * @code +CH_IRQ_HANDLER(myIRQ) { + CH_IRQ_PROLOGUE(); + + // Pends an event flag on all the listening threads. + chSysLockFromIsr(); + chEvtBroadcastI(&my_event_source); + chSysUnlockFromIsr(). + + CH_IRQ_EPILOGUE(); +} + * @endcode + */ -- cgit v1.2.3 From 157b6f9695e7f72f2d54b231c19cb4045710ed01 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 21 Feb 2010 07:24:53 +0000 Subject: Updated license dates. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1646 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 2 +- docs/src/atomic.dox | 2 +- docs/src/concepts.dox | 2 +- docs/src/createthread.dox | 2 +- docs/src/design.dox | 2 +- docs/src/goals.dox | 2 +- docs/src/interrupts.dox | 4 ++-- docs/src/jitter.dox | 2 +- docs/src/licfaq.dox | 4 ++-- docs/src/main.dox | 2 +- docs/src/memory.dox | 4 ++-- docs/src/mutualexcl.dox | 2 +- docs/src/portguide.dox | 2 +- docs/src/saveram.dox | 2 +- docs/src/stacks.dox | 2 +- docs/src/timing.dox | 2 +- docs/src/wakeup.dox | 2 +- 17 files changed, 20 insertions(+), 20 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index caf332d32..bcdb62b6c 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 5e2fb58cd..0e9974ff1 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 49c96b2c8..b6a9e8630 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox index 6ef1a61c5..0774e0e7e 100644 --- a/docs/src/createthread.dox +++ b/docs/src/createthread.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/design.dox b/docs/src/design.dox index bc88edf6f..80a5b8af8 100644 --- a/docs/src/design.dox +++ b/docs/src/design.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/goals.dox b/docs/src/goals.dox index e312b526a..f41308e26 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index b85db6efd..cbebe5d5b 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. @@ -49,4 +49,4 @@ CH_IRQ_HANDLER(myIRQ) { * please read about it in the ARM7 port section: @ref ARM7_IH * . */ - \ No newline at end of file + diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox index 5f4e7ff5e..6ac74116e 100644 --- a/docs/src/jitter.dox +++ b/docs/src/jitter.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index 33f9de5e2..ff8ccae0d 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. @@ -116,4 +116,4 @@ Program code and other code used in conjunction with the Program except the Non-GPL Code covered by this exception. * */ - \ No newline at end of file + diff --git a/docs/src/main.dox b/docs/src/main.dox index ddf608c3f..a5ae9a8ca 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/memory.dox b/docs/src/memory.dox index cf8495bcc..1bd39b266 100644 --- a/docs/src/memory.dox +++ b/docs/src/memory.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. @@ -135,4 +135,4 @@ * -# Consider the C-runtime allocator only for legacy code. * . */ - \ No newline at end of file + diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox index 69eb65dc8..7f0b90e21 100644 --- a/docs/src/mutualexcl.dox +++ b/docs/src/mutualexcl.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index fe5870732..d7de77485 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox index 6682fe0fe..233c322c6 100644 --- a/docs/src/saveram.dox +++ b/docs/src/saveram.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox index ddb416596..87c404f7a 100644 --- a/docs/src/stacks.dox +++ b/docs/src/stacks.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/timing.dox b/docs/src/timing.dox index a09db8575..4f61adfeb 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/wakeup.dox b/docs/src/wakeup.dox index 82766932b..b53806b78 100644 --- a/docs/src/wakeup.dox +++ b/docs/src/wakeup.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3 From 508b7bc93297fcb74af43b11b1435aa96add3c85 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 25 Feb 2010 16:48:00 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1675 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/architecture.dox | 261 ++++++++++++++++++++++++++++++++++++++++++++++ docs/src/articles.dox | 1 + docs/src/concepts.dox | 26 ++--- docs/src/goals.dox | 2 +- docs/src/lifecycle.dox | 67 ++++++++++++ docs/src/main.dox | 1 + 6 files changed, 337 insertions(+), 21 deletions(-) create mode 100644 docs/src/architecture.dox create mode 100644 docs/src/lifecycle.dox (limited to 'docs/src') diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox new file mode 100644 index 000000000..d9a512b10 --- /dev/null +++ b/docs/src/architecture.dox @@ -0,0 +1,261 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page architecture Architecture + * @brief ChibiOS/RT General Architecture + * - @ref components + * - @ref dependencies + * - @ref kernel_arch + * - @ref hal_arch + * . + * @section components Components + * ChibiOS/RT is composed of several major components, each component can be + * composed of one of more subsystems. The main components are: + * - Kernel, this is the platform independent part of the OS kernel. + * - HAL, this component contains a set of abstract device drivers + * that offer a common I/O API to the application across all the support + * platforms. The HAL code is totally portable across platforms. + * - Port, this is the platform dependent part of the OS kernel. This + * component is responsible of the system startup, interrupts abstraction, + * lock/unlock primitives, context switch related structures and code.
+ * The component usually contains very little code because the OS is very + * portable but the quality of the implementation of the Port component + * affects heavily the performance of the ported OS. It is probably the + * most critical part of the whole OS. + * - Platform, this component contains a set of device drivers + * implementations. + * - Various, a library of various extra components that do not belong + * to any particular component but can make life easier while developing an + * embedded application. + * . + * @section dependencies Dependencies + * The following diagram shows the relationships among the various components + * that compose the system:

+ * @dot + digraph example { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.25"]; + edge [fontname=Helvetica, fontsize=8]; + + Application [label="Application"]; + HAL [label="HAL"]; + Platform [label="Platform"]; + Kernel [label="Kernel"]; + Port [label="Port"]; + HW [label="Hardware", style="filled", width="3.0", height="0.3"]; + + Application -> Kernel; + Application -> HAL; + Application -> HW [label=" (not recommended)"]; + HAL -> Platform; + HAL -> Kernel; + Platform -> Kernel; + Platform -> HW; + Kernel -> Port; + Port -> HW; + } + * @enddot + * + * @section kernel_arch Kernel Architecture + * The kernel itself is very modular and is composed of several subsystems, + * most subsystems are optional and can be switched of in the kernel + * configuration file @p chconf.h.
+ * The current kernel subsystems are divided in five categories: + * - @ref base, this category contains the mandatory kernel + * subsystems: + * - @ref system, low level locks, initialization. + * - @ref time, virtual timers and time APIs. + * - @ref scheduler, scheduler APIs, all the higher level synchronization + * mechanism are implemented through this subsystem, it is very flexible + * but not recommended for direct use in user code. + * - @ref threads, thread-related APIs. + * . + * Base services diagram:

+ * @dot + digraph example { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.25"]; + edge [fontname=Helvetica, fontsize=8]; + + Threads -> Scheduler; + Scheduler-> System; + Scheduler-> Timers; + System-> Timers; + } + * @enddot + * - @ref synchronization, this category contains the synchronization-related + * subsystems, each one of the provided mechanism can be configured out of + * the kernel if not needed. + * - @ref semaphores, counter semaphores subsystem. + * - @ref mutexes, mutexes subsystem with support to the priority inheritance + * algorithm (fully implemented, any depht). + * - @ref condvars, condition variables, together with mutexes the condition + * variables allow the implementation of monitor constructs. + * - @ref events, event sources and event flags with flexible support for + * and/or conditions and automatic dispatching to handler functions. + * - @ref messages, lightweight synchronous messages. + * - @ref mailboxes, asynchronous messages queues. + * . + * All the synchronization mechanisms are built on top of the Scheduler APIs + * except Mailboxes that are build on top of Semaphores and Condition + * Variables that implicitly refer to Mutexes:

+ * @dot + digraph example { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.25"]; + edge [fontname=Helvetica, fontsize=8]; + + Semaphores -> Scheduler; + Mutexes -> Scheduler; + Condvars -> Scheduler; + Condvars -> Mutexes; + Events -> Scheduler; + Messages -> Scheduler; + Mailboxes -> Semaphores; + } + * @enddot + * - @ref memory, memory management, multiple non-alternative schemes are + * available: + * - @ref memcore, centralized core memory manager, this subsystems is used + * by the other allocators in order to get chunks of memory in a consistent + * way. + * - @ref heaps, central heap manager using a first fit strategy, it also + * allow the creation of multiple heaps in order to handle non uniform + * memory areas. + * - @ref pools, very fast fixed size objects allocator. + * - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT + * but there is the option for dynamic threads management, please see the + * article @ref article_lifecycle. + * . + * The various allocators follow a precise hierarchy:

+ * @dot + digraph example { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.25"]; + edge [fontname=Helvetica, fontsize=8]; + + Core [label="Core Allocator"]; + Dynamic [label="Dynamic Threads"]; + Heaps [label="Dynamic Heaps"]; + Pools [label="Memory Pools"]; + C [label="C-runtime"]; + + Dynamic -> Heaps; + Dynamic -> Pools; + Heaps -> Core; + Pools -> Core; + C -> Core; + } + * @enddot + * Please also see the article @ref article_manage_memory. + * - @ref io_support, the kernel also provides mechanisms and abstract data + * interfaces that can be used by non-kernel components, the HAL as example. + * - @ref data_streams, abstract streams interface. + * - @ref io_channels, abstract I/O channels that inherits from the abstract + * stream interface. + * - @ref io_queues, generic, byte wide, I/O queues APIs. + * . + * - @ref debug, debug services and APIs. The @ref registry susystem can be + * seen as part of the debug category even if it finds use in non-debug + * roles. + * . + * @section hal_arch HAL Architecture + * The HAL is a collection of abstract device drivers, it relies on the + * Platform component for the low level implementation on specific + * hardware.
+ * The current internal HAL organization is the following:

+ * @dot + digraph example { + rankdir="LR"; + + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.25"]; + edge [fontname=Helvetica, fontsize=8]; + + subgraph cluster_HAL { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.25"]; + ADC [label="ADC"]; + CAN [label="CAN"]; + HAL [label="HAL"]; + MAC [label="MAC"]; + PAL [label="PAL"]; + PWM [label="PWM"]; + SER [label="SER"]; + SPI [label="SPI"]; + MMC_SD [label="MMC/SD"]; + color = blue; + label = "HAL"; + } + + subgraph cluster_Platform { + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.25"]; + ADC_LLD [label="ADC_LLD"]; + CAN_LLD [label="CAN_LLD"]; + HAL_LLD [label="HAL_LLD"]; + MAC_LLD [label="MAC_LLD"]; + PAL_LLD [label="PAL_LLD"]; + PWM_LLD [label="PWM_LLD"]; + SER_LLD [label="SER_LLD"]; + SPI_LLD [label="SPI_LLD"]; + color = blue; + label = "Platform"; + } + + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1", height="0.5"]; + edge [fontname=Helvetica, fontsize=8]; + + Application [label="Application"]; + HW [label="Hardware", style="filled"]; + + ADC -> ADC_LLD; + CAN -> CAN_LLD; + HAL -> HAL_LLD; + MAC -> MAC_LLD; + PAL -> PAL_LLD; + PWM -> PWM_LLD; + SER -> SER_LLD; + SPI -> SPI_LLD; + MMC_SD -> SPI [constraint=false]; + + Application -> ADC; + Application -> CAN; + Application -> HAL; + Application -> MAC; + Application -> PAL; + Application -> PWM; + Application -> SER; + Application -> SPI; + Application -> MMC_SD; + ADC_LLD -> HW; + CAN_LLD -> HW; + HAL_LLD -> HW; + MAC_LLD -> HW; + PAL_LLD -> HW; + PWM_LLD -> HW; + SER_LLD -> HW; + SPI_LLD -> HW; + } + * @enddot + *
+ * See @ref IO for details about the various HAL subsystems. + */ diff --git a/docs/src/articles.dox b/docs/src/articles.dox index bcdb62b6c..f8a40e2f7 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -25,6 +25,7 @@ * - @subpage article_wakeup * - @subpage article_manage_memory * - @subpage article_stacks + * - @subpage article_lifecycle * - @subpage article_mutual_exclusion * - @subpage article_atomic * - @subpage article_saveram diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index b6a9e8630..e1d5f6156 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -18,8 +18,8 @@ */ /** - * @page concepts Concepts and Architecture - * @brief ChibiOS/RT Concepts and Architecture + * @page concepts Kernel Concepts + * @brief ChibiOS/RT Kernel Concepts * - @ref naming * - @ref api_suffixes * - @ref interrupt_classes @@ -28,7 +28,6 @@ * - @ref thread_states * - @ref priority * - @ref warea - * - @ref architecture * . * @section naming Naming Conventions * ChibiOS/RT APIs are all named following this convention: @@ -52,10 +51,10 @@ * @section interrupt_classes Interrupt Classes * In ChibiOS/RT there are three logical interrupt classes: * - Regular Interrupts. Maskable interrupt sources that cannot - * preempt the kernel code and are thus able to invoke operating system APIs - * from within their handlers. The interrupt handlers belonging to this class - * must be written following some rules. See the @ref system APIs group and - * @ref article_interrupts. + * preempt (small parts of) the kernel code and are thus able to invoke + * operating system APIs from within their handlers. The interrupt handlers + * belonging to this class must be written following some rules. See the + * @ref system APIs group and @ref article_interrupts. * - Fast Interrupts. Maskable interrupt sources with the ability * to preempt the kernel code and thus have a lower latency and are less * subject to jitter, see @ref article_jitter. Such sources are not @@ -246,17 +245,4 @@ * . * See the @ref core documentation for details, the area may change on * the various ports and some structures may not be present (or be zero-sized). - * - * @section architecture Architectural Diagram - * The following diagram shows the relationships among the hardware, the - * various ChibiOS/RT subsystems and the application code. - *

- * @image html arch.png - *
- * In this diagram the device drivers are at the same level of the application - * code because both have access to the system services and can directly - * access the hardware.
- * Of course it is possible to create in the application architecture several - * extra layers, this is just not part of the kernel architecture but part of - * the overall system design. */ diff --git a/docs/src/goals.dox b/docs/src/goals.dox index f41308e26..eb1b2bd81 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -69,7 +69,7 @@ *

Fast and compact

* Note, first "fast" then "compact", the focus is on speed and execution * efficiency and then on code size. This does not mean that the OS is large, - * the kernel size with all the subsystems activated is around 5.2KiB + * the kernel size with all the subsystems activated weighs around 5.3KiB * and can shrink down around to 1.2Kib in a minimal configuration * (STM32, Cortex-M3). It would be possible to make something even smaller but: * -# It would be pointless, it is already @a really small. diff --git a/docs/src/lifecycle.dox b/docs/src/lifecycle.dox new file mode 100644 index 000000000..d96795b21 --- /dev/null +++ b/docs/src/lifecycle.dox @@ -0,0 +1,67 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @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 + * 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 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 last reference to the thread is released while the thread is in + * its @p THD_STATE_FINAL state.
+ * The following diagram explains the mechanism: + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + + init [label="No thread", style="bold"]; + alive [label="Alive"]; + final [label="Terminated"]; + detached [label="Detached", style="bold"]; + + init -> alive [label="chThdCreateX()"]; + alive -> alive [label="chThdAddRef()"]; + alive -> alive [label="chThdRelease()\n[ref > 0]"]; + alive -> detached [label="chThdRelease()\n[ref == 0]"]; + alive -> init [label="chThdWait()\n[ref == 0]"]; + alive -> final [label="chThdExit()\nreturn"]; + final -> final [label="chThdAddRef()"]; + final -> final [label="chThdRelease()\nchThdWait()\n[ref > 0]"]; + final -> init [label="chThdRelease()\nchThdWait()\n[ref == 0]"]; + } + * @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.
+ * 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. + */ diff --git a/docs/src/main.dox b/docs/src/main.dox index a5ae9a8ca..39601e563 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -60,6 +60,7 @@ *

Related pages

* - @subpage lic_faq * - @subpage goals + * - @subpage architecture * - @subpage concepts * - @subpage articles * - @subpage testsuite -- cgit v1.2.3 From 10b1366c43353749a182c60c7dfbe2e9fa2fd567 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 26 Feb 2010 14:03:23 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1676 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index e1d5f6156..6ddc8035f 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -174,7 +174,42 @@ * 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 + * @dot + digraph example { + rankdir="LR"; + + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + edge [fontname=Helvetica, fontsize=8]; + + subgraph cluster_running { + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + currp [label="'currp'\npointer", style="bold"]; + T4 [label="Tuser(4)\nprio=100"]; + label = "Currently Running Thread"; + penwidth = 0; + } + + subgraph cluster_rlist { + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + rh [label="ready list\nheader\nprio=0", style="bold"]; + Ti [label="Tidle\nprio=1"]; + Tm [label="Tmain\nprio=64"]; + T1 [label="Tuser(1)\nprio=32"]; + T2 [label="Tuser(2)\nprio=32"]; + T3 [label="Tuser(3)\nprio=80"]; + label = "Threads Ready for Execution"; + penwidth = 0; + } + + currp -> T4 + rh -> Ti -> T1 -> T2 -> Tm -> T3 -> rh [label="p_next"]; + rh -> T3 -> Tm -> T2 -> T1 -> Ti -> rh [label="p_prev"]; + } + * @enddot + *
* 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. * -- cgit v1.2.3 From f1ffe4b7fafdca0e074a2076b194390c2c77d25a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 3 Mar 2010 13:11:51 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1703 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 1 + docs/src/target.dox | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/src/target.dox (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 39601e563..f639682ab 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -60,6 +60,7 @@ *

Related pages

* - @subpage lic_faq * - @subpage goals + * - @subpage target * - @subpage architecture * - @subpage concepts * - @subpage articles diff --git a/docs/src/target.dox b/docs/src/target.dox new file mode 100644 index 000000000..8b6fd6493 --- /dev/null +++ b/docs/src/target.dox @@ -0,0 +1,84 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page target Applicative Range + * @brief ChibiOS/RT Applicative Range + * ChibiOS/RT has a well defined Applicative Range: deeply embedded systems + * that range from low/mid-range 8bits MCUs up to complex 32bits SOCs. + * - @ref applications + * - @ref min_requirements + * - @ref desirable_features + * - @ref upper_limit + * . + * @section applications Applicative Scenarios + * ChibiOS/RT is usable in many applicative areas, as example and not limited + * to: + * - Automotive. + * - Robotic Applications. + * - Consumer Electronics. + * - Energy Management. + * - Teaching and Learning. + * - Hobby. + * . + * @section min_requirements Absolute Minimum Requirements + * A certain set of minimum system requirements must be satisfied in order to + * use ChibiOS/RT on a new architecture: + * - 8bits architecture minimum. + * - A "real" stack pointer that can be positioned anywhere in the data address + * space. The OS could be ported to architectures with an hardware stack but + * I wouldn't recommend it because the context switch would become + * ridiculously inefficient. + * - Support for maskable interrupt sources and at least an OS-dedicated timer. + * - Support for standard C89 (C99 supported) language with no + * architecture-related non-standard restrictions. Non standard mandatory + * language extensions or restrictions may result in reduced functionality + * or impossibility of use. + * - 384/512bytes RAM permanently allocated to the kernel and its two mandatory + * threads "idle" and "main", the exact value depends on the architecture. + * This figure is not inclusive of the HAL and device drivers (non mandatory + * components). + * - 8KiB of program space for a full featured kernel scalable down to about + * 1.2KiB for reduced configurations. This figure is not inclusive of the + * HAL and device drivers (non mandatory components). + * . + * @section desirable_features Desirable Features + * - Efficient instruction set for linked lists traversal. The kernel makes + * extensive use of simple and bidirectional linked lists so the performance + * is directly affected by the suported addressing modes, number of registers + * etc. + * - Uniformly sized C pointers. + * - 2KiB RAM. + * - 16KiB ROM/Flash. + * . + * @section upper_limit Upper Applicative Limit + * The application range of ChibiOS/RT ends when one or more of the following + * features are required: + * - Separation between user code space and kernel space, both just logical or + * using a Memory Management/Protection Unit. Applications in ChibiOS/RT are + * supposed to be monolithic and trusted. The kernel and the application + * share the same address space. + * - Multiple applications. ChibiOS/RT supports the single multithreaded + * application model. + * - Multicore SMP architectures. Currently ChibiOS/RT only supports a single + * core unless running multiple distinct and separate OS instances. + * A true multicore kernel is planned for when multicore MCUs will become + * commonly available. + * . + */ -- cgit v1.2.3 From c25dfcb4c975fe7a43394d69536f80c9ebfee9e9 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 7 Mar 2010 08:53:19 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1730 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/target.dox | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/target.dox b/docs/src/target.dox index 8b6fd6493..db4f7d709 100644 --- a/docs/src/target.dox +++ b/docs/src/target.dox @@ -19,9 +19,7 @@ /** * @page target Applicative Range - * @brief ChibiOS/RT Applicative Range - * ChibiOS/RT has a well defined Applicative Range: deeply embedded systems - * that range from low/mid-range 8bits MCUs up to complex 32bits SOCs. + * @brief ChibiOS/RT Applicative Range. * - @ref applications * - @ref min_requirements * - @ref desirable_features -- cgit v1.2.3 From e4fed0ca868ce6365ef6cdf2774b49f83a430d6a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 7 Mar 2010 09:00:26 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1731 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/target.dox | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/target.dox b/docs/src/target.dox index db4f7d709..078a0d1cc 100644 --- a/docs/src/target.dox +++ b/docs/src/target.dox @@ -18,14 +18,14 @@ */ /** - * @page target Applicative Range - * @brief ChibiOS/RT Applicative Range. + * @page target Application Range + * @brief ChibiOS/RT Application Range. * - @ref applications * - @ref min_requirements * - @ref desirable_features * - @ref upper_limit * . - * @section applications Applicative Scenarios + * @section applications Application Scenarios * ChibiOS/RT is usable in many applicative areas, as example and not limited * to: * - Automotive. @@ -48,8 +48,8 @@ * architecture-related non-standard restrictions. Non standard mandatory * language extensions or restrictions may result in reduced functionality * or impossibility of use. - * - 384/512bytes RAM permanently allocated to the kernel and its two mandatory - * threads "idle" and "main", the exact value depends on the architecture. + * - 256/512bytes RAM permanently allocated to the kernel and its two mandatory + * threads "idle" and "main", the exact amount depends on the architecture. * This figure is not inclusive of the HAL and device drivers (non mandatory * components). * - 8KiB of program space for a full featured kernel scalable down to about @@ -65,7 +65,7 @@ * - 2KiB RAM. * - 16KiB ROM/Flash. * . - * @section upper_limit Upper Applicative Limit + * @section upper_limit Upper Recommended Limit * The application range of ChibiOS/RT ends when one or more of the following * features are required: * - Separation between user code space and kernel space, both just logical or -- cgit v1.2.3 From f1bb1a01ca40b8c999346c701450fcf0ca74827a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 12 Mar 2010 11:25:52 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1738 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/roundrobin.dox | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 docs/src/roundrobin.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index f8a40e2f7..ea471bdb7 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -25,6 +25,7 @@ * - @subpage article_wakeup * - @subpage article_manage_memory * - @subpage article_stacks + * - @subpage article_roundrobin * - @subpage article_lifecycle * - @subpage article_mutual_exclusion * - @subpage article_atomic diff --git a/docs/src/roundrobin.dox b/docs/src/roundrobin.dox new file mode 100644 index 000000000..8158a5c03 --- /dev/null +++ b/docs/src/roundrobin.dox @@ -0,0 +1,50 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_roundrobin Round Robin scheduling explained + * Unlike many other RTOSes, ChibiOS/RT supports multiple threads at the + * 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.
+ * 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. + * - 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. + * - 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. + * . + * 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 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. + */ -- cgit v1.2.3 From cf1b70f486a2696d523d585e91d0e4e5c7b8021c Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 18 Mar 2010 16:01:11 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1749 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/atomic.dox | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/src') diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox index 0e9974ff1..d3bc43ba5 100644 --- a/docs/src/atomic.dox +++ b/docs/src/atomic.dox @@ -20,38 +20,38 @@ /** * @page article_atomic Invoking multiple primitives as a single atomic operation * It is often necessary to invoke multiple operations involving a - * reschedulation as a single atomic operation.
+ * reschedule as a single atomic operation.
* ChibiOS/RT already implements APIs that perform complex operations, as * example the API @p chSemSignalWait() performs two operations atomically.
* If more complex operations are required in your application then it is * possible to build macro-operations, see the following example: * @code chSysLock(); - + chSemSignalI(&sem1); chSemSignalI(&sem2); chMtxUnlockS(); chSchRescheduleS(); - + chSysUnlock(); * @endcode * The above example performs a signal operation on two semaphores, unlocks the - * last aquired mutex and finally performs a reschedulation. All the operations + * last acquired mutex and finally performs a reschedule. All the operations * are performed atomically.
- * An hypotetical @p chSemSignalSignalWait() operation could be implemented as + * An hypothetical @p chSemSignalSignalWait() operation could be implemented as * follow: * @code chSysLock(); - + chSemSignalI(&sem1); chSemSignalI(&sem2); chSemWaitS(&Sem3); /* May reschedule or not. */ chSchRescheduleS(); /* This one reschedules if necessary. */ - + chSysUnlock(); * @endcode * In general multiple @ref I-Class and (non rescheduling) @ref S-Class APIs * can be included and the block is terminated by a rescheduling @ref S-Class * API. An extra @p chSchRescheduleS() can be present at the very end of the - * block, it only reschedules if a reschedulation is still required. + * block, it only reschedules if a reschedule is still required. */ -- cgit v1.2.3 From 05af5534a971e706b6ebde5111cd0fe7c514f63d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 18 Mar 2010 22:03:47 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1754 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/target.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/target.dox b/docs/src/target.dox index 078a0d1cc..9904f1426 100644 --- a/docs/src/target.dox +++ b/docs/src/target.dox @@ -59,8 +59,8 @@ * @section desirable_features Desirable Features * - Efficient instruction set for linked lists traversal. The kernel makes * extensive use of simple and bidirectional linked lists so the performance - * is directly affected by the suported addressing modes, number of registers - * etc. + * is directly affected by the supported addressing modes, number of + * registers etc. * - Uniformly sized C pointers. * - 2KiB RAM. * - 16KiB ROM/Flash. -- cgit v1.2.3 From 195c52c5d0f01dff4b779ba5bdca865a6ee8603d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 21 Mar 2010 10:55:42 +0000 Subject: Added toolchain installation guide. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1767 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/eclipse.dox | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 docs/src/eclipse.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index ea471bdb7..1ab76bbff 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,6 +20,7 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: + * . @subpage article_eclipse * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox new file mode 100644 index 000000000..79e60825d --- /dev/null +++ b/docs/src/eclipse.dox @@ -0,0 +1,164 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_eclipse Setting up a free embedded IDE + * @brief Free advanced embedded IDE for ChibiOS/RT + * This article will explain how to setup and use a free toolchain and use it + * with ChibiOS/RT and general embedded development. The IDE will allow you + * to: + * - Edit and reformat your source code. + * - Compile and verify errors. + * - Debug your code on the target board both in high level language and + * assembler. + * - Generate documentation from your source code. + * - Develop embedded applications with or without ChibiOS/RT. + * . + * The guide is meant mainly for Windows users but notes about Linux and + * MAC OSX are present where the setup differs, mostly the toolchain is + * exactly the same. + * + *

What this guide will not explain

+ * We will not enter in details of common system tasks like and not limited to: + * - Installing applications (unless a special procedure is required). + * - Creating desktop shortcuts. + * - Adding paths to the PATH variable. + * - Creating environment variables. + * - Any other normal PC usage task. + * . + * + *

Article Index

+ * - @ref required_components + * - @ref install_chibios + * - @ref install_compiler + * - @ref install_eclipse + * - @ref install_zylin + * - @ref install_doxygen + * - @ref install_graphviz + * - @ref install_eclox + * . + * + * @section required_components Required Components + * The first thing to do is to download all the required components, beginners + * should avoid the optional components initially: + * - A JTAG probe supporting GDB and OpenOCD, a list of compatible devices is + * available on the + * OpenOCD home page, more exactly + * here. + * - An STM32 development board (but this guide apply to all the ARM targets + * supported by ChibiOS/RT. This guide describes the Olimex STM32-P103. + * - + * ChibiOS/RT latest stable release. + * - Java runtime, you + * probably already have this installed. + * - Eclipse IDE + * for C/C++ Developers + * - YAGARTO ARM toolchain + * for Windows, note that you need both the compiler and the tools (make + * and binutils). + * - Zylin plugin for on-board debugging, see @ref install_zylin section. + * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but + * you can download them from here. This guide will describe the use with version + * 3.1 but it should apply to newer releases as well. + * - Optional, MinGW compiler, needed if you want to compile, debug + * and run the simulator from within Eclipse. Linux users do not need this + * one because all Linux distributions include the native GCC. + * - Optional, Doxygen, it is only required if you want to + * generate documentation from source files. + * - Optional, + * Graphwiz, it is only required if you want to generate diagrams + * within documentation from source files. + * - Optional, + * Eclox, it is only required if you want to generate documentation + * from source files from within Eclipse. + * . + * + * @section install_chibios ChibiOS/RT Installation + * Just unzip it into a directory in your home folder, Windows users may + * consider c:@\projects@\chibios. It is strongly suggested to not put version + * numbers into the ChibiOS/RT directory name because Eclipse workspaces + * have absolute paths inside and you don't want to setup everything again + * each time a new ChibiOS/RT version is released, use plain "chibios". + * + * @section install_compiler GCC ARM Compiler Installation + * Simply follow the YAGARTO installation guide. Linux/MACOS users have several + * other options: + * - Download the latest CodeSourcery free Linux package. + * - Build it yourself, Liam recommended a build script here: + * http://github.com/esden/summon-arm-toolchain, it looks interesting. + * . + * Make sure that the compiler binaries directory is listed in the PATH + * variable or Eclipse would not be able to locate it. + * + * @section install_eclipse Eclipse Installation + * Eclipse is distributed into a compressed archive, there is no installation + * procedure: + * - Verify if you have Java installed, if not install the runtime. You may + * verify this using the command: java -version. Make sure you have at + * least version 1.6. + * - Create an eclipse directory in your home and unpack the archive there. + * Windows users may unpack it into c:@\program files@\eclipse. + * - Create a desktop shortcut or other way to launch the Eclipse executable + * easily. + * - Launch Eclipse. + * - Eclipse will ask you a directory for its initial workspace, make it point + * to the ChibiOS/RT root directory (you may have as many workspaces you + * want, keep this for later), make sure to select the check box or it will + * ask you again each time. + * @image html tool001.jpg + * - Now you should see the welcome screen, close it and you will be in the + * normal C/C++ perspective. + * - Unselect "Project->Build Automatically" unless you like insanity. + * - Disable the "usage collector" in Window->Preferences->Usage_Data_Collector + * by unselecting "Enable capture". + * - If you are behind a proxy or firewall (corporate users usually are) + * configure the correct parameters in Window->Preferences->General->Network_Connections. + * - Let Eclipse auto update to the latest version Help->Check_for_Updates. + * . + * + * @section install_zylin Zylin Plugin Installation + * Eclipse requires an hardware debugger component in order to perform on board + * execution and debug. + * - Open Eclipse, then help->Install_New_Software... + * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt + * into the location field, then press OK. The Zylin plugin will appear in the + * available plugins view, select and install it. + * @image html tool002.jpg + * . + * + * @section install_doxygen Doxygen Installation + * Just use the installer, Linux users probably have Doxygen already available + * from the repositories. Make sure that the Doxygen binaries directory + * is listed in the PATH variable or Eclipse would not be able to locate it. + * + * @section install_graphviz Graphviz Installation + * Just use the installer, Linux users probably have Graphviz already available + * from the repositories. Make sure that the Graphviz binaries directory + * is listed in the PATH variable or Doxygen would not be able to locate it. + * + * @section install_eclox Eclox Installation + * Use the same installation steps used for the Zylin plugin except use the + * URL http://download.gna.org/eclox/update. Install "Eclox" not "Eclox Hot". + * After installing Eclox you will be able to compile Doxygen documentation + * using the button with the blue @@ inside. + */ -- cgit v1.2.3 From 51d47eb0795fb2acf0b374c0e348384654d84b17 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 21 Mar 2010 11:11:38 +0000 Subject: Small error. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1768 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 1ab76bbff..c2f9475a2 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,7 +20,7 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: - * . @subpage article_eclipse + * - @subpage article_eclipse * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup -- cgit v1.2.3 From 2732c959eb0435f5f056fd6b6e191395128ea882 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 22 Mar 2010 16:16:52 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1772 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse.dox | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index 79e60825d..385335d7e 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -62,8 +62,6 @@ * OpenOCD home page, more exactly * here. - * - An STM32 development board (but this guide apply to all the ARM targets - * supported by ChibiOS/RT. This guide describes the Olimex STM32-P103. * - * ChibiOS/RT latest stable release. * - Java runtime, you @@ -76,8 +74,8 @@ * - Zylin plugin for on-board debugging, see @ref install_zylin section. * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but * you can download them from here. This guide will describe the use with version - * 3.1 but it should apply to newer releases as well. + * target="_blank">here. Linux users can try + * here. * - Optional, MinGW compiler, needed if you want to compile, debug * and run the simulator from within Eclipse. Linux users do not need this @@ -125,7 +123,9 @@ * to the ChibiOS/RT root directory (you may have as many workspaces you * want, keep this for later), make sure to select the check box or it will * ask you again each time. + *
* @image html tool001.jpg + *
* - Now you should see the welcome screen, close it and you will be in the * normal C/C++ perspective. * - Unselect "Project->Build Automatically" unless you like insanity. @@ -143,9 +143,15 @@ * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt * into the location field, then press OK. The Zylin plugin will appear in the * available plugins view, select and install it. + *
* @image html tool002.jpg * . * + * @section install_openocd OpenOCD Installation + * Windows users just have to use the installer. Linux user should follow the + * normal installation procedure for deb or rpm packages, of course it is also + * possible to build it from the source code. + * * @section install_doxygen Doxygen Installation * Just use the installer, Linux users probably have Doxygen already available * from the repositories. Make sure that the Doxygen binaries directory @@ -157,8 +163,9 @@ * is listed in the PATH variable or Doxygen would not be able to locate it. * * @section install_eclox Eclox Installation - * Use the same installation steps used for the Zylin plugin except use the - * URL http://download.gna.org/eclox/update. Install "Eclox" not "Eclox Hot". + * Use the same installation steps used for the Zylin plugin except use + * http://download.gna.org/eclox/update as URL. Install "Eclox" not "Eclox + * Hot". * After installing Eclox you will be able to compile Doxygen documentation * using the button with the blue @@ inside. */ -- cgit v1.2.3 From 3039396b6a1b6acb98fa6025bd6c3461d4ee2817 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 22 Mar 2010 19:06:05 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1773 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index 385335d7e..77f21720d 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -123,7 +123,7 @@ * to the ChibiOS/RT root directory (you may have as many workspaces you * want, keep this for later), make sure to select the check box or it will * ask you again each time. - *
+ *

* @image html tool001.jpg *
* - Now you should see the welcome screen, close it and you will be in the @@ -143,7 +143,7 @@ * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt * into the location field, then press OK. The Zylin plugin will appear in the * available plugins view, select and install it. - *
+ *

* @image html tool002.jpg * . * -- cgit v1.2.3 From b57865fae9e00a5c07d4a63bf519bc0e86ae32f6 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 22 Mar 2010 21:37:51 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1774 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse.dox | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/src') diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index 77f21720d..09165f6ff 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -49,6 +49,7 @@ * - @ref install_compiler * - @ref install_eclipse * - @ref install_zylin + * - @ref install_openocd * - @ref install_doxygen * - @ref install_graphviz * - @ref install_eclox -- cgit v1.2.3 From 2fc7d70a735c84daa85a92a9a0fb23c0997f8355 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 23 Mar 2010 15:45:30 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1775 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/eclipse.dox | 34 ++++----- docs/src/eclipse2.dox | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 219 insertions(+), 19 deletions(-) create mode 100644 docs/src/eclipse2.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index c2f9475a2..f6f02e811 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -21,6 +21,7 @@ * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: * - @subpage article_eclipse + * - @subpage article_eclipse2 * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index 09165f6ff..5b58bf5fe 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -19,28 +19,22 @@ /** * @page article_eclipse Setting up a free embedded IDE - * @brief Free advanced embedded IDE for ChibiOS/RT - * This article will explain how to setup and use a free toolchain and use it - * with ChibiOS/RT and general embedded development. The IDE will allow you - * to: - * - Edit and reformat your source code. - * - Compile and verify errors. - * - Debug your code on the target board both in high level language and - * assembler. - * - Generate documentation from your source code. - * - Develop embedded applications with or without ChibiOS/RT. - * . + * @brief Free advanced embedded IDE for ChibiOS/RT. + * details This article will explain how to setup a free toolchain for use with + * ChibiOS/RT and general embedded development.
* The guide is meant mainly for Windows users but notes about Linux and * MAC OSX are present where the setup differs, mostly the toolchain is * exactly the same. * - *

What this guide will not explain

+ *

What this guide does not cover

* We will not enter in details of common system tasks like and not limited to: * - Installing applications (unless a special procedure is required). * - Creating desktop shortcuts. * - Adding paths to the PATH variable. * - Creating environment variables. * - Any other normal PC usage task. + * - Use of the toolchain, the use is covered by the "@ref article_eclipse2" + * article. * . * *

Article Index

@@ -75,7 +69,7 @@ * - Zylin plugin for on-board debugging, see @ref install_zylin section. * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but * you can download them from here. Linux users can try + * target="_blank">here. Linux users can try * here. * - Optional, MinGW compiler, needed if you want to compile, debug @@ -113,7 +107,7 @@ * Eclipse is distributed into a compressed archive, there is no installation * procedure: * - Verify if you have Java installed, if not install the runtime. You may - * verify this using the command: java -version. Make sure you have at + * verify this using the command: "java -version". Make sure you have at * least version 1.6. * - Create an eclipse directory in your home and unpack the archive there. * Windows users may unpack it into c:@\program files@\eclipse. @@ -130,17 +124,19 @@ * - Now you should see the welcome screen, close it and you will be in the * normal C/C++ perspective. * - Unselect "Project->Build Automatically" unless you like insanity. - * - Disable the "usage collector" in Window->Preferences->Usage_Data_Collector - * by unselecting "Enable capture". + * - Disable the "usage collector" in + * "Window->Preferences->Usage_Data_Collector" by unselecting "Enable + * capture". * - If you are behind a proxy or firewall (corporate users usually are) - * configure the correct parameters in Window->Preferences->General->Network_Connections. - * - Let Eclipse auto update to the latest version Help->Check_for_Updates. + * configure the correct parameters in + * "Window->Preferences->General->Network_Connections". + * - Let Eclipse auto update to the latest version "Help->Check_for_Updates". * . * * @section install_zylin Zylin Plugin Installation * Eclipse requires an hardware debugger component in order to perform on board * execution and debug. - * - Open Eclipse, then help->Install_New_Software... + * - Open Eclipse, then "Help->Install_New_Software...". * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt * into the location field, then press OK. The Zylin plugin will appear in the * available plugins view, select and install it. diff --git a/docs/src/eclipse2.dox b/docs/src/eclipse2.dox new file mode 100644 index 000000000..18c4d565a --- /dev/null +++ b/docs/src/eclipse2.dox @@ -0,0 +1,203 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_eclipse2 Embedded development using Eclipse + * @brief Compiling and debugging ChibiOS/RT applications using Eclipse. + * @details This article will explain how to use an Eclipse based toolchain + * (see @ref article_eclipse) to develop ChibiOS/RT based applications. + * This guide will allow you to: + * - Importing ChibiOS/RT demos into the Eclipse environment. + * - Edit and reformat your source code. + * - Compile and examine errors and warnings. + * - Upload your program on the target board. + * - Debug your code on the target board both in high level language and + * assembler. + * - Develop embedded applications with or without ChibiOS/RT. + * . + * + *

What this guide does not cover

+ * This guide assumes knowledge in following areas: + * - OpenOCD setup is not covered by this guide because the setup changes + * depending on the JTAG probe used, the target MCU and also the target + * board. The guide will show the setup for a specific JTAG probe and a + * specific target, a valuable source for the OpenOCD setup is the + * + * dedicated forum, most questions you may have about OpenOCD have + * most likely already been answered there. + * - Hardware setup. + * . + * In general this guide is not a replacement for the Eclipse, GCC, Make, + * binutils, newlib, GDB, OpenOCD user manuals, the guide simply aims to + * give you a faster start. + * + *

Article Index

+ * - @ref eclipse2_requirements + * - @ref eclipse2_importing + * - @ref eclipse2_creating + * - @ref eclipse2_compiling + * - @ref eclipse2_configuring + * - @ref eclipse2_configuring_gdb + * - @ref eclipse2_configuring_openocd + * . + * - @ref eclipse2_debugging + * - @ref eclipse2_debugging_start + * - @ref eclipse2_debugging_stop + * . + * . + * + * @section eclipse2_requirements Required Components + * This guide requires: + * - An Eclipse/GCC/OpenOCD based toolchain, as example the one described in + * the article @ref article_eclipse. + * - An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM + * JTAG probe as long it is supported by OpenOCD. + * - An Olimex STM32-P103 target board, this guide applies to any other ARM + * target except for the OpenOCD setup part. + * - A terminal emulator for capturing the board serial output, Windows users + * may use Hyper Terminal, Linux and MAC OS-X users may use + * CuteCom. + * All ChibiOS/RT demos generate on the serial port a test report when a + * button on the target board is pressed, other demos may activate a command + * shell on the serial port, in both cases a terminal emulator is required. + * . + * + * @section eclipse2_importing Importing existing ChibiOS/RT demos into Eclipse + * The first step is to import a project into the Eclipse environment. + * ChibiOS/RT demos do not include Eclipse project files but just a normal + * Makefile. Eclipse is able to import a Makefile project and create + * its own project file so this is not a problem. This is how it is done: + * - Open you Eclipse environment and select the workspace created into the + * ChibiOS/RT project directory. + * - From within Eclipse select "File->New->C_Project", a dialog box will show. + * - Select "Makefile_project->Empty_Project" in the "Project type:" box. + * - Select "-- Other Toolchain --" in the "Toolchains:" box. + * - Unselect the "Use default location" check box. + * - Select the demo directory using the "Browse..." button. Something like + * "C:\Projects\ChibiOS-RT\demos\ARMCM3-STM32F103-GCC" will appear in the + * "Location:" box. + * - In the project name box put the same name of the directory containing + * the demo, ARMCM3-STM32F103-GCC in this example. + *

+ * @image html eclipse003.jpg + *
+ * - Press the "Finish" button and the project will be created and shown in + * the "Project Explorer". + * - Right click on the imported project and select "Index->Rebuild", this + * will make Eclipse build its internal symbols database. + * - Repeat the above steps for each ChibiOS/RT demo you want to import in + * Eclipse, all the demos that have a makefile can be imported. + * . + * + * @section eclipse2_creating Creating a new ChibiOS/RT application + * If you want to create a new application it is recommended that you create + * a Makefile project first then you can import it into eclipse using the above + * procedure. Makefile projects have the advantage that can be compiled + * everywhere even without Eclipse. Creation steps: + * - Create your own development directory under the ChibiOS/RT installation + * directory, as example "chibios/myprojects". + * - Copy an existing demo, of course choose a demo using your same target, + * under the new directory and rename it, as example + * "chibios/myprojects/myapplication". + * - Customize the Makefile if needed, usually you just need to do this if + * your application is composed by more than one source file. You may also + * want to remove the ChibiOS/RT test code from your application. + * - Once your makefile is ready, import the project under the Eclipse + * workspace using the procedure described in @ref eclipse2_importing. + * . + * + * @section eclipse2_compiling Compiling and Cleaning applications + * Once imported, an application can be compiled by using the "Build All" in + * the toolbar or by right clicking on the project and selecting "Build + * Project". In order to clean a project (removing all the temporary and binary + * files) right click on the project and select "Clean Project". + *

+ * @image html eclipse004.jpg + *
+ * The compilation result is visible as a complete log in the "Console" window, + * the detail of all errors an warnings is available in the "Problems" window. + *

+ * @image html eclipse005.jpg + *
+ * The build process produces the binary files specified in the Makefile, all + * the ChibiOS/RT demos produce binary files named ch.elf, ch.bin and/or + * ch.hex. The image must be loaded on the target board in order to execute + * it. The build process usually creates also some other useful files + * containing details about the built application (usually named ch.map and + * ch.dmp). + * + * @section eclipse2_configuring Preparing for Debug + * In order to debug your application a debug configuration must be created. + * The configuration instructs GDB (the source debugger used by Eclipse) on + * how to load the image, load the symbols and place the initial breakpoint + * in the make function. Note that GDB performs its function by connecting + * to a "GDB server", the DGB server implements the low level communication + * with the target device through the JTAG probe. In our scenario the GDB + * server functionality is performed by OpenOCD, this mean that OpenOCD must + * be running while performing a debug session within Eclipse. + * + * @subsection eclipse2_configuring_gdb Creating a GDB Debug Configuration + * A target specific debug configuration is required in order to: + * - Establish a connection with the GDB server. + * - Stop and reset the target. + * - Upload the binary code in Flash or RAM. + * - Set an initial breakpoint in the main function. + * - Start the target (which will immediately stop on the breakpoint). + * . + * **To be completed** + * + * @subsection eclipse2_configuring_openocd Configuring and running OpenOCD + * OpenOCD must be run, with appropriate parameters, before starting your + * debug session. Please refer to the OpenOCD documentation in order to + * properly launch it for your target. + *
**To be completed** + * + * @section eclipse2_debugging Debugging + * Now we are ready to debug an application on the target. Note that Eclipse + * have a mechanism called "Perspectives", you edit and compile your source + * code while you are in the "C/C++ perspective" while the debugging is + * performed in the "Debug perspective". You can switch perspective at any + * time, even while there is an active debug session. If you install more of + * the many Eclipse extension plugins (there are thousands) you may have even + * more perspectives available. + * + * @subsection eclipse2_debugging_start Starting a Debug Session + * In order to start a debugging session first make sure that OpenOCD is + * running then press the drop down menu on the right side of the + * debug icon in the toolbar (the small green bug) and select your + * debug configuration (we created just one but you may have multiple + * debug configurations in your project, as example I usually create + * another debug configuration that just starts the target without + * uploading the code).
+ * The debugger will be initialized, you will see the operation in progress on + * the console then Eclipse will switch to the debug perspective and you will + * see your program stopped on the default breakpoint in the main function. + * From there you can perform all the usual debugging tasks, set breakpoints, + * single step execution, variables, memory and registers inspection etc. + * Please refer to the Eclipse documentation about those "normal" operations. + * Note that if the debugging start procedure hangs then there is probably + * an error in your configuration or problems with the target, read the + * console log and/or the OpenOCD output in order to understand where the + * problem is. + * + * @subsection eclipse2_debugging_stop Stopping a Debug Session + * From the debug perspective press the stop button (small red square) in the + * debug window, the target will be stopped and you may both return to the + * C/C++ perspective or start it again. + */ -- cgit v1.2.3 From f38a21493342f3bd2f7e3371508e4ff280f76fb3 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 23 Mar 2010 19:09:32 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1776 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse2.dox | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/eclipse2.dox b/docs/src/eclipse2.dox index 18c4d565a..88a222fc8 100644 --- a/docs/src/eclipse2.dox +++ b/docs/src/eclipse2.dox @@ -160,7 +160,47 @@ * - Set an initial breakpoint in the main function. * - Start the target (which will immediately stop on the breakpoint). * . - * **To be completed** + * The first thing to do is to open the "Debug Configurations..." dialog: + *

+ * @image html eclipse006.jpg + *
+ * The configuration dialog will appear, we must create a native Zylin + * configuration: + *

+ * @image html eclipse007.jpg + *
+ * Now we must give the configuration a name, "ARMCM3-STM32F103-GCC (flash and + * run)" in this example, then setup the various configuration pages as follow: + *

+ * The "Main" tab: + * @image html eclipse008.jpg + *

+ * The "Debugger" tab: + * @image html eclipse009.jpg + *

+ * The "Commands" tab: + * @image html eclipse010.jpg + *
+ * Note that the "Commands" tab contains the part that changes depending on + * the target. The complete commands sequence (it is not fully visible in the + * image) for STM32 is: + * @code + * monitor soft_reset_halt + * monitor wait_halt + * monitor poll + * monitor flash probe 0 + * monitor stm32x mass_erase 0 + * monitor flash write_bank 0 ch.bin 0 + * monitor soft_reset_halt + * symbol-file ch.elf + * thbreak main + * continue + * @endcode + *

+ * The "Common" tab: + * @image html eclipse011.jpg + *
+ * Now the debug configuration is complete. * * @subsection eclipse2_configuring_openocd Configuring and running OpenOCD * OpenOCD must be run, with appropriate parameters, before starting your @@ -184,10 +224,16 @@ * debug configuration (we created just one but you may have multiple * debug configurations in your project, as example I usually create * another debug configuration that just starts the target without - * uploading the code).
+ * uploading the code). + *

+ * @image html eclipse012.jpg + *
* The debugger will be initialized, you will see the operation in progress on * the console then Eclipse will switch to the debug perspective and you will * see your program stopped on the default breakpoint in the main function. + *

+ * @image html eclipse013.jpg + *
* From there you can perform all the usual debugging tasks, set breakpoints, * single step execution, variables, memory and registers inspection etc. * Please refer to the Eclipse documentation about those "normal" operations. -- cgit v1.2.3 From 74b8a1756b6f05878569c9934b436fde36c0f86e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 7 Apr 2010 12:34:26 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1858 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse.dox | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index 5b58bf5fe..f3d9b557a 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -97,8 +97,9 @@ * Simply follow the YAGARTO installation guide. Linux/MACOS users have several * other options: * - Download the latest CodeSourcery free Linux package. - * - Build it yourself, Liam recommended a build script here: - * http://github.com/esden/summon-arm-toolchain, it looks interesting. + * - Build it yourself, Liam recommended a build script + * + * here, it looks interesting. * . * Make sure that the compiler binaries directory is listed in the PATH * variable or Eclipse would not be able to locate it. -- cgit v1.2.3 From 09126fe34f64af501fd163d4d385a71479d71096 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 18 Apr 2010 11:48:03 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1874 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/eclipse.dox | 2 +- docs/src/goals.dox | 6 +++--- docs/src/interrupts.dox | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/src') diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox index f3d9b557a..4e2dfe0fc 100644 --- a/docs/src/eclipse.dox +++ b/docs/src/eclipse.dox @@ -33,7 +33,7 @@ * - Adding paths to the PATH variable. * - Creating environment variables. * - Any other normal PC usage task. - * - Use of the toolchain, the use is covered by the "@ref article_eclipse2" + * - Use of the toolchain, the use is covered by the @ref article_eclipse2 * article. * . * diff --git a/docs/src/goals.dox b/docs/src/goals.dox index eb1b2bd81..6dc8f0034 100644 --- a/docs/src/goals.dox +++ b/docs/src/goals.dox @@ -32,7 +32,7 @@ * - When, after a while, I needed a RTOS again, none of the existing FOSS * projects met my expectations or my ideas of how a RTOS should be, not * even close (see below). I decided that work on that old project was - * a better idea that contribute to, or fork, something else. + * a better idea than contribute to, or fork, something else. * - I wanted another toy. * . *

Why is it different?

@@ -75,9 +75,9 @@ * -# It would be pointless, it is already @a really small. * -# I would not trade efficiency or features in order to save few bytes. * . - * About the "fast" part, the kernel is able to start/exit more than + * About the "fast" part, the kernel is able to start/exit over * 220,000 threads per second on a 72MHz STM32. - * The Context Switch takes 1.41 microseconds on the same STM32. + * The Context Switch takes 1.2 microseconds on the same STM32. * *

Tests and metrics

* I think it is nice to know how an OS is tested and how it performs before diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index cbebe5d5b..64f336f08 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -31,7 +31,7 @@ CH_IRQ_HANDLER(myIRQ) { chSysLockFromIsr(); // Invocation of some I-Class system APIs, never preemptable. - chSysUnlockFromIsr(). + chSysUnlockFromIsr(); // More IRQ handling code, again preemptable. -- cgit v1.2.3 From 75792b3d6af243e043e66b1b2f7199229d430ef8 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 21 Apr 2010 14:11:12 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1882 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/debug.dox | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+) create mode 100644 docs/src/debug.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index f6f02e811..5aff3203e 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -22,6 +22,7 @@ * ChibiOS/RT Articles and Code Examples: * - @subpage article_eclipse * - @subpage article_eclipse2 + * - @subpage article_debug * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup diff --git a/docs/src/debug.dox b/docs/src/debug.dox new file mode 100644 index 000000000..46a67dfb2 --- /dev/null +++ b/docs/src/debug.dox @@ -0,0 +1,138 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_debug Debugging ChibiOS/RT applications + * ChibiOS/RT offers several mechanisms that can help in the debug phase of + * the development cycle. + * + *

What this guide does not cover

+ * This guide assumes knowledge in following areas: + * - General knowledge of embedded development. + * - RTOS concepts. + * - Setup of your specific target hardware and toolchain. + * - Knowledge of your toolchain. The guide will explain what you need to do, + * not how it is done using you specific debugger, compiler, JTAG probe and + * target hardware. + * . + *

Helpful debugging configuration settings

+ * There are several settings in your kernel configuration file + * (see @ref templates/chconf.h) that you may want to enable during + * debugging and in general during the whole development process. + * - @p CH_OPTIMIZE_SPEED=FALSE, this disables inlining into the kernel code + * and makes it easier to debug using your debugger, you may also want + * to reduce or disable compiler optimizations (-O0 using GCC). + * - @p CH_DBG_ENABLE_CHECKS=TRUE, this setting enables the checks on the + * API parameters, useful to understand if you are passing wrong parameters + * to the OS functions. + * - @p CH_DBG_ENABLE_ASSERTS=TRUE, this setting enables the OS internal + * consistency checks, this can trap several kind of errors in the user + * code (or in the kernel itself). + * - @p CH_DBG_ENABLE_STACK_CHECK=TRUE, this setting enables checks on + * threads stack overflow. Note that this option is not available in + * all ports, check your port documentation. If not supported then it + * is silently ignored, see also the article @ref article_stacks. + * - @p CH_DBG_FILL_THREADS=TRUE, this setting enables the threads workspace + * filling, this can help examining the stack usage from your debugger. + * . + * Note that all the failed checks lock the kernel into the @p port_halt() + * function. In order to assess what triggered the lock the global variable + * @p panic_msg must be inspected using the debugger, the variable is a + * pointer to an error message (a zero terminated string), the pointer may + * contain @p NULL if the lock was triggered by a stack overflow. + * + *

Common errors and symptoms

+ * There are some common errors while using an RTOS, use the following + * table as a check list, if your problem is not a generic programming error + * then probably it is one of the following common RTOS/embedded related + * mistakes: + * - Insufficient stack allocated to one or more threads.
+ * Common symptoms: + * - Target instability. + * - Target locked into the @p port_halt() function. + * - Target trapped into an exception handler (architecture dependent). + * - Target apparent self reset (not real resets usually). + * . + * - Insufficient stack allocated to the IRQ stack (in those architectures + * that have a separate IRQ stack, ARM as example).
+ * Common symptoms: + * - Target instability. + * - Target trapped into an exception handler (architecture dependent). + * - Target apparent self reset (not real resets usually). + * . + * - Use of a non reentrant function from within an interrupt handler, as + * example most C runtime functions.
+ * Common symptoms: + * - Target instability. + * - Unexpected application behavior. + * . + * - Missing use of a mutual exclusion mechanism to protect data + * (or non reentrant code) shared among multiple threads and/or + * threads and interrupt handlers, see also the article + * @ref article_mutual_exclusion.
+ * Common symptoms: + * - Target instability. + * - Unexpected application behavior. + * . + * - Use of S-class or I-class APIs outside a proper lock state, see the + * @ref concepts article, specifically the @ref api_suffixes and + * @ref system_states sections.
+ * Common symptoms: + * - Target instability. + * - Target trapped into an exception handler (architecture dependent). + * - Target apparent self reset (not real resets usually). + * . + * - Use of a non I-class API from an interrupt handler, see the + * @ref concepts article, specifically the @ref api_suffixes and + * @ref system_states sections.
+ * Common symptoms: + * - Target instability. + * - Target trapped into an exception handler (architecture dependent). + * - Target apparent self reset (not real resets usually). + * . + * - Wrong threads priority assignment. One of the most critical things + * to do when designing an RTOS based application is to assign correct + * priorities to the threads in the system.
+ * Common symptoms: + * - Excessive or unpredictable response times. + * - Threads that appear to be never executed (CPU intensive threads at + * higher priority). + * . + * . + *

General suggestions

+ * For the less expert users, there are several things you may do in order + * to minimize the need for debugging: + * - Read carefully the documentation first. + * - Try to find a code examples for things are you going to do, good sources + * are: the documentation, the test code, under "./test" you will + * find examples for almost any API in the ChibiOS/RT kernel and most + * 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. + * - 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 + * spawned from questions in the forum or in the tracker). + * - Never give up :-) + * . + */ -- cgit v1.2.3 From 314ba53ca7082138720a173f76467a9450f1c371 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 26 Apr 2010 12:34:10 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1892 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/interrupts.dox | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) (limited to 'docs/src') diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox index 64f336f08..bceea96c4 100644 --- a/docs/src/interrupts.dox +++ b/docs/src/interrupts.dox @@ -21,8 +21,11 @@ * @page article_interrupts How to write interrupt handlers * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing * interrupt handlers. Port-related and compiler-related details are - * encapsulated within standard system macros.
- * An interrupt handler assumes the following general form: + * encapsulated within standard system macros. + * + *

Writing Regular Interrupt handlers

+ * A Regular Interrupts handler (see @ref interrupt_classes) must be written + * using the following general form: * @code CH_IRQ_HANDLER(myIRQ) { CH_IRQ_PROLOGUE(); @@ -38,15 +41,29 @@ CH_IRQ_HANDLER(myIRQ) { CH_IRQ_EPILOGUE(); } * @endcode - * Note that only interrupt handlers that have to invoke system @ref I-Class - * APIs must be written in this form, handlers unrelated to the OS activity can - * omit the macros. - * Another note about the handler name "myIRQ", in some ports it must be a + * + *

Writing Fast Interrupt handlers

+ * In those architectures (@ref ARM7 and @ref ARMCMx) supporting Fast + * Interrupts (see @ref interrupt_classes) handlers must be written + * using the following general form: + * @code +CH_FAST_IRQ_HANDLER(myIRQ) { + + // Fast IRQ handling code, preemptable if the architecture supports it. + // The invocation of any API is forbidden here because fast interrupt + // handlers can preempt the kernel even within its critical zones in + // order to minimize latency. +} + * @endcode + * + *

Handlers naming

+ * A note about the handler name "myIRQ", in some ports it must be a * vector number rather than a function name, it could also be a name from * within a predefined set, see the notes about the various ports. + * *

Important Notes

* - There is an important application note about ARM7 interrupt handlers, * please read about it in the ARM7 port section: @ref ARM7_IH * . */ - + \ No newline at end of file -- cgit v1.2.3 From 0da7d5d0ec626ff70dc6dd4c28b6e3e06496ce48 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 6 May 2010 15:08:13 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1905 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 4 +- docs/src/integrationguide.dox | 95 +++++++++++++++++++++++++++++++++++++++++++ docs/src/portguide.dox | 17 ++++---- docs/src/stop_os.dox | 63 ++++++++++++++++++++++++++++ 4 files changed, 171 insertions(+), 8 deletions(-) create mode 100644 docs/src/integrationguide.dox create mode 100644 docs/src/stop_os.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 5aff3203e..69066c0cc 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -22,11 +22,14 @@ * ChibiOS/RT Articles and Code Examples: * - @subpage article_eclipse * - @subpage article_eclipse2 + * - @subpage article_integrationguide + * - @subpage article_portguide * - @subpage article_debug * - @subpage article_create_thread * - @subpage article_interrupts * - @subpage article_wakeup * - @subpage article_manage_memory + * - @subpage article_stop_os * - @subpage article_stacks * - @subpage article_roundrobin * - @subpage article_lifecycle @@ -35,7 +38,6 @@ * - @subpage article_saveram * - @subpage article_jitter * - @subpage article_timing - * - @subpage article_portguide * - @subpage article_design * . */ diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox new file mode 100644 index 000000000..6eec61e75 --- /dev/null +++ b/docs/src/integrationguide.dox @@ -0,0 +1,95 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_integrationguide Integration Guide + * All the delivered ChibiOS/RT demos are stand alone applications so if + * you just start your application from an existing demo there isn't any + * 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. + * + *

What this guide does not cover

+ * This guide has a limited scope, the following topics are handled elsewhere: + * - Porting the OS to different architectures or different compilers is + * not covered in this guide, see @ref article_portguide instead. + * - This guide does not describe any specific environment or development + * tool, it is assumed you already know in detail the environment you + * want to work with. + * . + * + *

Article Index

+ * - @ref integrationguide_kernel + * - @ref integrationguide_hal + * . + * @section integrationguide_kernel Integrating the Kernel + * This section covers the scenario where you want to use the ChibiOS/RT + * kernel into an existing application. In order to accomplish this you need + * to import in your project two components: + * - The portable kernel. + * - The port layer for your microcontroller. + * . + * See the @ref architecture for more details. + * You need to add the following files to your build process: + * - All the source files contained under ./os/kernel/src, note that + * you should add all of them even if you don't plan to use some of the + * 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. + * . + * 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/@/@. + * . + * @section integrationguide_hal Integrating the HAL + * If, in addition to the kernel as described in the previous section, you also + * need to integrate the HAL into your application you also need to import + * the following components: + * - HAL portable files. + * - Platform specific files. + * . + * See the @ref architecture for more details. + * You need to add the following files to your build process: + * - All the source files contained under ./os/hal/src, note that + * you should add all of them even if you don't plan to use some of the + * subsystems. Unused drivers can be excluded from the HAL configuration + * file @p halconf.h. + * - All the source files contained under + * ./os/hal/platforms/@. + * - All the source files contained under + * ./boards/@. + * . + * You also need to add to the compiler options the following paths for + * searching header files: + * - The portable HAL headers ./os/hal/src. + * - The platform layer headers + * ./os/hal/platforms/@. + * - The board description headers + * ./boards/@. + * . + */ diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index d7de77485..3af53c4cf 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -40,17 +40,20 @@ * applies when porting the OS on a custom hardware using a supported * microcontroller. This task can be easily performed with the following * steps: - * -# Create a new directory under the ChibiOS/RT installation directory: - * ./projects/@ - * -# Copy the microcontroller demo code under the newly created directory. - * -# Customize the demo. Usually there are only four files that need to - * be modified: + * -# Create a new directory under ./boards and copy inside the board files + * from another board using the same microcontroller. + * -# Customize the board files: * - @p board.h This file contains the I/O pins setup for the uC, it - * may also contain other board-dependent settings, as example, clock and - * PLL settings. Customize this file depending on your target hardware. + * may also contain other board-dependent settings, as example, the clock + * frequency. Customize this file depending on your target hardware. * - @p board.c This file contains the initialization code, it is possible * you just need to customize @p board.h and not this file. If you have * some hardware specific initialization code then put it here. + * . + * -# Create a new directory under the ChibiOS/RT installation directory: + * ./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 * sources and/or add you application source files. * - @p main.c It contains the demo simple code, clean it and write your diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox new file mode 100644 index 000000000..4fb489a57 --- /dev/null +++ b/docs/src/stop_os.dox @@ -0,0 +1,63 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_stop_os How to cleanly stop the OS + * Stopping the OS should not be normally required but there are scenarios + * where one might want the complete control over the system again. + * As example entering into a bootload mode, or invoking some flashing + * algorithm locked in ROM.
+ * ChibiOS/RT does not have a shutdown API and there is a reason for this, + * stopping the kernel would not be enough, a well defined operations sequence + * is required.
+ * The shutdown operation should always be implemented into the @p main() + * function because in that context the stack pointer is guaranteed to be + * in the area allocated by the startup code. Stopping from a thread would + * leave the stack pointer "somewhere".
+ * The shutdown sequence should include the following steps, some steps + * are optional and depend on the application: + * - Safely stop critical threads. As example a thread that uses a File System + * should flush all the modified buffers to the persistent storage before + * terminating.
+ * The system should be designed to request the thread termination using + * @p chThdTerminate() and then wait its termination using @p chThdWait(). + * This phase can be skipped for non-critical threads. + * - Invoke the xxxStop() method on all the active device drivers, this + * disables the interrupt sources used by the various peripherals. This + * is required in order to not have interrupts after the shutdown that + * may invoke OS primitives. + * - Invoke chSysDisable(). + * - Stop the system timer whose service routine invokes + * @p chSysTimerHandlerI(). + * - Disable any other interrupt source that may invoke OS APIs. In general + * all the interrupt sources that have handlers declared by using the + * @p CH_IRQ_HANDLER() macro. + * - Perform any application related de-initialization. + * - Invoke chSysEnable(). + * . + * Now the OS is stopped and you can safely assume there are nothing going on + * under the hood. From here you can also restart the OS after finishing your + * critical operations using the following sequence: + * - Invoke chSysDisable(). + * - Restart the system timer. + * - Reinitialize the OS by invoking @p chSysInit(). + * - Restart your device drivers using the @p xxxStart() methods. + * - Restart all your threads. + * . + */ -- cgit v1.2.3 From c86fdb275a9a7b43eae4a7c80cf915dcb2cd129c Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 7 May 2010 15:23:42 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1907 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 34 ++++++++++++++++++++----- docs/src/stop_os.dox | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 69066c0cc..3846b01f0 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -20,24 +20,46 @@ /** * @page articles Articles and Code Samples * ChibiOS/RT Articles and Code Examples: + * - @subpage page_general + * - @subpage page_kb + * - @subpage page_howtos + * . + */ + +/** + * @page page_general General. + * Articles and guides not necessarily related to ChibiOS/RT. * - @subpage article_eclipse * - @subpage article_eclipse2 + * - @subpage article_jitter + * . + */ + +/** + * @page page_kb Knowledge Base. + * Articles and guides about ChibiOS/RT. * - @subpage article_integrationguide * - @subpage article_portguide * - @subpage article_debug - * - @subpage article_create_thread - * - @subpage article_interrupts - * - @subpage article_wakeup - * - @subpage article_manage_memory - * - @subpage article_stop_os * - @subpage article_stacks * - @subpage article_roundrobin * - @subpage article_lifecycle * - @subpage article_mutual_exclusion * - @subpage article_atomic * - @subpage article_saveram - * - @subpage article_jitter * - @subpage article_timing * - @subpage article_design * . */ + +/** + * @page page_howtos How To's. + * Articles describing how to implement specific tasks using ChibiOS/RT. + * - @subpage article_create_thread + * - @subpage article_interrupts + * - @subpage article_wakeup + * - @subpage article_manage_memory + * - @subpage article_stop_os + * . + */ + diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox index 4fb489a57..d2434dea9 100644 --- a/docs/src/stop_os.dox +++ b/docs/src/stop_os.dox @@ -60,4 +60,74 @@ * - Restart your device drivers using the @p xxxStart() methods. * - Restart all your threads. * . + *

Example

+ * This is an example of an hypothetical application that have to shutdown + * the OS when a certain event is generated. + * @code +#include "ch.h" +#include "hal.h" + +/* A shutdown flag.*/ +bool_t shutdown_required; + +/* Critical thread.*/ +static void my_thread(void *p) { + + while (!chThdShouldTerminate()) { + /* Normal thread activity code.*/ + } + /* Thread de-initialization before terminating, here you put the critical + thread finalization code.*/ + return 0; +} + +/* Main program, it is entered with interrupts disabled.*/ +void main(void) { + + /* HAL initialization, you need to do this just once.*/ + halInit(); + + /* Main loop, the main() function never exits.*/ + while (TRUE) { + Thread *tp; + + shutdown_required = FALSE; + + /* ChibiOS/RT initialization. This function becomes an OS thread.*/ + chSysInit(); + + /* Starting a device driver, SD2 in this case.*/ + sdStart(&SD2, NULL); + + /* Starting our critical thread.*/ + tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256), + NORMALPRIO, my_thread, &SD2); + + /* Main thread activity into a loop.*/ + while (!shutdown_required) { + /* Main activity, OS active until a shutdown becomes necessary.*/ + } + + /* Starting the shutdown sequence.*/ + chThdTerminate(tp); /* Requesting termination. */ + chThdWait(tp); /* Waiting for the actual termination. */ + sdStop(&SD2); /* Stopping serial port 2. */ + chSysDisable(); + stop_system_timer(); + stop_any_other_interrupt(); + chSysEnable(); + + /* Now the main function is again a normal function, no more a + OS thread.*/ + do_funny_stuff(); + + /* Restarting the OS but you could also stop the system or trigger a + reset instead.*/ + chSysDisable(); + } +} + * @endcode + * As you can see it is possible to jump in and out of the "OS mode" quite + * easily. Note that this is just an example, the real code could be very + * different depending on your requirements. */ -- cgit v1.2.3 From dd0dcbb957c69dd08ab2d4b4eb1b7543e4c6aad8 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 7 May 2010 17:11:12 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1908 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 3846b01f0..9d3aee8d0 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -27,7 +27,7 @@ */ /** - * @page page_general General. + * @page page_general General * Articles and guides not necessarily related to ChibiOS/RT. * - @subpage article_eclipse * - @subpage article_eclipse2 @@ -36,7 +36,7 @@ */ /** - * @page page_kb Knowledge Base. + * @page page_kb Knowledge Base * Articles and guides about ChibiOS/RT. * - @subpage article_integrationguide * - @subpage article_portguide @@ -53,7 +53,7 @@ */ /** - * @page page_howtos How To's. + * @page page_howtos How To's * Articles describing how to implement specific tasks using ChibiOS/RT. * - @subpage article_create_thread * - @subpage article_interrupts -- cgit v1.2.3 From eb49256ae9fe038c844bdbab776015863a71632d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 14 May 2010 12:23:26 +0000 Subject: Added thanks to the documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1924 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 1 + docs/src/thanks.dox | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 docs/src/thanks.dox (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index f639682ab..4813e6543 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -59,6 +59,7 @@ * . *

Related pages

* - @subpage lic_faq + * - @subpage thanks * - @subpage goals * - @subpage target * - @subpage architecture diff --git a/docs/src/thanks.dox b/docs/src/thanks.dox new file mode 100644 index 000000000..47d8a1729 --- /dev/null +++ b/docs/src/thanks.dox @@ -0,0 +1,49 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page thanks Thanks + * @brief Contributors + * + * I want to thanks to all the people that directly or indirectly contributed + * to the project, I beg pardon if someone is missing: + * - Adamo Reggiani, working on the Fujitsu port. + * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. + * - Egon Carusi, STM32 port improvements, testing and bug fixes. + * - Enrico Cavazza, working on the Fujitsu port and a GUI subsystem. + * - Eric Weddington, because his work on WinAVR and helping me sorting + * out issues with the ChibiOS/RT license. + * - Isidoro Orabona, co-developer of the ChibiOS/RT grandfather back + * in 1988, it is a long long story involving a 6502 and a Z80... + * - Jacek, Ride7 demo for STM32 Primer. + * - Leon Woestenberg, CondVars idea and implementation, documentation + * improvements and a lot of other ideas, he also helped with the lwIP port + * (he is one of the developers of that project too). + * - Leszek Bednarz, H8S and ColdFire ports and drivers. + * - Liam Staskawicz, Posix simulator, AT91SAM7x and STM32 related + * contributions, many bug fixes and excellent suggestions. + * - Michael Fischer, because the work on YAGARTO and the excellent + * feedback. + * - Riccardo Scanu, another long story, this time involving reverse + * engineering and giant robots... + * - Vladimir, first tested and fixed the AVR port, I don't know the + * surname but he has been the first contributor. + * - Walter Goossens, fixes to the LPC21xx support. + * . + */ -- cgit v1.2.3 From 9a1d38e85b3d898d70c1d70645e21c49bdd83c6a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 14 May 2010 12:43:14 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1925 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 2 +- docs/src/thanks.dox | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/main.dox b/docs/src/main.dox index 4813e6543..49bf41741 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -59,7 +59,7 @@ * . *

Related pages

* - @subpage lic_faq - * - @subpage thanks + * - @subpage credits * - @subpage goals * - @subpage target * - @subpage architecture diff --git a/docs/src/thanks.dox b/docs/src/thanks.dox index 47d8a1729..eec6bf2cf 100644 --- a/docs/src/thanks.dox +++ b/docs/src/thanks.dox @@ -18,10 +18,10 @@ */ /** - * @page thanks Thanks + * @page credits Credits * @brief Contributors * - * I want to thanks to all the people that directly or indirectly contributed + * I want to thank to all the people that directly or indirectly contributed * to the project, I beg pardon if someone is missing: * - Adamo Reggiani, working on the Fujitsu port. * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. -- cgit v1.2.3 From d42f2e5da46e8b8b7f175ad4fb1b512285e2f2f4 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 14 May 2010 12:43:57 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1926 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/src/thanks.dox | 49 ------------------------------------------------- 2 files changed, 49 insertions(+), 49 deletions(-) create mode 100644 docs/src/credits.dox delete mode 100644 docs/src/thanks.dox (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox new file mode 100644 index 000000000..eec6bf2cf --- /dev/null +++ b/docs/src/credits.dox @@ -0,0 +1,49 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page credits Credits + * @brief Contributors + * + * I want to thank to all the people that directly or indirectly contributed + * to the project, I beg pardon if someone is missing: + * - Adamo Reggiani, working on the Fujitsu port. + * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. + * - Egon Carusi, STM32 port improvements, testing and bug fixes. + * - Enrico Cavazza, working on the Fujitsu port and a GUI subsystem. + * - Eric Weddington, because his work on WinAVR and helping me sorting + * out issues with the ChibiOS/RT license. + * - Isidoro Orabona, co-developer of the ChibiOS/RT grandfather back + * in 1988, it is a long long story involving a 6502 and a Z80... + * - Jacek, Ride7 demo for STM32 Primer. + * - Leon Woestenberg, CondVars idea and implementation, documentation + * improvements and a lot of other ideas, he also helped with the lwIP port + * (he is one of the developers of that project too). + * - Leszek Bednarz, H8S and ColdFire ports and drivers. + * - Liam Staskawicz, Posix simulator, AT91SAM7x and STM32 related + * contributions, many bug fixes and excellent suggestions. + * - Michael Fischer, because the work on YAGARTO and the excellent + * feedback. + * - Riccardo Scanu, another long story, this time involving reverse + * engineering and giant robots... + * - Vladimir, first tested and fixed the AVR port, I don't know the + * surname but he has been the first contributor. + * - Walter Goossens, fixes to the LPC21xx support. + * . + */ diff --git a/docs/src/thanks.dox b/docs/src/thanks.dox deleted file mode 100644 index eec6bf2cf..000000000 --- a/docs/src/thanks.dox +++ /dev/null @@ -1,49 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page credits Credits - * @brief Contributors - * - * I want to thank to all the people that directly or indirectly contributed - * to the project, I beg pardon if someone is missing: - * - Adamo Reggiani, working on the Fujitsu port. - * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. - * - Egon Carusi, STM32 port improvements, testing and bug fixes. - * - Enrico Cavazza, working on the Fujitsu port and a GUI subsystem. - * - Eric Weddington, because his work on WinAVR and helping me sorting - * out issues with the ChibiOS/RT license. - * - Isidoro Orabona, co-developer of the ChibiOS/RT grandfather back - * in 1988, it is a long long story involving a 6502 and a Z80... - * - Jacek, Ride7 demo for STM32 Primer. - * - Leon Woestenberg, CondVars idea and implementation, documentation - * improvements and a lot of other ideas, he also helped with the lwIP port - * (he is one of the developers of that project too). - * - Leszek Bednarz, H8S and ColdFire ports and drivers. - * - Liam Staskawicz, Posix simulator, AT91SAM7x and STM32 related - * contributions, many bug fixes and excellent suggestions. - * - Michael Fischer, because the work on YAGARTO and the excellent - * feedback. - * - Riccardo Scanu, another long story, this time involving reverse - * engineering and giant robots... - * - Vladimir, first tested and fixed the AVR port, I don't know the - * surname but he has been the first contributor. - * - Walter Goossens, fixes to the LPC21xx support. - * . - */ -- cgit v1.2.3 From 88d93ba5bf533bfd49df40ba7998b747d1fbadc2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 17 May 2010 15:02:27 +0000 Subject: 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 +++++----- 11 files changed, 62 insertions(+), 60 deletions(-) (limited to 'docs/src') 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. * . */ -- cgit v1.2.3 From 6b6bce2f392da97f2007fa219fbabb33529665f2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 18 May 2010 13:36:33 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1935 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index eec6bf2cf..28343dc14 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -35,15 +35,16 @@ * - Leon Woestenberg, CondVars idea and implementation, documentation * improvements and a lot of other ideas, he also helped with the lwIP port * (he is one of the developers of that project too). - * - Leszek Bednarz, H8S and ColdFire ports and drivers. + * - Leszek Bednarz, H8S and ColdFire ports and drivers maintainer. * - Liam Staskawicz, Posix simulator, AT91SAM7x and STM32 related - * contributions, many bug fixes and excellent suggestions. + * contributions, general improvements, many bug fixes and excellent + * suggestions. * - Michael Fischer, because the work on YAGARTO and the excellent * feedback. * - Riccardo Scanu, another long story, this time involving reverse * engineering and giant robots... * - Vladimir, first tested and fixed the AVR port, I don't know the * surname but he has been the first contributor. - * - Walter Goossens, fixes to the LPC21xx support. + * - Walter Goossens, several fixes to the LPC21xx support. * . */ -- cgit v1.2.3 From 42476118ad82557a6acf94b61fdf396986531493 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 21 May 2010 13:03:42 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1946 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/timing.dox | 46 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 7 deletions(-) (limited to 'docs/src') diff --git a/docs/src/timing.dox b/docs/src/timing.dox index 4f61adfeb..14c3b14ec 100644 --- a/docs/src/timing.dox +++ b/docs/src/timing.dox @@ -27,13 +27,13 @@ msg_t my_thread(void *param) { while (TRUE) { do_something(); - chThdSleepMilliseconds(1000); /* Fixed interval */ + chThdSleepMilliseconds(1000); // Fixed interval } } * @endcode - * This example works well assuming that @p do_something() execution time is - * well below the system tick period and that @p my_thread() is not preempted - * by other threads inserting long intervals.
+ * This example works well assuming that the @p do_something() execution time + * is well below the system tick period and that @p my_thread() is not + * preempted by other threads that could insert long intervals.
* If the above conditions are not satisfied you may have @p do_something() * executed at irregular intervals, as example:

* T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.

@@ -45,9 +45,9 @@ msg_t my_thread(void *param) { * @code msg_t my_thread(void *param) { - systick_t time = chTimeNow(); /* T0 */ + systick_t time = chTimeNow(); // T0 while (TRUE) { - time += MS2ST(1000); /* Next deadline */ + time += MS2ST(1000); // Next deadline do_something(); chThdSleepUntil(time); } @@ -55,5 +55,37 @@ msg_t my_thread(void *param) { * @endcode * Using this code @p do_something() will always be executed at an absolute * deadline time and the error will not accumulate over time regardless of - * the execution time and delays inserted by other threads. + * the execution time and delays inserted by other threads.
+ * Note that this solution requires that the @p do_something() execution + * time must not exceed the deadline or the thread would stay sleeping into + * @p chThdSleepUntil(). + * + *

A different way

+ * Another way to perform activities at regular intervals is the use of a + * virtual timer. Virtual timers are able to generate callbacks at scheduled + * intervals. Virtual timers are one shot timers so you need to restart them + * from within the callback if you need a periodic timer like in this case. + * @code +VirtualTimer vt; + +void do_something(void *p) { + + chVTSetI(&vt, MS2ST(1000), do_something, p); // Restarts the timer. + // Periodic code here. +} + +int main(int argc, char **argv) { + + chSysLock(); + chVTSetI(&vt, MS2ST(1000), do_something, NULL); // Starts the timer. + chSysUnlock(); + ... +} + * @endcode + * Note that the callback code is executed from within the I-Locked state (see + * @ref system_states) so you can only execute I-Class APIs from there (see + * @ref api_suffixes).
+ * This solution has the advantage to not require a dedicated thread and + * thus uses much less RAM but the periodic code must have a very short + * execution time or it would degrade the overall system response time. */ -- cgit v1.2.3 From 1858286fa5e20193b4613693109ca7d67ed0c9cc Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 24 May 2010 14:25:37 +0000 Subject: Preparations for 2.0.0 release. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1951 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 45 +++++++++++++++++++++++++++++++++++++++++++-- docs/src/licfaq.dox | 8 ++++---- 2 files changed, 47 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index 28343dc14..bb65a625e 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -18,9 +18,50 @@ */ /** - * @page credits Credits - * @brief Contributors + * @page credits Copyright and Credits + * @brief Copyright and Credits * + *

Copyright Statement

+@verbatim + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. +@endverbatim + * + *

Contributions and Copyright Assignment

+ * Contributing to the ChibiOS/RT project requires assigning the copyright + * on the contributed code to myself (Giovanni Di Sirio).
+ * There are several reasons for this requirement: + * - ChibiOS/RT will probably become also a commercial product and I could not + * re-license the code without ownership. Note that the commercial product + * would not be a different or better product, just the same GPL product + * made available, on request, under a different license. The code will + * always be available to you under the current licensing terms. + * - I need ownership when changing the licensing terms and this happens + * each time the project goes from development/unstable to stable and + * back because the addition/removal of the GPL linking exception. + * - It will be easier for the project adopters to have a single ownership + * point in case of licensing issues (both GPL or commercial). + * - Losing the ownership on the code could preclude me the opportunity to + * make this project a full time job as I hope. + * - I definitely don't want to have to sort out copyright related issues + * in the future so better be clear than sorry. + * . + * Note that contributions will always be welcome even without such copyright + * assignment, the difference is that the contributed code would not be + * merged into the main line, it will still made available as contributed + * code with the contributor(s) copyright notice intact.
+ * Submissions of code with copyright notice should only happen through + * email, please do not commit code with copyright notices directly on + * the repository.
+ * When submitting code please state clearly your intention to keep the + * copyright on your work by adding your own copyright notice within the + * source code and by clearly mentioning your intentions in the message. Code + * contributed without copyright notice will be considered donated.
+ * If in doubt with licensing issues please don't hesitate to contact me + * in order to sort out any problem you may have.
+ * Of course the copyright assignment does not mean you would not be + * recognized for your hard work, see the following section. + * + *

Credits

* I want to thank to all the people that directly or indirectly contributed * to the project, I beg pardon if someone is missing: * - Adamo Reggiani, working on the Fujitsu port. diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox index ff8ccae0d..f2563134c 100644 --- a/docs/src/licfaq.dox +++ b/docs/src/licfaq.dox @@ -47,8 +47,8 @@ * . * - Is the exception applicable to any ChibiOS/RT version ?
* The exception is valid only for ChibiOS/RT releases marked as @e stable. - * Beta or unstable versions are covered by the GPL3 alone because are meant - * for testing only. + * Beta, unstable or development versions are covered by the GPL3 alone + * because are meant for testing only. * - I don't want to be bound by any of the above restriction, is this * possible?
* You may contact us about a commercial license. @@ -90,7 +90,7 @@ in this paragraph. -# The files of Non-GPL Code may link to the unmodified ChibiOS/RT distribution files contained under: - ./os/kernel/src - - ./os/hal/sec + - ./os/hal/src - ./os/hal/platforms - ./os/various . @@ -116,4 +116,4 @@ Program code and other code used in conjunction with the Program except the Non-GPL Code covered by this exception. * */ - + -- cgit v1.2.3 From 4e1bba17e9910a45e35c835246403160c5b80015 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 24 May 2010 18:38:29 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1953 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index bb65a625e..4e3249922 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -27,9 +27,12 @@ @endverbatim * *

Contributions and Copyright Assignment

- * Contributing to the ChibiOS/RT project requires assigning the copyright - * on the contributed code to myself (Giovanni Di Sirio).
- * There are several reasons for this requirement: + * If you plan to contribute code to the ChibiOS/RT project then there is a + * requirement you should be aware of: contributing code for inclusion in + * the ChibiOS/RT main line requires assigning the copyright on the + * contributed code to me (Giovanni Di Sirio).
+ * This may sound a bit harsh but is pretty standard for this kind of projects, + * there are several reasons for this requirement: * - ChibiOS/RT will probably become also a commercial product and I could not * re-license the code without ownership. Note that the commercial product * would not be a different or better product, just the same GPL product -- cgit v1.2.3 From d1f6246ea7d25abd5834314b8966297a99d4f6ac Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 24 May 2010 18:47:03 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1954 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index 4e3249922..a40c6fadb 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -33,12 +33,13 @@ * contributed code to me (Giovanni Di Sirio).
* This may sound a bit harsh but is pretty standard for this kind of projects, * there are several reasons for this requirement: - * - ChibiOS/RT will probably become also a commercial product and I could not - * re-license the code without ownership. Note that the commercial product - * would not be a different or better product, just the same GPL product - * made available, on request, under a different license. The code will - * always be available to you under the current licensing terms. - * - I need ownership when changing the licensing terms and this happens + * - ChibiOS/RT will probably also become a commercial product and it would + * not be possible to re-license the code without ownership. Note that the + * commercial product would not be a different or better product, just the + * same GPL product made available, on request, under a different license. + * The code will always be available to you under the current licensing + * terms. + * - Ownership is required when changing the licensing terms and this happens * each time the project goes from development/unstable to stable and * back because the addition/removal of the GPL linking exception. * - It will be easier for the project adopters to have a single ownership -- cgit v1.2.3 From 29d727356b71e0706a7069e41e70e1d5e885f4d3 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 28 May 2010 13:43:00 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1960 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/events.dox | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/src/events.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 42d1606ae..c34e34d43 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -40,6 +40,7 @@ * Articles and guides about ChibiOS/RT. * - @subpage article_integrationguide * - @subpage article_portguide + * - @subpage article_events * - @subpage article_debug * - @subpage article_stacks * - @subpage article_roundrobin diff --git a/docs/src/events.dox b/docs/src/events.dox new file mode 100644 index 000000000..22e4afec7 --- /dev/null +++ b/docs/src/events.dox @@ -0,0 +1,123 @@ +/* + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @page article_events Events Explained + * Events are an important feature in ChibiOS/RT, most device drivers generate + * events in order to notify the application that something happened at the + * I/O level.
+ * While event flags are not something unknown in other operating systems, + * their peculiar implementation in ChibiOS/RT requires a more in depth + * explanation.
+ * Lets start with the events related terminology: + * - Event Source, an @p EventSource is a system object that can be + * @a broadcasted asynchronously in response of a system event, as example, + * when the CAN driver receives a packet from the CAN bus it @a broadcasts + * an event source in order to inform the registered threads that a packet + * has just arrived. + * - Broadcast, the operation performed on an event source in order + * to inform the @a registered threads that an event just occurred. + * Broadcasting can happened both in interrupt handlers and in threads. + * - Event Listener, a system object that associates a @p Thread object + * to an event source. The process of associating a @p Thread to an + * @p EventSource using an @p EventListener is called @a registration. + * - Registration, action performed by a thread in order to be informed + * of events from a specific event source. Of course a thread can be + * @a registered on more than one event source by using multiple + * @p EventListener objects. Threads can also @a unregister from an event + * source. + * - Pend, each thread has a mask of @a pending events. The @a broadcast + * operation @a pends an event mask on all the @a registered threads. + * - Wait, synchronous operation performed by a thread in order to + * @a wait a specific combination of events. The API offers a variety of + * @a wait functions, please refer to the events API documentation. + * . + * Note that events are asynchronously generated, as example in an interrupt + * handler, but are synchronously served. + * + *

Events related data structures

+ * The following diagram explains the relationship between an event source, + * its list of event listeners and the @a registered threads. + * @dot + digraph example { + rankdir="LR"; + + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.0", height="0.5"]; + edge [fontname=Helvetica, fontsize=8, sep=3.0]; + + es [shape=record, label="EventSource | es_next", style="bold"]; + + subgraph cluster_0 { + fontname=Helvetica; + label = "Listeners List"; + color = blue; + node [shape=record, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.5", height="1.0"]; + el4 [label="EventListener 4 | el_mask: 0x0001 | el_listener | el_next"]; + el3 [label="EventListener 3 | el_mask: 0x0C00 | el_listener | el_next"]; + el2 [label="EventListener 2 | el_mask: 0x0001 | el_listener | el_next"]; + el1 [label="EventListener 1 | el_mask: 0x0004 | el_listener | el_next"]; + el1 -> el2 -> el3 -> el4 [label=" el_next", constraint=false]; + } + + subgraph cluster_1 { + fontname=Helvetica; + label = "Registered Threads"; + color = blue; + node [shape=record, fontname=Helvetica, fontsize=8, + fixedsize="true", width="1.5", height="0.8"]; + t1 [label="Thread 1 | p_epending:0x0000 | p_ewmask:0xFFFF"]; + t2 [label="Thread 2 | p_epending:0x000F | p_ewmask:0x0C01"]; + t3 [label="Thread 3 | p_epending:0x0008 | p_ewmask:0x0001"]; + t4 [label="Thread 4 | p_epending:0x0000 | p_ewmask:0xFFFF"]; + } + + es -> el1 [label=" es_next"]; + el4 -> es [label=" el_next"]; + el1 -> t1 [label="el_listener"]; + el2 -> t2 [label="el_listener"]; + el3 -> t3 [label="el_listener"]; + el4 -> t4 [label="el_listener"]; + } + * @enddot + * Note that each event listener has a different bit mask to be @a pended on + * its associated thread when the event source is @a broadcasted, this means + * that each thread can define its own event identifiers independently. A + * @a broadcast operation can also @a pend more than one bit on the + * @a registered threads.
+ * The threads have a variety of @a wait primitives, they can @a wait for one + * or more event flags to become @a pending, and can also specify AND/OR + * conditions, as example a thread can @a wait for any event to become + * @a pending or @w wait for all the specified events to become @a pending.
+ * The field @p p_epending is the mask of the currently pending events, + * the field @p p_ewmask is the mask of the events the thread is interested + * on in that moment (AND or OR condition depending on the invoked + * @a wait API). + * + *

Use Scenarios

+ * Events are best used when one of more of the following conditions are + * required: + * - Having to wait on multiple conditions, Events are the only mechanism + * that easily allow that. + * - Synchronous response to one or more asynchronous events. + * - Single threaded applications working in a event driver environment (but + * events are not limited to single threaded applications). + * . + */ -- cgit v1.2.3 From a5e0616537530926193d73c2e41bf780d4a55f05 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 29 May 2010 06:09:11 +0000 Subject: Added AT91SAM7S256 demo. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1961 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 6 +++--- docs/src/events.dox | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index a40c6fadb..bcaebb046 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -31,8 +31,8 @@ * requirement you should be aware of: contributing code for inclusion in * the ChibiOS/RT main line requires assigning the copyright on the * contributed code to me (Giovanni Di Sirio).
- * This may sound a bit harsh but is pretty standard for this kind of projects, - * there are several reasons for this requirement: + * This may sound a bit strange but is pretty standard for this kind of + * projects, there are several reasons for this requirement: * - ChibiOS/RT will probably also become a commercial product and it would * not be possible to re-license the code without ownership. Note that the * commercial product would not be a different or better product, just the @@ -66,7 +66,7 @@ * recognized for your hard work, see the following section. * *

Credits

- * I want to thank to all the people that directly or indirectly contributed + * I want to thank all the people that directly or indirectly contributed * to the project, I beg pardon if someone is missing: * - Adamo Reggiani, working on the Fujitsu port. * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. diff --git a/docs/src/events.dox b/docs/src/events.dox index 22e4afec7..98ba8d55f 100644 --- a/docs/src/events.dox +++ b/docs/src/events.dox @@ -105,7 +105,7 @@ * The threads have a variety of @a wait primitives, they can @a wait for one * or more event flags to become @a pending, and can also specify AND/OR * conditions, as example a thread can @a wait for any event to become - * @a pending or @w wait for all the specified events to become @a pending.
+ * @a pending or @a wait for all the specified events to become @a pending.
* The field @p p_epending is the mask of the currently pending events, * the field @p p_ewmask is the mask of the events the thread is interested * on in that moment (AND or OR condition depending on the invoked -- cgit v1.2.3 From dcf03f2c4438711637dac80b723be632bd7a605a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 29 May 2010 06:20:26 +0000 Subject: Version 1.5.8, release candidate 2 for version 2.0.0. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1962 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/credits.dox | 2 ++ docs/src/main.dox | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/credits.dox b/docs/src/credits.dox index bcaebb046..d0a40cb04 100644 --- a/docs/src/credits.dox +++ b/docs/src/credits.dox @@ -69,6 +69,8 @@ * I want to thank all the people that directly or indirectly contributed * to the project, I beg pardon if someone is missing: * - Adamo Reggiani, working on the Fujitsu port. + * - Alexander Kozaruk, AT91SAM7S256 demo and description files for + * the Olimex SAM7-P256 board. * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. * - Egon Carusi, STM32 port improvements, testing and bug fixes. * - Enrico Cavazza, working on the Fujitsu port and a GUI subsystem. diff --git a/docs/src/main.dox b/docs/src/main.dox index 49bf41741..e5872cdf5 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -58,8 +58,8 @@ * driver models and device driver implementations. * . *

Related pages

- * - @subpage lic_faq * - @subpage credits + * - @subpage lic_faq * - @subpage goals * - @subpage target * - @subpage architecture -- cgit v1.2.3 From 17bd98c1fa7948c0b9df0aab555db9a8c1062f45 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 12 Jul 2010 08:49:55 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2073 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/architecture.dox | 15 ++++++++++++++- docs/src/createthread.dox | 2 +- docs/src/memory.dox | 2 +- docs/src/portguide.dox | 6 +++--- 4 files changed, 19 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox index d9a512b10..e5a73239e 100644 --- a/docs/src/architecture.dox +++ b/docs/src/architecture.dox @@ -59,6 +59,7 @@ Platform [label="Platform"]; Kernel [label="Kernel"]; Port [label="Port"]; + Board [label="Board Setup"]; HW [label="Hardware", style="filled", width="3.0", height="0.3"]; Application -> Kernel; @@ -66,9 +67,12 @@ Application -> HW [label=" (not recommended)"]; HAL -> Platform; HAL -> Kernel; + Board -> HW; Platform -> Kernel; + Platform -> Board; Platform -> HW; Kernel -> Port; + Port -> Board [label="Optional", style="dotted"]; Port -> HW; } * @enddot @@ -119,7 +123,7 @@ * @dot digraph example { node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.25"]; + fixedsize="true", width="1.1", height="0.25"]; edge [fontname=Helvetica, fontsize=8]; Semaphores -> Scheduler; @@ -128,6 +132,7 @@ Condvars -> Mutexes; Events -> Scheduler; Messages -> Scheduler; + "Binary Semaphores" -> Semaphores; Mailboxes -> Semaphores; } * @enddot @@ -151,17 +156,25 @@ fixedsize="true", width="1.0", height="0.25"]; edge [fontname=Helvetica, fontsize=8]; + Application [label="Application", width="2.0"]; + RAM [label="RAM", style="filled", width="2.0"]; Core [label="Core Allocator"]; Dynamic [label="Dynamic Threads"]; Heaps [label="Dynamic Heaps"]; Pools [label="Memory Pools"]; C [label="C-runtime"]; + Application -> Dynamic; + Application -> Heaps; + Application -> Pools; + Application -> C [label="(not recommended)"]; + Application -> Core; Dynamic -> Heaps; Dynamic -> Pools; Heaps -> Core; Pools -> Core; C -> Core; + Core -> RAM } * @enddot * Please also see the article @ref article_manage_memory. diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox index 8bbd74a2d..f3b8e8362 100644 --- a/docs/src/createthread.dox +++ b/docs/src/createthread.dox @@ -147,7 +147,7 @@ int main(int argc, char *argv[]) { } * @endcode * - *

Creating a dynamic thread using the heap allocator

+ *

Creating a dynamic thread using the memory pool allocator

* A pool is a collection of equally sized memory blocks, creating a thread from * a memry pool is very similar to the previous example but the memory of * terminated threads is returned to the memory pool rather than to a heap: diff --git a/docs/src/memory.dox b/docs/src/memory.dox index 1bd39b266..f41dff32f 100644 --- a/docs/src/memory.dox +++ b/docs/src/memory.dox @@ -126,7 +126,7 @@ *
* When designing a system it is recommended to proceed as follow: * -# Use static objects and initializers whenever possible. - * -# Where dynamic allocation is required without have to free the allocated + * -# Where dynamic allocation is required without having to free the allocated * memory then use the Core Memory Manager allocation APIs. * -# Where dynamic allocation is required evaluate if one or more memory * pools can be used. diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox index 170ca75a3..087724084 100644 --- a/docs/src/portguide.dox +++ b/docs/src/portguide.dox @@ -78,7 +78,7 @@ * 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/hal/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 @@ -87,11 +87,11 @@ * 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/hal/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 - * is required if you want to regenerate this documentation including + * is only required if you want to regenerate this documentation including * your work. * . * Usually this kind of port just requires a serial driver (and those are very -- cgit v1.2.3 From 29c73be182b70fd08a44f1fb597a3eac6aff777d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 9 Sep 2010 14:54:43 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2170 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/architecture.dox | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/src') diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox index e5a73239e..d71a43fc8 100644 --- a/docs/src/architecture.dox +++ b/docs/src/architecture.dox @@ -109,7 +109,7 @@ * the kernel if not needed. * - @ref semaphores, counter semaphores subsystem. * - @ref mutexes, mutexes subsystem with support to the priority inheritance - * algorithm (fully implemented, any depht). + * algorithm (fully implemented, any depth). * - @ref condvars, condition variables, together with mutexes the condition * variables allow the implementation of monitor constructs. * - @ref events, event sources and event flags with flexible support for @@ -142,7 +142,7 @@ * by the other allocators in order to get chunks of memory in a consistent * way. * - @ref heaps, central heap manager using a first fit strategy, it also - * allow the creation of multiple heaps in order to handle non uniform + * allows the creation of multiple heaps in order to handle non uniform * memory areas. * - @ref pools, very fast fixed size objects allocator. * - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT @@ -185,7 +185,7 @@ * stream interface. * - @ref io_queues, generic, byte wide, I/O queues APIs. * . - * - @ref debug, debug services and APIs. The @ref registry susystem can be + * - @ref debug, debug services and APIs. The @ref registry subsystem can be * seen as part of the debug category even if it finds use in non-debug * roles. * . -- cgit v1.2.3 From 6c3bddd257cc521db0d5bf5fb9524fdd234e038e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 18 Sep 2010 08:31:12 +0000 Subject: Fixed bug 3069854, fixed documentation article about events. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2180 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/events.dox | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) (limited to 'docs/src') diff --git a/docs/src/events.dox b/docs/src/events.dox index 98ba8d55f..27de187e4 100644 --- a/docs/src/events.dox +++ b/docs/src/events.dox @@ -27,33 +27,34 @@ * explanation.
* Lets start with the events related terminology: * - Event Source, an @p EventSource is a system object that can be - * @a broadcasted asynchronously in response of a system event, as example, - * when the CAN driver receives a packet from the CAN bus it @a broadcasts + * broadcasted asynchronously in response of a system event, as example, + * when the CAN driver receives a packet from the CAN bus it broadcasts * an event source in order to inform the registered threads that a packet * has just arrived. * - Broadcast, the operation performed on an event source in order - * to inform the @a registered threads that an event just occurred. + * to inform the registered threads that an event just occurred. * Broadcasting can happened both in interrupt handlers and in threads. * - Event Listener, a system object that associates a @p Thread object * to an event source. The process of associating a @p Thread to an - * @p EventSource using an @p EventListener is called @a registration. + * @p EventSource using an @p EventListener is called registration. * - Registration, action performed by a thread in order to be informed * of events from a specific event source. Of course a thread can be - * @a registered on more than one event source by using multiple - * @p EventListener objects. Threads can also @a unregister from an event + * registered on more than one event source by using multiple + * @p EventListener objects. Threads can also unregister from an event * source. - * - Pend, each thread has a mask of @a pending events. The @a broadcast - * operation @a pends an event mask on all the @a registered threads. + * - Pending Events, event flags waiting to be served by a thread. + * - Add, the broadcast operation adds (logical or) an events + * mask to all the registered threads. * - Wait, synchronous operation performed by a thread in order to - * @a wait a specific combination of events. The API offers a variety of - * @a wait functions, please refer to the events API documentation. + * wait a specific combination of events. The API offers a variety of + * wait functions, please refer to the events API documentation. * . * Note that events are asynchronously generated, as example in an interrupt * handler, but are synchronously served. * *

Events related data structures

* The following diagram explains the relationship between an event source, - * its list of event listeners and the @a registered threads. + * its list of event listeners and the registered threads. * @dot digraph example { rankdir="LR"; @@ -97,19 +98,19 @@ el4 -> t4 [label="el_listener"]; } * @enddot - * Note that each event listener has a different bit mask to be @a pended on - * its associated thread when the event source is @a broadcasted, this means + * Note that each event listener has a different bit mask to be added on + * its associated thread when the event source is broadcasted, this means * that each thread can define its own event identifiers independently. A - * @a broadcast operation can also @a pend more than one bit on the - * @a registered threads.
- * The threads have a variety of @a wait primitives, they can @a wait for one - * or more event flags to become @a pending, and can also specify AND/OR - * conditions, as example a thread can @a wait for any event to become - * @a pending or @a wait for all the specified events to become @a pending.
+ * broadcast operation can also add more than one bit on the + * registered threads.
+ * The threads have a variety of wait primitives, they can wait for one + * or more event flags, and can also specify AND/OR conditions, as example + * a thread can wait for any of the specified events or wait for all the + * specified events.
* The field @p p_epending is the mask of the currently pending events, * the field @p p_ewmask is the mask of the events the thread is interested * on in that moment (AND or OR condition depending on the invoked - * @a wait API). + * wait API). * *

Use Scenarios

* Events are best used when one of more of the following conditions are -- cgit v1.2.3 From fd9d0b74cacfeb38e223c13de25185ea713cad3d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 18 Sep 2010 10:08:34 +0000 Subject: Improvements to the concepts article. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2181 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 246 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 181 insertions(+), 65 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 9c09041a7..35c086506 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -36,7 +36,7 @@ * @a Mtx, @a Cond, @a Evt, @a Msg, @a SequentialStream, @a IO, @a IQ, @a OQ, * @a Dbg, @a Core, @a Heap, @a Pool. * - * @section api_suffixes API Names Suffixes + * @section api_suffixes API Name Suffixes * The suffix can be one of the following: * - None, APIs without any suffix can be invoked only from the user * code in the Normal state unless differently specified. See @@ -112,58 +112,104 @@ * real associated machine state on some architectures. The following diagram * shows the possible transitions between the states: * + * @if LATEX_PDF * @dot digraph example { - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - init [label="Init", style="bold"]; - norm [label="Normal", shape=doublecircle]; - susp [label="Suspended"]; - disab [label="Disabled"]; - slock [label="S-Locked"]; - ilock [label="I-Locked"]; - slock [label="S-Locked"]; - sleep [label="Sleep"]; - sri [label="SRI"]; - init -> norm [label="chSysInit()"]; - norm -> slock [label="chSysLock()", constraint=false]; - slock -> norm [label="chSysUnlock()"]; - norm -> susp [label="chSysSuspend()"]; - susp -> disab [label="chSysDisable()"]; - norm -> disab [label="chSysDisable()"]; - susp -> norm [label="chSysEnable()"]; - disab -> norm [label="chSysEnable()"]; - slock -> ilock [label="Context Switch", dir="both"]; - norm -> sri [label="Regular IRQ", style="dotted"]; - sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8]; - sri -> ilock [label="chSysLockFromIsr()", constraint=false]; - ilock -> sri [label="chSysUnlockFromIsr()", fontsize=8]; - norm -> sleep [label="Idle Thread"]; - sleep -> sri [label="Regular IRQ", style="dotted"]; + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + init [label="Init", style="bold"]; + norm [label="Normal", shape=doublecircle]; + susp [label="Suspended"]; + disab [label="Disabled"]; + slock [label="S-Locked"]; + ilock [label="I-Locked"]; + slock [label="S-Locked"]; + sleep [label="Sleep"]; + sri [label="SRI"]; + init -> norm [label="chSysInit()"]; + norm -> slock [label="chSysLock()", constraint=false]; + slock -> norm [label="chSysUnlock()"]; + norm -> susp [label="chSysSuspend()"]; + susp -> disab [label="chSysDisable()"]; + norm -> disab [label="chSysDisable()"]; + susp -> norm [label="chSysEnable()"]; + disab -> norm [label="chSysEnable()"]; + disab -> susp [label="chSysSuspend()"]; + slock -> ilock [label="Context Switch", dir="both"]; + norm -> sri [label="Regular IRQ", style="dotted"]; + sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8]; + sri -> ilock [label="chSysLockFromIsr()", constraint=false]; + ilock -> sri [label="chSysUnlockFromIsr()", fontsize=8]; + norm -> sleep [label="Idle Thread"]; + sleep -> sri [label="Regular IRQ", style="dotted"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + init [label="Init", style="bold"]; + norm [label="Normal", shape=doublecircle]; + susp [label="Suspended"]; + disab [label="Disabled"]; + slock [label="S-Locked"]; + ilock [label="I-Locked"]; + slock [label="S-Locked"]; + sleep [label="Sleep"]; + sri [label="SRI"]; + init -> norm [label="chSysInit()"]; + norm -> slock [label="chSysLock()", constraint=false]; + slock -> norm [label="chSysUnlock()"]; + norm -> susp [label="chSysSuspend()"]; + susp -> disab [label="chSysDisable()"]; + norm -> disab [label="chSysDisable()"]; + susp -> norm [label="chSysEnable()"]; + disab -> norm [label="chSysEnable()"]; + disab -> susp [label="chSysSuspend()"]; + slock -> ilock [label="Context Switch", dir="both"]; + norm -> sri [label="Regular IRQ", style="dotted"]; + sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8]; + sri -> ilock [label="chSysLockFromIsr()", constraint=false]; + ilock -> sri [label="chSysUnlockFromIsr()", fontsize=8]; + norm -> sleep [label="Idle Thread"]; + sleep -> sri [label="Regular IRQ", style="dotted"]; } * @enddot + * @endif * Note, the SFI, Halted and SNMI states were not shown * because those are reachable from most states: * * @dot digraph example { - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - any1 [label="Any State\nexcept *"]; - any2 [label="Any State"]; - sfi [label="SFI"]; - halt [label="Halted"]; - SNMI [label="SNMI"]; - any1 -> sfi [style="dotted", label="Fast IRQ"]; - sfi -> any1 [label="Fast IRQ return"]; - any2 -> halt [label="chSysHalt()"]; - any2 -> SNMI [label="Synchronous NMI"]; - any2 -> SNMI [label="Asynchronous NMI", style="dotted"]; - SNMI -> any2 [label="NMI return"]; - halt -> SNMI [label="Asynchronous NMI", style="dotted"]; - SNMI -> halt [label="NMI return"]; + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + any1 [label="Any State\nexcept *"]; + sfi [label="SFI"]; + any1 -> sfi [style="dotted", label="Fast IRQ"]; + sfi -> any1 [label="Fast IRQ return"]; + } + * @enddot + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + any2 [label="Any State"]; + halt [label="Halted"]; + SNMI [label="SNMI"]; + any2 -> halt [label="chSysHalt()"]; + any2 -> SNMI [label="Synchronous NMI"]; + any2 -> SNMI [label="Asynchronous NMI", style="dotted"]; + SNMI -> any2 [label="NMI return"]; + halt -> SNMI [label="Asynchronous NMI", style="dotted"]; + SNMI -> halt [label="NMI return"]; } * @enddot * @attention * except: Init, Halt, SNMI, Disabled. @@ -174,8 +220,10 @@ * 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.

+ * @if LATEX_PDF * @dot digraph example { + size="5, 7"; rankdir="LR"; node [shape=square, fontname=Helvetica, fontsize=8, @@ -209,35 +257,99 @@ rh -> T3 -> Tm -> T2 -> T1 -> Ti -> rh [label="p_prev"]; } * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + edge [fontname=Helvetica, fontsize=8]; + + subgraph cluster_running { + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + currp [label="'currp'\npointer", style="bold"]; + T4 [label="Tuser(4)\nprio=100"]; + label = "Currently Running Thread"; + penwidth = 0; + } + + subgraph cluster_rlist { + node [shape=square, fontname=Helvetica, fontsize=8, + fixedsize="true", width="0.6", height="0.5"]; + rh [label="ready list\nheader\nprio=0", style="bold"]; + Ti [label="Tidle\nprio=1"]; + Tm [label="Tmain\nprio=64"]; + T1 [label="Tuser(1)\nprio=32"]; + T2 [label="Tuser(2)\nprio=32"]; + T3 [label="Tuser(3)\nprio=80"]; + label = "Threads Ready for Execution"; + penwidth = 0; + } + + currp -> T4 + rh -> Ti -> T1 -> T2 -> Tm -> T3 -> rh [label="p_next"]; + rh -> T3 -> Tm -> T2 -> T1 -> Ti -> rh [label="p_prev"]; + } + * @enddot + * @endif *
* 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 thread_states Threads States + * @section thread_states Thread States * The image shows how threads can change their state in ChibiOS/RT.
+ * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + start [label="Start", style="bold"]; + run [label="Running"]; + ready [label="Ready"]; + suspend [label="Suspended"]; + sleep [label="Sleeping"]; + stop [label="Stop", style="bold"]; + start -> suspend [label="chThdInit()", constraint=false]; + start -> run [label="chThdCreate()"]; + start -> ready [label="chThdCreate()"]; + run -> ready [label="Reschedule", dir="both"]; + suspend -> run [label="chThdResume()"]; + suspend -> ready [label="chThdResume()"]; + run -> sleep [label="chSchGoSleepS()"]; + sleep -> run [label="chSchWakepuS()"]; + sleep -> ready [label="chSchWakepuS()"]; + run -> stop [label="chThdExit()"]; + } + * @enddot + * @else * @dot digraph example { - /*rankdir="LR";*/ - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - start [label="Start", style="bold"]; - run [label="Running"]; - ready [label="Ready"]; - suspend [label="Suspended"]; - sleep [label="Sleeping"]; - stop [label="Stop", style="bold"]; - start -> suspend [label="chThdInit()", constraint=false]; - start -> run [label="chThdCreate()"]; - start -> ready [label="chThdCreate()"]; - run -> ready [label="Reschedule", dir="both"]; - suspend -> run [label="chThdResume()"]; - suspend -> ready [label="chThdResume()"]; - run -> sleep [label="chSchGoSleepS()"]; - sleep -> run [label="chSchWakepS()"]; - sleep -> ready [label="chSchWakepS()"]; - run -> stop [label="chThdExit()"]; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; + start [label="Start", style="bold"]; + run [label="Running"]; + ready [label="Ready"]; + suspend [label="Suspended"]; + sleep [label="Sleeping"]; + stop [label="Stop", style="bold"]; + start -> suspend [label="chThdInit()", constraint=false]; + start -> run [label="chThdCreate()"]; + start -> ready [label="chThdCreate()"]; + run -> ready [label="Reschedule", dir="both"]; + suspend -> run [label="chThdResume()"]; + suspend -> ready [label="chThdResume()"]; + run -> sleep [label="chSchGoSleepS()"]; + sleep -> run [label="chSchWakepuS()"]; + sleep -> ready [label="chSchWakepuS()"]; + run -> stop [label="chThdExit()"]; } * @enddot + * @endif * * @section priority Priority Levels * Priorities in ChibiOS/RT are a contiguous numerical range but the initial @@ -261,13 +373,17 @@ * (inclusive) are reserved. This is the highest numerical value of the * priorities space. * . - * @section warea Threads Working Area + * @section warea Thread Working Area * Each thread has its own stack, a Thread structure and some preemption * areas. All the structures are allocated into a "Thread Working Area", * a thread private heap, usually statically declared in your code. * Threads do not use any memory outside the allocated working area * except when accessing static shared data.

+ * @if LATEX_PDF + * @image latex workspace.eps + * @else * @image html workspace.png + * @endif *
* Note that the preemption area is only present when the thread is not * running (switched out), the context switching is done by pushing the -- cgit v1.2.3 From a6856d757a7960e9c50cb2cdce3e31ace9671541 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 3 Oct 2010 13:20:13 +0000 Subject: Removed redundant articles in the generated documentation. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2232 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/architecture.dox | 274 ------------------------------------------ docs/src/articles.dox | 66 ---------- docs/src/atomic.dox | 57 --------- docs/src/concepts.dox | 12 +- docs/src/createthread.dox | 187 ---------------------------- docs/src/credits.dox | 97 --------------- docs/src/debug.dox | 138 --------------------- docs/src/design.dox | 110 ----------------- docs/src/eclipse.dox | 169 -------------------------- docs/src/eclipse2.dox | 249 -------------------------------------- docs/src/events.dox | 124 ------------------- docs/src/goals.dox | 88 -------------- docs/src/integrationguide.dox | 95 --------------- docs/src/interrupts.dox | 69 ----------- docs/src/jitter.dox | 135 --------------------- docs/src/licfaq.dox | 119 ------------------ docs/src/lifecycle.dox | 68 ----------- docs/src/main.dox | 6 - docs/src/memory.dox | 138 --------------------- docs/src/mutualexcl.dox | 210 -------------------------------- docs/src/portguide.dox | 120 ------------------ docs/src/roundrobin.dox | 50 -------- docs/src/saveram.dox | 81 ------------- docs/src/stacks.dox | 107 ----------------- docs/src/stop_os.dox | 133 -------------------- docs/src/target.dox | 82 ------------- docs/src/timing.dox | 91 -------------- docs/src/wakeup.dox | 148 ----------------------- 28 files changed, 8 insertions(+), 3215 deletions(-) delete mode 100644 docs/src/architecture.dox delete mode 100644 docs/src/articles.dox delete mode 100644 docs/src/atomic.dox delete mode 100644 docs/src/createthread.dox delete mode 100644 docs/src/credits.dox delete mode 100644 docs/src/debug.dox delete mode 100644 docs/src/design.dox delete mode 100644 docs/src/eclipse.dox delete mode 100644 docs/src/eclipse2.dox delete mode 100644 docs/src/events.dox delete mode 100644 docs/src/goals.dox delete mode 100644 docs/src/integrationguide.dox delete mode 100644 docs/src/interrupts.dox delete mode 100644 docs/src/jitter.dox delete mode 100644 docs/src/licfaq.dox delete mode 100644 docs/src/lifecycle.dox delete mode 100644 docs/src/memory.dox delete mode 100644 docs/src/mutualexcl.dox delete mode 100644 docs/src/portguide.dox delete mode 100644 docs/src/roundrobin.dox delete mode 100644 docs/src/saveram.dox delete mode 100644 docs/src/stacks.dox delete mode 100644 docs/src/stop_os.dox delete mode 100644 docs/src/target.dox delete mode 100644 docs/src/timing.dox delete mode 100644 docs/src/wakeup.dox (limited to 'docs/src') diff --git a/docs/src/architecture.dox b/docs/src/architecture.dox deleted file mode 100644 index d71a43fc8..000000000 --- a/docs/src/architecture.dox +++ /dev/null @@ -1,274 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page architecture Architecture - * @brief ChibiOS/RT General Architecture - * - @ref components - * - @ref dependencies - * - @ref kernel_arch - * - @ref hal_arch - * . - * @section components Components - * ChibiOS/RT is composed of several major components, each component can be - * composed of one of more subsystems. The main components are: - * - Kernel, this is the platform independent part of the OS kernel. - * - HAL, this component contains a set of abstract device drivers - * that offer a common I/O API to the application across all the support - * platforms. The HAL code is totally portable across platforms. - * - Port, this is the platform dependent part of the OS kernel. This - * component is responsible of the system startup, interrupts abstraction, - * lock/unlock primitives, context switch related structures and code.
- * The component usually contains very little code because the OS is very - * portable but the quality of the implementation of the Port component - * affects heavily the performance of the ported OS. It is probably the - * most critical part of the whole OS. - * - Platform, this component contains a set of device drivers - * implementations. - * - Various, a library of various extra components that do not belong - * to any particular component but can make life easier while developing an - * embedded application. - * . - * @section dependencies Dependencies - * The following diagram shows the relationships among the various components - * that compose the system:

- * @dot - digraph example { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.25"]; - edge [fontname=Helvetica, fontsize=8]; - - Application [label="Application"]; - HAL [label="HAL"]; - Platform [label="Platform"]; - Kernel [label="Kernel"]; - Port [label="Port"]; - Board [label="Board Setup"]; - HW [label="Hardware", style="filled", width="3.0", height="0.3"]; - - Application -> Kernel; - Application -> HAL; - Application -> HW [label=" (not recommended)"]; - HAL -> Platform; - HAL -> Kernel; - Board -> HW; - Platform -> Kernel; - Platform -> Board; - Platform -> HW; - Kernel -> Port; - Port -> Board [label="Optional", style="dotted"]; - Port -> HW; - } - * @enddot - * - * @section kernel_arch Kernel Architecture - * The kernel itself is very modular and is composed of several subsystems, - * most subsystems are optional and can be switched of in the kernel - * configuration file @p chconf.h.
- * The current kernel subsystems are divided in five categories: - * - @ref base, this category contains the mandatory kernel - * subsystems: - * - @ref system, low level locks, initialization. - * - @ref time, virtual timers and time APIs. - * - @ref scheduler, scheduler APIs, all the higher level synchronization - * mechanism are implemented through this subsystem, it is very flexible - * but not recommended for direct use in user code. - * - @ref threads, thread-related APIs. - * . - * Base services diagram:

- * @dot - digraph example { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.25"]; - edge [fontname=Helvetica, fontsize=8]; - - Threads -> Scheduler; - Scheduler-> System; - Scheduler-> Timers; - System-> Timers; - } - * @enddot - * - @ref synchronization, this category contains the synchronization-related - * subsystems, each one of the provided mechanism can be configured out of - * the kernel if not needed. - * - @ref semaphores, counter semaphores subsystem. - * - @ref mutexes, mutexes subsystem with support to the priority inheritance - * algorithm (fully implemented, any depth). - * - @ref condvars, condition variables, together with mutexes the condition - * variables allow the implementation of monitor constructs. - * - @ref events, event sources and event flags with flexible support for - * and/or conditions and automatic dispatching to handler functions. - * - @ref messages, lightweight synchronous messages. - * - @ref mailboxes, asynchronous messages queues. - * . - * All the synchronization mechanisms are built on top of the Scheduler APIs - * except Mailboxes that are build on top of Semaphores and Condition - * Variables that implicitly refer to Mutexes:

- * @dot - digraph example { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.1", height="0.25"]; - edge [fontname=Helvetica, fontsize=8]; - - Semaphores -> Scheduler; - Mutexes -> Scheduler; - Condvars -> Scheduler; - Condvars -> Mutexes; - Events -> Scheduler; - Messages -> Scheduler; - "Binary Semaphores" -> Semaphores; - Mailboxes -> Semaphores; - } - * @enddot - * - @ref memory, memory management, multiple non-alternative schemes are - * available: - * - @ref memcore, centralized core memory manager, this subsystems is used - * by the other allocators in order to get chunks of memory in a consistent - * way. - * - @ref heaps, central heap manager using a first fit strategy, it also - * allows the creation of multiple heaps in order to handle non uniform - * memory areas. - * - @ref pools, very fast fixed size objects allocator. - * - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT - * but there is the option for dynamic threads management, please see the - * article @ref article_lifecycle. - * . - * The various allocators follow a precise hierarchy:

- * @dot - digraph example { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.25"]; - edge [fontname=Helvetica, fontsize=8]; - - Application [label="Application", width="2.0"]; - RAM [label="RAM", style="filled", width="2.0"]; - Core [label="Core Allocator"]; - Dynamic [label="Dynamic Threads"]; - Heaps [label="Dynamic Heaps"]; - Pools [label="Memory Pools"]; - C [label="C-runtime"]; - - Application -> Dynamic; - Application -> Heaps; - Application -> Pools; - Application -> C [label="(not recommended)"]; - Application -> Core; - Dynamic -> Heaps; - Dynamic -> Pools; - Heaps -> Core; - Pools -> Core; - C -> Core; - Core -> RAM - } - * @enddot - * Please also see the article @ref article_manage_memory. - * - @ref io_support, the kernel also provides mechanisms and abstract data - * interfaces that can be used by non-kernel components, the HAL as example. - * - @ref data_streams, abstract streams interface. - * - @ref io_channels, abstract I/O channels that inherits from the abstract - * stream interface. - * - @ref io_queues, generic, byte wide, I/O queues APIs. - * . - * - @ref debug, debug services and APIs. The @ref registry subsystem can be - * seen as part of the debug category even if it finds use in non-debug - * roles. - * . - * @section hal_arch HAL Architecture - * The HAL is a collection of abstract device drivers, it relies on the - * Platform component for the low level implementation on specific - * hardware.
- * The current internal HAL organization is the following:

- * @dot - digraph example { - rankdir="LR"; - - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.25"]; - edge [fontname=Helvetica, fontsize=8]; - - subgraph cluster_HAL { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="0.6", height="0.25"]; - ADC [label="ADC"]; - CAN [label="CAN"]; - HAL [label="HAL"]; - MAC [label="MAC"]; - PAL [label="PAL"]; - PWM [label="PWM"]; - SER [label="SER"]; - SPI [label="SPI"]; - MMC_SD [label="MMC/SD"]; - color = blue; - label = "HAL"; - } - - subgraph cluster_Platform { - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="0.6", height="0.25"]; - ADC_LLD [label="ADC_LLD"]; - CAN_LLD [label="CAN_LLD"]; - HAL_LLD [label="HAL_LLD"]; - MAC_LLD [label="MAC_LLD"]; - PAL_LLD [label="PAL_LLD"]; - PWM_LLD [label="PWM_LLD"]; - SER_LLD [label="SER_LLD"]; - SPI_LLD [label="SPI_LLD"]; - color = blue; - label = "Platform"; - } - - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1", height="0.5"]; - edge [fontname=Helvetica, fontsize=8]; - - Application [label="Application"]; - HW [label="Hardware", style="filled"]; - - ADC -> ADC_LLD; - CAN -> CAN_LLD; - HAL -> HAL_LLD; - MAC -> MAC_LLD; - PAL -> PAL_LLD; - PWM -> PWM_LLD; - SER -> SER_LLD; - SPI -> SPI_LLD; - MMC_SD -> SPI [constraint=false]; - - Application -> ADC; - Application -> CAN; - Application -> HAL; - Application -> MAC; - Application -> PAL; - Application -> PWM; - Application -> SER; - Application -> SPI; - Application -> MMC_SD; - ADC_LLD -> HW; - CAN_LLD -> HW; - HAL_LLD -> HW; - MAC_LLD -> HW; - PAL_LLD -> HW; - PWM_LLD -> HW; - SER_LLD -> HW; - SPI_LLD -> HW; - } - * @enddot - *
- * See @ref IO for details about the various HAL subsystems. - */ diff --git a/docs/src/articles.dox b/docs/src/articles.dox deleted file mode 100644 index c34e34d43..000000000 --- a/docs/src/articles.dox +++ /dev/null @@ -1,66 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page articles Articles and Code Samples - * ChibiOS/RT Articles and Code Samples: - * - @subpage page_general - * - @subpage page_kb - * - @subpage page_howtos - * . - */ - -/** - * @page page_general General - * Articles and guides not necessarily related to ChibiOS/RT. - * - @subpage article_eclipse - * - @subpage article_eclipse2 - * - @subpage article_jitter - * . - */ - -/** - * @page page_kb Knowledge Base - * Articles and guides about ChibiOS/RT. - * - @subpage article_integrationguide - * - @subpage article_portguide - * - @subpage article_events - * - @subpage article_debug - * - @subpage article_stacks - * - @subpage article_roundrobin - * - @subpage article_lifecycle - * - @subpage article_mutual_exclusion - * - @subpage article_atomic - * - @subpage article_saveram - * - @subpage article_timing - * - @subpage article_design - * . - */ - -/** - * @page page_howtos How To's - * Articles describing how to implement specific tasks using ChibiOS/RT. - * - @subpage article_create_thread - * - @subpage article_interrupts - * - @subpage article_wakeup - * - @subpage article_manage_memory - * - @subpage article_stop_os - * . - */ - diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox deleted file mode 100644 index d3bc43ba5..000000000 --- a/docs/src/atomic.dox +++ /dev/null @@ -1,57 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_atomic Invoking multiple primitives as a single atomic operation - * It is often necessary to invoke multiple operations involving a - * reschedule as a single atomic operation.
- * ChibiOS/RT already implements APIs that perform complex operations, as - * example the API @p chSemSignalWait() performs two operations atomically.
- * If more complex operations are required in your application then it is - * possible to build macro-operations, see the following example: - * @code - chSysLock(); - - chSemSignalI(&sem1); - chSemSignalI(&sem2); - chMtxUnlockS(); - chSchRescheduleS(); - - chSysUnlock(); - * @endcode - * The above example performs a signal operation on two semaphores, unlocks the - * last acquired mutex and finally performs a reschedule. All the operations - * are performed atomically.
- * An hypothetical @p chSemSignalSignalWait() operation could be implemented as - * follow: - * @code - chSysLock(); - - chSemSignalI(&sem1); - chSemSignalI(&sem2); - chSemWaitS(&Sem3); /* May reschedule or not. */ - chSchRescheduleS(); /* This one reschedules if necessary. */ - - chSysUnlock(); - * @endcode - * In general multiple @ref I-Class and (non rescheduling) @ref S-Class APIs - * can be included and the block is terminated by a rescheduling @ref S-Class - * API. An extra @p chSchRescheduleS() can be present at the very end of the - * block, it only reschedules if a reschedule is still required. - */ diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 35c086506..bcb6a5b97 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -54,11 +54,15 @@ * preempt (small parts of) the kernel code and are thus able to invoke * operating system APIs from within their handlers. The interrupt handlers * belonging to this class must be written following some rules. See the - * @ref system APIs group and @ref article_interrupts. + * @ref system APIs group and the web article + * + * How to write interrupt handlers. * - Fast Interrupts. Maskable interrupt sources with the ability * to preempt the kernel code and thus have a lower latency and are less - * subject to jitter, see @ref article_jitter. Such sources are not - * supported on all the architectures.
+ * subject to jitter, see the web article + * + * Response Time and Jitter. + * Such sources are not supported on all the architectures.
* Fast interrupts are not allowed to invoke any operating system API from * within their handlers. Fast interrupt sources may, however, pend a lower * priority regular interrupt where access to the operating system is @@ -394,6 +398,6 @@ * - Interrupt Stack. * - Internal Context. * . - * See the @ref core documentation for details, the area may change on + * See the port documentation for details, the area may change on * the various ports and some structures may not be present (or be zero-sized). */ diff --git a/docs/src/createthread.dox b/docs/src/createthread.dox deleted file mode 100644 index f3b8e8362..000000000 --- a/docs/src/createthread.dox +++ /dev/null @@ -1,187 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_create_thread How to create a thread - * At the system startup there are already two active threads: - * - Idle thread. This thread has the lowest priority in the system so - * it runs only when the other threads in the system are sleeping. This - * threads usually switches the system in a low power mode and does nothing - * else. - * - Main thread. This thread executes your @p main() function at - * startup. The main thread is created at the @p NORMALPRIO level but it - * can change its own priority if required. It is from the main thread - * that the other threads are usually created. - * . - * There are two kind of threads in ChibiOS/RT: - * - Static Threads. This kind of threads are statically allocated in - * memory. The memory used by the thread cannot reused except for restarting - * the threads. - * - Dynamic Threads. Threads created by allocating memory from a memory - * heap or a memory pool. - * . - *

Creating a static thread

- * In order to create a static thread a working area must be declared using - * the macro @p WORKING_AREA as shown: - * @code -static WORKING_AREA(myThreadWorkingArea, 128); - * @endcode - * This macro reserves 128 bytes of stack for the thread and space for all - * the required thread related structures. The total size and the alignment - * problems are handled inside the macro, you only need to specify the pure - * stack size.
- * A thread can be started by invoking @p chThdCreateStatic() as shown in this - * example: - * @code - Thread *tp = chThdCreateStatic(myThreadWorkingArea, - sizeof(myThreadWorkingArea), - NORMALPRIO, /* Initial priority. */ - myThread, /* Thread function. */ - NULL); /* Thread parameter. */ - * @endcode - * The variable tp receives the pointer to the thread object, it is taken - * by other APIs as parameter.
- * Now a complete example: - * @code -/* -* * My simple application. - */ - -#include - -/* -* * Working area for the LED flashing thread. - */ -static WORKING_AREA(myThreadWorkingArea, 128); - -/* -* * LED flashing thread. - */ -static msg_t myThread(void *arg) { - - while (TRUE) { - LED_ON(); - chThdSleepMilliseconds(500); - LED_OFF(); - chThdSleepMilliseconds(500); - } -} - -int main(int argc, char *argv[]) { - - /* Starting the flashing LEDs thread.*/ - (void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea), - NORMALPRIO, myThread, NULL); - . - . - . -} - * @endcode - * 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. */ - 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 - * thread final status (its return value) is collected by the spawning thread. - * As example: - * @code -static msg_t myThread(void *arg) { - - unsigned i = 10; - while (i > 0) { - LED_ON(); - chThdSleepMilliseconds(500); - LED_OFF(); - chThdSleepMilliseconds(500); - i--; - } - return (msg_t)i; -} - -int main(int argc, char *argv[]) { - - Thread *tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(128), NORMALPRIO+1, - myThread, NULL); - if (tp == NULL) - chSysHalt(); /* Memory exausted. */ - - /* The main thread continues its normal execution.*/ - . - . - /* -* * Now waits for the spawned thread to terminate (if it has not terminated -* * already) then gets the thread exit message (msg) and returns the -* * terminated thread memory to the heap (default system heap in this -* * example). - */ - msg_t msg = chThdWait(tp); - . - . -} - * @endcode - * - *

Creating a dynamic thread using the memory pool allocator

- * A pool is a collection of equally sized memory blocks, creating a thread from - * a memry pool is very similar to the previous example but the memory of - * terminated threads is returned to the memory pool rather than to a heap: - * @code -static msg_t myThread(void *arg) { - - unsigned i = 10; - while (i > 0) { - LED_ON(); - chThdSleepMilliseconds(500); - LED_OFF(); - chThdSleepMilliseconds(500); - i--; - } - return (msg_t)i; -} - -int main(int argc, char *argv[]) { - - Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL); - if (tp == NULL) - chSysHalt(); /* Pool empty. */ - - /* The main thread continues its normal execution.*/ - . - . - /* -* * Now waits for the spawned thread to terminate (if it has not terminated -* * already) then gets the thread exit message (msg) and returns the -* * terminated thread memory to the original memory pool. - */ - msg_t msg = chThdWait(tp); - . - . -} - * @endcode - */ diff --git a/docs/src/credits.dox b/docs/src/credits.dox deleted file mode 100644 index d0a40cb04..000000000 --- a/docs/src/credits.dox +++ /dev/null @@ -1,97 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page credits Copyright and Credits - * @brief Copyright and Credits - * - *

Copyright Statement

-@verbatim - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. -@endverbatim - * - *

Contributions and Copyright Assignment

- * If you plan to contribute code to the ChibiOS/RT project then there is a - * requirement you should be aware of: contributing code for inclusion in - * the ChibiOS/RT main line requires assigning the copyright on the - * contributed code to me (Giovanni Di Sirio).
- * This may sound a bit strange but is pretty standard for this kind of - * projects, there are several reasons for this requirement: - * - ChibiOS/RT will probably also become a commercial product and it would - * not be possible to re-license the code without ownership. Note that the - * commercial product would not be a different or better product, just the - * same GPL product made available, on request, under a different license. - * The code will always be available to you under the current licensing - * terms. - * - Ownership is required when changing the licensing terms and this happens - * each time the project goes from development/unstable to stable and - * back because the addition/removal of the GPL linking exception. - * - It will be easier for the project adopters to have a single ownership - * point in case of licensing issues (both GPL or commercial). - * - Losing the ownership on the code could preclude me the opportunity to - * make this project a full time job as I hope. - * - I definitely don't want to have to sort out copyright related issues - * in the future so better be clear than sorry. - * . - * Note that contributions will always be welcome even without such copyright - * assignment, the difference is that the contributed code would not be - * merged into the main line, it will still made available as contributed - * code with the contributor(s) copyright notice intact.
- * Submissions of code with copyright notice should only happen through - * email, please do not commit code with copyright notices directly on - * the repository.
- * When submitting code please state clearly your intention to keep the - * copyright on your work by adding your own copyright notice within the - * source code and by clearly mentioning your intentions in the message. Code - * contributed without copyright notice will be considered donated.
- * If in doubt with licensing issues please don't hesitate to contact me - * in order to sort out any problem you may have.
- * Of course the copyright assignment does not mean you would not be - * recognized for your hard work, see the following section. - * - *

Credits

- * I want to thank all the people that directly or indirectly contributed - * to the project, I beg pardon if someone is missing: - * - Adamo Reggiani, working on the Fujitsu port. - * - Alexander Kozaruk, AT91SAM7S256 demo and description files for - * the Olimex SAM7-P256 board. - * - Brian Weaver, STM8 port, STM8 and STM32 testing and improvements. - * - Egon Carusi, STM32 port improvements, testing and bug fixes. - * - Enrico Cavazza, working on the Fujitsu port and a GUI subsystem. - * - Eric Weddington, because his work on WinAVR and helping me sorting - * out issues with the ChibiOS/RT license. - * - Isidoro Orabona, co-developer of the ChibiOS/RT grandfather back - * in 1988, it is a long long story involving a 6502 and a Z80... - * - Jacek, Ride7 demo for STM32 Primer. - * - Leon Woestenberg, CondVars idea and implementation, documentation - * improvements and a lot of other ideas, he also helped with the lwIP port - * (he is one of the developers of that project too). - * - Leszek Bednarz, H8S and ColdFire ports and drivers maintainer. - * - Liam Staskawicz, Posix simulator, AT91SAM7x and STM32 related - * contributions, general improvements, many bug fixes and excellent - * suggestions. - * - Michael Fischer, because the work on YAGARTO and the excellent - * feedback. - * - Riccardo Scanu, another long story, this time involving reverse - * engineering and giant robots... - * - Vladimir, first tested and fixed the AVR port, I don't know the - * surname but he has been the first contributor. - * - Walter Goossens, several fixes to the LPC21xx support. - * . - */ diff --git a/docs/src/debug.dox b/docs/src/debug.dox deleted file mode 100644 index 341e852c6..000000000 --- a/docs/src/debug.dox +++ /dev/null @@ -1,138 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_debug Debugging ChibiOS/RT applications - * ChibiOS/RT offers several mechanisms that can help in the debug phase of - * the development cycle. - * - *

What this guide does not cover

- * This guide assumes knowledge in following areas: - * - General knowledge of embedded development. - * - RTOS concepts. - * - Setup of your specific target hardware and toolchain. - * - Knowledge of your toolchain. The guide will explain what you need to do, - * not how it is done using you specific debugger, compiler, JTAG probe and - * target hardware. - * . - *

Helpful debugging configuration settings

- * There are several settings in your kernel configuration file - * (see @ref templates/chconf.h) that you may want to enable during - * debugging and in general during the whole development process. - * - @p CH_OPTIMIZE_SPEED=FALSE, this disables inlining into the kernel code - * and makes it easier to debug using your debugger, you may also want - * to reduce or disable compiler optimizations (-O0 using GCC). - * - @p CH_DBG_ENABLE_CHECKS=TRUE, this setting enables the checks on the - * API parameters, useful to understand if you are passing wrong parameters - * to the OS functions. - * - @p CH_DBG_ENABLE_ASSERTS=TRUE, this setting enables the OS internal - * consistency checks, this can trap several kind of errors in the user - * code (or in the kernel itself). - * - @p CH_DBG_ENABLE_STACK_CHECK=TRUE, this setting enables checks on - * threads stack overflow. Note that this option is not available in - * all ports, check your port documentation. If not supported then it - * is silently ignored, see also the article @ref article_stacks. - * - @p CH_DBG_FILL_THREADS=TRUE, this setting enables the threads workspace - * filling, this can help examining the stack usage from your debugger. - * . - * Note that all the failed checks lock the kernel into the @p port_halt() - * function. In order to assess what triggered the lock the global variable - * @p panic_msg must be inspected using the debugger, the variable is a - * pointer to an error message (a zero terminated string), the pointer may - * contain @p NULL if the lock was triggered by a stack overflow. - * - *

Common errors and symptoms

- * There are some common errors while using an RTOS, use the following - * table as a check list, if your problem is not a generic programming error - * then probably it is one of the following common RTOS/embedded related - * mistakes: - * - Insufficient stack allocated to one or more threads.
- * Common symptoms: - * - Target instability. - * - Target locked into the @p port_halt() function. - * - Target trapped into an exception handler (architecture dependent). - * - Target apparent self reset (not real resets usually). - * . - * - Insufficient stack allocated to the IRQ stack (in those architectures - * that have a separate IRQ stack, ARM as example).
- * Common symptoms: - * - Target instability. - * - Target trapped into an exception handler (architecture dependent). - * - Target apparent self reset (not real resets usually). - * . - * - Use of a non reentrant function from within an interrupt handler, as - * example most C runtime functions.
- * Common symptoms: - * - Target instability. - * - Unexpected application behavior. - * . - * - Missing use of a mutual exclusion mechanism to protect data - * (or non reentrant code) shared among multiple threads and/or - * threads and interrupt handlers, see also the article - * @ref article_mutual_exclusion.
- * Common symptoms: - * - Target instability. - * - Unexpected application behavior. - * . - * - Use of S-class or I-class APIs outside a proper lock state, see the - * @ref concepts article, specifically the @ref api_suffixes and - * @ref system_states sections.
- * Common symptoms: - * - Target instability. - * - Target trapped into an exception handler (architecture dependent). - * - Target apparent self reset (not real resets usually). - * . - * - Use of a non I-class API from an interrupt handler, see the - * @ref concepts article, specifically the @ref api_suffixes and - * @ref system_states sections.
- * Common symptoms: - * - Target instability. - * - Target trapped into an exception handler (architecture dependent). - * - Target apparent self reset (not real resets usually). - * . - * - Wrong threads priority assignment. One of the most critical things - * to do when designing an RTOS based application is to assign correct - * priorities to the threads in the system.
- * Common symptoms: - * - Excessive or unpredictable response times. - * - Threads that appear to be never executed (CPU intensive threads at - * higher priority). - * . - * . - *

General suggestions

- * For the less expert users, there are several things you may do in order - * to minimize the need for debugging: - * - Read carefully the documentation first. - * - Try to find a code examples for things are you going to do, good sources - * are: the documentation, the test code, under "./test" you will - * find examples for almost any API in the ChibiOS/RT kernel and most - * 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 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 - * spawned from questions in the forum or in the tracker). - * - Never give up :-) - * . - */ diff --git a/docs/src/design.dox b/docs/src/design.dox deleted file mode 100644 index 80a5b8af8..000000000 --- a/docs/src/design.dox +++ /dev/null @@ -1,110 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_design Designing an embedded application - * ChibiOS/RT offers a variety of mechanisms and primitives, often it is - * better to focus on a single approach for the system design and use only - * part of the available subsystems.
- * When designing your application you may choose among several design - * alternatives: - * - @ref nothreads - * - @ref messpass - * - @ref thdshared - * - @ref thdmixed - * . - * @section nothreads Single threaded superloop - * Correct, single thread, it is not mandatory to use the multithreading - * features of the OS. You may choose to implements everything as a complex - * state machine handled in the main thread alone. In this scenario the OS - * still offers a variety of useful mechanisms: - * - Interrupt handling. - * - Virtual Timers, very useful in state machines in order to handle time - * triggered state transitions. - * - Power management. - * - Event Flags and/or Semaphores as communication mechanism between - * interrupt handlers and the main. - * - I/O queues. - * - Memory allocation. - * - System time. - * . - * In this configuration the kernel size is really minimal, everything else - * is disabled and takes no space. You always have the option to use more - * threads at a later time in order to perform separate tasks. - * - * @section messpass Message Passing - * In this scenario there are multiple threads in the system that never - * share data, everything is done by exchanging messages. Each thread - * represents a service, the other threads can request the service by sending - * a message.
- * In this scenario the following subsystems can be used: - * - Synchronous Messages. - * - Mailboxes (asynchronous message queues). - * . - * The advantage of this approach is to not have to deal with mutual exclusion, - * each functionality is encapsulated into a server thread that sequentially - * serves all the requests. As example, you can have the following scenario: - * - A buffers allocator server. - * - A disk driver server. - * - A file system server. - * - One or more client threads. - * . - * Example: - *

- * @dot - digraph example { - rankdir="RL"; - node [shape=rectangle, fontname=Helvetica, fontsize=8, fixedsize="true", - width="1.2", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - disk [label="Server Thread\nDisk Driver"]; - buf [label="Server Thread\nBuffers Allocator"]; - fs [label="Client&Server Thread\nFile System"]; - cl1 [label="Client Thread"]; - cl2 [label="Client Thread"]; - cl3 [label="Client Thread"]; - fs -> disk [label="I/O request", constraint=false]; - disk -> fs [label="status", style="dotted", constraint=false]; - fs -> buf [label="buffer request"]; - buf -> fs [label="buffer", style="dotted"]; - cl1 -> fs [label="FS transaction"]; - fs -> cl1 [label="result", style="dotted"]; - cl2 -> fs [label="FS transaction"]; - fs -> cl2 [label="result", style="dotted"]; - cl3 -> fs [label="FS transaction"]; - fs -> cl3 [label="result", style="dotted"]; - } - * @enddot - *

- * Note that the threads should not exchange complex messages but just - * pointers to data structures in order to optimize the performance. - * Also note that a thread can be both client and server at the same - * time, the FS service in the previous scenario as example. - * - * @section thdshared Threads sharing data - * This is the most common scenario, several threads have access to both their - * private data and shared data. Synchronization happens with one of the - * mechanisms described in the @ref article_mutual_exclusion article.
- * - * @section thdmixed Mixed - * All the above approaches can be freely mixed in a single application but - * usually I prefer to choose a way and consistently design the system around - * it. The OS is a toolbox that offers a lot of tools but you don't have - * to use them all necessarily. - */ diff --git a/docs/src/eclipse.dox b/docs/src/eclipse.dox deleted file mode 100644 index 4e2dfe0fc..000000000 --- a/docs/src/eclipse.dox +++ /dev/null @@ -1,169 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_eclipse Setting up a free embedded IDE - * @brief Free advanced embedded IDE for ChibiOS/RT. - * details This article will explain how to setup a free toolchain for use with - * ChibiOS/RT and general embedded development.
- * The guide is meant mainly for Windows users but notes about Linux and - * MAC OSX are present where the setup differs, mostly the toolchain is - * exactly the same. - * - *

What this guide does not cover

- * We will not enter in details of common system tasks like and not limited to: - * - Installing applications (unless a special procedure is required). - * - Creating desktop shortcuts. - * - Adding paths to the PATH variable. - * - Creating environment variables. - * - Any other normal PC usage task. - * - Use of the toolchain, the use is covered by the @ref article_eclipse2 - * article. - * . - * - *

Article Index

- * - @ref required_components - * - @ref install_chibios - * - @ref install_compiler - * - @ref install_eclipse - * - @ref install_zylin - * - @ref install_openocd - * - @ref install_doxygen - * - @ref install_graphviz - * - @ref install_eclox - * . - * - * @section required_components Required Components - * The first thing to do is to download all the required components, beginners - * should avoid the optional components initially: - * - A JTAG probe supporting GDB and OpenOCD, a list of compatible devices is - * available on the - * OpenOCD home page, more exactly - * here. - * - - * ChibiOS/RT latest stable release. - * - Java runtime, you - * probably already have this installed. - * - Eclipse IDE - * for C/C++ Developers - * - YAGARTO ARM toolchain - * for Windows, note that you need both the compiler and the tools (make - * and binutils). - * - Zylin plugin for on-board debugging, see @ref install_zylin section. - * - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but - * you can download them from here. Linux users can try - * here. - * - Optional, MinGW compiler, needed if you want to compile, debug - * and run the simulator from within Eclipse. Linux users do not need this - * one because all Linux distributions include the native GCC. - * - Optional, Doxygen, it is only required if you want to - * generate documentation from source files. - * - Optional, - * Graphwiz, it is only required if you want to generate diagrams - * within documentation from source files. - * - Optional, - * Eclox, it is only required if you want to generate documentation - * from source files from within Eclipse. - * . - * - * @section install_chibios ChibiOS/RT Installation - * Just unzip it into a directory in your home folder, Windows users may - * consider c:@\projects@\chibios. It is strongly suggested to not put version - * numbers into the ChibiOS/RT directory name because Eclipse workspaces - * have absolute paths inside and you don't want to setup everything again - * each time a new ChibiOS/RT version is released, use plain "chibios". - * - * @section install_compiler GCC ARM Compiler Installation - * Simply follow the YAGARTO installation guide. Linux/MACOS users have several - * other options: - * - Download the latest CodeSourcery free Linux package. - * - Build it yourself, Liam recommended a build script - * - * here, it looks interesting. - * . - * Make sure that the compiler binaries directory is listed in the PATH - * variable or Eclipse would not be able to locate it. - * - * @section install_eclipse Eclipse Installation - * Eclipse is distributed into a compressed archive, there is no installation - * procedure: - * - Verify if you have Java installed, if not install the runtime. You may - * verify this using the command: "java -version". Make sure you have at - * least version 1.6. - * - Create an eclipse directory in your home and unpack the archive there. - * Windows users may unpack it into c:@\program files@\eclipse. - * - Create a desktop shortcut or other way to launch the Eclipse executable - * easily. - * - Launch Eclipse. - * - Eclipse will ask you a directory for its initial workspace, make it point - * to the ChibiOS/RT root directory (you may have as many workspaces you - * want, keep this for later), make sure to select the check box or it will - * ask you again each time. - *

- * @image html tool001.jpg - *
- * - Now you should see the welcome screen, close it and you will be in the - * normal C/C++ perspective. - * - Unselect "Project->Build Automatically" unless you like insanity. - * - Disable the "usage collector" in - * "Window->Preferences->Usage_Data_Collector" by unselecting "Enable - * capture". - * - If you are behind a proxy or firewall (corporate users usually are) - * configure the correct parameters in - * "Window->Preferences->General->Network_Connections". - * - Let Eclipse auto update to the latest version "Help->Check_for_Updates". - * . - * - * @section install_zylin Zylin Plugin Installation - * Eclipse requires an hardware debugger component in order to perform on board - * execution and debug. - * - Open Eclipse, then "Help->Install_New_Software...". - * - Press the "Add..." button and put http://opensource.zylin.com/zylincdt - * into the location field, then press OK. The Zylin plugin will appear in the - * available plugins view, select and install it. - *

- * @image html tool002.jpg - * . - * - * @section install_openocd OpenOCD Installation - * Windows users just have to use the installer. Linux user should follow the - * normal installation procedure for deb or rpm packages, of course it is also - * possible to build it from the source code. - * - * @section install_doxygen Doxygen Installation - * Just use the installer, Linux users probably have Doxygen already available - * from the repositories. Make sure that the Doxygen binaries directory - * is listed in the PATH variable or Eclipse would not be able to locate it. - * - * @section install_graphviz Graphviz Installation - * Just use the installer, Linux users probably have Graphviz already available - * from the repositories. Make sure that the Graphviz binaries directory - * is listed in the PATH variable or Doxygen would not be able to locate it. - * - * @section install_eclox Eclox Installation - * Use the same installation steps used for the Zylin plugin except use - * http://download.gna.org/eclox/update as URL. Install "Eclox" not "Eclox - * Hot". - * After installing Eclox you will be able to compile Doxygen documentation - * using the button with the blue @@ inside. - */ diff --git a/docs/src/eclipse2.dox b/docs/src/eclipse2.dox deleted file mode 100644 index 88a222fc8..000000000 --- a/docs/src/eclipse2.dox +++ /dev/null @@ -1,249 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_eclipse2 Embedded development using Eclipse - * @brief Compiling and debugging ChibiOS/RT applications using Eclipse. - * @details This article will explain how to use an Eclipse based toolchain - * (see @ref article_eclipse) to develop ChibiOS/RT based applications. - * This guide will allow you to: - * - Importing ChibiOS/RT demos into the Eclipse environment. - * - Edit and reformat your source code. - * - Compile and examine errors and warnings. - * - Upload your program on the target board. - * - Debug your code on the target board both in high level language and - * assembler. - * - Develop embedded applications with or without ChibiOS/RT. - * . - * - *

What this guide does not cover

- * This guide assumes knowledge in following areas: - * - OpenOCD setup is not covered by this guide because the setup changes - * depending on the JTAG probe used, the target MCU and also the target - * board. The guide will show the setup for a specific JTAG probe and a - * specific target, a valuable source for the OpenOCD setup is the - * - * dedicated forum, most questions you may have about OpenOCD have - * most likely already been answered there. - * - Hardware setup. - * . - * In general this guide is not a replacement for the Eclipse, GCC, Make, - * binutils, newlib, GDB, OpenOCD user manuals, the guide simply aims to - * give you a faster start. - * - *

Article Index

- * - @ref eclipse2_requirements - * - @ref eclipse2_importing - * - @ref eclipse2_creating - * - @ref eclipse2_compiling - * - @ref eclipse2_configuring - * - @ref eclipse2_configuring_gdb - * - @ref eclipse2_configuring_openocd - * . - * - @ref eclipse2_debugging - * - @ref eclipse2_debugging_start - * - @ref eclipse2_debugging_stop - * . - * . - * - * @section eclipse2_requirements Required Components - * This guide requires: - * - An Eclipse/GCC/OpenOCD based toolchain, as example the one described in - * the article @ref article_eclipse. - * - An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM - * JTAG probe as long it is supported by OpenOCD. - * - An Olimex STM32-P103 target board, this guide applies to any other ARM - * target except for the OpenOCD setup part. - * - A terminal emulator for capturing the board serial output, Windows users - * may use Hyper Terminal, Linux and MAC OS-X users may use - * CuteCom. - * All ChibiOS/RT demos generate on the serial port a test report when a - * button on the target board is pressed, other demos may activate a command - * shell on the serial port, in both cases a terminal emulator is required. - * . - * - * @section eclipse2_importing Importing existing ChibiOS/RT demos into Eclipse - * The first step is to import a project into the Eclipse environment. - * ChibiOS/RT demos do not include Eclipse project files but just a normal - * Makefile. Eclipse is able to import a Makefile project and create - * its own project file so this is not a problem. This is how it is done: - * - Open you Eclipse environment and select the workspace created into the - * ChibiOS/RT project directory. - * - From within Eclipse select "File->New->C_Project", a dialog box will show. - * - Select "Makefile_project->Empty_Project" in the "Project type:" box. - * - Select "-- Other Toolchain --" in the "Toolchains:" box. - * - Unselect the "Use default location" check box. - * - Select the demo directory using the "Browse..." button. Something like - * "C:\Projects\ChibiOS-RT\demos\ARMCM3-STM32F103-GCC" will appear in the - * "Location:" box. - * - In the project name box put the same name of the directory containing - * the demo, ARMCM3-STM32F103-GCC in this example. - *

- * @image html eclipse003.jpg - *
- * - Press the "Finish" button and the project will be created and shown in - * the "Project Explorer". - * - Right click on the imported project and select "Index->Rebuild", this - * will make Eclipse build its internal symbols database. - * - Repeat the above steps for each ChibiOS/RT demo you want to import in - * Eclipse, all the demos that have a makefile can be imported. - * . - * - * @section eclipse2_creating Creating a new ChibiOS/RT application - * If you want to create a new application it is recommended that you create - * a Makefile project first then you can import it into eclipse using the above - * procedure. Makefile projects have the advantage that can be compiled - * everywhere even without Eclipse. Creation steps: - * - Create your own development directory under the ChibiOS/RT installation - * directory, as example "chibios/myprojects". - * - Copy an existing demo, of course choose a demo using your same target, - * under the new directory and rename it, as example - * "chibios/myprojects/myapplication". - * - Customize the Makefile if needed, usually you just need to do this if - * your application is composed by more than one source file. You may also - * want to remove the ChibiOS/RT test code from your application. - * - Once your makefile is ready, import the project under the Eclipse - * workspace using the procedure described in @ref eclipse2_importing. - * . - * - * @section eclipse2_compiling Compiling and Cleaning applications - * Once imported, an application can be compiled by using the "Build All" in - * the toolbar or by right clicking on the project and selecting "Build - * Project". In order to clean a project (removing all the temporary and binary - * files) right click on the project and select "Clean Project". - *

- * @image html eclipse004.jpg - *
- * The compilation result is visible as a complete log in the "Console" window, - * the detail of all errors an warnings is available in the "Problems" window. - *

- * @image html eclipse005.jpg - *
- * The build process produces the binary files specified in the Makefile, all - * the ChibiOS/RT demos produce binary files named ch.elf, ch.bin and/or - * ch.hex. The image must be loaded on the target board in order to execute - * it. The build process usually creates also some other useful files - * containing details about the built application (usually named ch.map and - * ch.dmp). - * - * @section eclipse2_configuring Preparing for Debug - * In order to debug your application a debug configuration must be created. - * The configuration instructs GDB (the source debugger used by Eclipse) on - * how to load the image, load the symbols and place the initial breakpoint - * in the make function. Note that GDB performs its function by connecting - * to a "GDB server", the DGB server implements the low level communication - * with the target device through the JTAG probe. In our scenario the GDB - * server functionality is performed by OpenOCD, this mean that OpenOCD must - * be running while performing a debug session within Eclipse. - * - * @subsection eclipse2_configuring_gdb Creating a GDB Debug Configuration - * A target specific debug configuration is required in order to: - * - Establish a connection with the GDB server. - * - Stop and reset the target. - * - Upload the binary code in Flash or RAM. - * - Set an initial breakpoint in the main function. - * - Start the target (which will immediately stop on the breakpoint). - * . - * The first thing to do is to open the "Debug Configurations..." dialog: - *

- * @image html eclipse006.jpg - *
- * The configuration dialog will appear, we must create a native Zylin - * configuration: - *

- * @image html eclipse007.jpg - *
- * Now we must give the configuration a name, "ARMCM3-STM32F103-GCC (flash and - * run)" in this example, then setup the various configuration pages as follow: - *

- * The "Main" tab: - * @image html eclipse008.jpg - *

- * The "Debugger" tab: - * @image html eclipse009.jpg - *

- * The "Commands" tab: - * @image html eclipse010.jpg - *
- * Note that the "Commands" tab contains the part that changes depending on - * the target. The complete commands sequence (it is not fully visible in the - * image) for STM32 is: - * @code - * monitor soft_reset_halt - * monitor wait_halt - * monitor poll - * monitor flash probe 0 - * monitor stm32x mass_erase 0 - * monitor flash write_bank 0 ch.bin 0 - * monitor soft_reset_halt - * symbol-file ch.elf - * thbreak main - * continue - * @endcode - *

- * The "Common" tab: - * @image html eclipse011.jpg - *
- * Now the debug configuration is complete. - * - * @subsection eclipse2_configuring_openocd Configuring and running OpenOCD - * OpenOCD must be run, with appropriate parameters, before starting your - * debug session. Please refer to the OpenOCD documentation in order to - * properly launch it for your target. - *
**To be completed** - * - * @section eclipse2_debugging Debugging - * Now we are ready to debug an application on the target. Note that Eclipse - * have a mechanism called "Perspectives", you edit and compile your source - * code while you are in the "C/C++ perspective" while the debugging is - * performed in the "Debug perspective". You can switch perspective at any - * time, even while there is an active debug session. If you install more of - * the many Eclipse extension plugins (there are thousands) you may have even - * more perspectives available. - * - * @subsection eclipse2_debugging_start Starting a Debug Session - * In order to start a debugging session first make sure that OpenOCD is - * running then press the drop down menu on the right side of the - * debug icon in the toolbar (the small green bug) and select your - * debug configuration (we created just one but you may have multiple - * debug configurations in your project, as example I usually create - * another debug configuration that just starts the target without - * uploading the code). - *

- * @image html eclipse012.jpg - *
- * The debugger will be initialized, you will see the operation in progress on - * the console then Eclipse will switch to the debug perspective and you will - * see your program stopped on the default breakpoint in the main function. - *

- * @image html eclipse013.jpg - *
- * From there you can perform all the usual debugging tasks, set breakpoints, - * single step execution, variables, memory and registers inspection etc. - * Please refer to the Eclipse documentation about those "normal" operations. - * Note that if the debugging start procedure hangs then there is probably - * an error in your configuration or problems with the target, read the - * console log and/or the OpenOCD output in order to understand where the - * problem is. - * - * @subsection eclipse2_debugging_stop Stopping a Debug Session - * From the debug perspective press the stop button (small red square) in the - * debug window, the target will be stopped and you may both return to the - * C/C++ perspective or start it again. - */ diff --git a/docs/src/events.dox b/docs/src/events.dox deleted file mode 100644 index 27de187e4..000000000 --- a/docs/src/events.dox +++ /dev/null @@ -1,124 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_events Events Explained - * Events are an important feature in ChibiOS/RT, most device drivers generate - * events in order to notify the application that something happened at the - * I/O level.
- * While event flags are not something unknown in other operating systems, - * their peculiar implementation in ChibiOS/RT requires a more in depth - * explanation.
- * Lets start with the events related terminology: - * - Event Source, an @p EventSource is a system object that can be - * broadcasted asynchronously in response of a system event, as example, - * when the CAN driver receives a packet from the CAN bus it broadcasts - * an event source in order to inform the registered threads that a packet - * has just arrived. - * - Broadcast, the operation performed on an event source in order - * to inform the registered threads that an event just occurred. - * Broadcasting can happened both in interrupt handlers and in threads. - * - Event Listener, a system object that associates a @p Thread object - * to an event source. The process of associating a @p Thread to an - * @p EventSource using an @p EventListener is called registration. - * - Registration, action performed by a thread in order to be informed - * of events from a specific event source. Of course a thread can be - * registered on more than one event source by using multiple - * @p EventListener objects. Threads can also unregister from an event - * source. - * - Pending Events, event flags waiting to be served by a thread. - * - Add, the broadcast operation adds (logical or) an events - * mask to all the registered threads. - * - Wait, synchronous operation performed by a thread in order to - * wait a specific combination of events. The API offers a variety of - * wait functions, please refer to the events API documentation. - * . - * Note that events are asynchronously generated, as example in an interrupt - * handler, but are synchronously served. - * - *

Events related data structures

- * The following diagram explains the relationship between an event source, - * its list of event listeners and the registered threads. - * @dot - digraph example { - rankdir="LR"; - - node [shape=rectangle, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.0", height="0.5"]; - edge [fontname=Helvetica, fontsize=8, sep=3.0]; - - es [shape=record, label="EventSource | es_next", style="bold"]; - - subgraph cluster_0 { - fontname=Helvetica; - label = "Listeners List"; - color = blue; - node [shape=record, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.5", height="1.0"]; - el4 [label="EventListener 4 | el_mask: 0x0001 | el_listener | el_next"]; - el3 [label="EventListener 3 | el_mask: 0x0C00 | el_listener | el_next"]; - el2 [label="EventListener 2 | el_mask: 0x0001 | el_listener | el_next"]; - el1 [label="EventListener 1 | el_mask: 0x0004 | el_listener | el_next"]; - el1 -> el2 -> el3 -> el4 [label=" el_next", constraint=false]; - } - - subgraph cluster_1 { - fontname=Helvetica; - label = "Registered Threads"; - color = blue; - node [shape=record, fontname=Helvetica, fontsize=8, - fixedsize="true", width="1.5", height="0.8"]; - t1 [label="Thread 1 | p_epending:0x0000 | p_ewmask:0xFFFF"]; - t2 [label="Thread 2 | p_epending:0x000F | p_ewmask:0x0C01"]; - t3 [label="Thread 3 | p_epending:0x0008 | p_ewmask:0x0001"]; - t4 [label="Thread 4 | p_epending:0x0000 | p_ewmask:0xFFFF"]; - } - - es -> el1 [label=" es_next"]; - el4 -> es [label=" el_next"]; - el1 -> t1 [label="el_listener"]; - el2 -> t2 [label="el_listener"]; - el3 -> t3 [label="el_listener"]; - el4 -> t4 [label="el_listener"]; - } - * @enddot - * Note that each event listener has a different bit mask to be added on - * its associated thread when the event source is broadcasted, this means - * that each thread can define its own event identifiers independently. A - * broadcast operation can also add more than one bit on the - * registered threads.
- * The threads have a variety of wait primitives, they can wait for one - * or more event flags, and can also specify AND/OR conditions, as example - * a thread can wait for any of the specified events or wait for all the - * specified events.
- * The field @p p_epending is the mask of the currently pending events, - * the field @p p_ewmask is the mask of the events the thread is interested - * on in that moment (AND or OR condition depending on the invoked - * wait API). - * - *

Use Scenarios

- * Events are best used when one of more of the following conditions are - * required: - * - Having to wait on multiple conditions, Events are the only mechanism - * that easily allow that. - * - Synchronous response to one or more asynchronous events. - * - Single threaded applications working in a event driver environment (but - * events are not limited to single threaded applications). - * . - */ diff --git a/docs/src/goals.dox b/docs/src/goals.dox deleted file mode 100644 index 6dc8f0034..000000000 --- a/docs/src/goals.dox +++ /dev/null @@ -1,88 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page goals Project Goals - *

Another RTOS?

- * The first question to be answered is: there was really the need for YET - * ANOTHER RTOS?
- * There are several reasons: - * - The ChibiOS/RT ancestor was created more than 15 years ago and while it - * had far less features than the current product it was complete and - * functioning. ChibiOS/RT is just a new (and silly) name given to - * something created when there were not many free RTOSes around (actually - * none, at least none in my knowledge, there was no widespread Internet - * at that time). - * - When, after a while, I needed a RTOS again, none of the existing FOSS - * projects met my expectations or my ideas of how a RTOS should be, not - * even close (see below). I decided that work on that old project was - * a better idea than contribute to, or fork, something else. - * - I wanted another toy. - * . - *

Why is it different?

- * Well, there are some design choices that should be explained and contribute - * to make ChibiOS/RT a peculiar design. Nothing really new in itself but - * the whole is interesting: - * - *

Static design

- * Everything in the kernel is static, nowhere memory is allocated or freed, - * there are three allocator subsystems but those are options and not part of - * core OS. Safety is something you design in, not something you can add later. - * - *

No tables, arrays or other fixed structures

- * The kernel has no internal tables, there is nothing that must be configured - * at compile time or that can overflow at run time. No upper bounds, the - * internal structures are all dynamic even if all the objects are statically - * allocated. - * - *

No error conditions and no error checks

- * All the system APIs have no error conditions, all the previous points are - * finalized to this objective. Everything you can invoke in the kernel is - * designed to not fail unless you pass garbage as parameters, stray pointers - * as examples. The APIs are not slowed down by parameter checks, - * parameter checks (and consistency checks) do exist but only when the - * debug switch is activated.
- * All the static core APIs always succeed if correct parameters are passed. - * Exception to this are the optional allocators APIs that, of course, - * can report memory exhausted. - * - *

Very simple APIs

- * Each API should have the parameters you would expect for that function and - * do just one thing with no options. - * - *

Fast and compact

- * Note, first "fast" then "compact", the focus is on speed and execution - * efficiency and then on code size. This does not mean that the OS is large, - * the kernel size with all the subsystems activated weighs around 5.3KiB - * and can shrink down around to 1.2Kib in a minimal configuration - * (STM32, Cortex-M3). It would be possible to make something even smaller but: - * -# It would be pointless, it is already @a really small. - * -# I would not trade efficiency or features in order to save few bytes. - * . - * About the "fast" part, the kernel is able to start/exit over - * 220,000 threads per second on a 72MHz STM32. - * The Context Switch takes 1.2 microseconds on the same STM32. - * - *

Tests and metrics

- * I think it is nice to know how an OS is tested and how it performs before - * committing to use it. Test results on all the supported platforms and - * performance metrics are included in each ChibiOS/RT release. The test - * code is released as well, all the included demos are capable of executing - * the test suite and the OS benchmarks, see @ref testsuite. - */ diff --git a/docs/src/integrationguide.dox b/docs/src/integrationguide.dox deleted file mode 100644 index dd91d8cf8..000000000 --- a/docs/src/integrationguide.dox +++ /dev/null @@ -1,95 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_integrationguide Integration Guide - * All the delivered ChibiOS/RT demos are stand alone applications so if - * you just start your application from an existing demo there isn't any - * 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 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: - * - Porting the OS to different architectures or different compilers is - * not covered in this guide, see @ref article_portguide instead. - * - This guide does not describe any specific environment or development - * tool, it is assumed you already know in detail the environment you - * want to work with. - * . - * - *

Article Index

- * - @ref integrationguide_kernel - * - @ref integrationguide_hal - * . - * @section integrationguide_kernel Integrating the Kernel - * This section covers the scenario where you want to use the ChibiOS/RT - * kernel into an existing application. In order to accomplish this you need - * to import in your project two components: - * - The portable kernel. - * - The port layer for your microcontroller. - * . - * See the @ref architecture for more details. - * You need to add the following files to your build process: - * - All the source files contained under ./os/kernel/src, note that - * you should add all of them even if you don't plan to use some of the - * subsystems. Unused subsystems can be excluded from the kernel - * configuration file @p chconf.h. - * - All the source files contained under - * ./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/ports/@/@. - * . - * @section integrationguide_hal Integrating the HAL - * If, in addition to the kernel as described in the previous section, you also - * need to integrate the HAL into your application you also need to import - * the following components: - * - HAL portable files. - * - Platform specific files. - * . - * See the @ref architecture for more details. - * You need to add the following files to your build process: - * - All the source files contained under ./os/hal/src, note that - * you should add all of them even if you don't plan to use some of the - * subsystems. Unused drivers can be excluded from the HAL configuration - * file @p halconf.h. - * - All the source files contained under - * ./os/hal/platforms/@. - * - All the source files contained under - * ./boards/@. - * . - * You also need to add to the compiler options the following paths for - * searching header files: - * - The portable HAL headers ./os/hal/include. - * - The platform layer headers - * ./os/hal/platforms/@. - * - The board description headers - * ./boards/@. - * . - */ diff --git a/docs/src/interrupts.dox b/docs/src/interrupts.dox deleted file mode 100644 index bceea96c4..000000000 --- a/docs/src/interrupts.dox +++ /dev/null @@ -1,69 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_interrupts How to write interrupt handlers - * Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing - * interrupt handlers. Port-related and compiler-related details are - * encapsulated within standard system macros. - * - *

Writing Regular Interrupt handlers

- * A Regular Interrupts handler (see @ref interrupt_classes) must be written - * using the following general form: - * @code -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // IRQ handling code, preemptable if the architecture supports it. - - chSysLockFromIsr(); - // Invocation of some I-Class system APIs, never preemptable. - chSysUnlockFromIsr(); - - // More IRQ handling code, again preemptable. - - CH_IRQ_EPILOGUE(); -} - * @endcode - * - *

Writing Fast Interrupt handlers

- * In those architectures (@ref ARM7 and @ref ARMCMx) supporting Fast - * Interrupts (see @ref interrupt_classes) handlers must be written - * using the following general form: - * @code -CH_FAST_IRQ_HANDLER(myIRQ) { - - // Fast IRQ handling code, preemptable if the architecture supports it. - // The invocation of any API is forbidden here because fast interrupt - // handlers can preempt the kernel even within its critical zones in - // order to minimize latency. -} - * @endcode - * - *

Handlers naming

- * A note about the handler name "myIRQ", in some ports it must be a - * vector number rather than a function name, it could also be a name from - * within a predefined set, see the notes about the various ports. - * - *

Important Notes

- * - There is an important application note about ARM7 interrupt handlers, - * please read about it in the ARM7 port section: @ref ARM7_IH - * . - */ - \ No newline at end of file diff --git a/docs/src/jitter.dox b/docs/src/jitter.dox deleted file mode 100644 index 759425b4e..000000000 --- a/docs/src/jitter.dox +++ /dev/null @@ -1,135 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_jitter Response Time and Jitter - * Response time jitter is one of the most sneaky source of problems when - * designing a real time system. When using a RTOS like ChibiOS/RT one must - * be aware of what the jitter is and how it can affect the performance of the - * system. A good place to start is this - * Wikipedia - * article. - * - *

Interrupt handlers execution time

- * The total execution time of an interrupt handler includes: - * - Hardware interrupts latency, this parameter is pretty much fixed and - * characteristic of the system. - * - Fixed handler overhead, as example registers stacking/unstacking. - * - Interrupt specific handler code execution time, as example, in a serial - * driver, this is the time used by the handler to transfer data from/to - * the UART. - * - OS overhead. Any operating system requires to run some extra code - * in interrupt handlers in order to handle correct preemption and Context - * Switching. - * . - *

Interrupt Response Time

- * The Interrupt Response Time is the time from an interrupt event and the - * execution of the handler code. Unfortunately this time is not constant - * in most cases, see the following graph: - * - * @dot - digraph example { - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - int [label="Interrupt"]; - busy [label="Busy"]; - served [label="Interrupt\nServed"]; - int -> served [label="Not Busy (minimum latency)"]; - int -> busy [label="Not Ready"]; - busy -> busy [label="Still Busy\n(added latency)"]; - busy -> served [label="Finally Ready"]; - } - * @enddot - * - * In this scenario the jitter (busy state) is represented by the sum of: - * - Higher or equal priority interrupt handlers execution time combined. - * This time can go from zero to the maximum randomly. This value can be - * guaranteed to be zero only if the interrupt has the highest priority in - * the system. - * - Highest execution time among lower priority handlers. This value is zero - * on those architectures (Cortex-M3 as example) where interrupt handlers - * can be preempted by higher priority sources. - * - Longest time in a kernel lock zone that can delay interrupt servicing. - * This value is zero for fast interrupt sources, see @ref system_states. - * . - *

Threads Flyback Time

- * This is the time between an event, as example an interrupt, and the - * execution of the thread that will process it. Imagine the following - * graph as the continuation of the previous one. - * - * @dot - digraph example { - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - served [label="Interrupt\nServed"]; - busy [label="Busy"]; - thread [label="Thread\nAwakened"]; - served -> busy [label="Not highest Priority"]; - busy -> busy [label="Higher priority Threads\n(added latency)"]; - busy -> thread [label="Highest Priority"]; - served -> thread [label="Highest Priority (minimum latency)"]; - } - * @enddot - * - * In this scenario all the jitter sources previously discussed are also - * present and there is the added jitter caused by the activity of the - * higher priority threads. - * - *

Jitter Mitigation

- * For each of the previously described jitter sources there are possible - * mitigation actions. - * - *

Interrupt handlers optimization

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

Kernel lock zones

- * The OS kernel protects some critical internal data structure by disabling - * (fully in simple architecture, to some extent in more advanced - * microcontrollers) the interrupt sources. Because of this the kernel itself - * is a jitter cause, a good OS design minimizes the jitter generated by the - * kernel by using adequate data structures, algorithms and coding - * practices.
- * A good OS design is not the whole story, some OS primitives may generate - * more or less jitter depending on the system state, as example the maximum - * number of threads on a certain queue, the maximum number of nested mutexes - * and so on. Some algorithms employed internally can have constant execution - * time but others may have linear execution time or be even more complex. - * - *

Higher priority threads activity

- * At thread level, the response time is affected by the interrupt-related - * jitter but mainly by the activity of the higher priority threads and - * contention on protected resources.
- * It is possible to improve the system overall response time and reduce jitter - * by carefully assigning priorities to the various threads and carefully - * designing mutual exclusion zones.
- * The use of the proper synchronization mechanism (semaphores, mutexes, events, - * messages and so on) also helps to improve the overall system performance. - * The use of the Priority Inheritance algorithm implemented in the mutexes - * subsystem can improve the overall response time and reduce jitter but it is - * not a magic wand, a proper system design comes first. - */ diff --git a/docs/src/licfaq.dox b/docs/src/licfaq.dox deleted file mode 100644 index f2563134c..000000000 --- a/docs/src/licfaq.dox +++ /dev/null @@ -1,119 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page lic_faq License and F.A.Q. - * ChibiOS/RT is a - * GPL3-licensed product but it offers a linking exception in its stable - * releases.
- * This article contains some answers about the exception. - * - * @section faq Frequently Asked Questions - * - Is ChibiOS/RT free ?
- * Yes, free as both in free beer and freedom. - * - Can I use it in my commercial embedded product?
- * Yes, you just have to advertise that you are using ChibiOS/RT by putting - * a link to the project somewhere on your web site or documentation. - * - Am I forced to release the source code of my product?
- * The exception to the GPL allows you to use ChibiOS/RT in your commercial - * application without have to release your source code under certains - * conditions. See the @ref exception_text under "Approved Interfaces" for - * details. - * - What I have to contribute back?
- * In general you have to offer changes done on existing files (where - * allowed) or new developments done using the OS template files. As example: - * - Ports to new architectures because a new port uses copyrighted OS - * template files. - * - New, HAL-style, device drivers because device drivers use copyrighted - * template files. - * - Improvements on modifiable OS code as described in the - * "approved interfaces" section of the @ref exception_text. - * . - * - Is the exception applicable to any ChibiOS/RT version ?
- * The exception is valid only for ChibiOS/RT releases marked as @e stable. - * Beta, unstable or development versions are covered by the GPL3 alone - * because are meant for testing only. - * - I don't want to be bound by any of the above restriction, is this - * possible?
- * You may contact us about a commercial license. - * . - * @section exception_text GPL Exception Text - -
GPL Exception Text for ChibiOS/RT 1.4.x
- - In addition, as a special exception, the copyright holder of ChibiOS/RT, -gives You the additional right to link the unmodified code of this Program with -code not covered under the GNU General Public License ("Non-GPL Code") and to -distribute linked combinations including the two, subject to the limitations -in this paragraph. - - -# Non-GPL Code permitted under this exception must only link to the - unmodified code of this Program through those well defined interfaces - identified as "Approved Interfaces". - -# Every copy of the combined work is accompanied by a written statement - that details to the recipient the version of ChibiOS/RT used and an - offer by yourself to provide the ChibiOS/RT source code should the - recipient request it. - -# The combined work is not itself an RTOS, scheduler, kernel or related - product. - -# The combined work is not itself a binary library intended for linking - into other software applications. - . - -
The Approved Interfaces
- - -# The files of Non-GPL Code may include the unmodified ChibiOS/RT - distribution header files contained under: - - ./os/kernel/include - - ./os/hal/include - - ./os/hal/platforms - - ./os/various - . - without causing the resulting work to be covered by the GNU General - Public License. - -# The files of Non-GPL Code may link to the unmodified ChibiOS/RT - distribution files contained under: - - ./os/kernel/src - - ./os/hal/src - - ./os/hal/platforms - - ./os/various - . - without causing the resulting work to be covered by the GNU General - Public License. - -# The files of Non-GPL Code may link to, or include, the modified or - unmodified ChibiOS/RT distribution files contained under: - - ./os/kernel/templates - - ./os/hal/templates - - ./os/ports - - ./boards - - ./demos - . - without causing the resulting work to be covered by the GNU General - Public License. - . - - Only the copyright holder of ChibiOS/RT may make changes or additions to the -list of Approved Interfaces. - - You must obey the GNU General Public License in all respects for all of the -Program code and other code used in conjunction with the Program except the -Non-GPL Code covered by this exception. - * - */ - diff --git a/docs/src/lifecycle.dox b/docs/src/lifecycle.dox deleted file mode 100644 index 18875e7da..000000000 --- a/docs/src/lifecycle.dox +++ /dev/null @@ -1,68 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @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 - * 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 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 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: - * @dot - digraph example { - rankdir="LR"; - node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; - edge [fontname=Helvetica, fontsize=8]; - - init [label="No thread", style="bold"]; - alive [label="Alive"]; - final [label="Terminated"]; - detached [label="Detached", style="bold"]; - - init -> alive [label="chThdCreateX()"]; - alive -> alive [label="chThdAddRef()"]; - alive -> alive [label="chThdRelease()\n[ref > 0]"]; - alive -> detached [label="chThdRelease()\n[ref == 0]"]; - alive -> init [label="chThdWait()\n[ref == 0]"]; - alive -> final [label="chThdExit()\nreturn"]; - final -> final [label="chThdAddRef()"]; - final -> final [label="chThdRelease()\nchThdWait()\n[ref > 0]"]; - final -> init [label="chThdRelease()\nchThdWait()\n[ref == 0]"]; - } - * @enddot - *
- * 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, scanning the registry - * has the side effect to release the zombies (detached and then terminated - * threads). - */ diff --git a/docs/src/main.dox b/docs/src/main.dox index e5872cdf5..76a39bff7 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -58,13 +58,7 @@ * driver models and device driver implementations. * . *

Related pages

- * - @subpage credits - * - @subpage lic_faq - * - @subpage goals - * - @subpage target - * - @subpage architecture * - @subpage concepts - * - @subpage articles * - @subpage testsuite * . */ diff --git a/docs/src/memory.dox b/docs/src/memory.dox deleted file mode 100644 index f41dff32f..000000000 --- a/docs/src/memory.dox +++ /dev/null @@ -1,138 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_manage_memory How to manage memory - * ChibiOS/RT is a static kernel so you don't need to manage memory at all - * if your application doesn't really require it. This doesn't mean that - * the OS is unable to manage memory but just that memory management is an - * optional part of the whole.
- * The OS offers three distinct ways to manage memory, each one with its - * weaknesses and strengths: - * - Core Memory Manager. See @ref memcore. - * - Heap Allocator. See @ref heaps. - * - Memory Pools. See @ref pools. - * . - * The three mechanisms are able to coexist and are well integrated, as example - * the heap allocator uses the core memory manager in order to get more - * memory blocks, memory pools can optionally do the same thing. - * - *

The three subsystems

- * This is a small comparison table regarding the three subsystems, C-runtime - * and static objects are thrown in there for comparison:

- *
- * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
- * Subsystem - * - * Free capable - * - * Constant time - * - * Safe - * - * From IRQ - * - * Notes - *
- * Static Objects - * N/AN/AYESYES - * Preferred solution for safety applications. - *
- * Core Memory Manager - * NOYESYESYES - * Fast and safe but unable to free allocated memory. - *
- * Heap Allocator - * YESNONONO - * Unsafe because fragmentation and not constant time, cannot be used - * from IRQ handlers. - *
- * Memory Pools - * YESYESYESYES - * Fast and safe but it can handle fixed size objects only, you may have - * multiple memory pools however. - *
- * C-Runtime - * YESNONONO - * Unsafe because fragmentation, not constant time, cannot be used - * from IRQ handlers and not thread safe. The C runtime must also be - * modified in order to work with the other allocators. - *
- *
- * When designing a system it is recommended to proceed as follow: - * -# Use static objects and initializers whenever possible. - * -# Where dynamic allocation is required without having to free the allocated - * memory then use the Core Memory Manager allocation APIs. - * -# Where dynamic allocation is required evaluate if one or more memory - * pools can be used. - * -# If all the above points do not satisfy your requirements then use the - * heap allocator. - * -# Consider the C-runtime allocator only for legacy code. - * . - */ - diff --git a/docs/src/mutualexcl.dox b/docs/src/mutualexcl.dox deleted file mode 100644 index 260732e19..000000000 --- a/docs/src/mutualexcl.dox +++ /dev/null @@ -1,210 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_mutual_exclusion Mutual Exclusion guide - * The most common problem when writing multithreaded code is the - * synchronization on the shared resources/services.
- * ChibiOS/RT offers a rich variety of mechanisms that apparently solve the - * same problem. I wrote apparently because each mechanism has its pro and - * cons. - * This article will introduce the various mechanisms and the explain the - * right scenarios for each one. - * - *

Basics

- * Some of the concepts mentioned in this article can be found in the - * following Wikipedia articles: - * - - * Mutual Exclusion - * - - * Priority Inversion - * - Priority Inheritance - * - - * Priority Ceiling - * . - *

Mutual exclusion by System Locks

- * This is the lowest level mechanism, the system is locked by invoking the - * @p chSysLock() API and then unlocked by invoking @p chSysUnlock().
- * The implementation is architecture dependent but it is guaranteed to, at - * least, disable the interrupt sources with hardware priority below or equal - * the kernel level. - * - *

Advantages

- * - It is the lightest as execution time, often a lock or unlock becomes just a - * single inlined assembler instruction. - * - It ensures mutual exclusion among threads but also interrupt handling code. - * - The implementation would ensure mutual exclusion even on multicore - * architectures where multiple hardware threads are present. - * . - *

Disadvantages

- * - Disabling interrupts for a long period of time can deteriorate the overall - * system response time and/or introduce jitter. - * . - *

When use Locks

- * - When mutual exclusion with interrupt handlers is required. - * - When the operation within the lock zone is very simple and has finite - * time. - * . - *

Example

- * @code - * ... - * chSysLock(); - * /* Protected code */ - * chSysUnlock(); - * ... - * @endcode - * - *

Mutual exclusion by Semaphores

- * In ChibiOS/RT the counting semaphores are mainly meant as a - * synchronization mechanism between interrupt handlers and high level code - * 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 - * the semaphore counter to one. - * - *

Advantages

- * - 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. - * - A semaphore takes less RAM than a mutex (12 vs 16 bytes on 32 bit - * architectures). - * . - *

Disadvantages

- * - Semaphore queues are FIFO ordered by default, an option exist to make - * them priority ordered but this can impact I/O performance because - * semaphores are used in I/O queues. - * - Semaphores do not implement the Priority Inheritance algorithm. - * . - *

When use Semaphores

- * - When you don't need queuing by priority nor the Priority Inheritance - * algorithm. - * - When RAM/ROM space is scarce. - * . - *

Example

- * @code - * static Semaphore sem; /* Semaphore declaration */ - * ... - * chSemInit(&sem, 1); /* Semaphore initialization before use */ - * ... - * chSemWait(&sem); - * /* Protected code */ - * chSemSignal(&sem); - * ... - * @endcode - * - *

Mutual exclusion by Mutexes

- * 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 another tool for the system designer). - * . - *

Disadvantages

- * - Heaviest among all the possible choices. The Priority Inheritance method - * is efficiently implemented but nothing is more efficient than no code at - * all. - * . - *

When use Mutexes

- * - When you are designing a very complex system with hard realtime - * requirements. - * . - *

Example

- * @code - * static Mutex mtx; /* Mutex declaration */ - * ... - * chMtxInit(&mtx); /* Mutex initialization before use */ - * ... - * chMtxLock(&mtx); - * /* Protected code */ - * chMtxUnlock(); - * ... - * @endcode - * - *

Mutual exclusion by priority boost

- * Another way to implement mutual exclusion is to boost the thread priority - * to a level higher than all of the threads competing for a certain resource. - * This solution effectively implements an Immediate Priority Ceiling - * algorithm. - * - *

Advantages

- * - Almost free as code size, you need no semaphores nor mutexes. - * - No RAM overhead. - * - Fast execution, priority change is a quick operation under ChibiOS/RT. - * - The Priority Ceiling protocol can help mitigate potential Priority - * Inversion problems. - * . - *

Disadvantages

- * - Makes the design more complicated because priorities must be assigned to - * not just threads but also assigned to the resources to be protected. - * - Locking a resource affects all the threads with lower priority even if - * not interested to the resource. - * - All the threads that can access the resource must have lower priority - * than the resource itself. - * - The mechanism is not easy to understand in the code unless it is clearly - * documented. - * - This method does not work in on multicore architectures where multiple - * hardware threads are present. - * - Only useful in very simple applications. - * . - *

Example

- * @code - * /* Priority assigned to the resource, threads must have lower - * priority than this.*/ - * #define AAA_RESOURCE_PRIORITY NORMALPRIO+10 - * ... - * /* Locks the resources AAA.*/ - * tprio_t aaa_old_prio = chThdSetPriority(AAA_RESOURCE_PRIORITY); - * /* Accessing resource AAA */ - * chThdSetPriority(aaa_old_prio); /* Unlocks AAA.*/ - * ... - * @endcode - * - *

Mutual exclusion by message passing

- * Another method is to make a single dedicated thread execute the critical - * code and make it work as a messages server. The other threads can request - * the service to the server by sending a properly formatted message and - * then wait for the answer with the result.
- * This method is very useful when integrating into the system components not - * designed to be reentrant or to be executed in a multithreaded environment, - * as example a 3rd part file system or a networking protocol stack. - * - *

Advantages

- * - It is possible to encapsulate very complex logic without worry about - * about concurrent accesses. - * - If the encapsulate code uses a large stack area only the server thread - * have to allocate enough RAM, the client threads save RAM by just - * requesting the service to the server. - * - Clean system architecture. - * - This method also implements a form of Priority Ceiling. The ceiling is - * the priority of the server thread itself. - * . - *

Disadvantages

- * - More complex implementation, a protocol must be created between clients - * and server. - * - Two context switches are required for each request to the server (but - * ChibiOSRT is very efficient at that). - * - Requires a dedicated thread as server. - * . - */ diff --git a/docs/src/portguide.dox b/docs/src/portguide.dox deleted file mode 100644 index 087724084..000000000 --- a/docs/src/portguide.dox +++ /dev/null @@ -1,120 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_portguide Porting ChibiOS/RT for Dummies - * Porting the operating system on a new platform is one of the most common - * tasks. The difficulty can range from easy to very difficult depending - * on several factors.
- * We can divide in problem in several classes of progressively increasing - * difficulty: - * - @ref port_board - * - @ref port_family - * - @ref port_chip - * - @ref port_core - * . - * Another kind of port type is porting to another compiler and this is an - * added complexity level on the above classes. The kernel itself is portable - * but the port-specific code usually contains compiler specific extensions to - * the C language and the asm files syntax is almost never compatible. - * - * @section port_board Porting the OS to a new board - * This is the easiest port type, the scenario is that the specific - * microcontroller is already supported and a demo exists. This scenario also - * applies when porting the OS on a custom hardware using a supported - * microcontroller. This task can be easily performed with the following - * steps: - * -# Create a new directory under ./boards and copy inside the board files - * from another board using the same microcontroller. - * -# Customize the board files: - * - @p board.h This file contains the I/O pins setup for the uC, it - * may also contain other board-dependent settings, as example, the clock - * frequency. Customize this file depending on your target hardware. - * - @p board.c This file contains the initialization code, it is possible - * you just need to customize @p board.h and not this file. If you have - * some hardware specific initialization code then put it here. - * . - * -# Create a new directory under the ChibiOS/RT installation directory: - * ./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 - * sources and/or add you application source files. - * - @p main.c It contains the demo simple code, clean it and write your - * own @p main() function here, use this file just as a template. - * -# Compile your application and debug. - * . - * @section port_family Porting the OS to a closely related microcontroller - * In this scenario all the above steps are required but an analysis must - * be performed to evaluate the differences between from the supported micro - * and the target micro. Often the micros just differ for the memory area - * sizes and a change to the linker script is enough (the file is usually - * named @p ch.ld). Chips having more or less peripherals, everything else - * being the same or compatible are not a problem also as long the timer and - * the serial peripherals used by the port do not change.
- * If there are differences in the internal peripherals, as example non - * compatible interrupt controllers (this happens in the LPC2000 family) - * or differences in UARTS, timers etc then the port falls in the following - * category. - * - * @section port_chip Porting the OS to another microcontroller using the same core - * This kind of port is required when a target microcontroller has the same - * 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/hal/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 - * 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/hal/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 - * is only required if you want to regenerate this documentation including - * your work. - * . - * Usually this kind of port just requires a serial driver (and those are very - * similar each other) and some code for the interrupt controller (this one - * can be part of the core port, as example the Cortex-M3 has this as standard - * part of the core).
- * When the chip port is completed created your application as seen in the - * previous sections. - * - * @section port_core Porting the OS to a whole new architecture - * This is the hardest scenario, the time required by core ports depends - * strongly by the target architecture complexity and the level of support you - * need for the architecture specific features.
- * As a reference, the MSP430 port took me 2 hours and it worked at the first - * run, it can be a reference for simple architectures, the ARM Cortex-M3 was - * painful instead, the architecture enforces you to implement things in a very - * specific way and I spent 2 week to go through all the documentation and - * figure out the correct way to implement the port (you can see that the - * preemption context switch is done in a very peculiar way because the - * exceptions architecture).
- * One thing is sure, port an OS to a new architecture is not an easy task and - * if you have the required experience for such an effort then probably you - * don't need any advice from me. Just follow the directory patterns and fill - * the OS template files, the hardest part is decide the correct and efficient - * way to implement the context switching. - */ diff --git a/docs/src/roundrobin.dox b/docs/src/roundrobin.dox deleted file mode 100644 index df57ec971..000000000 --- a/docs/src/roundrobin.dox +++ /dev/null @@ -1,50 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_roundrobin Round Robin scheduling explained - * Unlike many other RTOSes, ChibiOS/RT supports multiple threads at the - * same priority level and schedules them using an aggressive - * round-robin strategy.
- * The strategy is defined as aggressive because any scheduling event - * 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 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 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 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 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/saveram.dox b/docs/src/saveram.dox deleted file mode 100644 index 233c322c6..000000000 --- a/docs/src/saveram.dox +++ /dev/null @@ -1,81 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_saveram Saving RAM by declaring thread functions "noreturn" - * One of the problems, when writing embedded multi-threaded applications, - * is that the thread functions do save the registers in the function - * entry code even if the system does not require it, exiting such - * a function would terminate the thread so there is no need to preserve - * the register values. This can waste tens of bytes for each thread.
- * Consider the following code: - * @code -#include - -static WORKING_AREA(waMyThread, 64); - -static t_msg MyThread(void *arg) { - while (!chThdShoudTerminate()) { - /* Do thread inner work */ - } - return 1; -} - -main() { - chSysInit(); - ... - chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL); - ... -} - * @endcode - * The resulting ASM code for the thread function would be something like this: - * @code -MyThread: - stmfd sp!, {r4, r5, r6, lr} - ... - ldmfd sp!, {r4, r5, r6, pc} - * @endcode - * Being that function a thread there is no need to save those registers, in - * embedded applications often the RAM is a scarce resource. That space can be - * saved by modifying the code as follow, using some advanced GCC extensions: - * @code -#include - -static WORKING_AREA(waMyThread, 64); - -__attribute__((noreturn)) -static void MyThread(void *arg) { - while (!chThdShoudTerminate()) { - /* Do thread inner work */ - } - chThdExit(1); -} - -main() { - chSysInit(); - ... - chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, - (tfunc_t)MyThread, NULL); - ... -} - * @endcode - * This will make GCC believe that the function cannot return and there is no - * need to save registers. The code will be a bit less readable and less - * portable on other compilers however. - */ diff --git a/docs/src/stacks.dox b/docs/src/stacks.dox deleted file mode 100644 index d87d183f6..000000000 --- a/docs/src/stacks.dox +++ /dev/null @@ -1,107 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_stacks Stacks and stack sizes - * 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 - * others are present only in some architectures: - * - Main stack, this stack is used by the @p main() function and the - * thread that execute it. It is not a normal thread stack because it is - * initialized in the startup code and its size is defined in a port - * dependent way. Details are in the various ports documentation. - * - Interrupt Stack, some architectures have a dedicated interrupt - * stack. This is an important feature in a multithreaded environment, - * without a dedicated interrupt stack each thread has to reserve - * enough space, for interrupts servicing, within its own stack. This space, - * multiplied by the total threads number, can amount to a significant RAM - * overhead. - * - Thread Stack, each thread has a dedicated stack for its own - * execution and context switch. - * - Other Stacks, some architectures (ARM) can have other stacks but - * the OS does not directly use any of them. - * . - *

Risks

- * The most critical thing when writing an embedded multithreaded application - * is to determine the correct stack size for main, threads and, when present, - * interrupts.
- * 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 - * stack requirements but this requires much time, experience and patience.
- * An alternative way is to use an interactive method. Follow this procedure - * for each thread in the system: - * - Enable the following debug options in the kernel: - * - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any - * context switch. This option halts the system in @p chSysHalt() just - * before a stack overflow happens. The halt condition is caused by - * a stack overflow when the global variable @p panic_msg is set to - * @p NULL, normally it would point to a panic message. - * - @p CH_DBG_FILL_THREADS, this option fills the threads working area - * with an easily recognizable pattern (0x55). - * - Assign a large and safe size to the thread stack, as example 256 bytes - * on 32 MCUs, 128 bytes on 8/16 bit MCUs. This is almost always too much - * for simple threads. - * - Run the application, if the application crashes or halts then increase - * the stack size and repeat (you know how to use the debugger right?). - * - Let the application run and make sure to trigger the thread in a way to - * make it follow most or all its code paths. If the application crashes or - * halts then increase the stack size and repeat. - * - Stop the application using the debugger and examine the thread working - * area (you know what a map file is, right?). You can see that the thread - * stack overwrote the fill pattern (0x55) from the top of the working area - * downward. You can estimate the excess stack by counting the untouched - * locations. - * - Trim down the stack size and repeat until the application still runs - * correctly and you have a decent margin in the stack. - * - Repeat for all the thread classes in the system. - * - Turn off the debug options. - * - Done. - * . - *

Final Notes

- * Some useful info: - * - Stack overflows are the most common problems source during development, - * when in trouble with crashes or anomalous behaviors always first verify - * stack sizes. - * - The required stack size can, and very often does change when changing - * compiler vendor, compiler version, compiler options, code type (ARM - * or THUMB as example). - * - Code compiled in THUMB mode uses more stack space compared to the - * same code compiled in ARM mode. In GCC this is related to lack of tail - * calls optimizations in THUMB mode, this is probably true also in other - * compilers. - * - Speed optimized code often requires less stack space compared to space - * optimized code. Be careful when changing optimizations. - * - The interrupts space overhead on the thread stacks (@p INT_REQUIRED_STACK - * defined in @p chcore.h) is included in the total working area size - * by the system macros @p THD_WA_SIZE() and @p WORKING_AREA().
- * The correct way to reserve space into the thread stacks for interrupts - * processing is to override the @p INT_REQUIRED_STACK default value. - * Architectures with a dedicated interrupt stack do not require changes - * 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, it is best to optimize stack space - * at the very end of your development cycle. - * . - */ diff --git a/docs/src/stop_os.dox b/docs/src/stop_os.dox deleted file mode 100644 index d2434dea9..000000000 --- a/docs/src/stop_os.dox +++ /dev/null @@ -1,133 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_stop_os How to cleanly stop the OS - * Stopping the OS should not be normally required but there are scenarios - * where one might want the complete control over the system again. - * As example entering into a bootload mode, or invoking some flashing - * algorithm locked in ROM.
- * ChibiOS/RT does not have a shutdown API and there is a reason for this, - * stopping the kernel would not be enough, a well defined operations sequence - * is required.
- * The shutdown operation should always be implemented into the @p main() - * function because in that context the stack pointer is guaranteed to be - * in the area allocated by the startup code. Stopping from a thread would - * leave the stack pointer "somewhere".
- * The shutdown sequence should include the following steps, some steps - * are optional and depend on the application: - * - Safely stop critical threads. As example a thread that uses a File System - * should flush all the modified buffers to the persistent storage before - * terminating.
- * The system should be designed to request the thread termination using - * @p chThdTerminate() and then wait its termination using @p chThdWait(). - * This phase can be skipped for non-critical threads. - * - Invoke the xxxStop() method on all the active device drivers, this - * disables the interrupt sources used by the various peripherals. This - * is required in order to not have interrupts after the shutdown that - * may invoke OS primitives. - * - Invoke chSysDisable(). - * - Stop the system timer whose service routine invokes - * @p chSysTimerHandlerI(). - * - Disable any other interrupt source that may invoke OS APIs. In general - * all the interrupt sources that have handlers declared by using the - * @p CH_IRQ_HANDLER() macro. - * - Perform any application related de-initialization. - * - Invoke chSysEnable(). - * . - * Now the OS is stopped and you can safely assume there are nothing going on - * under the hood. From here you can also restart the OS after finishing your - * critical operations using the following sequence: - * - Invoke chSysDisable(). - * - Restart the system timer. - * - Reinitialize the OS by invoking @p chSysInit(). - * - Restart your device drivers using the @p xxxStart() methods. - * - Restart all your threads. - * . - *

Example

- * This is an example of an hypothetical application that have to shutdown - * the OS when a certain event is generated. - * @code -#include "ch.h" -#include "hal.h" - -/* A shutdown flag.*/ -bool_t shutdown_required; - -/* Critical thread.*/ -static void my_thread(void *p) { - - while (!chThdShouldTerminate()) { - /* Normal thread activity code.*/ - } - /* Thread de-initialization before terminating, here you put the critical - thread finalization code.*/ - return 0; -} - -/* Main program, it is entered with interrupts disabled.*/ -void main(void) { - - /* HAL initialization, you need to do this just once.*/ - halInit(); - - /* Main loop, the main() function never exits.*/ - while (TRUE) { - Thread *tp; - - shutdown_required = FALSE; - - /* ChibiOS/RT initialization. This function becomes an OS thread.*/ - chSysInit(); - - /* Starting a device driver, SD2 in this case.*/ - sdStart(&SD2, NULL); - - /* Starting our critical thread.*/ - tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256), - NORMALPRIO, my_thread, &SD2); - - /* Main thread activity into a loop.*/ - while (!shutdown_required) { - /* Main activity, OS active until a shutdown becomes necessary.*/ - } - - /* Starting the shutdown sequence.*/ - chThdTerminate(tp); /* Requesting termination. */ - chThdWait(tp); /* Waiting for the actual termination. */ - sdStop(&SD2); /* Stopping serial port 2. */ - chSysDisable(); - stop_system_timer(); - stop_any_other_interrupt(); - chSysEnable(); - - /* Now the main function is again a normal function, no more a - OS thread.*/ - do_funny_stuff(); - - /* Restarting the OS but you could also stop the system or trigger a - reset instead.*/ - chSysDisable(); - } -} - * @endcode - * As you can see it is possible to jump in and out of the "OS mode" quite - * easily. Note that this is just an example, the real code could be very - * different depending on your requirements. - */ diff --git a/docs/src/target.dox b/docs/src/target.dox deleted file mode 100644 index 9904f1426..000000000 --- a/docs/src/target.dox +++ /dev/null @@ -1,82 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page target Application Range - * @brief ChibiOS/RT Application Range. - * - @ref applications - * - @ref min_requirements - * - @ref desirable_features - * - @ref upper_limit - * . - * @section applications Application Scenarios - * ChibiOS/RT is usable in many applicative areas, as example and not limited - * to: - * - Automotive. - * - Robotic Applications. - * - Consumer Electronics. - * - Energy Management. - * - Teaching and Learning. - * - Hobby. - * . - * @section min_requirements Absolute Minimum Requirements - * A certain set of minimum system requirements must be satisfied in order to - * use ChibiOS/RT on a new architecture: - * - 8bits architecture minimum. - * - A "real" stack pointer that can be positioned anywhere in the data address - * space. The OS could be ported to architectures with an hardware stack but - * I wouldn't recommend it because the context switch would become - * ridiculously inefficient. - * - Support for maskable interrupt sources and at least an OS-dedicated timer. - * - Support for standard C89 (C99 supported) language with no - * architecture-related non-standard restrictions. Non standard mandatory - * language extensions or restrictions may result in reduced functionality - * or impossibility of use. - * - 256/512bytes RAM permanently allocated to the kernel and its two mandatory - * threads "idle" and "main", the exact amount depends on the architecture. - * This figure is not inclusive of the HAL and device drivers (non mandatory - * components). - * - 8KiB of program space for a full featured kernel scalable down to about - * 1.2KiB for reduced configurations. This figure is not inclusive of the - * HAL and device drivers (non mandatory components). - * . - * @section desirable_features Desirable Features - * - Efficient instruction set for linked lists traversal. The kernel makes - * extensive use of simple and bidirectional linked lists so the performance - * is directly affected by the supported addressing modes, number of - * registers etc. - * - Uniformly sized C pointers. - * - 2KiB RAM. - * - 16KiB ROM/Flash. - * . - * @section upper_limit Upper Recommended Limit - * The application range of ChibiOS/RT ends when one or more of the following - * features are required: - * - Separation between user code space and kernel space, both just logical or - * using a Memory Management/Protection Unit. Applications in ChibiOS/RT are - * supposed to be monolithic and trusted. The kernel and the application - * share the same address space. - * - Multiple applications. ChibiOS/RT supports the single multithreaded - * application model. - * - Multicore SMP architectures. Currently ChibiOS/RT only supports a single - * core unless running multiple distinct and separate OS instances. - * A true multicore kernel is planned for when multicore MCUs will become - * commonly available. - * . - */ diff --git a/docs/src/timing.dox b/docs/src/timing.dox deleted file mode 100644 index 14c3b14ec..000000000 --- a/docs/src/timing.dox +++ /dev/null @@ -1,91 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_timing Reliable timings using Threads - * One common task is to have threads do something at regular, scheduled, - * intervals. - * An obvious solution is to write something like this: - * @code -msg_t my_thread(void *param) { - - while (TRUE) { - do_something(); - chThdSleepMilliseconds(1000); // Fixed interval - } -} - * @endcode - * This example works well assuming that the @p do_something() execution time - * is well below the system tick period and that @p my_thread() is not - * preempted by other threads that could insert long intervals.
- * If the above conditions are not satisfied you may have @p do_something() - * executed at irregular intervals, as example:

- * T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.

- * Also note that the error increases over time and this kind of behavior can - * lead to anomalies really hard to debug. - *

A better solution

- * It is possible to rewrite the above code using absolute deadlines rather - * than fixed intervals: - * @code -msg_t my_thread(void *param) { - - systick_t time = chTimeNow(); // T0 - while (TRUE) { - time += MS2ST(1000); // Next deadline - do_something(); - chThdSleepUntil(time); - } -} - * @endcode - * Using this code @p do_something() will always be executed at an absolute - * deadline time and the error will not accumulate over time regardless of - * the execution time and delays inserted by other threads.
- * Note that this solution requires that the @p do_something() execution - * time must not exceed the deadline or the thread would stay sleeping into - * @p chThdSleepUntil(). - * - *

A different way

- * Another way to perform activities at regular intervals is the use of a - * virtual timer. Virtual timers are able to generate callbacks at scheduled - * intervals. Virtual timers are one shot timers so you need to restart them - * from within the callback if you need a periodic timer like in this case. - * @code -VirtualTimer vt; - -void do_something(void *p) { - - chVTSetI(&vt, MS2ST(1000), do_something, p); // Restarts the timer. - // Periodic code here. -} - -int main(int argc, char **argv) { - - chSysLock(); - chVTSetI(&vt, MS2ST(1000), do_something, NULL); // Starts the timer. - chSysUnlock(); - ... -} - * @endcode - * Note that the callback code is executed from within the I-Locked state (see - * @ref system_states) so you can only execute I-Class APIs from there (see - * @ref api_suffixes).
- * This solution has the advantage to not require a dedicated thread and - * thus uses much less RAM but the periodic code must have a very short - * execution time or it would degrade the overall system response time. - */ diff --git a/docs/src/wakeup.dox b/docs/src/wakeup.dox deleted file mode 100644 index b53806b78..000000000 --- a/docs/src/wakeup.dox +++ /dev/null @@ -1,148 +0,0 @@ -/* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. - - This file is part of ChibiOS/RT. - - ChibiOS/RT is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 3 of the License, or - (at your option) any later version. - - ChibiOS/RT is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . -*/ - -/** - * @page article_wakeup How to wake up a thread from an interrupt handler - * Waking up a thread after an hardware event is one of the most common tasks - * that an RTOS must be able to perform efficiently. In ChibiOS/RT there are - * several mechanisms that can be used, often each mechanism is best suited - * in a specific scenario. - * - *

Synchronously waking up a specific thread

- * A common situation is to have to synchronously wake up a specific thread. - * This can be accomplished without the use of any specific synchronization - * primitive, it uses the very efficient low level scheduler APIs, note that - * you can also optionally send a simple message from the IRQ handler to - * the thread. - * @code -static Thread *tp = NULL; - -void mythread(void *p) { - - while (TRUE) { - msg_t msg; - - // Waiting for the IRQ to happen. - chSysLock(); - tp = chThdSelf(); - chSchGoSleepS(PRSUSPENDED); - msg = chThdSelf()->p_rdymsg; // Retrieving the message, optional - chSysUnlock(); - // Perform processing here. - } -} - -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // Wakes up the thread. - chSysLockFromIsr(); - if (tp != NULL) { - tp->p_rdymsg = (msg_t)55; // Sending the message, optional - chSchReadyI(tp); - tp = NULL; - } - chSysUnlockFromIsr(). - - CH_IRQ_EPILOGUE(); -} - * @endcode - * - *

Synchronously waking up one of the waiting threads

- * Lets assume you have a queue of waiting threads, you want to wake up - * the threads one by one in FIFO order, if there are no waiting threads - * then nothing happens.
- * This can be accomplished using a @p Semaphore object initialized to zero: - * @code -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // If there is at least one waiting thread then signal it. - chSysLockFromIsr(); - if (chSemGetCounterI(&mysem) < 0) - chSemSignalI(&mysem); - chSysUnlockFromIsr(). - - CH_IRQ_EPILOGUE(); -} - * @endcode - * - *

Synchronously waking up all the waiting threads

- * In this scenario you want to synchronously wake up all the waiting threads, - * if there are no waiting threads then nothing happens.
- * This can be accomplished using a @p Semaphore object initialized to zero: - * @code -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // Wakes up all the threads waiting on the semaphore. - chSysLockFromIsr(); - chSemResetI(&mysem); - chSysUnlockFromIsr(). - - CH_IRQ_EPILOGUE(); -} - * @endcode - * - *

Asynchronously waking up a specific thread

- * If you have to asynchronously wake up a specific thread then a simple - * event flags can be used. - * @code -static Thread *tp; - -void mythread(void *p) { - - tp = chThdSelf(); - while (TRUE) { - // Checks if an IRQ happened else wait. - chEvtWaitAny((eventmask_t)1); - // Perform processing here. - } -} - -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // Wakes up the thread. - chSysLockFromIsr(); - chEvtSignalI(tp, (eventmask_t)1); - chSysUnlockFromIsr(). - - CH_IRQ_EPILOGUE(); -} - * @endcode - * - *

Asynchronously waking up one or more threads

- * By using event sources it is possible to asynchronously wake up one or more - * listener threads. The mechanism requires a single initialized - * @p EventSource object, all the threads registered as listeners on the - * event source will be broadcasted. - * @code -CH_IRQ_HANDLER(myIRQ) { - CH_IRQ_PROLOGUE(); - - // Pends an event flag on all the listening threads. - chSysLockFromIsr(); - chEvtBroadcastI(&my_event_source); - chSysUnlockFromIsr(). - - CH_IRQ_EPILOGUE(); -} - * @endcode - */ -- cgit v1.2.3 From e7e79a6ccb4f3e320b2b8b7bad1b14d65218641d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 18 Mar 2011 18:38:08 +0000 Subject: License updated. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2827 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 3 ++- docs/src/main.dox | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index bcb6a5b97..f1047b6e0 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -1,5 +1,6 @@ /* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/main.dox b/docs/src/main.dox index 76a39bff7..82b4ee243 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -1,5 +1,6 @@ /* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3 From c39d08fc2ae9c43f73114e24292520306bddde19 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 23 Sep 2011 15:48:55 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@3384 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index f1047b6e0..a0c6a4f76 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -34,8 +34,8 @@ * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). * The possible groups are: @a Sys, @a Sch, @a Time, @a VT, @a Thd, @a Sem, - * @a Mtx, @a Cond, @a Evt, @a Msg, @a SequentialStream, @a IO, @a IQ, @a OQ, - * @a Dbg, @a Core, @a Heap, @a Pool. + * @a Mtx, @a Cond, @a Evt, @a Msg, @a Reg, @a SequentialStream, @a IO, @a IQ, + * @a OQ, @a Dbg, @a Core, @a Heap, @a Pool. * * @section api_suffixes API Name Suffixes * The suffix can be one of the following: @@ -308,17 +308,20 @@ * @if LATEX_PDF * @dot digraph example { - size="5, 7"; rankdir="LR"; node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + size="5, 7"; + edge [fontname=Helvetica, fontsize=8]; start [label="Start", style="bold"]; + run [label="Running"]; ready [label="Ready"]; suspend [label="Suspended"]; sleep [label="Sleeping"]; stop [label="Stop", style="bold"]; - start -> suspend [label="chThdInit()", constraint=false]; + + start -> suspend [label="\n chThdCreateI()", constraint=false, dir=back]; start -> run [label="chThdCreate()"]; start -> ready [label="chThdCreate()"]; run -> ready [label="Reschedule", dir="both"]; @@ -335,14 +338,17 @@ digraph example { rankdir="LR"; node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"]; + edge [fontname=Helvetica, fontsize=8]; start [label="Start", style="bold"]; + run [label="Running"]; ready [label="Ready"]; suspend [label="Suspended"]; sleep [label="Sleeping"]; stop [label="Stop", style="bold"]; - start -> suspend [label="chThdInit()", constraint=false]; + + start -> suspend [label="\n chThdCreateI()", constraint=false, dir=back]; start -> run [label="chThdCreate()"]; start -> ready [label="chThdCreate()"]; run -> ready [label="Reschedule", dir="both"]; -- cgit v1.2.3 From de5dcbba856524599a8f06d3a9bdbf1b01db44c2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 21 Jan 2012 14:29:42 +0000 Subject: License text updated with new year. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@3846 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- docs/src/main.dox | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index a0c6a4f76..d2d311cfc 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011 Giovanni Di Sirio. + 2011,2012 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/main.dox b/docs/src/main.dox index 82b4ee243..71e2ef43f 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011 Giovanni Di Sirio. + 2011,2012 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3 From 184a71345c6a36a9a8664eda8fbcc3ea728267a8 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 2 Feb 2013 10:58:09 +0000 Subject: Updated license years. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@5102 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- docs/src/main.dox | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index d2d311cfc..150c62bc5 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011,2012 Giovanni Di Sirio. + 2011,2012,2013 Giovanni Di Sirio. This file is part of ChibiOS/RT. diff --git a/docs/src/main.dox b/docs/src/main.dox index 71e2ef43f..535689d22 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011,2012 Giovanni Di Sirio. + 2011,2012,2013 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3 From aef5278c9081ccbf0b5964bf1ff1951c75a09823 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 8 Jun 2013 07:19:55 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@5824 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/concepts.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 150c62bc5..f46f8b06b 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -55,7 +55,7 @@ * preempt (small parts of) the kernel code and are thus able to invoke * operating system APIs from within their handlers. The interrupt handlers * belonging to this class must be written following some rules. See the - * @ref system APIs group and the web article + * system APIs group and the web article * * How to write interrupt handlers. * - Fast Interrupts. Maskable interrupt sources with the ability -- cgit v1.2.3