GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> QSEP / V3-5-1 > qsep / sun-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » QSD » source » QSEP » V3-5-1 » src

SIV.h File Reference

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


Typedefs

typedef enum _SIV_V SIV_V
 Typedef for enum _SIV_V.
typedef enum _SIV_M SIV_M
 Typedef for SIV_M.
typedef signed int SIV
 The state information vector.

Enumerations

enum  _SIV_V {
  SIV_V_STATE = 30,
  SIV_V_STATE_MORE = SIV_V_STATE + 1,
  SIV_V_STATE_NOTFIRST = SIV_V_STATE + 0,
  SIV_V_RSVD = 24,
  SIV_V_ERR = 16,
  SIV_V_ERR_RSVD_7 = SIV_V_ERR + 7,
  SIV_V_ERR_RSVD_6 = SIV_V_ERR + 6,
  SIV_V_ERR_SEQ = SIV_V_ERR + 5,
  SIV_V_ERR_SEQ0 = SIV_V_ERR + 4,
  SIV_V_ERR_EBM = SIV_V_ERR + 3,
  SIV_V_ERR_PARITY = SIV_V_ERR + 2,
  SIV_V_ERR_XFR = SIV_V_ERR + 1,
  SIV_V_ERR_RCV = SIV_V_ERR + 0,
  SIV_V_VAL = 0,
  SIV_V_VAL_RSVD = SIV_V_VAL + 13,
  SIV_V_VAL_EDWSTATUS = SIV_V_VAL + 8,
  SIV_V_VAL_EBMERR = SIV_V_VAL + 5,
  SIV_V_VAL_EBMSEQ = SIV_V_VAL + 0
}
 The right justified bit offsets of the Packet Reassembly state information vector. More...
enum  _SIV_M {
  SIV_M_STATE = (0x3 << SIV_V_STATE),
  SIV_M_STATE_MORE = (1 << SIV_V_STATE_MORE),
  SIV_M_STATE_NOTFIRST = (1 << SIV_V_STATE_NOTFIRST),
  SIV_M_RSVD = (0x3f << SIV_V_RSVD),
  SIV_M_ERR = (0xff << SIV_V_ERR),
  SIV_M_ERR_SEQ = (1 << SIV_V_ERR_SEQ ),
  SIV_M_ERR_SEQ0 = (1 << SIV_V_ERR_SEQ0),
  SIV_M_ERR_EBM = (1 << SIV_V_ERR_EBM),
  SIV_M_ERR_PARITY = (1 << SIV_V_ERR_PARITY),
  SIV_M_ERR_XFR = (1 << SIV_V_ERR_XFR ),
  SIV_M_ERR_RCV = (1 << SIV_V_ERR_RCV ),
  SIV_M_VAL = (0xffff << SIV_V_VAL),
  SIV_M_VAL_RSVD = (0x3 << SIV_V_VAL_RSVD),
  SIV_M_VAL_EDWSTATUS = (0x1f << SIV_V_VAL_EDWSTATUS),
  SIV_M_VAL_EBMERR = (0x7 << SIV_V_VAL_EBMERR),
  SIV_M_VAL_EBMSEQ = (0x1f << SIV_V_VAL_EBMSEQ)
}
 The in place mask of the Packet Reassembly state information vector. More...

Functions

SIV SIV_init (void)
 Returns an initializes the Packet Reassembly State Information Vector.
SIV SIV_update (SIV siv, unsigned int edw, const EBF_pkt *pkt)
 Returns the updated the State Information Vector.
static __inline int SIV__isFirst (SIV siv)
 Returns non-zero is this is the first or only packet in a sequence.
static __inline int SIV__isNotFirst (SIV siv)
 Returns non-zero is this is the not first or only packet in a sequence.
static __inline int SIV__isMid (SIV siv)
 Returns non-zero is this is not the first or last member of a sequence.
static __inline int SIV__isFirstOrLast (SIV siv)
 Returns non-zero is this is the first or last member of a sequence.
static __inline int SIV__isLast (SIV siv)
 Returns non-zero is this is not the last or only member of a sequence.
static __inline int SIV__isMore (SIV siv)
 Returns non-zero if there are more packets to come.
static __inline int SIV__isList (SIV siv)
 Returns non-zero is this is a member of a sequence.
static __inline int SIV__isOnly (SIV siv)
 Returns non-zero is this is not the only member of a sequence.
static __inline int SIV__isLastSeq (SIV siv)
 Returns non-zero if this is the last packet in a sequence.
static __inline int SIV__hasErrors (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: SIV.h,v 1.1 2006/02/15 22:31:41 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 SIV_Update (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.
  • SIV__isFirst - is the only or first packet of a sequence
  • SIV__isNotFirst - is not the first packet of a sequence

  • SIV__issMid - is the middle packet of a sequence
  • SIV__isFirstOrLast - is the first and/or last packet

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

  • SIV__isList - is member of a list
  • SIV__isOnly - is the only packet

  • SIV__isLastSeq - is the last member of a sequence

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

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

        if (SIV_isLast (siv))                   // Check is sequence is done
        {
            EBF_dirReassemble (dir, ALL);
        }

Enumeration Type Documentation

enum _SIV_M

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

Enumerator:
SIV_M_STATE  State field mask
SIV_M_STATE_MORE  More packets are expected, i.e. a list is in progress
SIV_M_STATE_NOTFIRST  More than one packet is on the list
SIV_M_RSVD  Reserved field mask
SIV_M_ERR  Error field mask
SIV_M_ERR_SEQ  Unexpected sequence number on the other than the first packet
SIV_M_ERR_SEQ0  Unexpected sequence number on the first packet
SIV_M_ERR_EBM  The error field of EBM word of the first contributor was non-zero
SIV_M_ERR_PARITY  Parity error in the LATp word of the first contributor
SIV_M_ERR_XFR  Transfer error in the event descriptor
SIV_M_ERR_RCV  Receive error in the event descriptor
SIV_M_VAL  Value field mask
SIV_M_VAL_RSVD  Reserved value field mask
SIV_M_VAL_EDWSTATUS  The EDW (event descriptor word status
SIV_M_VAL_EBMERR  The EBM error field mask
SIV_M_VAL_EBMSEQ  The expected sequence number

enum _SIV_V

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

Enumerator:
SIV_V_STATE  Beginning of the state field
SIV_V_STATE_MORE  More packets are expected, i.e. a list is in progress
SIV_V_STATE_NOTFIRST  Not the first packet on the list
SIV_V_RSVD  6 bit reserved field
SIV_V_ERR  Beginning of the error field
SIV_V_ERR_RSVD_7  Reserved for future use
SIV_V_ERR_RSVD_6  Reserved for future use
SIV_V_ERR_SEQ  Unexpected sequence number on the other than the first packet
SIV_V_ERR_SEQ0  Unexpected sequence number on the first packet
SIV_V_ERR_EBM  The error field of the EBM word of the first contributor was non-zero. .
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.
SIV_V_ERR_XFR  Transfer error in event descriptor
SIV_V_ERR_RCV  Receive error in event descriptor
SIV_V_VAL  Beginning of the value field
SIV_V_VAL_RSVD  3 bit reserved field
SIV_V_VAL_EDWSTATUS  5 bit field holding the receive and transmit status from the event descriptor word.
SIV_V_VAL_EBMERR  3 bit field holding the EBM error field from the first contribution
SIV_V_VAL_EBMSEQ  5 bit field holding the expected sequence number

Function Documentation

static __inline int SIV__hasErrors ( 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 SIV_M_ERR.

Referenced by evtA_0_decode().

static __inline int SIV__isFirst ( 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 SIV__isNotFirst

References SIV_M_STATE_NOTFIRST.

static __inline int SIV__isFirstOrLast ( 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 SIV_M_STATE_MORE, and SIV_M_STATE_NOTFIRST.

static __inline int SIV__isLast ( 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 SIV__errRemove;
This is logical opposite of EBF__sivIsMore.

Referenced by evtA_0_decode().

static __inline int SIV__isLastSeq ( 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 SIV_M_STATE_MORE, and SIV_M_STATE_NOTFIRST.

static __inline int SIV__isList ( 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 SIV__isOnly

References SIV_M_STATE_MORE, and SIV_M_STATE_NOTFIRST.

static __inline int SIV__isMid ( 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 SIV_M_STATE_MORE, and SIV_M_STATE_NOTFIRST.

static __inline int SIV__isMore ( 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 SIV__isLast.

static __inline int SIV__isNotFirst ( 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 SIV_M_STATE_NOTFIRST.

Referenced by evtA_0_decode().

static __inline int SIV__isOnly ( 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 SIV__isList

References SIV_M_STATE_MORE, and SIV_M_STATE_NOTFIRST.

SIV SIV_init ( void   ) 

Returns an initializes the Packet Reassembly State Information Vector.

Returns:
The inialization value of the Packet Reassembly State Information

Referenced by evtA_0_decode().

SIV_update ( SIV  siv,
unsigned int  edw,
const EBF_pkt *  pkt 
)

Returns the updated the State Information Vector.

Returns:
The updated the State Information Vector
Parameters:
siv The current value of the State Information Vector
edw The event descriptor word
pkt The new EBF packet. This contains the information used to perform the update

References ERR_EBM, ERR_XFR, MORE_ERR_RCV, NOTFIRST, SIV_M_ERR, SIV_M_STATE_MORE, SIV_M_VAL, SIV_M_VAL_EBMSEQ, SIV_V_ERR_PARITY, SIV_V_ERR_SEQ0, SIV_V_STATE_NOTFIRST, SIV_V_VAL_EBMERR, SIV_V_VAL_EBMSEQ, and SIV_V_VAL_EDWSTATUS.

Referenced by evtA_0_decode().

Generated on Fri Nov 30 11:42:42 2012 by  doxygen 1.5.8