---

BFC.c File Reference

Balloon Flight Control, Implementation. More...

#include <vxWorks.h>
#include <stdlib.h>
#include <sysLib.h>
#include <tickLib.h>
#include <wdLib.h>
#include "BBC/FPA.h"
#include "BFU/BFC.h"

Data Structures
struct	_BFC_msgDst
	Defines a BFC message destination. More...
struct	_BFC_rto
	Defines a BFC run timeout control structure. More...
struct	_BFC_runCtl
	Encapsulates the information needed to control a run. More...
Defines
#define	BFC_M_RUN_ACTIVE
	A bit mask, where the set bits indicate states which occur during an active run. More...
#define	_TICKS(_time, _scale_factor, _ticks_per_second)   ((_time * _ticks_per_second) / _scale_factor)
	Converts a time to VxWorks Ticks. More...
Typedefs
typedef _BFC_msgDst	BFC_msgDst
	Typedef for struct _BFC_msgDst. More...
typedef _BFC_rto	BFC_rto
	Typedef for struct _BFC_rto. More...
typedef int(*	BFC_setRtn )(BFC_runCtl *rc, unsigned int value)
	Typedef for generic set routine. More...
Functions
int	destroy (BFC_runCtl *rc)
	Returns all the resources associated with the run control block. More...
int	runIsActive (BFC_runState state)
	Indicates whether the specified run state occurs while a run is active. More...
FPA_fcb *	msgsInit (int nmsgs, int msgSize)
	Initializes a fixed packet pool to contain nmsgs. More...
void	msgInit (void *unused, void *msg, int size, int loff)
	Initializes each packet as it is put on the free list. More...
void	rtoRtn (BFC_rto *rto)
	Watchdog timer routine to signal the end of a run. 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_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_maxBlimitSet (BFC_runCtl *rc, unsigned int nbytes)
	Sets the max byte limit for files. More...
int	BFC_tlimitSet (BFC_runCtl *rc, unsigned int msecs)
	Sets the time limit for the run duration. More...
int	BFC_quantitySet (BFC_runCtl *rc, BFC_quantity name, unsigned int value)
	Sets one of the run control quantities. More...
int	BFC_runIsActive (const BFC_runCtl *rc)
	Indicates whether the specified run state occurs while a run is active. More...
int	BFC_runNumberSet (BFC_runCtl *rc, unsigned int runNumber)
	Assigns the number to be to designate the next 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...
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_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_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_msgStreamInit (BFC_msgStream *mstrm, BFC_runCtl *rc, int ackTo)
	Initializes a message stream. 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...
const BFC_runInfo *	BFC_runInfoGet (const BFC_runCtl *rc)
BFC_runState	BFC_runStateGet (const BFC_runCtl *rc)
	Returns the current run state. More...
unsigned int	BFC_runNumberGet (const BFC_runCtl *rc)
	Returns the current run state. 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_tlimitGet (const BFC_runCtl *rc)
	Returns the run time limit in ticks. More...
int	BFC_maxBlimitGet (const BFC_runCtl *rc)
	Returns the max number of bytes one can ever write. More...

---

Detailed Description

Balloon Flight Control, Implementation.

Author:

JJRussell - russell@slac.stanford.edu

---

Define Documentation

#define _TICKS (  _time, _scale_factor, _ticks_per_second    )     ((_time * _ticks_per_second) / _scale_factor)

Converts a time to VxWorks Ticks. A time, _time, expressed in some units, _scale_factor, is converted to VxWorks ticks. The calculation is straightforward. ticks = (time * ticks_per_second) / scale_factor For example, if one had a time, expressed in milliseconds, then ticks = _TICKS(time_in_msecs, 1000, sysClkRateGet())

#define BFC_M_RUN_ACTIVE

Value: (((1 << (BFC_K_STATE_STOPPING - BFC_K_STATE_STARTED + 1)) -1) \ << BFC_K_STATE_STARTED) A bit mask, where the set bits indicate states which occur during an active run.

---

Typedef Documentation

BFC_msgDst

Typedef for struct _BFC_msgDst. A BFC message destination contains information to direct a message from the sender to receiver, ie the destination. The BFC command path is a full-duplex, synchronous, many-to-one arrangement. Many applications can messages to a single command handler. The command handler serially handles each message and acknowledges this by returning the original message to the sender along with a disposition status code. Since this is a synchronous protocol, the sender is blocked until the message is returned or a timeout occurs. 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_rto

Typedef for struct _BFC_rto. When a run expires on a time limit, a watchdog timer is activated. This ISR routine merely sends the appropriate signal to the BFI group.

typedef int(* BFC_setRtn)(BFC_runCtl *rc, unsigned int value)

Typedef for generic set routine. \typdef BFC_setRtn The call signature of the generic set routine is status = (*set) (BFC_runCtl *rc, int value);

---

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.

int destroy (  BFC_runCtl *    rc )  [static]

Returns all the resources associated with the run control block. Parameters: rc  The run control structure. Return values: -1, always.  This is not a wind down routine. It is only a convenience routine used to return resources if the initialization sequence fails.

void msgInit (  void *    unused, void *    msg, int    size, int    loff )  [static]

Initializes each packet as it is put on the free list. Parameters: unused  An unused user context parameter. msg  The message packet to initialize size  The size of the message packet loff  The byte offset to the control links

FPA_fcb * msgsInit (  int    nmsgs, int    msgSize )  [inline, static]

Initializes a fixed packet pool to contain nmsgs. Parameters: nmsgs  The number of messages to place in the pool. msgSize  The size, in bytes, of a single message. Returns: The handle of the newly created FPA pool.

void rtoRtn (  BFC_rto *    rto )  [static]

Watchdog timer routine to signal the end of a run. Parameters: rc  The run control structure. This is the watchdog ISR routine to handle delivering an end of run due to time limit signal.

int runIsActive (  BFC_runState    state )  [inline, static]

Indicates whether the specified run state occurs while a run is active. Parameters: state  The run state to test. 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.

---