GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> GRBP / V1-0-4 > attstream / rhel6-64

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » GRBP » V1-0-4 » src » io

ATT_stream.c File Reference

Generic ATT file reading facility. More...

#include <GRBP/io/ATT_stream.h>
#include <GRBP/io/ATT_dgm.h>
#include <PBI/PTR.h>
#include <PBI/Endianness.h>
#include <stdio.h>
#include <stdlib.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  _ATT_streamHeader
 Standard header for both input and output streams. More...
struct  _ATT_istreamBody
 Internal structure used to control the input access to an ATT file or data section. More...
struct  _ATT_ostreamBody
 Context for an output event/packet stream. More...
union  _ATT_streamBody
 Union of all the stream types. More...
union  _ATT_stream
 Standard ATT stream handle. More...

Typedefs

typedef enum _ATT_STREAM_DIR_K ATT_STREAM_DIR_K
 Typedef for enum _ATT_STREAM_DIR_K.
typedef enum _ATT_STREAM_DIR_K ATT_streamDir
 Typedef for enum _ATT_STREAM_DIR_K.
typedef enum _ATT_STREAM_BOUNDS_K ATT_STREAM_BOUNDS_K
 Typedef for enum _ATT_STREAM_BOUNDS_K.
typedef int(* streamClose )(void *file)
 Generic stream close function signature.
typedef struct _streamCloseCbp streamCloseCbp
 Typedef for struct _streamCloseCbp.
typedef struct _ATT_streamHeader ATT_streamHeader
 Typedef for struct _ATT_streamHeader.
typedef struct _ATT_istreamBody ATT_istreamBody
 Typedef for struct _ATT_streamFileBody.
typedef struct _ATT_ostreamBody ATT_ostreamBody
 Typedef for struct _ATT_ostreamBody.
typedef union _ATT_streamBody ATT_streamBody
 Typedef for union _ATT_streamBody.
typedef struct _ATT_stream ATT_stream
 Typedef for struct _ATT_stream.

Enumerations

enum  _ATT_STREAM_DIR_K {
  ATT_STREAM_DIR_K_READ = 0,
  ATT_STREAM_DIR_K_WRITE = 1
}
 Enumeration of the IO direction, i.e. read or write. More...
enum  _ATT_STREAM_BOUNDS_K {
  ATT_STREAM_BOUNDS_K_MAXDGM = 1 << 16,
  ATT_STREAM_BOUNDS_K_LOWER = ATT_STREAM_BOUNDS_K_MAXDGM,
  ATT_STREAM_BOUNDS_K_UPPER = 1 << 25,
  ATT_STREAM_BOUNDS_K_OVERFLOW = ATT_STREAM_BOUNDS_K_MAXDGM
}
 Upper and lower bounds on the segment size. More...

Functions

static ATT_stream * fileOpen (ATT_streamType type, const char *fileName, int segment_size)
 Opens a ATT file for reading.
static int fileRead (ATT_stream *stream, unsigned int *ptr, size_t nbytes)
 Reads the specified number of bytes.
static ATT_stream * map (unsigned int *grb_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 void dgm_swap (ATT_dgm *dgm)
 Byte-swap the datagram.
static __inline void swap32_lclXbigN (unsigned int *w, int n)
ATT_stream * ATT_streamOpen (ATT_streamType type, const void *name, int segment)
 Opens a ATT file or data for reading.
int ATT_streamRead (ATT_stream *stream)
 Reads the ATT file associated with the event stream handle istream.
const ATT_dgm * ATT_streamLocate (ATT_stream *stream, int advance)
 Returns a pointer to the current packet and, optionally, advances the current packet to the next packet.
const ATT_attitude * ATT_streamAttNext (ATT_stream *stream)
 Returns a pointer to the next attitude record or NULL if exhausted.
int ATT_streamClose (ATT_stream *stream)
 Closes the file after it has been read.
ATT_stream * ATT_streamCreate (ATT_streamType type, const char *name, int rsvd_mbz)
 Creates a file to receive the ATT data packets.
int ATT_streamFree (ATT_stream *stream)
 Frees the memory associated with the contents of the file.
int ATT_streamDgmWrite (ATT_stream *stream, const ATT_dgm *dgm)
 Writes the specified packet to the output file.

Detailed Description

Generic ATT file reading facility.

Author:
JJRussell - russell@slac.stanford.edu

   CVS $Id: ATT_stream.c,v 1.3 2011/03/30 22:11:52 russell Exp $

Typedef Documentation

ATT_STREAM_BOUNDS_K

Typedef for enum _ATT_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 _ATT_STREAM_BOUNDS_K

Upper and lower bounds on the segment size.

Enumerator:
ATT_STREAM_BOUNDS_K_MAXDGM  Size of maximum event
ATT_STREAM_BOUNDS_K_LOWER  Lower bound must be at least size of a maximally sized datagram
ATT_STREAM_BOUNDS_K_UPPER  Upper bound must be at least the lower bound, choose 32Mbytes
ATT_STREAM_BOUNDS_K_OVERFLOW  Overflow area must at least the size of a maximally sized event

enum _ATT_STREAM_DIR_K

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

Enumerator:
ATT_STREAM_DIR_K_READ  Stream direction is read
ATT_STREAM_DIR_K_WRITE  Stream directory is write

Function Documentation

const ATT_attitude* ATT_streamAttNext ( ATT_stream *  stream  ) 

Returns a pointer to the next attitude record or NULL if exhausted.

Returns:
a pointer to the next attitude record or NULL if exhausted
Parameters:
stream The attitude stream

References ATT_streamLocate(), _ATT_stream::bdy, _ATT_streamBody::in, _ATT_istreamBody::lst_att, and _ATT_istreamBody::nxt_att.

int ATT_streamClose ( ATT_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 ATT_streamFree().

References _ATT_streamHeader::close, _ATT_stream::hdr, _streamCloseCbp::prm, and _streamCloseCbp::rtn.

ATT_stream* ATT_streamCreate ( ATT_streamType  type,
const char *  name,
int  rsvd_mbz 
)

Creates a file to receive the ATT data packets.

Returns:
The stream handle
Parameters:
type The type of stream to open ATT_STREAM_TYPE_K_FILE or ATT_STREAM_TYPE_K_DATA
name The name of the section or file to create
rsvd_mbz Reserved, must be 0

References ATT_STREAM_DIR_K_WRITE, ATT_STREAM_TYPE_K_DATA, ATT_STREAM_TYPE_K_FILE, _ATT_stream::bdy, _ATT_streamHeader::close, _ATT_streamHeader::dir, _ATT_ostreamBody::file, _ATT_streamHeader::free, _ATT_stream::hdr, mem_alloc(), _ATT_ostreamBody::name, _ATT_streamBody::out, _streamCloseCbp::prm, _streamCloseCbp::rtn, and _ATT_streamHeader::type.

int ATT_streamDgmWrite ( ATT_stream *  stream,
const ATT_dgm *  dgm 
)

Writes the specified packet to the output file.

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

References _ATT_stream::bdy, _ATT_ostreamBody::file, and _ATT_streamBody::out.

int ATT_streamFree ( ATT_stream *  stream  ) 

Frees the memory associated with the contents of the file.

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

References _ATT_streamHeader::free, _ATT_stream::hdr, and mem_free().

const ATT_dgm* ATT_streamLocate ( ATT_stream *  stream,
int  advance 
)

Returns a pointer to the current packet and, optionally, advances the current packet to the next packet.

Returns:
Pointer to the current packet or NULL if at EOF
Parameters:
stream The stream handle
advance If non-zero, advance to the internal next packet pointer to the next packet. This is the normal way one would serially read a file of packets

References ATT__dgmNext(), _ATT_ctbbdy::attitude, _ATT_ctb::bdy, _ATT_stream::bdy, _ATT_dgm::ctb, _ATT_istreamBody::cur_dgm, dgm_swap(), _ATT_streamBody::in, _ATT_istreamBody::lst_att, _ATT_istreamBody::lst_dgm, and _ATT_istreamBody::nxt_att.

Referenced by ATT_streamAttNext().

ATT_stream* ATT_streamOpen ( ATT_streamType  type,
const void *  name,
int  segment 
)

Opens a ATT file or data for reading.

Parameters:
type The type of stream to open
  • ATT_STREAM_TYPE_K_FILE
  • ATT_STREAM_TYPE_K_FILESEG
  • ATT_STREAM_TYPE_K_DATA If ATT_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 ATT_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 ATT file or the address of data section to open
segment Interpretation is dependent on type. If type is
  • ATT_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).
  • ATT_STREAM_TYPE_K_DATA, then is ignored
Returns:
If successful, the file handle else, NULL

References ATT_STREAM_TYPE_K_DATA, ATT_STREAM_TYPE_K_FILE, ATT_STREAM_TYPE_K_FILESEG, fileOpen(), and map().

int ATT_streamRead ( ATT_stream *  stream  ) 

Reads the ATT 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 ATT_STREAM_TYPE_K_FILE, _ATT_stream::bdy, _ATT_istreamBody::buf, _ATT_istreamBody::cur_dgm, fileRead(), _ATT_stream::hdr, _ATT_streamBody::in, _ATT_istreamBody::lst_dgm, _ATT_istreamBody::seg_size, and _ATT_streamHeader::type.

static __inline void dgm_swap ( ATT_dgm *  dgm  )  [static]

Byte-swap the datagram.

Parameters:
dgm The datagram to byte-swap

Referenced by ATT_streamLocate().

static ATT_stream * fileOpen ( ATT_streamType  type,
const char *  fileName,
int  segmentSize 
) [static]

Opens a ATT file for reading.

Parameters:
type The stream type, must be either
  • ATT_STREAM_TYPE_K_FILE, this potentially offers the most efficient processing
  • ATT_STREAM_TYPE_K_FILESEG, this should be used when 2 or more streams are needed
fileName The name of the ATT 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

References ATT_STREAM_BOUNDS_K_LOWER, ATT_STREAM_BOUNDS_K_OVERFLOW, ATT_STREAM_BOUNDS_K_UPPER, ATT_STREAM_DIR_K_READ, ATT_STREAM_TYPE_K_FILE, _ATT_stream::bdy, _ATT_istreamBody::buf, _ATT_streamHeader::close, _ATT_istreamBody::cur_dgm, _ATT_istreamBody::cur_size, _ATT_streamHeader::dir, _ATT_istreamBody::fate, _ATT_istreamBody::fd, _ATT_streamHeader::free, _ATT_stream::hdr, _ATT_streamBody::in, mem_alloc(), _ATT_istreamBody::name, _ATT_istreamBody::nprocess, _streamCloseCbp::prm, _streamCloseCbp::rtn, _ATT_istreamBody::seg_size, _ATT_istreamBody::tot_left, _ATT_istreamBody::tot_size, _ATT_streamHeader::type, and _ATT_istreamBody::which.

Referenced by ATT_streamOpen().

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

Reads the specified number of bytes.

Returns:
Status

References _ATT_stream::bdy, _ATT_istreamBody::fd, _ATT_streamBody::in, and _ATT_istreamBody::name.

Referenced by ATT_streamRead().

static ATT_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 ATT_STREAM_DIR_K_READ, ATT_STREAM_TYPE_K_DATA, _ATT_streamHeader::close, _ATT_streamHeader::dir, _ATT_streamHeader::free, _ATT_stream::hdr, mem_alloc(), _streamCloseCbp::prm, _streamCloseCbp::rtn, and _ATT_streamHeader::type.

Referenced by ATT_streamOpen().

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 P B S) 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 ATT_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 ATT_streamFree().

Generated on Tue Nov 29 17:07:24 2011 by  doxygen 1.5.8