From 22fe505a817d26c5b88dae4f602b658498a8a18e Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
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.<br>
+ * The above example performs a signal operation on two semaphores and
+ * performs a final reschedulation. The two operations are performed
+ * atomically.<br>
  * 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.<br>
+ * If the above conditions are not satisfied you may have @p do_something()
+ * executed at irregular intevals, as example:<br><br>
+ * T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.<br><br>
+ * Also note that the error increases over time and this kind of behavior can
+ * lead anomalies really hard to debug.
+ * <h2>A better solution</h2>
+ * 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