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

1 files changed, 39 insertions, 7 deletions

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.

  */