EBF_edw.h File Reference

Layouts out the fields of the LCB Event (or more properly) Packet Descriptor Word packet. More...

#include <PBI/Endianness.h>

Classes
struct	_EBF_edw_bf
	Map of LCB event descriptor word with broken down status fields. More...
union	_EBF_edw
	Union of the 32-bit integer representation and the bit-field representation of the event descriptor word. More...
Defines
#define	EBF_EDW_LEN_TO_BYTES(_edw_len)   ((_edw_len) * sizeof (int))
	Convervsion of the len field found in EBF_edw_bf to bytes.
Typedefs
typedef enum _EBF_EDW_RSTATUS_K	EBF_EDW_RSTATUS_K
	Typedef for enum _EBF_EDW_RSTATUS_K.
typedef enum _EBF_EDW_XSTATUS_K	EBF_EDW_XSTATUS_K
	Typedef for enum _EBF_EDW_XSTATUS_K.
typedef enum _EBF_EDW_S	EBF_EDW_S
	Typedef for enum _EBF_EDW_S.
typedef enum _EBF_EDW_V	EBF_EDW_V
	Typedef for enum _EBF_EDW_V.
typedef enum _EBF_EDW_M	EBF_EDW_M
	Typedef for enum _EBF_EDW_M.
typedef struct _EBF_edw_bf	EBF_edw_bf
	typedef for struct _EBF_edw_bf
typedef union _EBF_edw	EBF_edw
	Typedef for union _EBF_edw.
Enumerations
enum	_EBF_EDW_RSTATUS_K {   EBF_EDW_RSTATUS_K_SUCCESS = 0,   EBF_EDW_RSTATUS_K_UNDEFINED_1 = 1,   EBF_EDW_RSTATUS_K_INVALID_DATA_PARITY = 2,   EBF_EDW_RSTATUS_K_PACKET_TRUNCATED = 3,   EBF_EDW_RSTATUS_K_CNT = 4 }
	Enumerates the values of the receive status field in the event descriptor word. More...
enum	_EBF_EDW_XSTATUS_K {   EBF_EDW_XSTATUS_K_SUCCESS = 0,   EBF_EDW_XSTATUS_K_PCI_MASTER_ABORT = 1,   EBF_EDW_XSTATUS_K_PCI_PARITY_ERROR = 2,   EBF_EDW_XSTATUS_K_PCI_TARGET_ABORT = 3,   EBF_EDW_XSTATUS_K_UNDEFINED_4 = 4,   EBF_EDW_XSTATUS_K_BUFFER_EMPTY = 5,   EBF_EDW_XSTATUS_K_UNDEFINED_6 = 6,   EBF_EDW_XSTATUS_K_Q_EMPTY = 7,   EBF_EDW_XSTATUS_K_CNT = 8 }
	Enumerates the values of the transfer status field in the event descriptor word. More...
enum	_EBF_EDW_S {   EBF_EDW_S_OFFSET = 17,   EBF_EDW_S_LEN = 10,   EBF_EDW_S_STATUS = 5,   EBF_EDW_S_XSTATUS = 3,   EBF_EDW_S_RSTATUS = 2 }
	Size, in bits, of the event descriptor word fields. More...
enum	_EBF_EDW_V {   EBF_EDW_V_OFFSET = 0,   EBF_EDW_V_LEN = 17,   EBF_EDW_V_STATUS = 27,   EBF_EDW_V_XSTATUS = 27,   EBF_EDW_V_RSTATUS = 30 }
	Right justified bit offsets of the event descriptor fields. More...
enum	_EBF_EDW_M {   EBF_EDW_M_OFFSET = 0x0001FFFF,   EBF_EDW_M_LEN = 0x07FE0000,   EBF_EDW_M_STATUS = 0xF8000000,   EBF_EDW_M_XSTATUS = 0x38000000,   EBF_EDW_M_RSTATUS = 0xC0000000 }
	Masks of the event descriptor word fields. More...
Functions
static __inline int	EBF__edwSize (unsigned int edw)
	Returns the size, in bytes, of the data associated with the specified event descriptor word.
static __inline int	EBF__edwPktSize (unsigned int edw)
	Returns the size, in bytes, of the packet associated with the specified event descriptor word.

---

Detailed Description

Layouts out the fields of the LCB Event (or more properly) Packet Descriptor Word packet.

Author:

JJRussell - russell@slac.stanford.edu

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

The event descriptor word is delivered by the LCB hardware when a packet is moved into the ring buffer. It contains the

1. Status of the transfer
2. Size of the transfer
3. Offset within the buffer

The definitions found here are from the LCB reference document. They are essentially a duplicate of what is found in the LCB driver package. However, since this particular code module will be used in the offline world, it was desirable to not depend on the LCB driver package. The only alternative was to duplicate this information here.

---

Define Documentation

#define EBF_EDW_LEN_TO_BYTES

(

_edw_len

)

((_edw_len) * sizeof (int))

Convervsion of the len field found in EBF_edw_bf to bytes.

Returns:

The equivalent number bytes represented by the event descriptor word's length field

Parameters:

_edw_len

The value of event descriptor's length field.

Referenced by EBF__edwPktSize(), EBF__edwSize(), and EBF__pktSize().

---

Typedef Documentation

EBF_EDW_RSTATUS_K

Typedef for enum _EBF_EDW_RSTATUS_K.

These are errors that the LCB detects when accepting data from a LATp event fabric. These map the 2-bit field in event descriptor.

Success

Successful and normal completion

Undefined Value # 1

This is the old header parity error. Packets with this error are trimmed in hardware on the belief that since the control information in the header is corrupted, the packet cannot be properly delivered

Invalid Data Parity

The data portion of the packet had a parity error

Packet Truncated

The data was successfully transmitted, but it was broken up by the hardware into multiple pieces. This values indicates there are more packets to come.

EBF_EDW_XSTATUS_K

Typedef for enum _EBF_EDW_XSTATUS_K.

These errors occur when the LCB transfers data across the PCI bus into the circular buffer. This maps the 3-bit transfer status filed in the event descriptor word.

PCI Master Abort

This is likely due to a bad DMA destination address. In this case, typically there is no data transferred, but one is still obligated to free the padding area and, if any, the number of words specified by the length, although, again, this is almost certainly going to be 0.

PCI Parity Error

PCI Parity Error occurs only on reads. Since this is a write operation, this error should not occur

PCI Target Abort

This error is a little iff'er in origin, but a bad address is a good candidate. The difference between this and a PCI Master Abort is that in the Master Abort, no one responded to the memory address. In this operation, the operation is rejected (like trying to write into read only memory). Basically, the operation being requested is not in the target's side repertorie.

Buffer Empty

This is an internal underflow situation where the descriptor claims so many words are available, but the FIFO runs dry before that. This is internal hardware inconsistency and is a design fault. The data fill have the last legitimate word duplicated until the requisite number of words (as claimed by the result descriptor) is exhausted. There is no way for the user to absolutely known where the last good word occcurred.

Empty

This is perfectly normal and occurs when the event descriptor que has run out.

---

Enumeration Type Documentation

enum _EBF_EDW_M

Masks of the event descriptor word fields.

Enumerator:

EBF_EDW_M_OFFSET	Circular buffer offset, mask
EBF_EDW_M_LEN	Size of the packet in units of 32-bit words, bit field mask
EBF_EDW_M_STATUS	Combined status, bit field mask
EBF_EDW_M_XSTATUS	Transfer status, bit field mask
EBF_EDW_M_RSTATUS	Receive status, bit field mask

enum _EBF_EDW_RSTATUS_K

Enumerates the values of the receive status field in the event descriptor word.

Enumerator:

EBF_EDW_RSTATUS_K_SUCCESS	Normal and successful
EBF_EDW_RSTATUS_K_UNDEFINED_1	Undefined status code
EBF_EDW_RSTATUS_K_INVALID_DATA_PARITY	Data parity error
EBF_EDW_RSTATUS_K_PACKET_TRUNCATED	Packet was truncated, more data to come
EBF_EDW_RSTATUS_K_CNT	Count of RSTATUS values

enum _EBF_EDW_S

Size, in bits, of the event descriptor word fields.

Enumerator:

EBF_EDW_S_OFFSET	Circular buffer offset, bit field offset
EBF_EDW_S_LEN	Size of the packet in units of 32-bit words, bit field offset
EBF_EDW_S_STATUS	Combined status, bit field offset
EBF_EDW_S_XSTATUS	Transfer status, bit field offset
EBF_EDW_S_RSTATUS	Receive status, bit field offset

enum _EBF_EDW_V

Right justified bit offsets of the event descriptor fields.

Enumerator:

EBF_EDW_V_OFFSET	Circular buffer offset, bit field offset
EBF_EDW_V_LEN	Size of the packet in units of 32-bit words, bit field offset
EBF_EDW_V_STATUS	Combined status, bit field offset
EBF_EDW_V_XSTATUS	Transfer status, bit field offset
EBF_EDW_V_RSTATUS	Receive status, bit field offset

enum _EBF_EDW_XSTATUS_K

Enumerates the values of the transfer status field in the event descriptor word.

Enumerator:

EBF_EDW_XSTATUS_K_SUCCESS	Transfer okay
EBF_EDW_XSTATUS_K_PCI_MASTER_ABORT	PCI Master Abort error
EBF_EDW_XSTATUS_K_PCI_PARITY_ERROR	PCI Parity Error,NOT REPORTED
EBF_EDW_XSTATUS_K_PCI_TARGET_ABORT	PCI Target Abort error
EBF_EDW_XSTATUS_K_UNDEFINED_4	PCI Stop asserted, DEFUNCT
EBF_EDW_XSTATUS_K_BUFFER_EMPTY	Undefined error #4
EBF_EDW_XSTATUS_K_UNDEFINED_6	Insufficient memory, DEFUNCT
EBF_EDW_XSTATUS_K_Q_EMPTY	Undefined error #6
EBF_EDW_XSTATUS_K_CNT	Count of XSTATUS values

---

Function Documentation

static __inline int EBF__edwPktSize

(

unsigned int

edw

)

[static]

Returns the size, in bytes, of the packet associated with the specified event descriptor word.

Returns:

The size in bytes, of the specified packet

Parameters:

edw

The event descriptor word

Note:

This is size includes the size of the fixed size header.

References EBF_EDW_LEN_TO_BYTES, EBF_EDW_M_LEN, and EBF_EDW_V_LEN.

static __inline int EBF__edwSize

(

unsigned int

edw

)

[static]

Returns the size, in bytes, of the data associated with the specified event descriptor word.

Returns:

The size in bytes, of the specified packet

Parameters:

edw

The event descriptor word

Note:

This is only the size of the data (which includes the LATp and EBW words) associated with the packet.

References EBF_EDW_LEN_TO_BYTES, EBF_EDW_M_LEN, and EBF_EDW_V_LEN.