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

3 files changed, 88 insertions, 8 deletions

diff --git a/docs/ch.txt b/docs/ch.txt
index 74436d6b5..86c1dba74 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -267,6 +267,7 @@
  * - @subpage article_atomic

  * - @subpage article_saveram

  * - @subpage article_interrupts

+ * - @subpage article_jitter

  * - @subpage article_timing

  */

 /** @} */

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

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

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

+ * A good place to start is this

+ * <a href="http://en.wikipedia.org/wiki/Jitter">Wikipedia article</a>.

+ * <h2>Jitter sources under ChibiOS/RT</h2>

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

+ *

+ * <h2>Jitter mitigation countermeasures</h2>

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

+ * mitigation actions.

+ *

+ * <h3>Hardware interrupt latency</h3>

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

+ *

+ * <h3>Interrupt service time</h3>

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

+ * Complex actions should never be performed in interrupt handlers.

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

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

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

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

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

+ *

+ * <h3>Kernel lock zones</h3>

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

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

+ *

+ * <h3>Higher priority threads activity</h3>

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

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

+ * The use of the proper synchronization mechanism (semaphores, mutexes, events,

+ * messages and so on) also helps to improve the system performance.

+ */

+/** @} */