GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> EDS / V2-11-6 > esu / rhel5-64

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » EDS » V2-11-6 » EDS

EBF_siv.h File Reference

Interface to the packet's State Information Vector. More...


Typedefs

typedef enum _EBF_SIV_V EBF_SIV_V
 Typedef for EBF_SIV_V.
typedef enum _EBF_SIV_M EBF_SIV_M
 Typedef for EBF_SIV_M.
typedef signed int EBF_siv
 The state information vector.

Enumerations

enum  _EBF_SIV_V {
  EBF_SIV_V_STATE = 30,
  EBF_SIV_V_STATE_MORE = EBF_SIV_V_STATE + 1,
  EBF_SIV_V_STATE_NOTFIRST = EBF_SIV_V_STATE + 0,
  EBF_SIV_V_RSVD = 24,
  EBF_SIV_V_ERR = 16,
  EBF_SIV_V_ERR_RSVD_7 = EBF_SIV_V_ERR + 7,
  EBF_SIV_V_ERR_RSVD_6 = EBF_SIV_V_ERR + 6,
  EBF_SIV_V_ERR_SEQ = EBF_SIV_V_ERR + 5,
  EBF_SIV_V_ERR_SEQ0 = EBF_SIV_V_ERR + 4,
  EBF_SIV_V_ERR_EBM = EBF_SIV_V_ERR + 3,
  EBF_SIV_V_ERR_PARITY = EBF_SIV_V_ERR + 2,
  EBF_SIV_V_ERR_XFR = EBF_SIV_V_ERR + 1,
  EBF_SIV_V_ERR_RCV = EBF_SIV_V_ERR + 0,
  EBF_SIV_V_VAL = 0,
  EBF_SIV_V_VAL_RSVD = EBF_SIV_V_VAL + 13,
  EBF_SIV_V_VAL_EDWSTATUS = EBF_SIV_V_VAL + 8,
  EBF_SIV_V_VAL_EBMERR = EBF_SIV_V_VAL + 5,
  EBF_SIV_V_VAL_EBMSEQ = EBF_SIV_V_VAL + 0
}
 The right justified bit offsets of the Packet Reassembly state information vector. More...
enum  _EBF_SIV_M {
  EBF_SIV_M_STATE = (0x3 << EBF_SIV_V_STATE),
  EBF_SIV_M_STATE_MORE = (1 << EBF_SIV_V_STATE_MORE),
  EBF_SIV_M_STATE_NOTFIRST = (1 << EBF_SIV_V_STATE_NOTFIRST),
  EBF_SIV_M_RSVD = (0x3f << EBF_SIV_V_RSVD),
  EBF_SIV_M_ERR = (0xff << EBF_SIV_V_ERR),
  EBF_SIV_M_ERR_SEQ = (1 << EBF_SIV_V_ERR_SEQ ),
  EBF_SIV_M_ERR_SEQ0 = (1 << EBF_SIV_V_ERR_SEQ0),
  EBF_SIV_M_ERR_EBM = (1 << EBF_SIV_V_ERR_EBM),
  EBF_SIV_M_ERR_PARITY = (1 << EBF_SIV_V_ERR_PARITY),
  EBF_SIV_M_ERR_XFR = (1 << EBF_SIV_V_ERR_XFR ),
  EBF_SIV_M_ERR_RCV = (1 << EBF_SIV_V_ERR_RCV ),
  EBF_SIV_M_VAL = (0xffff << EBF_SIV_V_VAL),
  EBF_SIV_M_VAL_RSVD = (0x3 << EBF_SIV_V_VAL_RSVD),
  EBF_SIV_M_VAL_EDWSTATUS = (0x1f << EBF_SIV_V_VAL_EDWSTATUS),
  EBF_SIV_M_VAL_EBMERR = (0x7 << EBF_SIV_V_VAL_EBMERR),
  EBF_SIV_M_VAL_EBMSEQ = (0x1f << EBF_SIV_V_VAL_EBMSEQ)
}
 The in place mask of the Packet Reassembly state information vector. More...

Functions

EBF_siv EBF_sivInit (void)
EBF_siv EBF_sivUpdate (EBF_siv siv, unsigned int edw, const EBF_pkt *pkt)
static __inline int EBF__sivIsFirst (EBF_siv siv)
 Returns non-zero is this is the first or only packet in a sequence.
static __inline int EBF__sivIsNotFirst (EBF_siv siv)
 Returns non-zero is this is the not first or only packet in a sequence.
static __inline int EBF__sivIsMid (EBF_siv siv)
 Returns non-zero is this is not the first or last member of a sequence.
static __inline int EBF__sivIsFirstOrLast (EBF_siv siv)
 Returns non-zero is this is the first or last member of a sequence.
static __inline int EBF__sivIsLast (EBF_siv siv)
 Returns non-zero is this is not the last or only member of a sequence.
static __inline int EBF__sivIsMore (EBF_siv siv)
 Returns non-zero if there are more packets to come.
static __inline int EBF__sivIsList (EBF_siv siv)
 Returns non-zero is this is a member of a sequence.
static __inline int EBF__sivIsOnly (EBF_siv siv)
 Returns non-zero is this is not the only member of a sequence.
static __inline int EBF__sivIsLastSeq (EBF_siv siv)
 Returns non-zero if this is the last packet in a sequence.
static __inline int EBF__sivHasErrors (EBF_siv siv)
 Returns a non-zero value if errors are present.

Detailed Description

Interface to the packet's State Information Vector.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: EBF_siv.h,v 1.4 2005/10/13 22:00:53 russell Exp $

Overview
The LCB delivers events and other information to a CPU in the form of packets. The hardware may break the data into multiple packets for two reasons
  1. The most common is because a packet has a finite length (the maximum is 4K - 128 = 3968 bytes on a byte-wide LCB). Data larger than this must broken into multiple packets each of which is smaller than this maximum
  2. The event fabric between the EBM and CPU can assert backpressure. In order to avoid deadlocks, the EBM relinquishes the event fabric and breaks the data into multiple packets.
By limiting the data shipped out of a CPU to the maximum, the first form of packetizing can be avoided. This would truly be nice if one could avoid the whole packet reassembly process for CPU-to-CPU communications, but, unfortunately, the second reason for packetization cannot be avoided.
What's Provided
Packet reassemble is presented in layers, with this routine at the lowest layers.It is a very simple routine to implement the state machine that guides the packet reassembly process.
Layout of this 32-bit word
This word comes in 4 major sub-fields
  1. State field, 2 bits
  2. Reserved field, 6 bits
  3. Error summary field, 8 bits
  4. Value field, 16 bits
Each of these fields is now discussed in turn
The State Field and the State Machine
The entire state of the packet reassembly process can be described by the following 3 booleans
  1. More packets to come
  2. List in progress (vs a single packet)
  3. An error was detected during the reassembly process

It is the job of the error field to summarize the source of errors which could b potentially fatal to the handling/decoding of the packet. The state field is constructed such that a standalone packet (the most normal case) has a value of 0.
The Error Field
The error field can be thought of as a group of bits summarizing the source of serious errors. The error field of a perfectly constructed packet will be zero
  1. First packet did not have sequence number 0
  2. Subsequent packets did not have the anticipated sequence number
  3. The event descriptor receive status had a value other than SUCCESS or PACKET_TRUNCATED. (There is only one other INVALID_DATA_PARITY.) This will be dealt with in more detail later.

Back to the State Machine
For purposes of this discussion, it is convenient to think of collapsing all the errors syndromes to a single bit, error or no error. Then the states of the packet reasssembly, plus the interpretation are
par
Packet Reassembly States
State Interpretation

Done, No list, No Error Well-behaved single packet

Done, No list, Error Single packet with an error

Done, List, No Error Completed list of packets, no error

Done, List,Error Completed list of packets, with error(s)

List in progress, No list, No Error First packet in a list of packets

List in progress, No list, Error First packet in a list of packets, with error(s)

List in progress, List, No Error Middle packet in a list of packets, no error

List in progress, List,Error Middle packet in a list of packets, with error(s)

State Transitions
A state transition occurs when a new packet arrives. The relevant information is extracted from the new packet causing the current state to be updated. The function EBF_sivUpdate (siv, edw, packet) performs this function.
The state information vector was carefully arranged so that 3 of the most interesting states told by a simply comparision with 0
  1. == 0, One and Only packet in the sequence
  2. > 0, Last packet in a sequence
  3. < 0, More packets to come

While the bits in the state information can be test directly, the user is encouraged to use the inlines provided for a more modular approach.
  • EBF__sivIsFirst - is the only or first packet of a sequence
  • EBF__sivIsNotFirst - is not the first packet of a sequence

  • EBF__stateIsMid - is the middle packet of a sequence
  • EBF__stateIsFirstOrLast - is the first and/or last packet

  • EBF__stateIsLast - is the only or last, i.e. no more to come
  • EBF__stateIsMore - more to follow

  • EBF__stateIsList - is member of a list
  • EBF__stateIsOnly - is the only packet

  • EBF__stateIsLastSeq - is the last member of a sequence

Typical Usage
The following code snippet illustrates typical usage
        siv = EBF_sivUpdate (ctl->siv, edw, pkt);  // Update the previous siv
        ctl->siv = siv;                            // Retain state

        EBF_dirCompose (dir, siv);                 // Always update the dir
        if (EBF_sivIsFirst (siv))                  // Check if first
        {
            ...
        }

        if (EBF_sivIsLast (siv))                   // Check is sequence is done
        {
            ..
            if (EBF_sivIsList (siv))               // If last in a list
            {
                EBF_dirReassemble (dir, ALL);
            }
        }

Enumeration Type Documentation

enum _EBF_SIV_M

The in place mask of the Packet Reassembly state information vector.

Enumerator:
EBF_SIV_M_STATE  State field mask
EBF_SIV_M_STATE_MORE  More packets are expected, i.e. a list is in progress
EBF_SIV_M_STATE_NOTFIRST  More than one packet is on the list
EBF_SIV_M_RSVD  Reserved field mask
EBF_SIV_M_ERR  Error field mask
EBF_SIV_M_ERR_SEQ  Unexpected sequence number on the other than the first packet
EBF_SIV_M_ERR_SEQ0  Unexpected sequence number on the first packet
EBF_SIV_M_ERR_EBM  The error field of EBM word of the first contributor was non-zero
EBF_SIV_M_ERR_PARITY  Parity error in the LATp word of the first contributor
EBF_SIV_M_ERR_XFR  Transfer error in the event descriptor
EBF_SIV_M_ERR_RCV  Receive error in the event descriptor
EBF_SIV_M_VAL  Value field mask
EBF_SIV_M_VAL_RSVD  Reserved value field mask
EBF_SIV_M_VAL_EDWSTATUS  The EDW (event descriptor word status
EBF_SIV_M_VAL_EBMERR  The EBM error field mask
EBF_SIV_M_VAL_EBMSEQ  The expected sequence number

enum _EBF_SIV_V

The right justified bit offsets of the Packet Reassembly state information vector.

Enumerator:
EBF_SIV_V_STATE  Beginning of the state field
EBF_SIV_V_STATE_MORE  More packets are expected, i.e. a list is in progress
EBF_SIV_V_STATE_NOTFIRST  Not the first packet on the list
EBF_SIV_V_RSVD  6 bit reserved field
EBF_SIV_V_ERR  Beginning of the error field
EBF_SIV_V_ERR_RSVD_7  Reserved for future use
EBF_SIV_V_ERR_RSVD_6  Reserved for future use
EBF_SIV_V_ERR_SEQ  Unexpected sequence number on the other than the first packet
EBF_SIV_V_ERR_SEQ0  Unexpected sequence number on the first packet
EBF_SIV_V_ERR_EBM  The error field of the EBM word of the first contributor was non-zero. .
EBF_SIV_V_ERR_PARITY  Parity error in the LATp word of the first contributor. In theory this should never occur. The LATp standard indicates that such packets should be discarded.
EBF_SIV_V_ERR_XFR  Transfer error in event descriptor
EBF_SIV_V_ERR_RCV  Receive error in event descriptor
EBF_SIV_V_VAL  Beginning of the value field
EBF_SIV_V_VAL_RSVD  3 bit reserved field
EBF_SIV_V_VAL_EDWSTATUS  5 bit field holding the receive and transmit status from the event descriptor word.
EBF_SIV_V_VAL_EBMERR  3 bit field holding the EBM error field from the first contribution
EBF_SIV_V_VAL_EBMSEQ  5 bit field holding the expected sequence number

Function Documentation

static __inline int EBF__sivHasErrors ( EBF_siv  siv  )  [static]

Returns a non-zero value if errors are present.

Return values:
Non-zero if errors are present
Zero is error free
Parameters:
siv The state information vector to test

References EBF_SIV_M_ERR.

static __inline int EBF__sivIsFirst ( EBF_siv  siv  )  [static]

Returns non-zero is this is the first or only packet in a sequence.

Return values:
== 0 if this is not the first or only member of a sequence != 0 if this is the first or only member of a sequence
Parameters:
siv The state information vector to test
This is logical opposite of EBF__sivIsNotFirst

References EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsFirstOrLast ( EBF_siv  siv  )  [static]

Returns non-zero is this is the first or last member of a sequence.

Return values:
== 0 if this is the first or last member of a sequence != 0 if this is not the first or last member of a sequence
Parameters:
siv The state information vector to test
This is the logical opposite of EBF__sivIsMid. Note that in the case that there is only one packet, this packet is both the first and the last, so this function will return non-zero.

References EBF_SIV_M_STATE_MORE, and EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsLast ( EBF_siv  siv  )  [static]

Returns non-zero is this is not the last or only member of a sequence.

Return values:
== 0 if this is not the last or only member of a sequence != 0 if this is the last or only member of a sequence
Parameters:
siv The state information vector to test
Warning:
To make these routines as trivial as possible, the user should strip the error fields using EBF__sivErrRemove;
This is logical opposite of EBF__sivIsMore.

static __inline int EBF__sivIsLastSeq ( EBF_siv  siv  )  [static]

Returns non-zero if this is the last packet in a sequence.

Return values:
== 0 if this is not the last member of a sequence != 0 if this is the last member of a sequence
Parameters:
siv The state information vector to test

References EBF_SIV_M_STATE_MORE, and EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsList ( EBF_siv  siv  )  [static]

Returns non-zero is this is a member of a sequence.

Return values:
== 0 if this is not a member of a sequence != 0 if this is a member of a sequence
Parameters:
siv The state information vector to test
This is the negation of EBF__sivIsOnly

References EBF_SIV_M_STATE_MORE, and EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsMid ( EBF_siv  siv  )  [static]

Returns non-zero is this is not the first or last member of a sequence.

Return values:
== 0 if this is not the first or last member of a sequence != 0 if this is the first or last member of a sequence
Parameters:
siv The state information vector to test
This is the logical opposite of EBF__sivIsFirstOrLast.

References EBF_SIV_M_STATE_MORE, and EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsMore ( EBF_siv  siv  )  [static]

Returns non-zero if there are more packets to come.

Return values:
== 0 if this is not the only member of a sequence != 0 if this is the only member of a sequence
Parameters:
siv The state information vector to test
This is logical opposite of EBF__sivIsLast.

static __inline int EBF__sivIsNotFirst ( EBF_siv  siv  )  [static]

Returns non-zero is this is the not first or only packet in a sequence.

Return values:
== 0 if this is the first or only member of a sequence != 0 if this is not the first or only member of a sequence
Parameters:
siv The state information vector to test
This is logical opposite of EBF__sivIsFirst

References EBF_SIV_M_STATE_NOTFIRST.

static __inline int EBF__sivIsOnly ( EBF_siv  siv  )  [static]

Returns non-zero is this is not the only member of a sequence.

Return values:
== 0 if this is not the only member of a sequence != 0 if this is the only member of a sequence
Parameters:
siv The state information vector to test
This is the negation of EBF__sivIsList

References EBF_SIV_M_STATE_MORE, and EBF_SIV_M_STATE_NOTFIRST.

Generated on Fri Dec 9 16:42:51 2011 by  doxygen 1.5.8