LCBD_nut.h File Reference

Defines the interface of the LCB nut (Notify User of state Transitions) routines. More...

#include "LCBD/LCBD_drv.h"
#include "PBS/Q.h"
#include "PBS/LI.h"
#include "PBS/FORK.h"

Include dependency graph for LCBD_nut.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_LCBD_nut
	The notification user of transients block. More...
union	_LCBD_nut_que
	Union of the possible data structures the LCBD_nut can be linked to. More...
Defines
#define	LCBD_OK 0
	Success return code, note that this is not an LCBD message code, but may be used as one.
#define	LCBD_NUT_K_DEFAULT_PRIORITY -1
	Instructs the notification service task creation routine LCBD_nut_handler_create to use a system defined default priority.
Typedefs
typedef enum _LCBD_NUT_FATE_M	LCBD_NUT_FATE_M
	Typedef for enum _LCBD_NUT_FATE_M.
typedef _LCBD_nut	LCBD_nut
	Typedef for struct _LCBD_nut.
typedef unsigned int(*	LCBD_nut_cb )(LCBD_nut *nut, LCBD lcb, LCBD_state state)
	Signature for the callback routine to notify the user of a state transition.
typedef _LCBD_nut_que	LCBD_nut_que
	Typedef for union _LCBD_nut_que.
typedef LI_head	LCBD_nut_head
	Typedef for the type of que head that LCBD_nut_post posts to and LCBD_nut_pendW pulls from.
Enumerations
enum	_LCBD_NUT_FATE_M { LCBD_NUT_FATE_M_KEEP = (1 << 0), LCBD_NUT_FATE_M_STOP = (1 << 1) }
	Enumerates the option bits that can be set on the return value of the user notification routine. More...
Functions
unsigned int	LCBD_nut_handler_create (LCBD lcb, int priority)
	Creates the notification handler task.
unsigned int	LCBD_nut_que_install (LCBD lcb, FORK_que *que)
	Installs the specified fork que.
unsigned int	LCBD_nut_cancel (LCBD lcb, LCBD_nut *nut)
	Cancels the specified user notification block.
unsigned int	LCBD_nut_notify (LCBD lcb, LCBD_nut *nut)
	Ques a notification block.
LCBD_state	LCBD_nut_notifyW (LCBD lcb, unsigned int states)
	Wait until the LCB driver is in one of the list of specified states.
unsigned int	LCBD_nut_head_create (LCBD_nut_head *head)
	Creates and initializes a NUT head posting que.
unsigned int	LCBD_nut_head_destroy (LCBD_nut_head *head)
	Initializes a NUT head posting que.
unsigned int	LCBD_nut_post (LCBD lcb, unsigned int states, LCBD_nut nut, LCBD_nut_head head)
	Posts a NUT block using a que as a synchronization mechanism.
LCBD_nut *	LCBD_nut_pendW (LCBD_nut_head *head)
	Pends for the next notification block on this que head.
unsigned int	LCBD_nut_fork (LCBD lcb, unsigned int states, LCBD_nut nut, FORK_que que, FORK_cb_rtn rtn)
	Ques a NUT block using a fork callback as the synchronization mechanism.
__inline void	LCBD__nut_fill (LCBD_nut nut, unsigned int states, LCBD_nut_cb rtn, void prm0, void *prm1)
	Convenience routine to fill in a NUT block.

Detailed Description

Defines the interface of the LCB nut (Notify User of state Transitions) routines.

Author:: JJRussell -- russell@slac.stanford.edu

  CVS $Id

Overview: This file implements routines for notifying the user of LCB driver state transitions. The LCB driver can be in one of a handful of states (see LCBD_state). Transitions between these states can be both synchronous or asynchronous. In a synchronous transition, the user did something in his code to cause the transitions, such as unloading the driver. In other cases (and even for threads of code running asynchronously with the thread effecting the state transition), the state change is asynchronous, such as the driver going offline because the 20MHz LATp-side clock has vanished.

: These routines allow the user to que a request to be notified when the driver enters a particular state or states.

Usage: The user allocates a Notify User of Transition block (LCBD_nut) and fills out the user portion, either by directly filling in the field members or using the inline routine LCBD__nut_fill. The critical parameters are

states, A bit mask of the states the user wishes to be notified of. These are drawn from the enumeration LCBD_state.
callback_routine, A routine to be called back when the driver is in or enters one of the states specified in the states variable. See LCBD_nut_cb for the callback sequence
callback_parameters, Two arbitrary user parameters

: Once filled in the NUT block can be que'd to the driver using LCBD_nut_que.

Pre-canned Callbacks: For convenience, 3 pre-canned synchronizing callback sequences are provided

LCBD_nut_queW, ques the NUT block and blocks the task until the condition is satified
LCBD_nut_post, ques the completed NUT block to a posting que where it is removed with LCBD_nut_pendW
LCBD_nut_fork, ques the completed NUT block to a FORK que

Synchronous Example

     // Submit a synchronous transaction
     SUBMIT_AGAIN:
     status = LCBD_submitW (xcb);

     // Check if OK
     if (status != LCBD_OK)
     {
         // Check if failed because the driver is OFFLINE
         if (status == LCBD_OFFLINE)
         {
             // Wait till the driver is ONLINE or someone unloads it 
             state = LCBD_nut_queW (lcb, (LCBD_STATE_M_ONLINE | 
                                          LCBD_STATE_M_UNLOADING);
     
             // Check if someone unloaded the driver
             if (state == LCBD_STATE_UNLOADING) return GIVE_UP;

             // Driver must be online (or at least it was at sometime)
             goto SUBMIT_AGAIN;
         }
     }

: This examples points out one of the gotcha's of using the NUT facility. Since the driver can spontaneously change state due to external events beyond softwares control (for example, the clock going away), the notification routines can only provide a good hint about what the state is at any given time. Just because the notification routines indicate that a given state was entered does not mean that it is still in that state.

Define Documentation

#define LCBD_NUT_K_DEFAULT_PRIORITY -1

Instructs the notification service task creation routine LCBD_nut_handler_create to use a system defined default priority.

This value can be used instead of a fixed numerical value to the aforementioned routines so that the tasks are created with default priorities. Note that this is only a flag value and that the default priorities are owned by the LCBD code. This means that if a new version of the driver changes these values, all code using the default values will also change. In many cases, this is exactly the correct behaviour, but in a limited number of cases (peculiar test circumstances), the user may wish tighter control. In these cases, use a fixed numerical value between 0 and 255.

Typedef Documentation

LCBD_nut

Typedef for struct _LCBD_nut.

This block encapsulates all the information needed to specify and subsequently notify the user of a driver state transition. See LCBD_state for the list of driver states that the user can be notified of when the driver is or has entered them.

unsigned int(* LCBD_nut_cb)(LCBD_nut *nut, LCBD lcb, LCBD_state state)

Signature for the callback routine to notify the user of a state transition.

Returns:
A bit mask of options drawn from LCBD_NUT_FATE_M

Parameters:

nut The user's notification block

lcb Handle to the LCB driver

state The end state causing the transition

LCBD_NUT_FATE_M

Typedef for enum _LCBD_NUT_FATE_M.

See also:
LCBD_nut_cb

The callback routine for notifying users of transitions (NUT), can a bit mask of the OR of any of the options in this enumeration.

LCBD_nut_que

Typedef for union _LCBD_nut_que.

During its journey through the system, the NUT block may find itself queued to various lists and ques. This data structure is a union of all such possible lists and ques. Since at any given time the NUT is on one and only one such que or list, this storage area can be reused by each stage.

Enumeration Type Documentation

enum _LCBD_NUT_FATE_M

Enumerates the option bits that can be set on the return value of the user notification routine.

Enumeration values:

LCBD_NUT_FATE_M_KEEP Normally the NUT block is deleted after servicing the user callback. Setting this option keeps the NUT block on the que, If the block if not eventually deleted, the service task could go into an infinite loop. This is meant to be used for testing purposes only

LCBD_NUT_FATE_M_STOP Instructs the notification service task to stop processing the queue. This is extremely dangerous, since other user's will not be notified now, or possibly ever, of the transition. This is meant to be used for testing purposes only

Function Documentation

__inline void LCBD__nut_fill ( LCBD_nut * nut,

unsigned int states,

LCBD_nut_cb rtn,

void * prm0,

void * prm1

) [static]

Convenience routine to fill in a NUT block.

Parameters:

nut The NUT block to fill in

states The states to wait on

rtn Notification callback routine

prm0 Arbritary user parameter

prm1 Arbritary user parameter

unsigned int LCBD_nut_cancel ( LCBD lcb,

LCBD_nut * nut

)

Cancels the specified user notification block.

Parameters:

lcb The LCB driver handle

nut The notification user of transition block to cancel

The que will be locked for time it takes to determine whether the item is on the que.

unsigned int LCBD_nut_fork ( LCBD lcb,

unsigned int states,

LCBD_nut * nut,

FORK_que * que,

FORK_cb_rtn rtn

)

Ques a NUT block using a fork callback as the synchronization mechanism.

Returns:
Status

Parameters:

lcb The LCB driver handle

states The states to wait on

nut The NUT block to post

que The FORK que to post to

rtn The FORK dispatch routine

LCBD_notify_fork is a convenience routine prepackaging parameters needed to dispatch the complete NUT block to a FORK dispatch routine. The message received in the FORK dispatch routine is the NUT block. The nut callback parameter (nut->prm[0]) contains the LCB driver handle