EBF_pkt.h File Reference

Defines the attributes and data structures relating to an EBF packet. More...

#include <EDS/EBF_ebw.h>

Classes
struct	_EBF_pktHdr
	Defines the packet header area. This is the are reserve by the LCB right before the packet is dropped into the ring buffer. More...
struct	_EBF_pktRestartCell
	Defines the restart cell. More...
struct	_EBF_pktRestartHdr
	Defines the restart packet header. More...
struct	_EBF_pkt
	Template of an packet as it appears in the LCB ring buffer. More...
Typedefs
typedef struct _EBF_pktHdr	EBF_pktHdr
	Typedef for struct _EBF_pktHdr.
typedef struct _EBF_pktRestartCell	EBF_pktRestartCell
	Typedef for struct _EBF_pktRestartCell.
typedef struct _EBF_pktRestartHdr	EBF_pktRestartHdr
	Typedef for struct _EBF_pktRestartHdr.
typedef struct _EBF_pkt	EBF_pkt
	Typedef for struct _EBF_pkt.
Functions
static __inline EBF_pkt *	EBF__pktAdvance (const EBF_pkt *pkt, int nbytes)
	Returns a pointer to the next packet.

---

Detailed Description

Defines the attributes and data structures relating to an EBF packet.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: EBF_pkt.h,v 1.5 2011/03/25 22:16:54 russell Exp $

General Description of an EBF packet

This lays out the structure of a packet produced by the Event Builder Module as it appears in the input ring buffer. The general form of a packet is a pad area, laid out by EBF_pktHdr structure, of 8 32-bit words. The LCB hardware itself does not write anything into these words. They are provided for the consumer (either the LCB driver or the end user) to store contextual information. The intent is to save the consumer from allocating yet another piece of memory. Perhaps, more importantly, it provides a place to store information contigious with the LCB data itself.

Use by the LCB Driver

The LCB driver uses the last word (word 7) to store the LCB event descriptor word, see EBF_edw. It also reserves the use of word 6.

Warning:

The general user should not reference words 6 or 7. They are considered private to the driver.

Distintion from an Event Packet, EBF_evt

A general packet delivered by the Event Builder Module is distinct from an event delivered by the Event Builder Module, see EBF_evt. When building an event, the Event Builder Module tacks on the Event Summary Word (EBF_esw) immediately after the EBF packet proper.

Structural Differences

There is a further, structurally more important, distinction. Packets are always considered in isolation. If the hardware breaks the data into multiple packets, they must be reassembled by the userr. The EBF_pra (Packet ReAssembly) code provides some assistance in this area.

Packetization

There are two reasons why data may be broken into multiple packets

1. The data is larger than the maximal size packet that can be transported. either 4 Kbytes - 128 bits (if the LCB is in bit-serial mode or 4 Kbytes - 128 bytes (if the LCB is in byte-serial mode.
2. The Event Builder Module detects the busy/pause line being asserted when transmitting data to the its destination LCB. In this case it relinquishes control and commences a new packet when it regains control.

---

Typedef Documentation

EBF_pkt

Typedef for struct _EBF_pkt.

This gives the template of an packet as it appears in the LCB ring buffer as an EBF packet header, EBF_phdr, followed 16-bit LATp word and the 16-bit Event Builder Formatting word. These are collectively represented by the EBF_ebw structure.

EBF_pktHdr

Typedef for struct _EBF_pktHdr.

The LCB hardware skips an area of 8 32-bit words between the last packet and the first byte of the incoming packet. This pad area is provided for the consumer (either driver or end user) to use to store contextual information. The intent is to save the consumer from allocating yet another piece of memory for this purpose.

The size of this area is not included in the 32-bit word length count found in the event descriptor word. The length in the event descriptor is the length associated with the number of bytes that the LCB wrote, including the 32-bit words it wrote to pad the data out to a 128 bit boundary (when the LCB is in bit-serial mode) or 128-byte boundary (when the LCB is in byte-serial mode). Note that by including the pad length in the event descriptor's 32-bit word count, the end consumer need not be aware of whether the LCB is in bit-serial or byte-serial mode.

EBF_pktRestartCell

Typedef for struct _EBF_pktRestartCell.

On continuation packets, i.e. those packets following packets with the Event Builder Word's receive status set to PACKET_TRUNCATE, the words immediately following the packet header, i.e. an EBF_pktHdr, are occupied by a restart cell. Only the first word has any meaning, the remaining 3 are filled with 0s. The first word contains a copy of the GEM's LATp word and an EBM word indicating the data is one cell in length.

EBF_pktRestartHdr

Typedef for struct _EBF_pktRestartHdr.

This is a combination of the normal 8 word packet header plus the restart cell.

---

Function Documentation

static __inline EBF_pkt * EBF__pktAdvance	(	const EBF_pkt *	pkt,
		int	nbytes
	)			[static]

Returns a pointer to the next packet.

Returns:

Pointer to the next packet

See also:

EBF_pktSize

Parameters:

	pkt	Pointer to the current packet
	nbytes	The number of bytes to advance

Note:

This function is useful only when going through a list of packets from the EBF_fileIn routines, that is, mainly in test programs. The LCB driver provides this functionality in the real system, handing the user a new event descriptor when a new packet is available.

To advance to the next packet, the size, nbytes, must include the size of the fixed length packet header, EBF_pktHdr, in units of bytes.

Warning:

Note that this routine makes no guarantee that there is a next packet. It merely advances the pointer by the amount specified.