[Xen-changelog] More details on ordering and safety of the Xen timer API.

[Xen patchbot -unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>]

# HG changeset patch
# User kaf24@xxxxxxxxxxxxxxxxxxxx
# Node ID 10d6c1dc1bc786bbf563c0239d925a896734b8c9
# Parent  26befe042dd54cf7539a5c82449fe57938ce1fd8
More details on ordering and safety of the Xen timer API.
Most functions are safe to call after a timer structure
has been initialised to all zeroes, as long as they are
*never* called concurrently with init_timer().

Signed-off-by: Keir Fraser <keir@xxxxxxxxxxxxx>

diff -r 26befe042dd5 -r 10d6c1dc1bc7 xen/include/xen/timer.h
--- a/xen/include/xen/timer.h   Thu Feb  9 11:10:28 2006
+++ b/xen/include/xen/timer.h   Thu Feb  9 11:17:35 2006
@@ -30,15 +30,21 @@
  * All functions below can be called for any CPU from any CPU in any context.
  */
 
-/* Returns TRUE if the given timer is on a timer list. */
+/*
+ * Returns TRUE if the given timer is on a timer list.
+ * The timer must *previously* have been initialised by init_timer(), or its
+ * structure initialised to all-zeroes.
+ */
 static __inline__ int active_timer(struct timer *timer)
 {
     return (timer->heap_offset != 0);
 }
 
 /*
- * It initialises the static fields of the timer structure.
- * It can be called multiple times to reinitialise a single (inactive) timer.
+ * Initialise a timer structure with an initial callback CPU, callback
+ * function and callback data pointer. This function may be called at any
+ * time (and multiple times) on an inactive timer. It must *never* execute
+ * concurrently with any other operation on the same timer.
  */
 static __inline__ void init_timer(
     struct timer *timer,
@@ -53,21 +59,23 @@
 }
 
 /*
- * Set the expiry time and activate a timer (which must previously have been
- * initialised by init_timer).
+ * Set the expiry time and activate a timer. The timer must *previously* have
+ * been initialised by init_timer() (so that callback details are known).
  */
 extern void set_timer(struct timer *timer, s_time_t expires);
 
 /*
- * Deactivate a timer (which must previously have been initialised by
- * init_timer). This function has no effect if the timer is not currently
+ * Deactivate a timer This function has no effect if the timer is not currently
  * active.
+ * The timer must *previously* have been initialised by init_timer(), or its
+ * structure initialised to all zeroes.
  */
 extern void stop_timer(struct timer *timer);
 
 /*
- * Migrate a timer to a different CPU. The timer must have been previously
- * initialised by init_timer(). The timer may be active.
+ * Migrate a timer to a different CPU. The timer may be currently active.
+ * The timer must *previously* have been initialised by init_timer(), or its
+ * structure initialised to all zeroes.
  */
 extern void migrate_timer(struct timer *timer, unsigned int new_cpu);
 
@@ -75,11 +83,13 @@
  * Deactivate a timer and prevent it from being re-set (future calls to
  * set_timer will silently fail). When this function returns it is guaranteed
  * that the timer callback handler is not running on any CPU.
+ * The timer must *previously* have been initialised by init_timer(), or its
+ * structure initialised to all zeroes.
  */
 extern void kill_timer(struct timer *timer);
 
 /*
- * Initialisation. Must be called before any other timer function.
+ * Bootstrap initialisation. Must be called before any other timer function.
  */
 extern void timer_init(void);
 

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog