---

BFC.h File Reference

Balloon Flight Control, Interface. More...

#include "BBC/LLI.h"
#include "BFU/BFI.h"

Data Structures
struct	_BFC_msg
	A standard BFC message. More...
struct	_BFC_msgStream
	Defines a BFC message stream. More...
struct	_BFC_runInfo
	The publically defined portion of the run control structure. More...
Typedefs
typedef enum _BFC_runState	BFC_runState
	Typedef for the enum _BFC_runState. More...
typedef enum _BFC_status	BFC_status
	Typedef of enum _BFC_status. More...
typedef _BFC_runCtl	BFC_runCtl
	Typedef for struct _BFC_runCtl. More...
typedef enum _BFC_quantity	BFC_quantity
	Typedef of the enum _BFC_quantity. More...
typedef _BFC_runInfo	BFC_runInfo
	Typedef of struct _BFC_runInfo. More...
typedef enum _BFC_msgState	BFC_msgState
	Typedef for the enum _BFC_msgState. More...
typedef _BFC_msgStream	BFC_msgStream
	Typedef for struct _BFC_msgStream. More...
typedef _BFC_msg	BFC_msg
	Typedef for struct _BFC_msg. More...
typedef int(*	BFC_runUsrRtn )(void *prm1, void *prm2)
	Signature for a state transition user callback routine. More...
Enumerations
enum	_BFC_runState {   BFC_K_STATE_FAILED = 0x00,   BFC_K_STATE_INITING = 0x01,   BFC_K_STATE_READY = 0x02,   BFC_K_STATE_STARTING = 0x03,   BFC_K_STATE_STARTED = 0x04,   BFC_K_STATE_PAUSING = 0x05,   BFC_K_STATE_PAUSED = 0x06,   BFC_K_STATE_RESUMING = 0x07,   BFC_K_STATE_UNUSED = 0x08,   BFC_K_STATE_STOPPING = 0x09,   BFC_K_STATE_STOPPED = 0x0a }
	Indicates the current state of the run. More...
enum	_BFC_status {   BFC_C_SUCCESS = 0,   BFC_C_WRONG_STATE = 0xFFFF8000,   BFC_C_BAD_NAME = 0xFFFF8020,   BFC_C_MSG_ERROR = 0xFFFF8021 }
	Enumeration of the return status codes. More...
enum	_BFC_quantity {   BFC_K_QUANTITY_MIN = 0,   BFC_K_QUANTITY_BLIMIT = 1,   BFC_K_QUANTITY_ELIMIT = 2,   BFC_K_QUANTITY_TLIMIT = 3,   BFC_K_QUANTITY_RUN_NUMBER = 4,   BFC_K_QUANTITY_MAX = 5 }
	The names of various run control parameters/quantities. More...
enum	_BFC_msgState {   BFC_K_MSGSTATE_FREE = 0,   BFC_K_MSGSTATE_ALLOCATED = 1,   BFC_K_MSGSTATE_SENT = 2,   BFC_K_MSGSTATE_RECEIVED = 3,   BFC_K_MSGSTATE_ACKNOWLEDGED = 4,   BFC_K_MSGSTATE_RETURNED = 5 }
	Enumerates the current state of the message. More...
Functions
int	BFC_msgStreamInit (BFC_msgStream *mstrm, BFC_runCtl *rc, int ackTo)
	Initializes a message stream. More...
BFC_msg *	BFC_msgAllocate (BFC_msgStream *mstrm, int timeout)
	Allocates a command message. More...
int	BFC_msgQue (BFC_msgStream *mstrm, BFC_msg *msg, unsigned int type, unsigned int prm)
	Ques a previously allocate message. More...
int	BFC_msgSend (BFC_msgStream *mstrm, unsigned int type, unsigned int prm)
	Sends a message to the event taking task. More...
BFC_msg *	BFC_msgReceive (BFC_runCtl *rc)
	Returns the message at the head of the send message que. More...
int	BFC_msgAcknowledge (BFC_msg *msg, int status)
	Acknowledges the receipt of the specified message. More...
int	BFC_configure (BFC_runCtl *rc, unsigned int elimit, unsigned int tlimit, unsigned int blimit)
	Convenience routine to set up some of the initial parameters. More...
BFC_runCtl *	BFC_get (void)
	Return a handle to the run control structure. More...
int	BFC_init (BFC_runCtl *rc, BFI_group group, unsigned int rto_signal, unsigned int msg_signal, int nmsgs, int msgSize)
	Initializes a previously allocated BFC run control structure. More...
int	BFC_quantitySet (BFC_runCtl *rc, BFC_quantity name, unsigned int value)
	Sets one of the run control quantities. More...
int	BFC_blimitSet (BFC_runCtl *rc, unsigned int nbytes)
	Sets the byte limit for the run duration. More...
int	BFC_elimitSet (BFC_runCtl *rc, unsigned int nevts)
	Sets the event limit for the run duration. More...
int	BFC_tlimitSet (BFC_runCtl *rc, unsigned int msecs)
	Sets the time limit for the run duration. More...
int	BFC_maxBlimitSet (BFC_runCtl *rc, unsigned int nbytes)
	Sets the max byte limit for files. More...
int	BFC_runNumberSet (BFC_runCtl *rc, unsigned int runNumber)
	Assigns the number to be to designate the next run. More...
int	BFC_runUpdate (BFC_runCtl *rc, unsigned int nevts, unsigned int nbytes)
	Updates the number of bytes of data taken during this run. More...
int	BFC_runStart (BFC_runCtl *rc, BFC_runUsrRtn usr, void *prm1, void *prm2)
	Starts a run. More...
int	BFC_runPause (BFC_runCtl *rc, BFC_runUsrRtn usr, void *prm1, void *prm2)
	Pause a run. More...
int	BFC_runResume (BFC_runCtl *rc, BFC_runUsrRtn usr, void *prm1, void *prm2)
	Pause a run. More...
int	BFC_runStop (BFC_runCtl *rc, BFC_runUsrRtn usr, void *prm1, void *prm2)
	Stops a run. More...
BFC_runState	BFC_runStateGet (const BFC_runCtl *rc)
	Returns the current run state. More...
int	BFC_runIsActive (const BFC_runCtl *rc)
	Indicates whether the specified run state occurs while a run is active. More...
const BFC_runInfo *	BFC_runInfoGet (const BFC_runCtl *rc)
int	BFC_tlimitGet (const BFC_runCtl *rc)
	Returns the run time limit in ticks. More...
int	BFC_timeLeftGet (const BFC_runCtl *rc)
	Returns the time left in the current run. More...
int	BFC_nbytesLeftGet (const BFC_runCtl *rc)
	Returns the number of bytes to be accumulated before the current run is finished. More...
int	BFC_nevtsLeftGet (const BFC_runCtl *rc)
	Returns the number of events to be accumulated before the current run is finished. More...
int	BFC_maxBlimitGet (const BFC_runCtl *rc)
	Returns the max number of bytes one can ever write. More...
unsigned int	BFC_runNumberGet (const BFC_runCtl *rc)
	Returns the current run state. More...

---

Detailed Description

Balloon Flight Control, Interface.

Author:

JJRussell - russell@slac.stanford.edu

This defines what is commonly thought of as run control for the Balloon Flight.

---

Typedef Documentation

BFC_msg

Typedef for struct _BFC_msg. While this is not strictly part of run control, it is used almost exclusively to when sending a run control message between a command interpreter and the command action routine. See BFC_msgAllocate(), VFC_msgQue(), BFC_msgReceive(), BFC_msgSend ().

BFC_msgState

Typedef for the enum _BFC_msgState. A message can be in one of a number of states. This is meant primarily as a debugging aid, but could prove useful to recover timed out messages. The normal lifecycle of a message is FREE - It is on the free list ALLOCATED - It has been allocated and is being composed SENT - It is now composed and being sent RECEIVED - It has been received a the destination ACKNOWLEDGED - It has been acted upon and is being returned RETURNED - It has been returned. The routines responsiblbe for these state transitions are FREE => ALLOCATED BFC_msgAllocate() ALLOCATED => SENT BFC_msgSend(), BFC_msgQue() SENT => RECEIVED BFC_msgReceive() RECEIVED => ACKNOWLEDGED BFC_msgAcknowledge() ACKNOWLEDGED => RETURNED BFC_msgSend(), BFC_msgQue() (completion) RETURNED => FREE BFC_msgSend(), BFC_msgQue() (completion) Because of the synchronous nature of some the protocal, some of these state transitions can only be seen during the execution of the BFC_msg routines. For example, when a message is returned, it goes from ACKNOWLEDGED => RETURNED => FREE within BFC_msgSend() or BFC_msgQue().

BFC_msgStream

Typedef for struct _BFC_msgStream. A BFC message stream is used to establish a full duplex communication path between a sender and a receiver. The receiver in this case is the application which fields run control requests. The sender is any application which wishes to send a run control request. Since the exchange of information is deemed to be synchronous, a application must send a request to the command handler. The sender then is blocked until the this request has been handled. After handling the request, the command handler returns the original message to the sender along with the completion status of the command. This unblocks the sender. The message stuff is strictly not part of the Run Control, but finds its must usage there. This stuff should really be split off to its own facility, but there is no time at this point.

BFC_quantity

Typedef of the enum _BFC_quantity. This enumeration is used to specify which quantity is being set when using the generic BFC_quantitySet() routine.

BFC_runCtl

Typedef for struct _BFC_runCtl. This contains all the information, both dynamic and static needed to control a run. It includes state information and the control structures needed to pass requests and acknowledgements between processes. Access to this structure is strictly controlled via a call interface, although one of the calls allows direct readout only access to the state information.

BFC_runInfo

Typedef of struct _BFC_runInfo. Readonly access to this structure is obtained using BFC_runInfoGet(). The caller is then allowed to examine the current state of the run control parameters, but not set them. Setting them requires going through one of the more formal interfaces, such as BFC_blimitSet() or the generic BFC_quantitySet(). Given that these are dynamic quantities, the caller is encouraged to use them wisely and to understand the conditions and environment to determine viability.

BFC_runState

Typedef for the enum _BFC_runState. This enumerates the state of the run. The group breaks into two distinct classes, resting states and transitory states. One normally finds the run in one of the resting states, either STARTED, PAUSED or STOPPED. The transitory states capture the transition of one state to the next. This is useful because it may take a finite amount to time to make the transition. Until the transition is complete, the meaning of some variables may be undefined.

BFC_runUsrRtn

Signature for a state transition user callback routine. A user start transition callback routine is activitated when one of the run control routines, BFC_runStart(), BFC_runPause(), BFC_runResume() or BFC_runStop() is called. This allows these routines to perform a set of integrity checks to determine if the transition is permitted, call an action routine to perform user specific actions associated with the transition, then complete the transition upon success.

BFC_status

Typedef of enum _BFC_status. A modest attempt at providing semi-unique status codes for BFC.

---

Enumeration Type Documentation

enum _BFC_msgState

Enumerates the current state of the message. Enumeration values: BFC_K_MSGSTATE_FREE  Message is on the free list BFC_K_MSGSTATE_ALLOCATED  Message has been allocated BFC_K_MSGSTATE_SENT  Message has been sent BFC_K_MSGSTATE_RECEIVED  Message has been received BFC_K_MSGSTATE_ACKNOWLEDGED  Message has been acknowledged BFC_K_MSGSTATE_RETURNED  Message has been returned

enum _BFC_quantity

The names of various run control parameters/quantities. Enumeration values: BFC_K_QUANTITY_MIN  Anything LE this is invalid BFC_K_QUANTITY_BLIMIT  Byte limit BFC_K_QUANTITY_ELIMIT  Event limit BFC_K_QUANTITY_TLIMIT  Time limit BFC_K_QUANTITY_RUN_NUMBER  Run number BFC_K_QUANTITY_MAX  Anything GE this is invalid

enum _BFC_runState

Indicates the current state of the run. Enumeration values: BFC_K_STATE_FAILED  Initialization failed BFC_K_STATE_INITING  Run state is being initialized BFC_K_STATE_READY  Ready to run BFC_K_STATE_STARTING  Run is being started BFC_K_STATE_STARTED  Running BFC_K_STATE_PAUSING  Run is being paused BFC_K_STATE_PAUSED  Paused, basically run in progress, but triggers temporarily disabled BFC_K_STATE_RESUMING  Run is being resumed BFC_K_STATE_UNUSED  Not used (resumed == STARTED) BFC_K_STATE_STOPPING  Run is being stopped BFC_K_STATE_STOPPED  Run is stopped

enum _BFC_status

Enumeration of the return status codes. Enumeration values: BFC_C_SUCCESS  Call was successful BFC_C_WRONG_STATE  System was in the wrong state low 4 bits give the state BFC_C_BAD_NAME  Bad name,quantity set/get routines BFC_C_MSG_ERROR  Error in sending a message

---

Function Documentation

int BFC_blimitSet (  BFC_runCtl *    rc, unsigned int    nbytes )

Sets the byte limit for the run duration. Parameters: rc  The run control structure. nbytes  The byte limit. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. The byte limit can only be set when a run is not in progress. Attempts to set the time limit when the run is in progress will be rejected. The run will be automatically ended when the byte limit is exceeded. Given that data is written to disk in units of complete events, one should not expect that precisely this number of bytes will be written. The run will be ended as soon as this threshold is crossed. If this number is specified as 0, then no byte limit will be imposed. This number is ultimately limited by the 'max_blimit'. This is limiting is not down until a run is actually started. This preserves the set value for as long as possible. This is somewhat of a kludge. The right way to handle this sort of problem is to have a current limit and an active limit. The current limit is only set be this routine. The active limit is meaningful only when a run is in progress and would be the minimum of the current and maximum.

int BFC_configure (  BFC_runCtl *    rc, unsigned int    elimit, unsigned int    tlimit, unsigned int    blimit )

Convenience routine to set up some of the initial parameters. Parameters: rc  The run control structure. elimit  The run duration, in number of events, May be specified as 0, in which case there is no time limit on the run. tlimit  The run duration, in milliseconds. May be specified as 0, in which case there is no time limit on the run. blimit  The run duration, in bytes. May be specified as as 0, in which case there is no byte limit on the run. Return values: -1, if  unsuccessful. 0, if  successful. This is merely a convenience routine to set parameters which are relatively stable. These values can all be set via other means. This routine can only be called when a run is not in progress. The byte limit parameter is used to set both the current limit and the maximum limit. If the user wishes to set the limit for the current run, BFC_blimitSet() should be called.

int BFC_elimitSet (  BFC_runCtl *    rc, unsigned int    nevts )

Sets the event limit for the run duration. Parameters: rc  The run control structure. nevts  The event limit. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. The event limit can only be set when a run is not in progress. Attempts to set the event limit when the run is in progress will be rejected. The run will be automatically ended when the event limit is exceeded. Given that triggers cannot not be stopped precisely, one should not expect that precisely this number of bytes will be written. The run will be ended as soon as this threshold is crossed. If this number is specified as 0, then no event limit will be imposed.

BFC_runCtl * BFC_get (  void    )

Return a handle to the run control structure. Returns: A handle to the run control structure. This routine only returns a handle to the run control structure. It does not initialize or muck with it in anyway.

int BFC_init (  BFC_runCtl *    rc, BFI_group    group, unsigned int    rto_signal, unsigned int    msg_signal, int    nmsgs, int    msgSize )

Initializes a previously allocated BFC run control structure. Parameters: rc  The run control structure to initialize. group  The BFI synchronization group to be notified for changes in state. rto_signal  The software signals to use when requesting stop run. msg_signal  The software signals to use when sending a message. nmsgs  The number of messages to be used to buffer requests. msgSize  The size, in bytes, of a single message. Return values: -1, if  failed to initialize 0, if  successful

int BFC_maxBlimitGet (  const BFC_runCtl *    rc )

Returns the max number of bytes one can ever write. Parameters: rc  The run control structure. Return values: The  run time limit in ticks.

int BFC_maxBlimitSet (  BFC_runCtl *    rc, unsigned int    nbytes )

Sets the max byte limit for files. Parameters: rc  The run control structure. nbytes  The byte limit. Return values: 0, if  successful This number can be set anytime, but only takes effect when the next run begins. See also BFC_maxBlimitSet() If this number is specified as 0, there is no maximum in effect.

int BFC_msgAcknowledge (  BFC_msg *    msg, int    status )

Acknowledges the receipt of the specified message. Parameters: msg  The message to acknowledge. status  The disposition status of the message The specified message is acknowledged as being received and acted upon. The caller is able to specify the disposition status of the message. This routine also returns the message to the free pool. The natural consequence of this is that the user may no longer reference the the message.

BFC_msg * BFC_msgAllocate (  BFC_msgStream *    mstrm, int    timeout )

Allocates a command message. Parameters: mstrm  The message stream to allocate the message from timeout  How long to wait. (-1 => wait forever). Returns: The allocate message

int BFC_msgQue (  BFC_msgStream *    mstrm, BFC_msg *    msg, unsigned int    type, unsigned int    prm )

Ques a previously allocate message. Parameters: mstrm  The message stream to que the message to. msg  The message to que. type  The message type. prm  An arbitrary parameter to pass along with the message. Return values: BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. BFC_C_MSG_ERROR, if  unsuccessful, protocol error. 0, if  successful

BFC_msg * BFC_msgReceive (  BFC_runCtl *    rc )

Returns the message at the head of the send message que. Parameters: rc  The run control structure. Returns: A pointer to the message or NULL if no message is available. Fetches the message at the head of the que. If one only uses this routine in response to a signal that the queue is not empty, it will deliver at message. However, to be safe, the user should check for NULL.

int BFC_msgSend (  BFC_msgStream *    mstrm, unsigned int    type, unsigned int    prm )

Sends a message to the event taking task. Parameters: mstrm  The message stream to send the message on type  The message type. prm  An arbitrary parameter to pass along with the message. Return values: BFC_C_MSG_ERROR, if  unsuccessful, protocol error. 0, if  successful

BFC_msg * BFC_msgStreamInit (  BFC_msgStream *    mstrm, BFC_runCtl *    rc, int    ackTo )

Initializes a message stream. Parameters: mstrm  The message stream to initialize. rc  The run control structure. This determines the destination of the message timeout  How long to wait, in milliseconds. (-1 => wait forever). Returns: Status.

int BFC_nbytesLeftGet (  const BFC_runCtl *    rc )

Returns the number of bytes to be accumulated before the current run is finished. Parameters: rc  The run control structure. Return values: >0, the  remaining bytes. -1, indicates  no byte limit or outside a run.

int BFC_nevtsLeftGet (  const BFC_runCtl *    rc )

Returns the number of events to be accumulated before the current run is finished. Parameters: rc  The run control structure. Return values: >0, the  remaining time, in ticks. -1, indicates  no event limit or outside a run.

int BFC_quantitySet (  BFC_runCtl *    rc, BFC_quantity    name, unsigned int    value )

Sets one of the run control quantities. Parameters: rc  The run control structure. name  The name of the quantity to set. value  The value of the quantity to set. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. BFC_C_BAD_NAME, if  unsuccessful because of invalid name. These values can only be when a run is not in progress. Attempts to set them when the run is in progress will be rejected. The exact meaning of the value depends on the quantity being set. See the individual routines for the this meaning. Note that this is only a convenience routine. The more specific set routines should be used when possible. This routine supports a more generic 'set' interface routine such as that found in a command parser.

const BFC_runInfo * BFC_runInfoGet (  const BFC_runCtl *    rc )

Parameters: rc  The run control structure. Returns: A pointer to the run information block.

int BFC_runIsActive (  const BFC_runCtl *    rc )

Indicates whether the specified run state occurs while a run is active. Parameters: rc  The run control structure. Return values: 0, if  the run state does not occur when a run is active !=0, if  the run state does occur when a run is active. A run is considered active is its state is one of STARTING, STARTED, PAUSING, PAUSED or RESUMING.

unsigned int BFC_runNumberGet (  const BFC_runCtl *    rc )

Returns the current run state. Parameters: rc  The run control structure.

int BFC_runNumberSet (  BFC_runCtl *    rc, unsigned int    runNumber )

Assigns the number to be to designate the next run. Parameters: rc  The run control structure. runNumber  The run number to use. Return values: 0, if  successful -1, if  unsuccessful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. The run number can only be set when a run is not in progress. Attempts to set the run number when the run is in progress will be rejected.

int BFC_runPause (  BFC_runCtl *    rc, BFC_runUsrRtn    usr, void *    prm1, void *    prm2 )

Pause a run. Parameters: rc  The run control structure. usr  A user callback routine to perform pause run actions. prm1  A parameter passed tranparently to the user pause run routine. prm2  A parameter passed tranparently to the user pause run routine. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in.

int BFC_runResume (  BFC_runCtl *    rc, BFC_runUsrRtn    usr, void *    prm1, void *    prm2 )

Pause a run. Parameters: rc  The run control structure. usr  A user callback routine to perform resume run actions. prm1  A parameter passed tranparently to the user pause run routine. prm2  A parameter passed tranparently to the user pause run routine. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in.

int BFC_runStart (  BFC_runCtl *    rc, BFC_runUsrRtn    usr, void *    prm1, void *    prm2 )

Starts a run. Parameters: rc  The run control structure. usr  A user callback routine to perform start-up actions. prm1  A parameter passed tranparently to the user start-up routine. prm2  A parameter passed tranparently to the user start-up routine. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in.

BFC_runState BFC_runStateGet (  const BFC_runCtl *    rc )

Returns the current run state. Parameters: rc  The run control structure.

int BFC_runStop (  BFC_runCtl *    rc, BFC_runUsrRtn    usr, void *    prm1, void *    prm2 )

Stops a run. Parameters: rc  The run control structure. usr  A user callback routine to perform end run actions. prm1  A parameter passed tranparently to the user end run routine. prm2  A parameter passed tranparently to the user end run routine. Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in.

int BFC_runUpdate (  BFC_runCtl *    rc, unsigned int    nevts, unsigned int    nbytes )

Updates the number of bytes of data taken during this run. Parameters: rc  The run control structure. nevts  The number of events to add to the current total. nbytes  The number of bytes to add to the current total. Return values: BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. 0, the  request was honored, still under the limit. 1, the  request was honored, the total number of events now exceeds the requested limit. 2, the  request was honored, the total number of bytes now exceeds the requested limit. 3, the  request was honored, the total number of events and bytes now exceeds the requested limit. The number of events/bytes can only be updated when a run is in progress. Attempts to update these numbers when a run is not in progress will be rejected.

int BFC_timeLeftGet (  const BFC_runCtl *    rc )

Returns the time left in the current run. Parameters: rc  The run control structure. Return values: >0, the  remaining time, in ticks. -1, indicates  no time limit or outside a run.

int BFC_tlimitGet (  const BFC_runCtl *    rc )

Returns the run time limit in ticks. Parameters: rc  The run control structure. Return values: The  run time limit in ticks.

int BFC_tlimitSet (  BFC_runCtl *    rc, unsigned int    msecs )

Sets the time limit for the run duration. Parameters: rc  The run control structure. msecs  The time limit, in milliseconds Return values: 0, if  successful BFC_C_WRONG_STATE, if  run is in the incorrect state. The low nibble gives the state it is in. The time limit can only be when a run is not in progress. Attempts to set the time limit when the run is in progress will be rejected. If this number is specified as 0, then no time limit will be imposed.

---