Clarifies 'handler-style' usage of alarms
authorBarret Rhoden <brho@cs.berkeley.edu>
Mon, 25 Jul 2011 21:55:29 +0000 (14:55 -0700)
committerKevin Klues <klueska@cs.berkeley.edu>
Thu, 3 Nov 2011 00:36:05 +0000 (17:36 -0700)
Since you shouldn't use an a_waiter on the stack if you aren't sleeping.

kern/include/alarm.h
kern/src/alarm.c

index e1c6d59..0828a95 100644 (file)
  *
  * Quick howto, using the pcpu tchains:
  *     struct timer_chain *tchain = &per_cpu_info[core_id()].tchain;
- *     struct alarm_waiter a_waiter;
  * 1) To block your kthread on an alarm:
+ *     struct alarm_waiter a_waiter;
  *     init_awaiter(&a_waiter, 0);
  *     set_awaiter_rel(&a_waiter, USEC);
  *     set_alarm(tchain, &a_waiter);
  *     sleep_on_awaiter(&a_waiter);
  * 2) To set a handler to run on an alarm:
- *     init_awaiter(&a_waiter, HANDLER);
- *     set_awaiter_rel(&a_waiter, USEC);
- *     set_alarm(tchain, &a_waiter);
- * If you want the HANDLER to run again, do this at the end of it::
+ *     struct alarm_waiter *waiter = kmalloc(sizeof(struct alarm_waiter), 0);
+ *     init_awaiter(waiter, HANDLER);
+ *     set_awaiter_rel(waiter, USEC);
+ *     set_alarm(tchain, waiter);
+ * If you want the HANDLER to run again, do this at the end of it:
  *     set_awaiter_rel(waiter, USEC);
  *     set_alarm(tchain, waiter);
+ *     kfree(waiter);
+ * In the future, we might have a slab for these.  You can get it from wherever
+ * you want, just don't use the stack for handler style, since you'll usually
+ * return and pop up the stack after setting the alarm.
  * */
 
 #ifndef ROS_KERN_ALARM_H
index 22bb4d3..fcfc828 100644 (file)
@@ -128,7 +128,7 @@ void trigger_tchain(struct timer_chain *tchain)
                        TAILQ_REMOVE(&tchain->waiters, i, next);
                        /* Don't touch the waiter after waking it, since it could be in use
                         * on another core (and the waiter can be clobbered as the kthread
-                        * unwinds its stack). */
+                        * unwinds its stack).  Or it could be kfreed */
                        wake_awaiter(i);
                } else {
                        break;