---

IVTE.ih File Reference

IVTE Inline Interface. More...

#include "BBC/inline.h"
#include "BBC/IVTE_id.h"

Data Structures
struct	_IVTE_dir
	Directory structure definition. More...
struct	_IVTE_hdr
	Header structure definition. More...
struct	_IVTE_tlr
	Trailer structure definition. More...
Defines
#define	IVTE_EXT_PROTO   INLINE_USR_EXT_PROTO
	Declaration for external function prototype.
#define	IVTE_LCL_PROTO   INLINE_USR_LCL_PROTO
	Declaration for internal function prototype.
#define	IVTE_EXT_FNC   INLINE_USR_EXT_FNC
	Declaration for external function.
#define	IVTE_LCL_FNC   INLINE_USR_LCL_FNC
	Declaration for internal function.
#define	IVTE_V_NDIR   0
	Shift amount to right justify the NDIR field.
#define	IVTE_W_NDIR   24
	Shift amount to left justify the NDIR field.
#define	IVTE_S_NDIR   8
	Size, in bits of the NDIR field.
#define	IVTE_M_NDIR   0xff
	Right justified mask for the NDIR field.
#define	IVTE_V_STATUS   8
	Shift amount to right justify the STATUS field.
#define	IVTE_W_STATUS   0
	Shift amount to left justify the STATUS field.
#define	IVTE_S_STATUS   24
	Size, in bits of the STATUS field.
#define	IVTE_M_STATUS   0xffffff00
	Right justified mask for the STATUS field.
#define	IVTE_DIR_SIZEOF   (sizeof(struct _IVTE_dir))
	Get the sizeof an IVTE directory structure. More...
#define	IVTE_HDR_SIZEOF   (sizeof(struct _IVTE_hdr) - sizeof(struct _IVTE_dir))
	Get the sizeof an IVTE header structure.
#define	IVTE_TLR_SIZEOF   (sizeof(struct _IVTE_tlr)
	Get the sizeof an IVTE trailer structure.
#define	IVTE_DIR_ALIGNMENT_SIZE   (sizeof (int))
	The IVTE directory alignment size, expressed in bytes.
#define	IVTE_DIR_ALIGNMENT_MASK   (~(IVTE_DIR_ALIGNMENT_SIZE-1))
	The IVTE directory alignment mask.
#define	IVTE_DATA_ALIGNMENT_SIZE   (sizeof (int))
	The IVTE data alignment size, expressed in bytes.
#define	IVTE_DATA_ALIGNMENT_MASK   (~(IVTE_DATA_ALIGNMENT_SIZE-1))
	The IVTE data alignment mask.
Typedefs
typedef _IVTE_dir	IVTE_dir
	Typedef for struct _IVTE_dir.
typedef _IVTE_hdr	IVTE_hdr
	Typedef for struct _IVTE_hdr.
typedef _IVTE_tlr	IVTE_tlr
	Typedef for struct _IVTE_tlr.
Functions
IVTE_EXT_PROTO int	IVTE__dir_sizeof (void)
	Returns the size of a directory entry. More...
IVTE_EXT_PROTO int	IVTE__hdr_sizeof (int ndir)
	Returns the size of an IVTE header structure needed to contain the specified number of directories. More...
IVTE_EXT_PROTO int	IVTE__tlr_sizeof (void)
	Returns the size of a trailer record. More...
IVTE_EXT_PROTO const struct _IVTE_hdr *	IVTE__hdr_next (const struct _IVTE_hdr *hdr)
	Advances the hdr pointer to point just past the end of the current event. More...
IVTE_EXT_PROTO const void *	IVTE__data_locate (const struct _IVTE_hdr *hdr, const struct _IVTE_dir *dir)
	Locates the data area associated with the specified directory. More...
IVTE_EXT_PROTO const struct _IVTE_tlr *	IVTE__tlr_locate (const struct _IVTE_hdr *hdr)
	Locates the trailer record for this event. More...
IVTE_EXT_PROTO int	IVTE__ndir (unsigned int status_ndir)
	Unpacks the number of directories from the status/directory count word. More...
IVTE_EXT_PROTO unsigned int	IVTE__status (unsigned int status_ndir)
	Unpacks the status word from the status/directory count word. More...
IVTE_EXT_PROTO unsigned int	IVTE__data_align (unsigned int offset)
	Computes where the next data block should start. More...
IVTE_EXT_PROTO void	IVTE__hdr_build (struct _IVTE_hdr *hdr, unsigned int hdr_id, unsigned int size, unsigned int sequence, unsigned int status, unsigned int dir_cnt)
	Builds an IVTE header record. More...
IVTE_EXT_PROTO void	IVTE__dir_build (struct _IVTE_dir *dir, unsigned int dir_id, int size, unsigned int offset, unsigned int status)
	Builds a directory record. More...
IVTE_EXT_PROTO void	IVTE__tlr_build (struct _IVTE_tlr *tlr, unsigned int tlr_id, unsigned int size)
	Builds an IVTE trailer record. More...

---

Detailed Description

IVTE Inline Interface.

Author:

JJRussell - russell@slac.stanford.edu

DESCRIPTION
-----------
This defines the event structure. This consists of a header giving global information, followed by a series of directory entries describing the record structure.

---

Define Documentation

#define IVTE_DIR_SIZEOF   (sizeof(struct _IVTE_dir))

Get the sizeof an IVTE directory structure. MACROs Parameterize the sizes of these structures. One should use these definitions or the callable versions, to ensure consistency. It is really only important for the IVTE header since it is a variable sized structure.

---

Function Documentation

IVTE_EXT_FNC unsigned int IVTE__data_align (  unsigned int    offset )

Computes where the next data block should start. Parameters: offset  The current offset Returns: The offset where the next data block should start

IVTE_EXT_FNC const void * IVTE__data_locate (  const struct _IVTE_hdr *    hdr, const struct _IVTE_dir *    dir )

Locates the data area associated with the specified directory. Parameters: hdr  The IVTE header dir  The IVTE directory to locate the data for. Returns: Pointer to the data area.

IVTE_EXT_FNC void IVTE__dir_build (  struct _IVTE_dir *    dir, unsigned int    dir_id, int    size, unsigned int    offset, unsigned int    status )

Builds a directory record. Parameters: dir  The IVTE directory to build dir_id  The id or name of this directory size  The size, in bytes, of the data described by this directory. offset  The offset, in bytes from the top of the IVTE data structure, of the data described by this directory. status  The 'status' to associate with this directory entry. The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this.

IVTE_EXT_FNC int IVTE__dir_sizeof (  void    )

Returns the size of a directory entry. Returns: The size, in bytes, of a directory entry Returns the size of a directory entry. This is no big deal, but is provided to give the same look and feel as when one asks for a IVTE header size. Note that one should not calculate the sizeof an IVTE structure needed to hold a number of directories by using nbytes = IVTE__hdr_sizeof(0) + n * IVTE__dir_sizeof () This calculation potentially neglects alignment issues. Instead, use IVTE__hdr_sizeof (n).

IVTE_EXT_FNC void IVTE__hdr_build (  struct _IVTE_hdr *    hdr, unsigned int    hdr_id, unsigned int    size, unsigned int    sequence, unsigned int    status, unsigned int    dir_cnt )

Builds an IVTE header record. Parameters: hdr  Pointer to the header structure to build. hdr_id  The header id or 'name' of this record. sequence  The sequence number of this event. size  The size, in bytes, of this event. status  The global status of this event. m dir_cnt The number of directories associated with this event. The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this. Warning: Note that the size parameter is the actual length of the event, i.e. how many bytes is it from the beginning of the header record to the end of the trailer record. Due to alignment factors, this number is not necessarily equivalent to the sum of the pieces.

IVTE_EXT_FNC const struct _IVTE_hdr * IVTE__hdr_next (  const struct _IVTE_hdr *    hdr )

Advances the hdr pointer to point just past the end of the current event. Parameters: hdr  Pointer to the beginning of the current event. Returns: Pointer to the next event. If multiple events are stored off this pointer, then the returned pointer points to the beginning of the next event. This is useful for iterating through a series of contigious events. If this is the last event, then the pointer points at where the next event will start.

IVTE_EXT_FNC int IVTE__hdr_sizeof (  int    ndir )

Returns the size of an IVTE header structure needed to contain the specified number of directories. Parameters: ndir  The number of directories this IVTE header needs to hold. Returns: The sizeof an IVTE an IVTE header structure with ndir directories. Returns the size of an IVTE header structure needed to hold the specified number of directory entries. Since various C compilers do not allow the usual trick of leaving an unspecified array size as the last member of a structure, one is forced to put some arbitrary number (but not 0) for the array size. Because of this, a formalized interface must be presented which subtracts off this contribution to the size of the structure.

IVTE_EXT_FNC int IVTE__ndir (  unsigned int    status_ndir )

Unpacks the number of directories from the status/directory count word. Parameters: status_dir  The status/directory count word to extract the directory count from. Returns: The number of directories. The user is encouraged to use this routine rather than the extracting the value using the bit field definitions. Because of the way inline functions work, those definitions are exposed, but are intended to be part of the public interface.

IVTE_EXT_FNC unsigned int IVTE__status (  unsigned int    status_ndir )

Unpacks the status word from the status/directory count word. Parameters: status_dir  The status/directory count word to extract the status word from. Returns: The status word. The user is encouraged to use this routine rather than the extracting the value using the bit field definitions. Because of the way inline functions work, those definitions are exposed, but are intended to be part of the public interface.

IVTE_EXT_FNC void IVTE__tlr_build (  struct _IVTE_tlr *    tlr, unsigned int    tlr_id, unsigned int    size )

Builds an IVTE trailer record. Parameters: tlr  The IVTE trailer record to build. tlr_id  The id or 'name' of the trailer record. size  The size, in bytes, of the IVTE data record. The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this. Warning: Note that the size parameter is the actual length of the event, i.e. how many bytes is it from the beginning of the header record to the end of the trailer record. Due to alignment factors, this number is not necessarily equivalent to the sum of the pieces.

IVTE_EXT_FNC const struct _IVTE_tlr * IVTE__tlr_locate (  const struct _IVTE_hdr *    hdr )

Locates the trailer record for this event. Parameters: hdr  The IVTE header Returns: A pointer to the trailer record for this event.

IVTE_EXT_FNC int IVTE__tlr_sizeof (  void    )

Returns the size of a trailer record. Returns: The size, in bytes, of a trailer record. Returns the size of an IVTE trailer structure. This is provided merely for consistency. This is a fixed sized structure and can easily be gotten from sizeof (IVTE_tlr). Warning: When calculating size requirements or appending a trailer record to the end of an IVTE data record, make sure that alignment factors are taken into account.

---