iPXE
retry.h
Go to the documentation of this file.
00001 #ifndef _IPXE_RETRY_H
00002 #define _IPXE_RETRY_H
00003 
00004 /** @file
00005  *
00006  * Retry timers
00007  *
00008  */
00009 
00010 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00011 
00012 #include <ipxe/list.h>
00013 
00014 /** Default minimum timeout value (in ticks) */
00015 #define DEFAULT_MIN_TIMEOUT ( TICKS_PER_SEC / 4 )
00016 
00017 /** Default maximum timeout value (in ticks) */
00018 #define DEFAULT_MAX_TIMEOUT ( 10 * TICKS_PER_SEC )
00019 
00020 /** A retry timer */
00021 struct retry_timer {
00022         /** List of active timers */
00023         struct list_head list;
00024         /** Timer is currently running */
00025         unsigned int running;
00026         /** Timeout value (in ticks) */
00027         unsigned long timeout;
00028         /** Minimum timeout value (in ticks), or zero to use default
00029          *
00030          * The timeout will never be reduced below this value.
00031          */
00032         unsigned long min;
00033         /** Maximum timeout value (in ticks), or zero to use default
00034          *
00035          * The timeout will be deemed permanent (according to the
00036          * failure indicator passed to expired()) when it exceeds this
00037          * value.
00038          */
00039         unsigned long max;
00040         /** Start time (in ticks) */
00041         unsigned long start;
00042         /** Retry count */
00043         unsigned int count;
00044         /** Timer expired callback
00045          *
00046          * @v timer     Retry timer
00047          * @v fail      Failure indicator
00048          *
00049          * The timer will already be stopped when this method is
00050          * called.  The failure indicator will be True if the retry
00051          * timeout has already exceeded @c max_timeout.
00052          */
00053         void ( * expired ) ( struct retry_timer *timer, int over );
00054         /** Reference counter
00055          *
00056          * If this interface is not part of a reference-counted
00057          * object, this field may be NULL.
00058          */
00059         struct refcnt *refcnt;
00060 };
00061 
00062 /**
00063  * Initialise a timer
00064  *
00065  * @v timer             Retry timer
00066  * @v expired           Timer expired callback
00067  * @v refcnt            Reference counter, or NULL
00068  */
00069 static inline __attribute__ (( always_inline )) void
00070 timer_init ( struct retry_timer *timer,
00071              void ( * expired ) ( struct retry_timer *timer, int over ),
00072              struct refcnt *refcnt ) {
00073         timer->expired = expired;
00074         timer->refcnt = refcnt;
00075 }
00076 
00077 /**
00078  * Initialise a static timer
00079  *
00080  * @v expired_fn        Timer expired callback
00081  */
00082 #define TIMER_INIT( expired_fn ) {                      \
00083                 .expired = (expired_fn),                \
00084         }
00085 
00086 extern void start_timer ( struct retry_timer *timer );
00087 extern void start_timer_fixed ( struct retry_timer *timer,
00088                                 unsigned long timeout );
00089 extern void stop_timer ( struct retry_timer *timer );
00090 extern void retry_poll ( void );
00091 
00092 /**
00093  * Start timer with no delay
00094  *
00095  * @v timer             Retry timer
00096  *
00097  * This starts the timer running with a zero timeout value.
00098  */
00099 static inline void start_timer_nodelay ( struct retry_timer *timer ) {
00100         start_timer_fixed ( timer, 0 );
00101 }
00102 
00103 /**
00104  * Test to see if timer is currently running
00105  *
00106  * @v timer             Retry timer
00107  * @ret running         Non-zero if timer is running
00108  */
00109 static inline __attribute__ (( always_inline )) unsigned long
00110 timer_running ( struct retry_timer *timer ) {
00111         return ( timer->running );
00112 }
00113 
00114 /**
00115  * Set minimum and maximum timeouts
00116  *
00117  * @v timer             Retry timer
00118  * @v min               Minimum timeout (in ticks), or zero to use default
00119  * @v max               Maximum timeout (in ticks), or zero to use default
00120  */
00121 static inline __attribute__ (( always_inline )) void
00122 set_timer_limits ( struct retry_timer *timer, unsigned long min,
00123                    unsigned long max ) {
00124         timer->min = min;
00125         timer->max = max;
00126 }
00127 
00128 #endif /* _IPXE_RETRY_H */