GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> EDS / V2-11-6 > ebfio / mv2304

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » EDS » V2-11-6 » EDS » io

EBF_stream.h File Reference

EBF stream Utilities, Interface. More...

#include <EDS/io/EBF_pkts.h>
#include <EDS/LCBV.h>

Typedefs

typedef enum _EBF_STREAM_TYPE_K EBF_STREAM_TYPE_K
 Standard typedef for _enum EBF_STREAM_TYPE_K.
typedef enum _EBF_STREAM_TYPE_K EBF_streamType
 Typedef for _enum EBF_STREAM_TYPE_K, used in procedure calls.
typedef enum _EBF_STREAM_UNIT_K EBF_STREAM_UNIT_K
 Typedef for enum _EBF_STREAM_UNIT_K.
typedef enum _EBF_STREAM_UNIT_K EBF_streamUnit
 Typedef for enum _EBF_streamUnit.
typedef int(* EBF_streamDirSizer )(EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Typedef for routines that sizes an event, as specified by a directory to the output stream.
typedef int(* EBF_streamDirWriter )(EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Typedef for routines that write an event, as specified by a directory to the output stream.

Enumerations

enum  _EBF_STREAM_TYPE_K {
  EBF_STREAM_TYPE_K_FILE = 0,
  EBF_STREAM_TYPE_K_DATA = 1,
  EBF_STREAM_TYPE_K_FILESEG = 2
}
enum  _EBF_STREAM_UNIT_K {
  EBF_STREAM_UNIT_K_PKTS = 0,
  EBF_STREAM_UNIT_K_EVTS = 1
}
 Enumeration of how to treat the input stream, as packets or events. More...
enum  _EBF_STREAM_PKT_SIZE_K_MAX {
  EBF_STREAM_PKT_SIZE_K_MAX = -1,
  EBF_STREAM_PKT_SIZE_K_DEF = 0
}
 Enumerates the sentinal values used when specifying a packet size. More...

Functions

EBF_stream * EBF_streamOpen (EBF_streamType type, const void *name, int segment)
 Opens a EBF file or data for reading.
int EBF_streamRead (EBF_stream *stream)
 Reads the EBF file associated with the event stream handle istream.
int EBF_streamRewind (EBF_stream *stream)
 Sets the read pointer back to the initial point.
EBF_pkts EBF_streamLocate (const EBF_stream *stream)
 Returns a packets iterator.
int EBF_streamProcess (EBF_stream *stream, EBF_streamUnit evtsPkts, int nskip, int nprocess, LCBV_pktCb process, void *processPrm)
 Processes the specified stream of as events or packets.
EBF_stream * EBF_streamCreate (EBF_streamType type, const char *name, int maxPktSize)
 Creates a file to receive the EBF data.
int EBF_streamWrite (EBF_stream *stream, const unsigned int *data, int nwrds)
 Writes the specified data to the output fil.
int EBF_streamDirWrite (EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Writes the event described by the event directory to the output stream.
int EBF_streamEvtWrite (EBF_stream *stream, const void *evt, int nwrds)
 Routine to an event to the output stream.
int EBF_streamEvtxWrite (EBF_stream *stream, const void *evt, int nwrds, int maxPktSize)
 Routine to an event to the output stream.
int EBF_streamEvtSize (const EBF_stream *stream, int evt_size, int maxPktSize)
 For a given event size (includes the initialize packet header) returns the size, in bytes, of the output packet.
int EBF_streamDirCopy (EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Copies the packets ASIS to the output stream.
int EBF_streamPktSizeFind (const EBF_stream *stream, int evtSize, int maxPktCnt, int maxPktSize)
 Returns the packet size, in bytes, required to accommodate an output event.
int EBF_streamDirWriteSize (const EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Checks if the directory event can be written using the maximum packet size as a constraint. If it can, the routine returns the size, in bytes, of the output event.
int EBF_streamDirCopySize (const EBF_stream *stream, const EBF_dir *dir, int maxPktSize)
 Checks if the directory packets can be copied asis. If they can routine returns the size, in bytes, of the output event.
int EBF_streamChange (EBF_stream *stream, const char *name)
 Changes the stream to the new file.
int EBF_streamClose (EBF_stream *stream)
 Closes the file after it has been read.
int EBF_streamFree (EBF_stream *stream)
 Frees the memory associated with the contents of the file.

Variables

enum _EBF_STREAM_PKT_SIZE_K_MAX EBF_STREAM_PKT_SIZE_K

Detailed Description

EBF stream Utilities, Interface.

Author:
JJRussell - russell@slac.stanford.edu
    CVS $Id: EBF_stream.h,v 1.6 2011/03/25 22:16:55 russell Exp $

Routines for reading/writing files/data sections in Event Builder format.

Typedef Documentation

int(* EBF_streamDirSizer)(EBF_stream *stream, const EBF_dir *dir, int maxPktSize)

Typedef for routines that sizes an event, as specified by a directory to the output stream.

Returns:
The size, in bytes, of the output event, or -1 if this specification cannot be meet. This would happen, for example, if an EBF_streamDirCopySize was requested on an packet that exceeded the maximum packet size.
Parameters:
stream The output stream handle
dir The event directory
maxPktSize May be used to override the packet size,
See also:
EBF_STREAM_PKT_SIZE_K
  • > 0 use this as the packet size (not implemented yet)
  • == 0 use packet size specified in the stream handle
  • 1 use maximum packet size
EBF_stream currently supports two versions of an event directory sizer EBF_streamDirWriteSize and EBF_streamDirCopySize.

int(* EBF_streamDirWriter)(EBF_stream *stream, const EBF_dir *dir, int maxPktSize)

Typedef for routines that write an event, as specified by a directory to the output stream.

Returns:
Status
Parameters:
stream The output stream handle
dir The event directory
maxPktSize May be used to override the packet size,
See also:
EBF_STREAM_PKT_SIZE_K
  • > 0 use this as the packet size (not implemented yet)
  • == 0 use packet size specified in the stream handle
  • 1 use maximum packet size
EBF_stream currently supports two versions of an event directory writer, EBF_streamDirWrite and EBF_streamDirCopy.

Enumeration Type Documentation

enum _EBF_STREAM_PKT_SIZE_K_MAX

Enumerates the sentinal values used when specifying a packet size.

Enumerator:
EBF_STREAM_PKT_SIZE_K_MAX  Typedef of struct _EBF_STREAM_PKT_SIZE_K.

Use the maximum packet size

EBF_STREAM_PKT_SIZE_K_DEF  Use the default packet size set in the stream handle

enum _EBF_STREAM_TYPE_K

Enumerator:
EBF_STREAM_TYPE_K_FILE  Stream type is a file
EBF_STREAM_TYPE_K_DATA  Stream type is a data section
EBF_STREAM_TYPE_K_FILESEG  Stream type is a segmented file

enum _EBF_STREAM_UNIT_K

Enumeration of how to treat the input stream, as packets or events.

Enumerator:
EBF_STREAM_UNIT_K_PKTS  Treat the stream as a stream of packets
EBF_STREAM_UNIT_K_EVTS  Treat the stream as a stream of events

Function Documentation

int EBF_streamChange ( EBF_stream *  stream,
const char *  name 
)

Changes the stream to the new file.

Returns:
Status
Parameters:
stream The stream handle
name The name of the new file

References _EBF_stream::bdy, _EBF_streamHeader::close, _EBF_ostreamBody::file, _EBF_stream::hdr, _EBF_ostreamBody::name, _EBF_streamBody::out, and _streamCloseCbp::prm.

Referenced by ESX_change().

int EBF_streamClose ( EBF_stream *  stream  ) 

Closes the file after it has been read.

This function only closes the file after its contents have been read into memory. To free the memory associated with the contents of the file, the user must call EBF_free().

References _EBF_streamHeader::close, _EBF_stream::hdr, _streamCloseCbp::prm, and _streamCloseCbp::rtn.

Referenced by ESX_close().

EBF_stream * EBF_streamCreate ( EBF_streamType  type,
const char *  name,
int  maxPktSize 
)

Creates a file to receive the EBF data.

Returns:
The stream handle
Parameters:
type The type of stream to open EBF_STREAM_TYPE_K_FILE or EBF_STREAM_TYPE_K_DATA
name The name of the section or file to create
maxPktSize The maximum number of byte to write per packet. This number will be rounded up to the nearest 128 byte boundary in keeping with how the hardware writes data. If 0 this defaults to 4096 - 128. If greater than 4096 - 128, it defaults to 4096-128

References _EBF_stream::bdy, _EBF_streamHeader::close, _EBF_streamHeader::dir, EBF_STREAM_DIR_K_WRITE, EBF_STREAM_TYPE_K_DATA, EBF_STREAM_TYPE_K_FILE, _EBF_ostreamBody::file, _EBF_streamHeader::free, _EBF_stream::hdr, max_pkt_size(), _EBF_ostreamBody::maxPktSize, mem_alloc(), _EBF_ostreamBody::name, _EBF_streamBody::out, _streamCloseCbp::prm, _streamCloseCbp::rtn, and _EBF_streamHeader::type.

int EBF_streamDirCopy ( EBF_stream *  stream,
const EBF_dir *  dir,
int  maxPktSize 
)

Copies the packets ASIS to the output stream.

Parameters:
stream The output stream handle
dir The directory
maxPktSize May be used to override the packet size,
See also:
EBF_STREAM_PKT_SIZE_K > 0 use this as the packet size (not implemented yet) == 0 use packet size specified in the stream handle
  • 1 use maximum packet size
Note:
If the event has been reasembled, it is possible that some packets will exceed the maximum permitted. In this case the event is written using packet size specified in the stream

References _EBF_stream::bdy, EBF_streamDirWrite(), EBF_streamWrite(), max_pkt_size(), _EBF_ostreamBody::maxPktSize, _EBF_dirPktDsc::nbytes, _EBF_dirTruncated::npktDscs, _EBF_streamBody::out, _EBF_dirPktDsc::pkt, _EBF_dirTruncated::pktDscs, and _EBF_dir::truncated.

Referenced by ESX_dir_write().

int EBF_streamDirCopySize ( const EBF_stream *  stream,
const EBF_dir *  dir,
int  maxPktSize 
)

Checks if the directory packets can be copied asis. If they can routine returns the size, in bytes, of the output event.

Returns:
>0, The size, in bytes, of the output event

==-1 Event cannot be committed as is

Parameters:
stream The output stream handle
dir The directory
maxPktSize Limits the maximum packet size,
See also:
EBF_STREAM_PKT_SIZE_K
  • > 0 use this as the packet size (not implemented yet)
  • == 0 use packet size specified in the stream handle
  • - 1 use maximum packet size
Note:
If the event has been reasembled, it is possible that some packets will exceed the maximum permitted. In this case the routine returns -1

References _EBF_stream::bdy, max_pkt_size(), _EBF_ostreamBody::maxPktSize, _EBF_dirPktDsc::nbytes, _EBF_dirTruncated::npktDscs, _EBF_streamBody::out, _EBF_dirTruncated::pktDscs, and _EBF_dir::truncated.

Referenced by ESX_dir_write().

int EBF_streamDirWrite ( EBF_stream *  stream,
const EBF_dir *  dir,
int  maxPktSize 
)

Writes the event described by the event directory to the output stream.

Parameters:
stream The output event stream
dir The event directory
maxPktSize May be used to override the streams packet size,
See also:
EBF_STREAM_PKT_SIZE_K > 0 use this as the packet size (not implemented yet) == 0 use packet size specified in the stream handle
  • 1 use maximum packet size

References copy_event(), EBF_streamEvtxWrite(), _EBF_dir::evt, _EBF_dirRedux::evt_len, MAX_EVT_SIZE, _EBF_dirTruncated::npktDscs, _EBF_dir::redux, and _EBF_dir::truncated.

Referenced by EBF_streamDirCopy(), and ESX_dir_write().

int EBF_streamDirWriteSize ( const EBF_stream *  stream,
const EBF_dir *  dir,
int  maxPktSize 
)

Checks if the directory event can be written using the maximum packet size as a constraint. If it can, the routine returns the size, in bytes, of the output event.

Returns:
>0, The size, in bytes, of the output event

==-1 Event cannot be committed as is

Parameters:
stream The output stream handle
dir The directory
maxPktSize Limits the maximum packet size,
See also:
EBF_STREAM_PKT_SIZE_K
  • > 0 use this as the packet size (not implemented yet)
  • == 0 use packet size specified in the stream handle
  • - 1 use maximum packet size

References EBF_streamEvtSize(), _EBF_dirRedux::evt_len, and _EBF_dir::redux.

Referenced by ESX_dir_write().

int EBF_streamEvtSize ( const EBF_stream *  stream,
int  evt_size,
int  maxPktSize 
)

For a given event size (includes the initialize packet header) returns the size, in bytes, of the output packet.

Returns:
The number of output bytes. This is inflated by packet headers and restart cells
Parameters:
stream The output stream
evt_size The size, in bytes, of the event. This is defined to be the sum of all the contributors + the packet header
maxPktSize May be used to override the streams packet size,
See also:
EBF_STREAM_PKT_SIZE_K > 0 use this as the packet size (not implemented yet) == 0 use packet size specified in the stream handle
  • 1 use maximum packet size

References _EBF_stream::bdy, max_pkt_size(), _EBF_ostreamBody::maxPktSize, and _EBF_streamBody::out.

Referenced by EBF_streamDirWriteSize().

int EBF_streamEvtWrite ( EBF_stream *  stream,
const void *  ebf_evt,
int  len 
)

Routine to an event to the output stream.

Return values:
0 on success
errno on failure
Parameters:
stream The output stream
ebf_evt The event to write
len The length, in bytes, of the event
The event is believed to be fully prepared except that on little-endian machines, the data to be written will be 32-bit byte swapped in-mass.

This routine differs from EBF_streamEvtxWrite in that it defaults the maximum packet size to that specified in the stream handle.

References EBF_streamEvtxWrite().

int EBF_streamEvtxWrite ( EBF_stream *  stream,
const void *  ebf_evt,
int  len,
int  maxPktSize 
)

Routine to an event to the output stream.

Return values:
0 on success
errno on failure
Parameters:
stream The output stream
ebf_evt The event to write
len The length, in bytes, of the event
maxPktSize May be used to override the streams packet size > 0 use this as the packet size == 0 use packet size specified in the stream handle
  • 1 use maximum packet size
The event is believed to be fully prepared except that on little-endian machines, the data to be written will be 32-bit byte swapped in-mass.

References _EBF_stream::bdy, _EBF_ebw::bf, _EBF_edw::bf, _RestartPkt::cell, EBF_EDW_RSTATUS_K_PACKET_TRUNCATED, EBF_EDW_RSTATUS_K_SUCCESS, EBF_EDW_XSTATUS_K_SUCCESS, EBF_streamWrite(), _EBF_pktRestartCell::ebw, _EBF_ostreamBody::file, _RestartPkt::hdr, _EBF_evt::hdr, _EBF_edw_bf::len, max_pkt_size(), _EBF_ostreamBody::maxPktSize, _EBF_streamBody::out, restart_construct(), _EBF_edw_bf::rstatus, _EBF_ebw::ui, _EBF_edw::ui, _EBF_pktHdr::undef, and _EBF_edw_bf::xstatus.

Referenced by EBF_streamDirWrite(), and EBF_streamEvtWrite().

int EBF_streamFree ( EBF_stream *  stream  ) 

Frees the memory associated with the contents of the file.

Parameters:
stream The event builder stream handle
After calling EBF_free, the contents and the event builder stream handle are no longer valid.

References _EBF_streamHeader::free, _EBF_stream::hdr, and mem_free().

Referenced by ESX_close().

EBF_pkts EBF_streamLocate ( const EBF_stream *  stream  ) 

Returns a packets iterator.

Parameters:
stream The event builder stream handle
This function is called after EBF_streamRead to locate the first packet Subsequent events using EBF__pktsNext or EBF__pktsAdvance
Warning:
This routine is not valid on output streams. On output streams, this routine will return the NULL packets iterator.

References _EBF_stream::bdy, _EBF_streamBody::in, _EBF_pkts_u::p, and _EBF_istreamBody::pkts.

Referenced by EBF_streamProcess().

EBF_stream * EBF_streamOpen ( EBF_streamType  type,
const void *  name,
int  segment 
)

Opens a EBF file or data for reading.

Parameters:
type The type of stream to open
  • EBF_STREAM_TYPE_K_FILE
  • EBF_STREAM_TYPE_K_FILESEG
  • EBF_STREAM_TYPE_K_DATA If EBF_STREAM_TYPE_K_FILE is opened, the segment size argument determines whether to the file is processed as a whole or in segments. This option can be specified for at most one stream in an application. It is meant to mimic the single stream properties of the LCB event stream. Specifying EBF_STREAM_TYPE_K_FILESEG always forces the file to processed in segments. (Of course if the file size is smaller than segment, then there is only one segment. This option should always be specified when processing more than one stream, the classic example would be a compare application.
name The name of the EBF file or the address of data section to open
segment Interpretation is dependent on type. If type is
  • EBF_STREAM_TYPE_K_FILE, then this is the largest portion of the file that will be buffered on a read.
    • If this is specified as 0, then a default upper bound of ~32Mbytes will be imposed. This was select purely to avoid long delays (as the whole file is being read in) on very large files. This can be annoying, particularly when working interactively and processing only the first few events.
    • If this is specified as -1, then the there is no segmenting, and the entire file is processed at once.
    • If a value < 64Kbytes is used, the segment size will be set to 64Kbytes. (The segment size must be large enough to hold one maximally sized event).
  • EBF_STREAM_TYPE_K_DATA, then is ignored
Returns:
If successful, the file handle else, NULL

References EBF_STREAM_TYPE_K_DATA, EBF_STREAM_TYPE_K_FILE, EBF_STREAM_TYPE_K_FILESEG, fileOpen(), and map().

int EBF_streamPktSizeFind ( const EBF_stream *  stream,
int  evtSize,
int  maxPktCnt,
int  maxPktSize 
)

Returns the packet size, in bytes, required to accommodate an output event.

Returns:
The packet size, in bytes, required to accommodate an output event.
Parameters:
stream The output stream
evtSize The number of bytes in the event to be output. Includes the initial event header.
maxPktCnt The maximum number of packets allowed
maxPktSize If, this value is greater than the minimum need, use this value > 0 use this as the packet size == 0 use packet size specified in the stream handle
  • 1 use maximum packet size

References _EBF_stream::bdy, max_pkt_size(), _EBF_ostreamBody::maxPktSize, and _EBF_streamBody::out.

Referenced by ESX_dir_write().

int EBF_streamProcess ( EBF_stream *  stream,
EBF_streamUnit  evtsPkts,
int  nskip,
int  nprocess,
LCBV_pktCb  process,
void *  processPrm 
)

Processes the specified stream of as events or packets.

Return values:
=0 Processed all values requested, either hit EOF or application requested to stop
<0 Error, an errno value
=1 Application requested a pause, caller is expected to recall EBF_streamProcess to resume processing
Parameters:
stream The stream of packets to process
evtsPkts When positioning the stream, position in units of packets (EBF_STREAM_UNIT_K_PKTS) or events (EBF_STREAM_UNIT_K_EVTS).
nskip The number of packets/events to skip
nprocess The number of packets/events to process
process The LCBV processing routine
processPrm The processing parameter

References _EBF_stream::bdy, EBF__evtsFromPkts(), EBF__evtsToPkts(), EBF_evtsSetup(), EBF_pktsSetup(), EBF_STREAM_UNIT_K_PKTS, EBF_streamLocate(), EBF_streamRead(), _EBF_istreamBody::fate, fileProcess(), _EBF_streamBody::in, _EBF_istreamBody::lcb, LCBP_create(), LCBP_edm_reset(), LCBP_evt_cb_set(), LCBP_evt_enable(), LCBP_pktsConnect(), LCBP_pktsDeliver(), LCBV_PKT_FATE_M_EOF, LCBV_PKT_FATE_M_IOERR, LCBV_PKT_FATE_M_PAUSE, and _EBF_istreamBody::status.

int EBF_streamRead ( EBF_stream *  stream  ) 

Reads the EBF file associated with the event stream handle istream.

Parameters:
stream A previously opened event builder stream handle
Return values:
0,if successful
-1,if not

References _EBF_stream::bdy, _EBF_istreamBody::buf, EBF_STREAM_TYPE_K_FILE, fileRead(), _EBF_stream::hdr, _EBF_streamBody::in, _EBF_pkts_ps::pkt, _EBF_istreamBody::pkts, _EBF_pkts_u::ps, _EBF_istreamBody::seg_size, _EBF_pkts_ps::size, and _EBF_streamHeader::type.

Referenced by EBF_streamProcess().

int EBF_streamRewind ( EBF_stream *  stream  ) 

Sets the read pointer back to the initial point.

This function is a NOOP on DATA streams.

References _EBF_stream::bdy, _EBF_istreamBody::cur_pkt, _EBF_istreamBody::cur_size, _EBF_streamHeader::dir, EBF_STREAM_DIR_K_READ, EBF_STREAM_DIR_K_WRITE, EBF_STREAM_TYPE_K_FILE, _EBF_istreamBody::fate, _EBF_istreamBody::fd, _EBF_ostreamBody::file, _EBF_stream::hdr, _EBF_streamBody::in, _EBF_istreamBody::nprocess, _EBF_streamBody::out, _EBF_istreamBody::tot_left, _EBF_istreamBody::tot_size, _EBF_streamHeader::type, and _EBF_istreamBody::which.

int EBF_streamWrite ( EBF_stream *  stream,
const unsigned int *  data,
int  nwrds 
)

Writes the specified data to the output fil.

Returns:
Status
Parameters:
stream The output stream handle
data The data to write
nwrds The number of 32-bit words to write
It is assumed that the packet is in the local machine endianness. If the endianness is not BIG ENDIAN, the packet will be byte-swapped to be 32-bit big-endian.

References _EBF_stream::bdy, _EBF_ostreamBody::buf, _EBF_ostreamBody::file, and _EBF_streamBody::out.

Referenced by EBF_streamDirCopy(), and EBF_streamEvtxWrite().

Generated on Fri Dec 9 16:49:19 2011 by  doxygen 1.5.8