WUT.h File Reference
WakeUp Timer, high resolution interrupt timers, function prototypes and public data structures.
More...
#include <PBS/TOV.h>
#include <PBS/WUT_cb.h>
|
Defines |
#define | WUT_INIT(_wut) (_wut)->state = WUT_K_ALLOCATED |
| Initializes a user allocated timer for use.
|
Typedefs |
typedef enum _WUT_state | WUT_state |
| Typedef for enum _WUT_state.
|
Enumerations |
enum | _WUT_state {
WUT_K_FREE = -2,
WUT_K_ACTIVE = -1,
WUT_K_QUEUED = 0,
WUT_K_ALLOCATED = 1,
WUT_K_CANCELLED = 2,
WUT_K_EXPIRED = 3
} |
| Enumerate the possible states of a WakeUp Timer entry. More...
|
Functions |
int | WUT_sys_adjust (long long int dnsecx) |
| Adjusts all the current entries on the WUT timer que in response to a change in the base time.
|
int | WUT_sys_init (int count) |
| One time WUT services initialization routine.
|
int | WUT_sys_connect (unsigned int keepalive, unsigned int update) |
| One time WUT connection routine to start WUT system.
|
int | WUT_sys_reset (unsigned int keepalive, unsigned int update) |
| Resets the keepalive and update times.
|
int | WUT_sys_shutdown (void) |
| Shuts down the WUT routine.
|
WUT_state | WUT_cancel (WUT_tmr *wut) |
| Cancels a WUT timer entry.
|
WUT_tmr * | WUT_create (void) |
| Allocate a WUT timer entry.
|
WUT_state | WUT_expire (WUT_tmr *wut) |
| Marks a wut timer as expire.
|
WUT_state | WUT_destroy (WUT_tmr *wut) |
| Destroys, ie frees, an unused WUT timer entry.
|
WUT_state | WUT_restart (WUT_tmr *wut, register TOV tov) |
| Restarts a WUT timer entry.
|
WUT_state | WUT_start (WUT_tmr *wut, register TOV tov, WUT_cb_routine cb, void *prm) |
| Establishes and starts a WUT timer entry.
|
WUT_state | WUT_state_get (const WUT_tmr *wut) |
| Gets the current state of the WUT timer entry.
|
TOV | WUT_tov_get (const WUT_tmr *wut) |
| Gets the current TOV of the WUT timer entry.
|
int | WUT_dec_get (void) |
| Gets the current time left till the next timer expiration.
|
unsigned int | WUT_frequency (void) |
| Gets frequency, in Hertz of the WUT clock.
|
Detailed Description
WakeUp Timer, high resolution interrupt timers, function prototypes and public data structures.
- Author:
- JJRussell - russell@slac.stanford.edu
CVS $Id: WUT.h,v 1.8 2011/03/24 23:05:44 apw Exp $
Interface file for the WakeUp Timer interrupt facility.
Define Documentation
#define WUT_INIT |
( |
_wut |
|
) |
(_wut)->state = WUT_K_ALLOCATED |
Initializes a user allocated timer for use.
- Parameters:
-
| _wut | A pointer to the user timer to initialize |
If a WUT timer is allocated in another way besides calling WUT_create, the timer must be initialized for use by calling this macro.
Referenced by wut_sys_shutdown().
Typedef Documentation
Typedef for enum _WUT_state.
The ownership of a timer handle is divided into two pieces.
When the value of the state is >= WUT_K_ALLOCATED, the user has ownership of the WUT timer handle. When the user has ownership of the WUT timer handle, it's state will not change except by user request. The user is allowed to request state changes, for example, by WUT_cancel, but there is no guarantee that these state changes will be granted.
When the value of the state is < WUT_K_ALLOCATED, the WUT services have ownership of the WUT handle. When the WUT services have ownership, the state may spontaneously change due to WUT activity.
Enumeration Type Documentation
Enumerate the possible states of a WakeUp Timer entry.
- Enumerator:
-
WUT_K_FREE |
It's back in the pool |
WUT_K_ACTIVE |
It's being serviced |
WUT_K_QUEUED |
On the active queue |
WUT_K_ALLOCATED |
It's been allocated |
WUT_K_CANCELLED |
It's been cancelled |
WUT_K_EXPIRED |
It's been serviced |
Function Documentation
Cancels a WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to cancel |
- Returns:
- The new state. If successful this is WUT_K_CANCELLED
- Cancels a WUT timer entry. Due to race conditions, this is a very tricky operation. Only timer entries in the WUT_K_QUEUED state may be cancelled. If the timer entry is not in this state, the cancel operation fails and the current state is returned to the user.
References arm_handler_nxt_wut(), _WCB::com, _Q_node::flnk, get_wut(), has_key(), lock_que(), _WUT_tmr::node, _Q_head::node, Q__unlink(), _WCB_common::que, remove_key(), _WUT_tmr::state, unlock_que(), Wcb, WUT_K_CANCELLED, and WUT_K_QUEUED.
Gets the current time left till the next timer expiration.
This primarily used as a debugging aid.
Destroys, ie frees, an unused WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to destroy |
- Returns:
- If successful, WUT_K_FREE, else its current state.
- A WUT timer entry can only be destroyed, ie returned to the free list, if it is in the state
- WUT_K_ALLOCATED
- WUT_K_CANCELLED
- WUT_K_EXPIRED
- or if it being destroyed as part of its ISR callback routine.
- The user should ensure the timer entry was destroyed by checking that the returned state is WUT_K_FREE. Note that this value may also be returned if the timer entry was already in the the freed state.
References _WCB::com, _WCB_common::fcb, FPA_free(), has_key(), remove_key(), _WUT_tmr::state, Wcb, WUT_K_ALLOCATED, and WUT_K_FREE.
Marks a wut timer as expire.
- Parameters:
-
| wut | The WUT timer entry to expire |
- Returns:
- IF successful, WUT_K_EXPIRED, else the current state
- This routine must only be called from the user's callback routine. The user must call this, or one of WUT_cancel, WUT_start or WUT_restart in his callback before calling the routine being used to synchronize with another thread of execution. If successful, the WUT timer entry will be changed from the ACTIVE state to the EXPIRED state. Once in the EXPIRED state, ownership of the timer entry is effectively transferred from the WUT facility back to the user.
- Warning:
- This mechanism should be used instead of passing back WUT_K_STATE_CHANGED_YES or WUT_K_STATE_CHANGED_NO from the user's callback routine. This mechanism will continued to be honored and will work correctly on platforms where the WUT callback routine executes in a higher priority thread (for us VxWorks and not any of the host platforms. So to be portable and correct, use this call in lieu of the return code. The return code in portable code should now always be WUT_K_STATE_CHANGED_YES.
This call is necessary on platforms on POSIX platforms that do not support task priorities. On these platforms, the WUT timer cannot be protected by having the callback routine run in a higher priority thread. This means that WUT driver servicing the timer que cannot touch the WUT timer after the user's callback has been called. If this were allowed, there is a possibility that as soon as the user calls his synchronization routine, the thread waiting on that synchronization mechanism can begin execution. In that case, the user would make the reasonable assumption that the WUT timer handle is no longer property of the WUT facility. This call effectively declares to the WUT timer entry is no longer property of the WUT facility.
- A previous implementation marked the timer entry EXPIRED after the return, thus allowing a hole between when the user called his synchronization method and when the driver marked it as inactive when the WUT timer was still property of the WUT facility. The user ownership assumption was thus violated.
- Technically the previous implementation was protected since the state of the timer was still active, thus prohibiting operations on the timer. However, while technically correct, this implementation gave the user no good method (other than spinning) to know when the timer entry went to the expired state.
References has_key(), remove_key(), _WUT_tmr::state, and WUT_K_EXPIRED.
unsigned int WUT_frequency |
( |
void |
|
) |
|
Gets frequency, in Hertz of the WUT clock.
- Returns:
- The frequency in Hertz of the WUT clock
- In principle this allows the caller to translate physical time units, like nanoseconds, into the internal time units used by the WUT facility. However, this is only a crude conversion. For more accurate conversions the TOV facility should be used. One should consider this function as for informational purposes only.
References PTS_frequency().
Restarts a WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to restart. |
| tov | The timeout value. |
- Returns:
- If successful, WUT_K_QUEUED
- Restarts an timer entry. Only inactive timer entries, ie those in the state WUT_K_ALLOCATED, WUT_K_CANCELLED and WUT_K_EXPIRED may be restarted or WUT_restart is being called from the timer entries callback handler. If the state of the timer entry to be restarted is not one of these, the operation fails and WUT_restart() returns the state of the timer entry.
References add_wut(), has_key(), remove_key(), _WUT_tmr::state, and WUT_K_ALLOCATED.
Referenced by WUT_keepalive_rtn().
Establishes and starts a WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to restart. |
| tov | The timeout value |
| cb | The address of the WUT timer entry's callback service routine. |
| prm | A user parameter passed transparently through to the timer entry's callback service routine |
- Returns:
- If successful, WUT_K_QUEUED
- Places the WUT timer entry on the active queue. The timer entry to be started must be in one of the inactive states, ie WUT_K_ALLOCATED, WUT_K_CANCELLED or WUT_K_EXPIRED or it must own the special key, allowing it is to be started from the callback routine. If it is not in one of these conditions are true, the current state of the timer entry is returned.
- The name is a bit of a misnomer, suggesting that this routine can only be called when the timer is initially place on the active que. Although it must be called to initially place the entry on the active que, this routine can be called to at any time (provided the state permits). When called in this fashion, it behaves very similarly to WUT_restart(). The difference is that this routine allows one to reset not only a new expiration time, but also the callback routine and callback parameter.
- Used cleverly, this routine could be used to create a state machine which executes at prescribed times, and whose next expiration callback is handled by a different routine.
References add_wut(), _WUT_tmr::cb, has_key(), _WUT_tmr::prm, remove_key(), _WUT_tmr::state, and WUT_K_ALLOCATED.
Referenced by wut_sys_shutdown().
Gets the current state of the WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to get the state for. |
- Returns:
- The current state of the WUT timer entry.
- Simple query routine to return the current state of a timer entry.
- Warning:
- If the timer is in an active state or is shared amongst different threads, the state may not be static, ie it may change immediately after it is fetched. The user is responsible for using the results of this query wisely.
References remove_key(), and _WUT_tmr::state.
int WUT_sys_adjust |
( |
long long int |
dnsecx |
) |
|
Adjusts all the current entries on the WUT timer que in response to a change in the base time.
- Returns:
- The number of entries that were adjusted
- Parameters:
-
| dnsecx | The number of nanoseconds to shift the timer que entries by. |
- This is a high level system routine used to fix-up the timer entries in response to a (hopefully) one-time resetting of the underlying system clock. The call to this routine will occur when the external time is known. Since this time is potentially well after the time WUT has started, it is necessary to adjust the entries on the WUT timer que to this new base time.
- Warning:
- There is a gotcha in this and that is that all timer que entries up to this point are assumed to be relative timers. It really does not make any sense to have placed any absolute timers on the que, since, until the external time is known, one has no basis for establishing when an absolute timer will expire.
It is assumed that interrupts are locked during the course of this execution.
References _WCB::com, _Q_node::flnk, get_wut(), _Q_head::node, _WCB_common::que, _WUT_tmr::tov, TOV_K_FOREVER, and Wcb.
int WUT_sys_connect |
( |
unsigned int |
keepalive, |
|
|
unsigned int |
update | |
|
) |
| | |
One time WUT connection routine to start WUT system.
- Parameters:
-
| keepalive | The timeout period, in nsecs, to run the keepalive timer. |
| update | The update period. If non-zero, the WCT clock will be updated at this rate. If 0, then WCT clock will be update externally. |
- Returns:
- Status
References _WUT_tmr::cb, _WCB::com, _WUT_keepalive::ctx, _WUT_keepalive_ctx::elapsed, _WCB_common::keepalive, _WUT_tmr::node, _WUT_keepalive_ctx::period, _WUT_tmr::prm, Q_insert(), _WCB_common::que, _WUT_tmr::state, _WCB_common::terminator, _WUT_keepalive::tmr, _WUT_tmr::tov, TOV_from_nsecs(), TOV_K_FOREVER, _WUT_keepalive_ctx::update, Wcb, WUT_K_QUEUED, WUT_keepalive_rtn(), WUT_keepalive_update(), and wut_sys_connect().
Referenced by PBS_initialize2().
int WUT_sys_init |
( |
int |
count |
) |
|
One time WUT services initialization routine.
- Parameters:
-
| count | The number of available timer entries |
- Returns:
- Status
- Initializes a pool of WakeUp Timer entries. This is a one time system initialization call and establishes a fixed pool of timer entries. Enough timer entries should be configured to handle the maximum possible number of simoultaneosly outstanding requests. Timer entries are fairly cheap (~50 bytes) so one should allocate generously.
- Having said that, the prudent programmer will allocate the timer entries he needs at his start-up time and hold on to them. While this is somewhat wasteful of system resources, it beats dealing with trying to allocate a timer entry during the meat of the code, only to come up empty handed. If this stategy is uniformily adopted it should be relatively easy to establish a working number.
References _WCB_common::cnt, _WCB::com, _WCB_common::fcb, FPA_fcb_sizeof(), FPA_init(), FPA_K_PCB_AT_EOP, FPA_K_TYPE_PENDING_FIFO, init_wut(), MBA_alloc(), Q_init(), _WCB_common::que, Wcb, and wut_spc_init().
Referenced by PBS_initialize2().
int WUT_sys_reset |
( |
unsigned int |
keepalive, |
|
|
unsigned int |
update | |
|
) |
| | |
Resets the keepalive and update times.
- Returns:
- Status
- Parameters:
-
| keepalive | The timeout period, in nsecs, to run the keepalive timer. One values is recognized as special
- 0, Leave as is
- anything else, The new keepalive period
|
| update | The new update period (in nanoseconds). Three values are recognized
- -1, Remove the updater, the implication is that the caller is assuming responsibility for this function
- 0, Leave as is
- anything else, the new update time, in nanoseconds
|
- This is used to establish new values for the keepalive and update timers. This is generally used after the initial initialization of the WUT facility, when one learns the absolute wall clock time.
References _WUT_tmr::cb, _WCB::com, _WUT_keepalive::ctx, _WCB_common::keepalive, _WUT_keepalive_ctx::period, _WUT_keepalive::tmr, _WUT_keepalive_ctx::update, Wcb, WUT_keepalive_rtn(), WUT_keepalive_update(), and wut_period_set().
int WUT_sys_shutdown |
( |
void |
|
) |
|
Shuts down the WUT routine.
- Returns:
- Status, 1 indicates WUT was not started, so cannot be shutdown.
- This is definitely a dicey function. It makes no check that the WUT que is empty. That is left to the poor user to guarantee.
- Warning:
- Given the degree of difficulty reclaiming all the resources, this function should probably be regarded as a debugging aid only. It can be used when reloading PBS>
- If one does call it from a real piece of code, then the user is obligated to cancel any and all WUT timers. In addition, any timers allocated from the WUT pool should be returned. This last step is not strictly necessary. WUT knows where all its timer entries are so it will free them whether the user does or doesn't. Freeing the timers is just for clean-living.
References _WCB::com, _WCB_common::fcb, MBA_free(), Wcb, and wut_sys_shutdown().
Referenced by PBS_shutdown().
Gets the current TOV of the WUT timer entry.
- Parameters:
-
| wut | The WUT timer entry to get the TOV for. |
- Returns:
- The current TOV of the WUT timer entry.
- Simply query routine to return the current state of a timer entry.
- Warning:
- If the timer is in an active state or is shared amongst different threads, the TOV may not be static, ie it may change immediately after it is fetched. The user is responsible for using the results of this query wisely.
References remove_key(), and _WUT_tmr::tov.