From 42476118ad82557a6acf94b61fdf396986531493 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
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.<br>
+ * 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.<br>
  * If the above conditions are not satisfied you may have @p do_something()
  * executed at irregular intervals, as example:<br><br>
  * T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.<br><br>
@@ -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.<br>
+ * 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().
+ *
+ * <h2>A different way</h2>
+ * 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).<br>
+ * 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