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

docs/ch.txt

@@ -267,6 +267,7 @@
  * - @subpage article_atomic
  * - @subpage article_saveram
  * - @subpage article_interrupts
+ * - @subpage article_jitter
  * - @subpage article_timing
  */
 /** @} */

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
+ * The above example performs a signal operation on two semaphores, unlocks the
- * performs a final reschedulation. The two operations are performed
+ * last aquired mutex and finally performs a reschedulation. All the operations
- * atomically.<br>
+ * 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);
+  chSemWaitS(&Sem3);  /* May reschedule or not. */
-  chSchRescheduleS(); /* Because chSemWaitS() might not reschedule internally.*/
+  chSchRescheduleS(); /* This one reschedules if necessary. */
  
   chSysUnlock();
  * @endcode
- * In general multiple I-Class APIs can be included and the block is terminated
+ * In general multiple I-Class and (non rescheduling) S-Class APIs can be
- * by an S-Class API that performs a reschedulation. Optionally a
+ * included and the block is terminated by a rescheduling S-Class API.
- * @p chSchRescheduleS() is present at the very end of the block.
+ * An extra @p chSchRescheduleS() can be present at the very end of the block,
+ * it only reschedules if a reschedulation is still required.
  */
 /** @} */

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