EBF_stream.c File Reference

EBF File Input/Output Stream Utilities. More...

#include <EDS/io/EBF_stream.h>
#include <EDS/io/EBF_evts.h>
#include <EDS/io/EBF_pkts.h>
#include <EDS/io/EBF_pkt.ih>
#include <EDS/io/LCBP.h>
#include <EDS/EBF_dir.h>
#include <EDS/EBF_cid.h>
#include <EDS/LCBV.h>
#include <EDS/EBF_pkt.h>
#include <PBI/Endianness.h>
#include <PBI/PTR.h>
#include <stdlib.h>
#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>
#include <string.h>
#include <errno.h>

Classes

struct _streamCloseCbp

Structure to bind the close callback routine with a parameter. More...

struct _EBF_streamHeader

Standard header for both input and output streams. More...

struct _EBF_istreamBody

Internal structure used to control the input access to an EBF file or data section. More...

struct _EBF_ostreamBody

Context for an output event/packet stream. More...

union _EBF_streamBody

Union of all the stream types. More...

union _EBF_stream

Standard EBF stream handle. More...

struct _RestartPkt

Defines an EBF restart packet. More...

Defines

#define MAX_EVT_SIZE   0x10000

The maximum size, in bytes, of the data portion of an event. This includes the 8 word header but not any other overheads such restart headers and cells.

Typedefs

typedef enum _EBF_STREAM_DIR_K EBF_STREAM_DIR_K

Typedef for enum _EBF_STREAM_DIR_K.

typedef enum _EBF_STREAM_DIR_K EBF_streamDir

Typedef for enum _EBF_STREAM_DIR_K.

typedef enum _EBF_STREAM_BOUNDS_K EBF_STREAM_BOUNDS_K

Typedef for enum _EBF_STREAM_BOUNDS_K.

typedef int(* streamClose )(void *file)

Generic stream close function signature.

typedef struct _streamCloseCbp streamCloseCbp

Typedef for struct _streamCloseCbp.

typedef struct _EBF_streamHeader EBF_streamHeader

Typedef for struct _EBF_streamHeader.

typedef struct _EBF_istreamBody EBF_istreamBody

Typedef for struct _EBF_streamFileBody.

typedef struct _EBF_ostreamBody EBF_ostreamBody

Typedef for struct _EBF_ostreamBody.

typedef union _EBF_streamBody EBF_streamBody

Typedef for union _EBF_streamBody.

typedef struct _EBF_stream EBF_stream

Typedef for struct _EBF_stream.

typedef struct _RestartPkt RestartPkt

Typedef for struct _RestartPkt.

Enumerations

enum _EBF_STREAM_DIR_K {
  EBF_STREAM_DIR_K_READ = 0,
  EBF_STREAM_DIR_K_WRITE = 1
}

Enumeration of the IO direction, i.e. read or write. More...

enum _EBF_STREAM_BOUNDS_K {
  EBF_STREAM_BOUNDS_K_MAXEVT = 1 << 16,
  EBF_STREAM_BOUNDS_K_MAXPKT = 1 << 12,
  EBF_STREAM_BOUNDS_K_LOWER = EBF_STREAM_BOUNDS_K_MAXEVT,
  EBF_STREAM_BOUNDS_K_UPPER = 1 << 25,
  EBF_STREAM_BOUNDS_K_OVERFLOW = EBF_STREAM_BOUNDS_K_MAXPKT
}

Upper and lower bounds on the segment size. More...

Functions

static EBF_stream * fileOpen (EBF_streamType type, const char *fileName, int segment_size)

Opens a EBF file for reading.

static EBF_stream * map (unsigned int *ebf_data)

Prepares an in memory data structure to be read.

static void * mem_alloc (unsigned int nbytes)

Wraps the 'real' allocator.

static void mem_free (void *ptr)

Wraps the 'real' deallocator.

static __inline int max_pkt_size (unsigned int maxPktSize, unsigned int defPktSize)

Returns the maximum packet size that can actually be realized.

static __inline unsigned char * copy_event (unsigned char *cur, const EBF_dir *dir)

Composes the output event by, potentially copying the data from the original event to the output descriptor.

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

Opens a EBF file or data for reading.

static int fileRead (EBF_stream *stream, unsigned int *ptr, size_t nbytes)

Reads the specified number of bytes.

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

Processes the specified stream of as events or packets.

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.

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.

EBF_pkts EBF_streamLocate (const EBF_stream *stream)

Returns a packets iterator.

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

Changes the stream to the new file.

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

Creates a file to receive the EBF data.

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.

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

Writes the specified data to the output fil.

static __inline unsigned int restart_construct (RestartPkt *restart, const EBF_evt *evt)

Constructs a template of the packet restart header. This includes both the 8 word header and the 4 word restart cell.

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_streamDirWrite (EBF_stream *stream, const EBF_dir *dir, int maxPktSize)

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

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

Copies the packets ASIS to the output stream.

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_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_streamEvtWrite (EBF_stream *stream, const void *ebf_evt, int len)

Routine to an event to the output stream.

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

Routine to an event 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.

Detailed Description

EBF File Input/Output Stream Utilities.

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

Reads/Writes an Event Builder File or data section and makes it look like the in-memory representation of data from the event builder.


    CVS $Id

Typedef Documentation

EBF_STREAM_BOUNDS_K

Typedef for enum _EBF_STREAM_BOUNDS_K.

The lower bound must be constrained to be at least the size of the largest event.

The upper bound is really only a default used and can be easily overridden. The upper bound must be at least the size of a maximally sized event, but really is set by purely practical considerations. Since this is unit of a read, on very large files, there can be a considerable delay if this read is very large. This is annoying, particularly in the case where one working interactively and just processing the first few events. So this size is set to be something that is large enough to be accommodate most files, but small enough to keep the read latency to something tolerable on human timescales.

The overflow region is provided as an area where discontigious events may be reassembled into a contigious block of memory. As such, it must be at least the size of a maximally sized event.

Enumeration Type Documentation

enum _EBF_STREAM_BOUNDS_K

Upper and lower bounds on the segment size.

Enumerator:

EBF_STREAM_BOUNDS_K_MAXEVT	Size of maximum event
EBF_STREAM_BOUNDS_K_MAXPKT	Size of maximum packet
EBF_STREAM_BOUNDS_K_LOWER	Lower bound must be at least the size of a maximally sized event
EBF_STREAM_BOUNDS_K_UPPER	Upper bound must be at least the lower bound, choose 32Mbytes
EBF_STREAM_BOUNDS_K_OVERFLOW	Overflow area must at least the size of a maximally sized packet

enum _EBF_STREAM_DIR_K

Enumeration of the IO direction, i.e. read or write.

Enumerator:

EBF_STREAM_DIR_K_READ	Stream direction is read
EBF_STREAM_DIR_K_WRITE	Stream directory is write

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().

static EBF_stream * fileOpen	(	EBF_streamType	type,
		const char *	fileName,
		int	segmentSize
	)			`[static]`

Opens a EBF file for reading.

Parameters:

	type	The stream type, must be either EBF_STREAM_TYPE_K_FILE, this potentially offers the most efficient processing EBF_STREAM_TYPE_K_FILESEG, this should be used when 2 or more streams are needed
	fileName	The name of the EBF file to open
	segmentSize	The largest portion of the file that will be buffered on a read. If specified as 0, an upper limit of about 32Mbytes will be used. If smaller than 64Kbytes (the maximum size of an event), the segment size will be reset to 64Kbytes If specified as -1, no uppper limit will be imposed, i.e. the whole file will be processed.

Returns:: If successful, the file handle else, NULL

Referenced by EBF_streamOpen().

static int fileProcess	(	EBF_stream *	stream,
		EBF_streamUnit	evtsPkts,
		int	nskip,
		int	nprocess,
		LCBV_pktCb	process,
		void *	processPrm
	)			`[static]`

Processes the specified stream of as events or packets.

Returns:: Status

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_edw::bf, _EBF_istreamBody::buf, _EBF_istreamBody::cur_pkt, _EBF_istreamBody::cur_size, EBF__pktAdvance(), EBF__pktSize(), EBF_EDW_RSTATUS_K_PACKET_TRUNCATED, EBF_STREAM_UNIT_K_PKTS, _EBF_istreamBody::error, _EBF_istreamBody::fate, fileRead(), _EBF_streamBody::in, LCBV_PKT_FATE_M_ABORT, LCBV_PKT_FATE_M_EOF, LCBV_PKT_FATE_M_IOERR, LCBV_PKT_FATE_M_NO_MORE, LCBV_PKT_FATE_M_PAUSE, _EBF_istreamBody::nprocess, _EBF_edw_bf::rstatus, _EBF_istreamBody::seg_size, _EBF_istreamBody::tot_left, _EBF_edw::ui, and _EBF_istreamBody::which.

Referenced by EBF_streamProcess().

static int fileRead	(	EBF_stream *	stream,
		unsigned int *	ptr,
		size_t	nbytes
	)			`[static]`

Reads the specified number of bytes.

Returns:: Status

References _EBF_stream::bdy, _EBF_istreamBody::fd, _EBF_streamBody::in, and _EBF_istreamBody::name.

Referenced by EBF_streamRead(), and fileProcess().

static EBF_stream * map ( unsigned int * data ) [static]

Prepares an in memory data structure to be read.

Parameters:

data

Pointer to the in memory data structure.

Returns:: If successful, the stream handle, else NULL

References _EBF_stream::bdy, _EBF_streamHeader::close, _EBF_streamHeader::dir, EBF_STREAM_DIR_K_READ, EBF_STREAM_TYPE_K_DATA, _EBF_streamHeader::free, _EBF_stream::hdr, _EBF_streamBody::in, mem_alloc(), _EBF_pkts_ps::pkt, _EBF_istreamBody::pkts, _streamCloseCbp::prm, _EBF_pkts_u::ps, _streamCloseCbp::rtn, _EBF_pkts_ps::size, and _EBF_streamHeader::type.

Referenced by EBF_streamOpen().

static __inline int max_pkt_size	(	unsigned int	maxPktSize,
		unsigned int	defPktSize
	)			`[static]`

Returns the maximum packet size that can actually be realized.

Returns:: The maximum packet size, in bytes. This includes the EBF packet header

Parameters:

	maxPktSize	The maximum packet size as specified by the user. If > 0 use this packet size, but limit to the maximum ==0 use the default, defPktSize
	defPktSize	The default packet size to use. This should include EBF_pktHdr.

Referenced by EBF_streamCreate(), EBF_streamDirCopy(), EBF_streamDirCopySize(), EBF_streamEvtSize(), EBF_streamEvtxWrite(), and EBF_streamPktSizeFind().

static void * mem_alloc ( unsigned int nbytes ) [static]

Wraps the 'real' allocator.

Returns:: Pointer to the allocated memory or NULL if not available

Parameters:

nbytes

The number of bytes

: On the embedded systems, the memory pool available to malloc is too small for the larger .ebf files. Typically in this environment one should use MBA_alloc/MBA_free, However, because the EDS package is supposed to be independent of other packages (including PBS) one can not link against in the traditional manner.

The solution is two fold

Do the usual thing and define wrapper functions that are different for the host and embedded systems.
Go one step further and define MBA_alloc/MBA_free as weak symbols.

: This second point effectively transfers the burden of determining when the MBA_alloc/MBA_free symbols need to be satistied. Instead of at the static link or dynamic load stage, this is deferred till runtime.

Note:: There is likely an even trickier way to do this. Currently the code checks if MBA_alloc/MBA_free are non-NULL and if so uses them, else it reverts to malloc/free. Ideally the dynamic loader should do this, thus eliminating the need for any run-time code.

Referenced by EBF_streamCreate(), fileOpen(), and map().

static void mem_free ( void * ptr ) [static]

Wraps the 'real' deallocator.

See also:: mem_alloc

Parameters:

ptr

Pointer to the memory to free

Note:: See mem_alloc for a discussion on why mem_alloc and mem_free exist and for the implementation details

Referenced by EBF_streamFree().

static __inline unsigned int restart_construct	(	RestartPkt *	restart,
		const EBF_evt *	evt
	)			`[static]`

Constructs a template of the packet restart header. This includes both the 8 word header and the 4 word restart cell.

Returns:: Template copy of the Event Builder Word

Parameters:

	restart	The target restart packet
	evt	The event to derive the information from

References _EBF_ebw::bf, _RestartPkt::cell, _EBF_evt::ctb, _EBF_pktRestartCell::ebw, _EBF_ctbHdr::ebw, _EBF_ctb::hdr, _EBF_evt::hdr, _RestartPkt::hdr, _EBF_pktRestartCell::mbz, and _EBF_ebw::ui.

Referenced by EBF_streamEvtxWrite().


Classes
struct	_streamCloseCbp
	Structure to bind the close callback routine with a parameter. More...
struct	_EBF_streamHeader
	Standard header for both input and output streams. More...
struct	_EBF_istreamBody
	Internal structure used to control the input access to an EBF file or data section. More...
struct	_EBF_ostreamBody
	Context for an output event/packet stream. More...
union	_EBF_streamBody
	Union of all the stream types. More...
union	_EBF_stream
	Standard EBF stream handle. More...
struct	_RestartPkt
	Defines an EBF restart packet. More...
Defines
#define	MAX_EVT_SIZE 0x10000
	The maximum size, in bytes, of the data portion of an event. This includes the 8 word header but not any other overheads such restart headers and cells.
Typedefs
typedef enum _EBF_STREAM_DIR_K	EBF_STREAM_DIR_K
	Typedef for enum _EBF_STREAM_DIR_K.
typedef enum _EBF_STREAM_DIR_K	EBF_streamDir
	Typedef for enum _EBF_STREAM_DIR_K.
typedef enum _EBF_STREAM_BOUNDS_K	EBF_STREAM_BOUNDS_K
	Typedef for enum _EBF_STREAM_BOUNDS_K.
typedef int(*	streamClose )(void *file)
	Generic stream close function signature.
typedef struct _streamCloseCbp	streamCloseCbp
	Typedef for struct _streamCloseCbp.
typedef struct _EBF_streamHeader	EBF_streamHeader
	Typedef for struct _EBF_streamHeader.
typedef struct _EBF_istreamBody	EBF_istreamBody
	Typedef for struct _EBF_streamFileBody.
typedef struct _EBF_ostreamBody	EBF_ostreamBody
	Typedef for struct _EBF_ostreamBody.
typedef union _EBF_streamBody	EBF_streamBody
	Typedef for union _EBF_streamBody.
typedef struct _EBF_stream	EBF_stream
	Typedef for struct _EBF_stream.
typedef struct _RestartPkt	RestartPkt
	Typedef for struct _RestartPkt.
Enumerations
enum	_EBF_STREAM_DIR_K { EBF_STREAM_DIR_K_READ = 0, EBF_STREAM_DIR_K_WRITE = 1 }
	Enumeration of the IO direction, i.e. read or write. More...
enum	_EBF_STREAM_BOUNDS_K { EBF_STREAM_BOUNDS_K_MAXEVT = 1 << 16, EBF_STREAM_BOUNDS_K_MAXPKT = 1 << 12, EBF_STREAM_BOUNDS_K_LOWER = EBF_STREAM_BOUNDS_K_MAXEVT, EBF_STREAM_BOUNDS_K_UPPER = 1 << 25, EBF_STREAM_BOUNDS_K_OVERFLOW = EBF_STREAM_BOUNDS_K_MAXPKT }
	Upper and lower bounds on the segment size. More...
Functions
static EBF_stream *	fileOpen (EBF_streamType type, const char *fileName, int segment_size)
	Opens a EBF file for reading.
static EBF_stream *	map (unsigned int *ebf_data)
	Prepares an in memory data structure to be read.
static void *	mem_alloc (unsigned int nbytes)
	Wraps the 'real' allocator.
static void	mem_free (void *ptr)
	Wraps the 'real' deallocator.
static __inline int	max_pkt_size (unsigned int maxPktSize, unsigned int defPktSize)
	Returns the maximum packet size that can actually be realized.
static __inline unsigned char *	copy_event (unsigned char cur, const EBF_dir dir)
	Composes the output event by, potentially copying the data from the original event to the output descriptor.
EBF_stream *	EBF_streamOpen (EBF_streamType type, const void *name, int segment)
	Opens a EBF file or data for reading.
static int	fileRead (EBF_stream stream, unsigned int ptr, size_t nbytes)
	Reads the specified number of bytes.
static int	fileProcess (EBF_stream stream, EBF_streamUnit evtsPkts, int nskip, int nprocess, LCBV_pktCb process, void processPrm)
	Processes the specified stream of as events or packets.
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.
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.
EBF_pkts	EBF_streamLocate (const EBF_stream *stream)
	Returns a packets iterator.
int	EBF_streamChange (EBF_stream stream, const char name)
	Changes the stream to the new file.
EBF_stream *	EBF_streamCreate (EBF_streamType type, const char *name, int maxPktSize)
	Creates a file to receive the EBF data.
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.
int	EBF_streamWrite (EBF_stream stream, const unsigned int data, int nwrds)
	Writes the specified data to the output fil.
static __inline unsigned int	restart_construct (RestartPkt restart, const EBF_evt evt)
	Constructs a template of the packet restart header. This includes both the 8 word header and the 4 word restart cell.
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_streamDirWrite (EBF_stream stream, const EBF_dir dir, int maxPktSize)
	Writes the event described by the event directory to the output stream.
int	EBF_streamDirCopy (EBF_stream stream, const EBF_dir dir, int maxPktSize)
	Copies the packets ASIS to the output stream.
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_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_streamEvtWrite (EBF_stream stream, const void ebf_evt, int len)
	Routine to an event to the output stream.
int	EBF_streamEvtxWrite (EBF_stream stream, const void ebf_evt, int len, int maxPktSize)
	Routine to an event 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.