GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > GNAT / V2-0-0

Constituent: gnat_cio     Tag: mv2304

Interface   Data Structures   File List   Data Fields   Globals  

latp.h File Reference

Defines public structs and methods of the LATp protocol. More...

This graph shows which files directly or indirectly include this file:

Included by dependency graph

Data Structures

struct  __BFcellHeader
 layout of a control cell header More...

union  __cellHeader
 union for 16-bit control cell header More...

struct  _BFrspErr
 Contains error info regarding LATp responses. More...

union  _generic_Cell
 union for 128-bit LATp cell -- either control or data cell. More...

struct  _gResponse
 Contains info for LATp responses. More...

struct  _LATp_Cell
 LATp cell structure. More...

struct  _LATp_ControlCell
 layout of a 128-bit LATp control cell. More...

struct  _LATp_DataCell
 layout of a 128-bit LATp data cell. More...

union  _LATp_RXstats
 Union for 16-bit LATp receiver statistics word. More...

struct  _LATp_RXstatsBF
 Structure that defines the LATp receiver statistics word. More...

union  _LATp_TXstats
 Union for 16-bit LATp transmitter statistics word. More...

struct  _LATp_TXstatsBF
 Structure that defines the LATp transmitter statistics word. More...

union  _rspErr
 union for 32-bit response error flags More...


Defines

#define WAIT_FOREVER   (0)
 Defined for local host compilation.

#define MAX_EVENT_SIZE   (4096)
 Maximum event size in bytes.

#define LATP_CELL_SIZE_BYTES   (sizeof(LATp_DataCell))
 Size of LATp cell in bytes.

#define ODD_PARITY(p)   (~(BITCOUNT(p)) & 0x1)
 Computes odd parity of 32-bit argument.

#define EVEN_PARITY(p)   ((BITCOUNT(p)) & 0x1)
 Computes even parity of 32-bit argument.

#define BITCOUNT(x)   (((BX_(x)+(BX_(x)>>4)) & 0x0F0F0F0F) % 255)
 Computes the number of bits set (1) in 32-but argument.

#define BX_(x)
 Replaces each 4-bit sequence in arg by the number of bits in sequence.


Typedefs

typedef _LATp_TXstats LATp_TXstats
 typedef for union _LATp_TXstats

typedef _LATp_RXstats LATp_RXstats
 typedef for union _LATp_RXstats

typedef _rspErr rspErr
 typedef for union _rspErr

typedef _gResponse gResponse
 Typedef for struct _gResponse.

typedef __cellHeader cellHeader
 typedef for union _cellHeader

typedef _LATp_ControlCell LATp_ControlCell
 typedef for struct _LATp_ControlCell

typedef _LATp_DataCell LATp_DataCell
 typedef for struct _LATp_DataCell

typedef enum _CellType CellType
 typedef of enum _CellType


Enumerations

enum  _CellType {
  dataCell = 0,
  ctrlCell = 1
}
 Enumeration of cell types: control or data.


Functions

int gSendPacket (gnatHandle gh, gResponse *rspInfo, unsigned short dest, unsigned short nWord16, unsigned short *payload)
 Sends a LATp packet on the LAT network.

int gLoadPacket (gnatHandle gh, gResponse *rspInfo, unsigned short dest, unsigned short nWord16, unsigned short *payload)
 Loads a LATp packet into the COMM board FIFO.

int gSendLAM (gnatHandle gh, unsigned short destAddr)
 Sends the "Look At Me" message to the LAT node destAddr.

int gSetAddr (gnatHandle gh, unsigned short addr)
 Sets the source address of the LATp interface associated with gh.

int gGetAddr (gnatHandle gh, unsigned short *addr)
 Gets the source address of the LATp interface associated with gh.

int gResetCommStats (gnatHandle gh)
 Resets the network statistics for the LATp interface associated with gh.

int gGetTXstats (gnatHandle gh, LATp_TXstats *txStats)
 Returns the current transmission statistics.

int gSetTXstats (gnatHandle gh, LATp_TXstats *txStats)
 Sets the current transmission statistics from txStats.

int gGetRXstats (gnatHandle gh, LATp_RXstats *rxStats)
 Returns the current recieve statistics.

int gSetRXstats (gnatHandle gh, LATp_RXstats *rxStats)
 Sets the current recieve statistics from rxStats.

int gSetLATpChnl (gnatHandle gh, unsigned char chnl)
 Sets the incoming LATp channel number for the board.

int gSetLATpMode (gnatHandle gh, unsigned char mode)
 Sets the running mode of the board.

int gSetProtocol (gnatHandle gh, unsigned short proto)
 Sets the protocol to use.

int gGetProtocol (gnatHandle gh, unsigned short *proto)
 Gets the current LATp protocol.

int gSetTimeout (gnatHandle gh, unsigned short timeout)
 Sets the timeout to use for LATp interface.

int gReadRsp (gnatHandle gh, gResponse *rspInfo)
 Transfers data from the record FIFO to the rspInfo structure.

int gWaitPacketIRQ (gnatHandle gh)
 Blocks on the ISR semaphore waiting for LATp packet ready IRQ.

int setLATpCellHeaderParity (gnatHandle gh, unsigned short p)
 p determines if the LATp CellHeader Parity is inverted

int getLATpCellHeaderParity (gnatHandle gh, unsigned short *p)
 Returns the current LATp cell header parity setting in p.

int setLATpCellBodyParity (gnatHandle gh, unsigned short p)
 p determines if the LATp CellBody Parity is inverted

int getLATpCellBodyParity (gnatHandle gh, unsigned short *p)
 Returns current LATp CellBody Parity in p.

int setLATpSkipRspWords (gnatHandle gh, unsigned short nSkip)
 nSkip controls how many FIFO words to skip before storing read back data.

int calcParity (unsigned int nWords, unsigned int *arr)
 Calculates the odd parity in arr.

Detailed Description

Defines public structs and methods of the LATp protocol.

Author:
Curt Brune -- curt@slac.stanford.edu

Define Documentation

#define BITCOUNT (  x   )     (((BX_(x)+(BX_(x)>>4)) & 0x0F0F0F0F) % 255)
 

Computes the number of bits set (1) in 32-but argument.

See also:
BX_
Macros to compute a bit value from a bit number, bit number from bit value, and the bit count (number of bits on) for 32-bit quantities. The results are compile-time constants if the arguments are.

The definition of BITCOUNT is based on an algorithm condensed from one extracted from a graph coloring register allocator which manipulates bitvectors. It was inspired by an analogous algorithm for counting bits in 36 bit words in MIT's HAKMEM, designed by Chris Smith, and written by Jane Hoffman. The original conversion to a form suitable for C on a VAX was by Brad Merrill; that code was fixed and re-written by Jerry Leichter. It assumes a 32-bit word. Note that the argument is evaluated multiple times, so should not have side-effects. A full explanation of the algorithm is too long to include here; in summary, BX_(x) replaces each 4-bit sequence in x by the number of bits in that sequence (which will, of course, fit in 4 bits). BITCOUNT folds the 4-bit sequences into 8-bit sequences. The 8-bit sequences are then added up by recognizing that they can be viewed as a base 256 number, and the sum of the digits of a base b number is the same mod b-1 as the number mod b-1.

The original implementation produce results in groups of 3, then 6 bits. While natural on a PDP-10's 36-bit word, this requires special case handling of the sign bit on a VAX, since the top 3-bit sequence is really only 2 bits long.

#define BX_ (  x   ) 
 

Value:

((x) - (((x)>>1)&0x77777777)                    \
                             - (((x)>>2)&0x33333333)                    \
                             - (((x)>>3)&0x11111111))
Replaces each 4-bit sequence in arg by the number of bits in sequence.

See also:
BITCOUNT
Replaces each 4-bit sequence in 32-bit argument by the number of bits in that sequence (which will, of course, fit in 4 bits).

Function Documentation

int calcParity (  unsigned int  nWords,
unsigned int *  arr
) 
 

Calculates the odd parity in arr.

Parameters:
nWords Number of unsigned ints in @ arr
arr Array of unsigned ints
Returns:
odd parity of the bits contained in @ arr.

int getLATpCellBodyParity (  gnatHandle  gh,
unsigned short *  p
) 
 

Returns current LATp CellBody Parity in p.

Parameters:
gh handle of device
p pointer to hold boolean value
Returns:
STATUS
If p is non-zero then all out going LATp packets will have their cell body parity inverted. This is used for testing parity errors. The default value is 0.

int getLATpCellHeaderParity (  gnatHandle  gh,
unsigned short *  p
) 
 

Returns the current LATp cell header parity setting in p.

Parameters:
gh handle of device
p pointer to hold boolean value
Returns:
STATUS
If p is non-zero then all out going LATp packets will have their cell header parity inverted. This is used for testing parity errors. The default value is 0.

int gGetAddr (  gnatHandle  gh,
unsigned short *  addr
) 
 

Gets the source address of the LATp interface associated with gh.

Parameters:
gh gnat driver handle previously allocated
addr pointer to storage for holding LATp address on return
Returns:
OK for success
See also:
gSetAddr()

int gGetProtocol (  gnatHandle  gh,
unsigned short *  proto
) 
 

Gets the current LATp protocol.

Parameters:
gh handle of device
proto pointer to storage to hold the protocol
See also:
gSetProtocol()
Returns:
OK on success
This gets the protocol field, which is applied to the cell header for all subsequent out bound packets.

int gGetRXstats (  gnatHandle  gh,
LATp_RXstats *  rxStats
) 
 

Returns the current recieve statistics.

Parameters:
gh gnat driver handle previously allocated
rxStats pointer to storage for holding the RX stats on return
Returns:
OK for success
See also:
gGetTXstats(), gResetCommStats()

int gGetTXstats (  gnatHandle  gh,
LATp_TXstats *  txStats
) 
 

Returns the current transmission statistics.

Parameters:
gh gnat driver handle previously allocated
txStats pointer to storage for holding the TX stats on return
Returns:
OK for success
See also:
gGetRXstats(), gResetCommStats()

int gLoadPacket (  gnatHandle  gh,
gResponse *  rspInfo,
unsigned short  dest,
unsigned short  nWord16,
unsigned short *  payload
) 
 

Loads a LATp packet into the COMM board FIFO.

Parameters:
gh gnat driver handle previously allocated
rspInfo pointer to storage for response
dest 6 bit LAT address of destination
nWord16 length of the 16-bit wide payload vector
payload pointer to an array of 16-bit words of length nWord16
Returns:
OK for success
See also:
sendLATpCell

Loads a LATp packet into the COMM board FIFO. Using rspInfo, dest, source it constructs a 16 bit header word for the control cell of the packet. It fills the remainder of the 128-bit control cell with data from payload (up to 14 bytes). The control cell is preceded by a 2 bit delineator and follow by a truncate bit and parity bit -- if the payload is larger than 14 bytes then additional data cells are created and injected with the appropriate delineator and suffix bits.

Caller is responsible for initializing FIFO and for initiating the playback.

Here is the call graph for this function:

int gReadRsp (  gnatHandle  gh,
gResponse *  rspInfo
) 
 

Transfers data from the record FIFO to the rspInfo structure.

Parameters:
gh gnat driver handle previously allocated
rspInfo pointer to storage to hold response data
After recieving the interrupt for "record FIFO packet ready" readRsp() transfers the packet from the record FIFO to rspInfo->m_rspBuffer;

The routine checks bits 17 and 18 of every 9th FIFO word to determine when the last packet has been processed -- when these bits are both zero we have reached the end of the packet chain (potentially multiple packets, if the packets are back-to-back).

Updates the LATp interface reciever statistics for packets received, cell parity errors and cell header parity errors. The response could contain multiple packets.

Coming off the response FIFO LATp cells are 9 words long. Word 1 has the cell announce and cell type bits, while word 9 has the truncate and parity error bits.

Additionally word 1 also has the cell header if the cell type is a control cell.

Here is the call graph for this function:

int gResetCommStats (  gnatHandle  gh  ) 
 

Resets the network statistics for the LATp interface associated with gh.

Parameters:
gh gnat driver handle previously allocated
Returns:
OK for success
See also:
gGetTXstats(), gGetRXstats()

int gSendLAM (  gnatHandle  gh,
unsigned short  destAddr
) 
 

Sends the "Look At Me" message to the LAT node destAddr.

Parameters:
gh gnat driver handle previously allocated
destAddr destination address of command
Returns:
G_OK on success
Sends the "Look At Me" message to the LAT node specified by destAddr. This is used to switch the command/response wire used by the LAT node. If the LAT node decodes the "Look At Me" message on either it's A or B command channel it will switch to that channel for future commanding.

Here is the call graph for this function:

int gSendPacket (  gnatHandle  gh,
gResponse *  rspInfo,
unsigned short  dest,
unsigned short  nWord16,
unsigned short *  payload
) 
 

Sends a LATp packet on the LAT network.

Parameters:
gh gnat driver handle previously allocated
rspInfo pointer to extra information required if command expects a response.
dest 6 bit LAT address of destination
nWord16 length of the 16-bit wide payload vector
payload pointer to an array of 16-bit words of length nWord16
Returns:
OK for success
See also:
sendLATpCell

Sends a LATp packet on the network. Using rspInfo, dest, source it constructs a 16 bit header word for the control cell of the packet. It fills the remainder of the 128-bit control cell with data from payload (up to 14 bytes). The control cell is injected in the network preceded by a 2 bit delineator and follow by a truncate bit and parity bit -- if the payload is larger than 14 bytes then additional data cells are created and injected with the appropriate delineator and suffix bits.

Here is the call graph for this function:

int gSetAddr (  gnatHandle  gh,
unsigned short  addr
) 
 

Sets the source address of the LATp interface associated with gh.

Parameters:
gh gnat driver handle previously allocated
addr LATp address
Returns:
OK for success
See also:
gGetAddr()

int gSetLATpChnl (  gnatHandle  gh,
unsigned char  chnl
) 
 

Sets the incoming LATp channel number for the board.

Parameters:
gh handle of device
chnl channel number
Returns:
OK on success
Sets the incoming LATp channel number of the COMM I/O board when running in LATp mode. Causes a read-modify-write of the COMM I/O control register.

int gSetLATpMode (  gnatHandle  gh,
unsigned char  mode
) 
 

Sets the running mode of the board.

Parameters:
gh handle of device
mode boolean for LATp mode
Returns:
OK on success
Sets the running mode of the COMM I/O board based on the boolean value of mode. When mode is non-zero the mode bit of the COMM I/O control register is set to 1, which puts the board in "LATp mode". When mode is zero the mode bit is cleared, which puts the board in "dumb record FIFO mode".

int gSetProtocol (  gnatHandle  gh,
unsigned short  proto
) 
 

Sets the protocol to use.

Parameters:
gh handle of device
proto 2 LSB define the protocol to use
See also:
gGetProtocol()
Returns:
OK on success
This sets the protocol field of the cell header for all subsequent out bound packets.

int gSetRXstats (  gnatHandle  gh,
LATp_RXstats *  rxStats
) 
 

Sets the current recieve statistics from rxStats.

Parameters:
gh gnat driver handle previously allocated
rxStats pointer to RX stats to set
Returns:
OK for success
See also:
gGetTXstats(), gResetCommStats()

int gSetTimeout (  gnatHandle  gh,
unsigned short  timeout
) 
 

Sets the timeout to use for LATp interface.

Parameters:
gh handle of device
timeout time in sysclk ticks to wait for response
Returns:
OK on success

int gSetTXstats (  gnatHandle  gh,
LATp_TXstats *  txStats
) 
 

Sets the current transmission statistics from txStats.

Parameters:
gh gnat driver handle previously allocated
txStats pointer to TX stats to set.
Returns:
OK for success
See also:
gGetRXstats(), gResetCommStats()

int gWaitPacketIRQ (  gnatHandle  gh  ) 
 

Blocks on the ISR semaphore waiting for LATp packet ready IRQ.

Parameters:
gh handle of device
Returns:
OK on success
See also:
gSetTimeout()
Blocks waiting for the ISR semaphore. The timeout value is set using gSetTimeout().

int setLATpCellBodyParity (  gnatHandle  gh,
unsigned short  p
) 
 

p determines if the LATp CellBody Parity is inverted

Parameters:
gh handle of device
p boolean value
Returns:
STATUS
If p is non-zero then all out going LATp packets will have their cell body parity inverted. This is used for testing parity errors. The default value is 0.

int setLATpCellHeaderParity (  gnatHandle  gh,
unsigned short  p
) 
 

p determines if the LATp CellHeader Parity is inverted

Parameters:
gh handle of device
p boolean value
Returns:
STATUS
If p is non-zero then all out going LATp packets will have their cell header parity inverted. This is used for testing parity errors. The default value is 0.

int setLATpSkipRspWords (  gnatHandle  gh,
unsigned short  nSkip
) 
 

nSkip controls how many FIFO words to skip before storing read back data.

Parameters:
gh handle of device
nSkip number of read back FIFO words to skip
Returns:
STATUS
Warning: This is only used for testing. The default value is 0 and should never be changed in normal operation.

Setting nSkip to a non-zero value causes the read back routine to skip nSkip FIFO words (read and discard) before storing the data.

This allows us to arbitrarily fill the record FIFO with N junk words and then instruct the read back routines to skip over the N junk words before reading and storing the data. With this technique we can probe the TEM to COMM flow control based on the Almost Full Flag of the record FIFO.

Generated on Thu Oct 21 08:27:22 2004 by doxygen 1.3.3