ia64/xen-unstable

changeset 8807:10d6c1dc1bc7

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@xensource.com>
author kaf24@firebug.cl.cam.ac.uk
date Thu Feb 09 12:17:35 2006 +0100 (2006-02-09)
parents 26befe042dd5
children 0a404794aac1
files xen/include/xen/timer.h
line diff
     1.1 --- a/xen/include/xen/timer.h	Thu Feb 09 12:10:28 2006 +0100
     1.2 +++ b/xen/include/xen/timer.h	Thu Feb 09 12:17:35 2006 +0100
     1.3 @@ -30,15 +30,21 @@ struct timer {
     1.4   * All functions below can be called for any CPU from any CPU in any context.
     1.5   */
     1.6  
     1.7 -/* Returns TRUE if the given timer is on a timer list. */
     1.8 +/*
     1.9 + * Returns TRUE if the given timer is on a timer list.
    1.10 + * The timer must *previously* have been initialised by init_timer(), or its
    1.11 + * structure initialised to all-zeroes.
    1.12 + */
    1.13  static __inline__ int active_timer(struct timer *timer)
    1.14  {
    1.15      return (timer->heap_offset != 0);
    1.16  }
    1.17  
    1.18  /*
    1.19 - * It initialises the static fields of the timer structure.
    1.20 - * It can be called multiple times to reinitialise a single (inactive) timer.
    1.21 + * Initialise a timer structure with an initial callback CPU, callback
    1.22 + * function and callback data pointer. This function may be called at any
    1.23 + * time (and multiple times) on an inactive timer. It must *never* execute
    1.24 + * concurrently with any other operation on the same timer.
    1.25   */
    1.26  static __inline__ void init_timer(
    1.27      struct timer *timer,
    1.28 @@ -53,21 +59,23 @@ static __inline__ void init_timer(
    1.29  }
    1.30  
    1.31  /*
    1.32 - * Set the expiry time and activate a timer (which must previously have been
    1.33 - * initialised by init_timer).
    1.34 + * Set the expiry time and activate a timer. The timer must *previously* have
    1.35 + * been initialised by init_timer() (so that callback details are known).
    1.36   */
    1.37  extern void set_timer(struct timer *timer, s_time_t expires);
    1.38  
    1.39  /*
    1.40 - * Deactivate a timer (which must previously have been initialised by
    1.41 - * init_timer). This function has no effect if the timer is not currently
    1.42 + * Deactivate a timer This function has no effect if the timer is not currently
    1.43   * active.
    1.44 + * The timer must *previously* have been initialised by init_timer(), or its
    1.45 + * structure initialised to all zeroes.
    1.46   */
    1.47  extern void stop_timer(struct timer *timer);
    1.48  
    1.49  /*
    1.50 - * Migrate a timer to a different CPU. The timer must have been previously
    1.51 - * initialised by init_timer(). The timer may be active.
    1.52 + * Migrate a timer to a different CPU. The timer may be currently active.
    1.53 + * The timer must *previously* have been initialised by init_timer(), or its
    1.54 + * structure initialised to all zeroes.
    1.55   */
    1.56  extern void migrate_timer(struct timer *timer, unsigned int new_cpu);
    1.57  
    1.58 @@ -75,11 +83,13 @@ extern void migrate_timer(struct timer *
    1.59   * Deactivate a timer and prevent it from being re-set (future calls to
    1.60   * set_timer will silently fail). When this function returns it is guaranteed
    1.61   * that the timer callback handler is not running on any CPU.
    1.62 + * The timer must *previously* have been initialised by init_timer(), or its
    1.63 + * structure initialised to all zeroes.
    1.64   */
    1.65  extern void kill_timer(struct timer *timer);
    1.66  
    1.67  /*
    1.68 - * Initialisation. Must be called before any other timer function.
    1.69 + * Bootstrap initialisation. Must be called before any other timer function.
    1.70   */
    1.71  extern void timer_init(void);
    1.72