GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > LSF / V0-0-2

Constituent: lsf Tag: sun-gcc

Interface Data Structures File List Data Fields Globals

g » glast » flight » SVC » source » LSF » V0-0-2 » LSF

LSF.h File Reference

Maps out the LSF data structures. More...

#include "LSF/LSF_endianness.h"

Include dependency graph for LSF.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_LSF_record_hdr_bf
	Layout of a record header, bit field representation. More...
union	_LSF_record_hdr
	Union of the record header as an uninterpretted 32-bit integer with a bit field representation. More...
union	_LSF_record_bdy
	The general structure of the body of an LSF record. More...
struct	_LSF_record
	The general structure of an LSF record. More...
struct	_LSF_identity_bf
	The bit field representation of the LSF identity word. More...
union	_LSF_identity
	Union of the bit field representation of the LSF_identity word and an uninterpretted 32-bit integer. More...
struct	_LSF_contribution_hdr
	The layout of a contribution header structure. More...
union	_LSF_contribution_bdy
	Beginning of the body of the LSF contribution. More...
struct	_LSF_contribution
	The general structure of an LSF contribution. More...
struct	_LSF_datagram_hdr
	The LSF datagram header. More...
union	_LSF_datagram_bdy
	Beginning of the body of the LSF datagram. More...
struct	_LSF_datagram
	The general structure of an LSF datagram. More...
Defines
#define	LSF_RECORD_HDR_COMPOSE(_type_id, _bridge, _len32)
	Composes a LSF record header.
#define	LSF_IDENTITY_COMPOSE(_type_id, _version, _dir)
	Composes the 32-bit identity word for either a datagram or a contribution from the specified pieces.
Typedefs
typedef enum _LSF_RECORD_HDR_S	LSF_RECORD_HDR_S
	Typedef for enum _LSF_RECORD_HDR_S.
typedef enum _LSF_RECORD_HDR_V	LSF_RECORD_HDR_V
	typedef for enum _LSF_RECORD_HDR_V
typedef enum _LSF_RECORD_HDR_M	LSF_RECORD_HDR_M
	typedef for enum _LSF_RECORD_HDR_M
typedef _LSF_record_hdr_bf	LSF_record_hdr_bf
	Typedef for struct _LSF_record_hdr_bf.
typedef _LSF_record_hdr	LSF_record_hdr
	Typedef union _LSF_record_hdr.
typedef _LSF_record_bdy	LSF_record_bdy
	Typedef for struct _LSF_record_bdy.
typedef _LSF_record	LSF_record
	Typedef for struct _LSF_record.
typedef enum _LSF_IDENTITY_S	LSF_IDENTITY_S
	Typedef for enum _LSF_IDENTITY_S.
typedef enum _LSF_IDENTITY_V	LSF_IDENTITY_V
	Typedef for enum _LSF_IDENTITY_V.
typedef enum _LSF_IDENTITY_M	LSF_IDENTITY_M
	Typedef for enum _LSF_IDENTITY_M.
typedef _LSF_identity_bf	LSF_identity_bf
	Typedef for struct _LSF_identity_bf.
typedef _LSF_identity	LSF_identity
	Typedef for union _LSF_identity.
typedef _LSF_contribution_hdr	LSF_contribution_hdr
	Typedef for struct _LSF_contribution_hdr.
typedef _LSF_contribution_bdy	LSF_contribution_bdy
	Typedef for union _LSF_contribution_bdy.
typedef _LSF_contribution	LSF_contribution
	Typedef for struct _LSF_contribution.
typedef _LSF_datagram_hdr	LSF_datagram_hdr
	Typedef for struct _LSF_datagram_hdr.
typedef _LSF_datagram_bdy	LSF_datagram_bdy
	Typedef for union _LSF_datagram_bdy.
typedef _LSF_datagram	LSF_datagram
	Typedef for struct _LSF_datagram.
Enumerations
enum	_LSF_RECORD_HDR_S { LSF_RECORD_HDR_S_BRIDGE = 8, LSF_RECORD_HDR_S_TYPEID = 4, LSF_RECORD_HDR_S_LEN32 = 20 }
	Record level header word, bit field sizes. More...
enum	_LSF_RECORD_HDR_V { LSF_RECORD_HDR_V_BRIDGE = 24, LSF_RECORD_HDR_V_TYPEID = 20, LSF_RECORD_HDR_V_LEN32 = 0 }
	Record Level header, bit field right justified offsets. More...
enum	_LSF_RECORD_HDR_M { LSF_RECORD_HDR_M_TYPEID, LSF_RECORD_HDR_M_BRIDGE, LSF_RECORD_HDR_M_LEN32 }
	Record Level header, bit field in place masks. More...
enum	_LSF_IDENTITY_S { LSF_IDENTITY_S_TYPEID = 20, LSF_IDENTITY_S_VERSION = 8, LSF_IDENTITY_S_RSVD = 3, LSF_IDENTITY_S_DIR = 1 }
	Enumeration giving the sizes of the bit fields in the LSF identity word. More...
enum	_LSF_IDENTITY_V { LSF_IDENTITY_V_TYPEID = 0, LSF_IDENTITY_V_VERSION = 20, LSF_IDENTITY_V_RSVD = 28, LSF_IDENTITY_V_DIR = 31 }
	Enumeration giving the right bit offsets of the bit fields in the LSF identity word. More...
enum	_LSF_IDENTITY_M { LSF_IDENTITY_M_TYPEID, LSF_IDENTITY_M_VERSION, LSF_IDENTITY_M_RSVD, LSF_IDENTITY_M_DIR }
	Enumeration giving the in place masks of the bit fields in the LSF identity word. More...
Functions
static __inline unsigned int	LSF_identityCompose (unsigned int type_id, unsigned int version, unsigned int dir)
	Composes the 32-bit identity word for either a datagram or a contribution from the specified pieces.
static __inline unsigned int	LSF_recordHdrCompose (unsigned int type_id, unsigned int bridge, unsigned int len32)
	Composes a LSF record header.
static __inline LSF_datagram *	LSF_datagramNext (const LSF_datagram *dgm)
	Advances the datagram pointer by the length field specified in the datagram.
static __inline LSF_datagram *	LSF_datagramAdvance (const LSF_datagram *dgm, unsigned int n32)
	Advances the datagram pointer by the specified number of 32-bit words.
static __inline LSF_contribution *	LSF_contributionNext (const LSF_contribution *ctb)
	Advances the contribution pointer by the length field specified in the contribution header.
static __inline LSF_contribution *	LSF_contributionAdvance (const LSF_contribution *ctb, unsigned int n32)
	Advances the contribution pointer by the specified number of 32-bit words.
static __inline LSF_record *	LSF_recordNext (const LSF_record *rec)
	Advances the record pointer by the length field specified in the record header.
static __inline LSF_record *	LSF_recordAdvance (const LSF_record *evt, unsigned int n32)
	Advances the record pointer by the specified number of 32-bit words.
static __inline unsigned int *	LSF_datAdvance (const unsigned int *dat, unsigned int n32)
	Advances the data pointer by the specified number of 32-bit wo.

Detailed Description

Maps out the LSF data structures.

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

   CVS $Id: LSF.h,v 1.6 2005/10/13 18:36:43 russell Exp $

Overview: This defines the generic aspects of the LAT Science Format (LSF) as implemented by the LAT Flight Software. It has its origins in LDF, but makes 2 significant departures

All lengths are in 32-bit words, not bytes
In addition to the datagram and contribution level objects, LSF adds a third level to this heirarchy, the record.

: LDF made no policy statement concerning the following two issues

Alignment of contribution
Scope of contribution level identifiers

LSF, however, does make a statement here

All contribution and record must be 32-bit aligned. This is semi-formalized by LSF specifying lengths in 32-bit words.
Contribution level and record level identifiers are scoped locally to a datagram. That is, these identifiers have meaning only within the context of a particular datagram and in no way are meant to universally identify a contribution/record in across all datagrams. This means there definition and management is purely a local affair, requiring no coordination to see if a particular number is available.

: LSF makes no references to the contents/data it will encapsulate. In particular, there are no references to anything specific to data that Flight Software may wrap in this protocol.

Heirarchy: Heirachicially, the order is

Datagram
Contribution
Record

: that is, datagram contain contribution and contribution contain records. Still ambivalent on whether

A datagram can carry data not contained in a contribution
Whether to demand the heirachy is strictly enforced, that is contributions must appear under datagrams and records within contributions. For now, the recommendation is that this rule be followed.

Define Documentation

#define LSF_IDENTITY_COMPOSE ( _type_id,
_version,
_dir )

Value:
( (((_dir) << LSF_IDENTITY_V_DIR) & LSF_IDENTITY_M_DIR ) \ | (((_version) << LSF_IDENTITY_V_VERSION) & LSF_IDENTITY_M_VERSION) \ | (((_type_id )<< LSF_IDENTITY_V_TYPEID) & LSF_IDENTITY_M_TYPEID ) )
Composes the 32-bit identity word for either a datagram or a contribution from the specified pieces.

Returns:
The 32-bit identity word;

Parameters:

_type_id The type/identifier of the datagram or contribution Examples would be LSF_ID_K_LSEP, LSF_ID_K_LSEC

_version The version of the data being presented

_dir A flag, if true indicating the datagram/contribution is composed of a series of contributions/records

This functionality is also available as an inline routine. The macro should be used only where calling a function is not allowed, as in a compile time data intialization statement.

#define LSF_RECORD_HDR_COMPOSE ( _type_id,
_bridge,
_len32 )

Value:
( (((_type_id) << LSF_RECORD_HDR_V_TYPEID) & LSF_RECORD_HDR_M_TYPEID) \ | ((( _bridge) << LSF_RECORD_HDR_V_BRIDGE) & LSF_RECORD_HDR_M_BRIDGE) \ | ((( _len32) << LSF_RECORD_HDR_V_LEN32) & LSF_RECORD_HDR_M_LEN32) )
Composes a LSF record header.

Returns:
The LSF record header

Parameters:

_type_id The type/id (0-15)

_bridge The value of the 8-bit reserved field

_len32 The length, in longwords, of the record

Note, this functionality is also available as an inline routine. This macro should be used when initially data structures, i.e, where calling a function is prohibited.

Typedef Documentation

LSF_contribution_hdr

Typedef for struct _LSF_contribution_hdr.

An LSF datagram consists of an outer header (a LSF_datagram_hdr) encapsulating a group of LSF contributors. Each LSF contributor itself is jacketed with its own header (this structure).

Not that because the length field is 24-bits, the maximum length of an LSF contribution is 2**24-1 32-bit words.

LSF_datagram_hdr

Typedef for struct _LSF_datagram_hdr.

An LSF datagram consists of an outer header (this structure) encapsulating a group of LSF contributors. Each LSF contributor itself is jacketed with its own header (an LSF_contributor_hdr)

LSF_identity_bf

Typedef for struct _LSF_identity_bf.

Except for the dir field, these fields are self-explanatory. The dir indicates whether the payload is a structured directory or just a bag of bytes. For datagrams, this flag indicates that the payload is/is not a series of contributions. For contributions, this flag indicates that the payload is/is not a series of records.

This flag allows a generic LSF parsing tool to decide whether it can drill down into the payload of a datagram or a contribution. Once an datagram or a contribution has set this flag all data in it must be presented as wrapped in a contribution or record header. It is not permitted to set this flag in a contribution and have, for example, the first item in the payload presented as a record and the next piece presented as an unstructured bag-of-bytes.

Rsvd Field
The likely use of this field when used in the datagram header will be indicate the revision level of LSF itself, and when used in the contribution header, will be to indicate the number of pad bytes to pad the data to a 32-bit boundary.

LSF_record_hdr_bf

Typedef for struct _LSF_record_hdr_bf.

A record header consists of a 4 bit subformat field nibble and a 20 20 long-word count in the low 16 bits, The remaining 8 bits are meant to be used as a bridge word between the protocol handler and the data handler and is, in general, subformat dependent.

Enumeration Type Documentation

enum _LSF_IDENTITY_M

Enumeration giving the in place masks of the bit fields in the LSF identity word.

Enumerator:

LSF_IDENTITY_M_TYPEID In place mask of the typeId field

LSF_IDENTITY_M_VERSION In place mask of the version field

LSF_IDENTITY_M_RSVD In place mask of the reserved field, must be zero

LSF_IDENTITY_M_DIR In place mask of the flag indicating the payload is a structured directory, i.e. it is not just a bag of bits but,

In the case of a datagram header,one or more contributions or
In the case of a contribution header, one or more records

enum _LSF_IDENTITY_S

Enumeration giving the sizes of the bit fields in the LSF identity word.

Enumerator:

LSF_IDENTITY_S_TYPEID Size, in bits, of the typeId field

LSF_IDENTITY_S_VERSION Size, in bits, of the version field

LSF_IDENTITY_S_RSVD Size, in bits, of the reserved field, must be zero

LSF_IDENTITY_S_DIR Size, in bits, of the flag indicating the payload is a structured directory, i.e. it is not just a bag of bits but,

In the case of a datagram header,one or more contributions or
In the case of a contribution header, one or more records

enum _LSF_IDENTITY_V

Enumeration giving the right bit offsets of the bit fields in the LSF identity word.

Enumerator:

LSF_IDENTITY_V_TYPEID Right justified bit offset of the typeId field

LSF_IDENTITY_V_VERSION Right justified bit offset of the version field

LSF_IDENTITY_V_RSVD Right justified bit offset of the reserved field, must be zero

LSF_IDENTITY_V_DIR Right justified bit offset of the flag indicating the payload is a structured directory, i.e. it is not just a bag of bits but,

In the case of a datagram header,one or more contributions or
In the case of a contribution header, one or more records

enum _LSF_RECORD_HDR_M

Record Level header, bit field in place masks.

Enumerator:

LSF_RECORD_HDR_M_TYPEID Subformat type, in place mask

LSF_RECORD_HDR_M_BRIDGE Subformat type reserved field, in place mask

LSF_RECORD_HDR_M_LEN32 Data length, in place mask

enum _LSF_RECORD_HDR_S

Record level header word, bit field sizes.

Enumerator:

LSF_RECORD_HDR_S_BRIDGE Subformat type reserved field, size in bits

LSF_RECORD_HDR_S_TYPEID Subformat identifier, size in bits

LSF_RECORD_HDR_S_LEN32 Data length, size in longwords

enum _LSF_RECORD_HDR_V

Record Level header, bit field right justified offsets.

Enumerator:

LSF_RECORD_HDR_V_BRIDGE Subformat type reserved field, size in bits

LSF_RECORD_HDR_V_TYPEID Subformat identifier, size in bits

LSF_RECORD_HDR_V_LEN32 Data length, size in longwords

Function Documentation

static __inline LSF_contribution * LSF_contributionAdvance ( const LSF_contribution * ctb,

unsigned int n32

) [static]

Advances the contribution pointer by the specified number of 32-bit words.

Returns:
The new contribution pointer

Parameters:

ctb The contribution pointer to advance

n32 The number of 32-bit words to advance the pointer

static __inline LSF_contribution * LSF_contributionNext ( const LSF_contribution * ctb ) [static]

Advances the contribution pointer by the length field specified in the contribution header.

Returns:
The new contribution pointer

Parameters:

ctb The contribution pointer to advance

static __inline unsigned int * LSF_datAdvance ( const unsigned int * dat,

unsigned int n32

) [static]

Advances the data pointer by the specified number of 32-bit wo.

Returns:
The new data pointer

Parameters:

dat The data pointer to advance

n32 The number of 32-bit words to advance the pointer

static __inline LSF_datagram * LSF_datagramAdvance ( const LSF_datagram * dgm,

unsigned int n32

) [static]

Advances the datagram pointer by the specified number of 32-bit words.

Returns:
The new contribution pointer

Parameters:

dgm The datagram pointer to advance

n32 The number of 32-bit words to advance the pointer

static __inline LSF_datagram * LSF_datagramNext ( const LSF_datagram * dgm ) [static]

Advances the datagram pointer by the length field specified in the datagram.

Returns:
The new datagram pointer

Parameters:

dgm The datagram pointer to advance

static __inline unsigned int LSF_identityCompose ( unsigned int type_id,

unsigned int version,

unsigned int dir

) [static]

Composes the 32-bit identity word for either a datagram or a contribution from the specified pieces.

Returns:
The 32-bit identity word;

Parameters:

dir A flag, if true indicating the datagram/contribution is composed of a series of contributions/records

version The version of the data being presented

type_id The type/identifier of the datagram or contribution Examples would be LSF_ID_K_LSEP, LSF_ID_K_LSEC

Note, this functionality is also available as a macro. The macro should be used when initializing data structures, i.e, where calling a function is prohibited. The inline is useful when debugging calls for setting a breakpoint on a routine.

static __inline LSF_record * LSF_recordAdvance ( const LSF_record * rec,

unsigned int n32

) [static]

Advances the record pointer by the specified number of 32-bit words.

Returns:
The new record pointer

Parameters:

rec The record pointer to advance

n32 The number of 32-bit words to advance the pointer

Warning:
The advancement is in the natural units of an record, i.e. 32-bit words.

static __inline unsigned int LSF_recordHdrCompose ( unsigned int type_id,

unsigned int bridge,

unsigned int len32

) [static]

Composes a LSF record header.

Returns:
The LSF record header

Parameters:

type_id The record's type/id (0-15)

bridge The value of the 8-bit bridge field

len32 The length, in longwords, of the record

Note, this functionality is also available as a macro. The macro should be used when initializing data structures, i.e, where calling a function is prohibited. The inline is useful when debugging calls for setting a breakpoint on a routine.

static __inline LSF_record * LSF_recordNext ( const LSF_record * rec ) [static]

Advances the record pointer by the length field specified in the record header.

Returns:
The new record pointer

Parameters:

rec The record pointer to advance

Generated on Thu Oct 13 23:46:56 2005 by

1.4.4

LSF.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation