---

BFO.c File Reference

Balloon Flight Output, Routines. More...

#include <errno.h>
#include <string.h>
#include <semLib.h>
#include <sockLib.h>
#include <inetLib.h>
#include <sysLib.h>
#include <tickLib.h>
#include "BBC/BUG.h"
#include "BBC/FPA.h"
#include "BBC/FORK.h"
#include "BBC/RNG.h"
#include "BFU/BFA.h"
#include "BFU/BFO.h"
#include "BFU/BFU_fileDsc.h"
#include "CCSDS/CCSDS_bfem.h"

Data Structures
struct	_BFO_biu
	Defines the parameters which control writing a sampled stream of events to the BIU. More...
struct	_BFO_biuDst
	Defines an BIU destination control structure. More...
struct	_BFO_dsk
	Defines the parameters which control writing a disk file. More...
struct	_BFO_msg
	Defines the contents of a message passed between the FORK tasks. More...
struct	_BFO_ocb
	The Output Control Block. More...
struct	_BFO_stats
	Defines an IO statistics block. More...
struct	_BFO_statsRec
	Defines an IO statistics record. More...
Defines
#define	BFO_K_BIU_MAX_PKT_SIZE   0x8000
	Limits the maximum UDP packet.
Typedefs
typedef _BFO_msg	BFO_msg
	Typedef for struct _BFO_msg.
typedef _BFO_dsk	BFO_dsk
	Typedef for struct _BFO_dsk.
typedef _BFO_statsRec	BFO_statsRec
	Typedef for struct _BFO_statsRec. More...
typedef _BFO_stats	BFO_stats
	Typedef for struct _BFO_stats. More...
typedef _BFO_biuDst	BFO_biuDst
	Typedef for struct _BFO_biuDst. More...
typedef _BFO_biu	BFO_biu
	Typedef for struct _BFO_biu.
Functions
FORK_cb_status	bfoDefault (BFO_ocb *bfo, BFO_msg *msg)
	Default Fork task handler. More...
FORK_cb_status	bfoFlush (BFO_ocb *bfo, BFO_msg *msg)
	Handles a FLUSH request. More...
FORK_cb_status	bfoSynch (BFO_ocb *bfo, BFO_msg *msg)
	Handles a SYNCH request. More...
FORK_cb_status	bfoWrite (BFO_ocb *bfo, BFO_msg *msg)
	Handles a WRITE request. More...
void	dskInit (BFO_dsk *dsk, BFO_dskWriteRtn wrt, RNG_rcb *rcb)
	Initializes the disk control structure. More...
int	dskWrite (BFO_dsk *dsk, const char *ptr, int nbytes)
	Controls writing data to disk. More...
void	biuInit (BFO_biu *biu)
	Initializes the BFO BIU output control structure. More...
int	biuWrite (BFO_biu *biu, BFU_fileDsc *fileDsc)
	Evaluates the number of bytes/events that the BIU can absorb and sends them. More...
int	biuWriteRecs (BFO_biuDst *dst, int nrecs, BFU_recDsc *recs, int inc, int credit)
	Evaluates the number of bytes/events that the BIU can absorb and sends them. More...
int	biuCreditCalc (const BFO_biu *biu, unsigned int curtime)
	Evaluates the number of bytes that the BIU can absorb. More...
int	biuIncCalc (const BFU_fileDsc *dsc, int credit)
	Makes a guess how many events can be sent. More...
BFO_ocb *	BFO_get (void)
	Returns a pointer to the BFO output control block. More...
int	BFO_ocb_sizeof (void)
	Returns the size of the BFO output control block. More...
int	BFO_msg_sizeof (void)
	Returns the size of a BFO message. More...
int	BFO_ocb_init (BFO_ocb *bfo, BFO_dskWriteRtn wrt, void *msgs, int msgs_size, struct _BFA_acb *acb)
	Initializes the Output Control Block. More...
int	BFO_biuDisable (BFO_ocb *bfo)
	Disables writing to the BIU sampling stream. More...
int	BFO_biuDstSet (BFO_ocb *bfo, unsigned int ip, unsigned short port)
	Sets the destination IP address. More...
int	BFO_biuEnable (BFO_ocb *bfo)
	Enables writing to the BIU sampling stream. More...
void	BFO_biuSamplingSet (BFO_ocb *bfo, int sampleRate, int limit)
	Sets the parameters controlling the BIU sampling factors. More...
void	BFO_dskBlkSizeSet (BFO_ocb *bfo, int blkSize)
	Sets the disk blocking size. More...
int	BFO_dskDisable (BFO_ocb *bfo)
	Disables writing to the disk. More...
int	BFO_dskEnable (BFO_ocb *bfo)
	Enables writing to the disk. More...
void	BFO_dskFileSet (BFO_ocb *bfo, int fd)
	Simply routine to set the current file descriptor. More...
int	BFO_dskFileGet (BFO_ocb *bfo)
	Simply query routine to return the current file descriptor. More...
int	BFO_write (BFO_ocb *bfo, struct _BFU_fileDsc *fileDsc)
	Ques a message to write the specified events to the output streams. More...
int	BFO_flush (BFO_ocb *bfo)
	Ques a message to flush data from all internal BFO buffers. More...
int	BFO_synch (BFO_ocb *bfo)
	Attempts to ensure that all previous requests have been acted upon. More...
Variables
BFO_ocb *	Bfo_Ocb = NULL
	Internal static for the BFO context block. More...

---

Detailed Description

Balloon Flight Output, Routines.

Author:

JJRussell - russell@slac.stanford.edu

---

Typedef Documentation

BFO_biuDst

Typedef for struct _BFO_biuDst.

BFO_stats

Typedef for struct _BFO_stats. An IO statistics block consists of IO statistics records for 3 cateogories of events. 1. Those events which are too big to send. 2. Those events which were successfully sent. 3. Those events which were encountered an error when sent.

BFO_statsRec

Typedef for struct _BFO_statsRec. An IO statistics record keeps track of the number on IOs and the total size of the IOs.

---

Function Documentation

int BFO_biuDisable (  BFO_ocb *    bfo )

Disables writing to the BIU sampling stream. Parameters: bfo  The Output Control Block Return values: 0, if  the BIU was already disabled 1, if  the BIU was previously enabled.

void BFO_biuDstSet (  BFO_ocb *    bfo, unsigned int    ip, unsigned short    port )

Sets the destination IP address. Parameters: bfo  The Output Control Block ip  The destination IP address. port  The destination port number. Returns: Status.

int BFO_biuEnable (  BFO_ocb *    bfo )

Enables writing to the BIU sampling stream. Parameters: bfo  The Output Control Block Return values: 0, if  the BIU was already enabled 1, if  the BIU was previously disabled. As a side effect, this routine restores the credit limit to its maximum. There seemed to be only 2 sensible choices, setting it to 0, and starting the timer, or setting to the maximum.

void BFO_biuSamplingSet (  BFO_ocb *    bfo, int    sampleRate, int    limit )

Sets the parameters controlling the BIU sampling factors. Parameters: bfo  The Output Control Block sampleRate  The sample rate expressed in bytes/sec. This number must be less than 2**22, i.e. around 4Mbytes/sec. limit  An upper limit on the number of bytes that one can accumulate. If this is specified as 0, the it is set to the amount on can accumulate in 1 second. Sets the sampling parameters for the BIU stream. This stream is allowed to output a stream of data at no more than 'sampleRate', expressed in bytes/second. In order to not allow pauses in the flow of data to accumulate a big backlog (imagine that little to no data flows for a long period of time, then deltaT * sampleRate will be a very big number), the amount one can 'save' is limited to some amount. This is essentially the second parameter.

void BFO_dskBlkSizeSet (  BFO_ocb *    bfo, int    blkSize )

Sets the disk blocking size. Parameters: bfo  The Output Control Block blkSize  The block size, in bytes. Sets the blocking size. Output will be written to the disk only when this many bytes are accumulated or an explicit write is forced using a BFO_flush() operation.

int BFO_dskDisable (  BFO_ocb *    bfo )

Disables writing to the disk. Parameters: bfo  The Output Control Block Return values: 0, if  the writing was already disabled 1, if  the writing was previously enabled. Warning: This routine is meant to be used only in a test situation. This routine is dangerous to use unless precautions are taken. Because the output is being buffered up, arbitrary disabling can leave the state of buffer in an inconsistent state. Always make sure that all output is flushed and that no more new output is sent before a call to this routine is issued. For disk writing efficiency, the previous file should be closed out and a new one opened. This is because the writing has been stopped before a new cluster is completely filled, leaving the disk driver always reading the partial record from disk, appending the new stuff, then writing it all back out. Since the disk writing routines always submit their output in clusters, one is permanently out of synch.

int BFO_dskEnable (  BFO_ocb *    bfo )

Enables writing to the disk. Parameters: bfo  The Output Control Block Return values: 0, if  the writing was already disabled 1, if  the writing was previously enabled. Warning: See BFO_dskDisable() for usage warnings.

int BFO_dskFileGet (  BFO_ocb *    bfo )

Simply query routine to return the current file descriptor. Parameters: bfo  The Output Control Block Returns: The file descriptor This is a simply query routine to return the current file descriptor. This saves the user from having to buffer the file descriptor.

int BFO_dskFileSet (  BFO_ocb *    bfo, int    fd )

Simply routine to set the current file descriptor. Parameters: bfo  The Output Control Block fd  The file descriptor. This is a simple routine to set the current file descriptor. Note that it is the user's responsibility to ensure that all previous activity on this stream is complete. This is usually accomplished by performing a BFO_flush() followed by a BFO_synch().

int BFO_flush (  BFO_ocb *    bfo )

Ques a message to flush data from all internal BFO buffers. Parameters: bfo  The output control block to perform the flush on. Returns: Status Flushes the whatever is in the disk buffers. This only posts the last remaining piece for writing. Because this only posts a message requesting a flush, use BFO_synch() to ensure that flush message has been consumed. Warning: It is imperative that no more data be written to the disk until after this operation has been completed. The stream should be disabled and BFO_synch().

int BFO_get (  void    )

Returns a pointer to the BFO output control block. Returns: A pointer to the BFO output control block.

int BFO_msg_sizeof (  void    )

Returns the size of a BFO message. Returns: The BFO message size. This routine allows the user to control the allocation and management of the pool messages used by the BFO routines to post messages across the FORK tasks. The customary usage would be to call BFO_msg_sizeof(), multiple the returned message size by however many messages that the user wished to use, allocate the that amount of memory, and, finally pass the allocated memory and its size to BFO_ocb_init().

int BFO_ocb_init (  BFO_ocb *    bfo, BFO_dskWriteRtn    wrt, void *    msgs, int    msgs_size, struct _BFA_acb *    acb )

Initializes the Output Control Block. Parameters: bfo  The Output Control Block to initialize. wrt  The routine to perform the writing. msgs  A pool of memory to be used for the messages. msgs_size  The size of msgs area acb  The allocation control structure. Returns: Status This routine only initialize properties of the BFO which are very static, ie the are very unlikely to change as long as the BFO control structure is in existence. Other properties, such as the file to write to and the BIU sampling parameters can be changed during the BFO stream's lifetime.

int BFO_ocb_sizeof (  void    )

Returns the size of the BFO output control block. Returns: The size of the BFO output control block. Returns the size of the Output Control Block. This includes the size of the FORK and Free Packet Pool control blocks. This allows the user to control and manage the allocation of this memory.

int BFO_synch (  BFO_ocb *    bfo )

Attempts to ensure that all previous requests have been acted upon. Parameters: bfo  The output control block to synchronize. Returns: Status. Currently the only failure modes are of the irrecoverable variety, ie program error or corruption. This routine can never really ensure that all the data is actually physically on the disk. The UNIX IO routines have no mechanism to enforce such a wish. All this routine can really do is ensure that all previous messages have been acted on. What one can do is perform a BFO_flush() operation, ensuring that all data within the internal BFO buffers are sent to disk with a UNIX 'write' operation. This should then be followed by a BFO_synch(), ensuring the flush message itself has been consumed.

int BFO_write (  BFO_ocb *    bfo, struct _BFU_fileDsc *    fileDsc )

Ques a message to write the specified events to the output streams. Parameters: bfo  The Output Control Block fileDsc  The 'file' descriptor describing the events to write. Returns: Status This routine posts a message to the write the specified events to the output streams. It does not actually perform the IO itself. To ensure that this message has been consumed, call BFO_synch().

FORK_cb_status bfoDefault (  BFO_ocb *    bfo, BFO_msg *    msg )

Default Fork task handler. Parameters: bfo  The output context block. msg  The message Returns: It BUG checks, since it should never be called. This is really a placeholder. No message should ever be dispatched to this routine.

FORK_cb_status bfoFlush (  BFO_ocb *    bfo, BFO_msg *    msg )

Handles a FLUSH request. Parameters: bfo  The output context block. msg  The flush message. Returns: FORK_C_CONTINUE A flush operation attempts to move all internally buffered data to the output stream.

FORK_cb_status bfoSynch (  BFO_ocb *    bfo, BFO_msg *    msg )

Handles a SYNCH request. Parameters: bfo  The output context block. msg  The synch message. Returns: FORK_C_CONTINUE A synch operation attempts to ensure that the message que is drained, thus guaranteeing that all messages preceeding the synch request have been at least acted upon.

FORK_cb_status bfoWrite (  BFO_ocb *    bfo, BFO_msg *    msg )

Handles a WRITE request. Parameters: bfo  The output context block. msg  The write message. Returns: FORK_C_CONTINUE A write operation makes data available to the output streams. In the case of the BIU, a number of events are sampled from the posted data and immediately transferred to the BIU. In the case of the DISK, data is accumulated in the ring buffer until a cluster size is reached. When sufficient data has accumulated, a write is initialiated.

int biuCreditCalc (  const BFO_biu *    biu, unsigned int    curtime )  [static]

Evaluates the number of bytes that the BIU can absorb. Parameters: biu  The BIU control structure curtime  The current time. Returns: The number of bytes one is permitted to send. The number of bytes that the BIU can absorb is a function of the bytes/sec that are permitted to be sent to the BIU and the elapsed time. The elapsed time is calculated from the time passed in curtime and the time of the last send. This number is always limited so that one does not accumulate a vast storehouse which would result in bursty behaviour.

int biuIncCalc (  const BFU_fileDsc *    dsc, int    credit )  [static]

Makes a guess how many events can be sent. Parameters: dsc  The 'file' descriptor. credit  The number of bytes one can send. Returns: An integer indicating that one can send every n'th event.

void biuInit (  BFO_biu *    biu )  [static]

Initializes the BFO BIU output control structure. Parameters: biu  The BFO BIU structure to initialize. Initializes the BFO BIU structure. All members are set to innocous values indicating the structure has been cleared but not yet filled with meaningful values.

int biuWrite (  BFO_biu *    biu, BFU_fileDsc *    dsc )  [static]

Evaluates the number of bytes/events that the BIU can absorb and sends them. Parameters: biu  The BIU control structure dsc  The event descriptor. Returns: Status of the write operation

int biuWriteRecs (  BFO_biuDst *    dst, int    nrecs, BFU_recDsc *    recs, int    inc, int    credit )  [static]

Evaluates the number of bytes/events that the BIU can absorb and sends them. Parameters: dst  The BIU destintation control structure. nrecs  The number of valid records in \recs array. recs  An array of nrecs record descriptors. inc  Every inc 'th record will be written until the credit limit is exceeded. credit  The number of bytes that can be written. Returns: The number of unused bytes remaining in the credit limit.

void dskInit (  BFO_dsk *    dsk, BFO_dskWriteRtn    wrt, RNG_rcb *    rcb )  [static]

Initializes the disk control structure. Parameters: dsk  The disk control structure to initialize. rcb  The Ring Buffer Control Block which holds the data to be written. All members are of the disk control structure are set to innocous values indicating the structure has been cleard, but not yet filled with meaningful values.

int dskWrite (  BFO_dsk *    dsk, const char *    buf, int    nbytes )  [static]

Controls writing data to disk. Parameters: dsk  The disk control structure buf  Pointer to the buffer to be written to disk nbytes  The number of bytes to be written to disk Returns: Status of the write operation. Commits the specified number of bytes to be written to disk. If the number of bytes to be written to disk exceeds the disk blocking size, those bytes are written to disk

---

Variable Documentation

Bfo_Ocb = NULL [static]

Internal static for the BFO context block. This will be NULL until it has been initialized by BFO_ocb_init ()

---