latp.h File Reference

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

Classes
struct	_LATp_TXstatsBF
	Structure that defines the LATp transmitter statistics word. More...
union	_LATp_TXstats
	Union for 16-bit LATp transmitter statistics word. More...
struct	_LATp_RXstatsBF
	Structure that defines the LATp receiver statistics word. More...
union	_LATp_RXstats
	Union for 16-bit LATp receiver statistics word. More...
struct	_BFrspErr
	Contains error info regarding LATp responses. More...
union	_rspErr
	union for 32-bit response error flags More...
struct	_gResponse
	Contains info for LATp responses. More...
struct	__BFcellHeader
	layout of a control cell header More...
union	__cellHeader
	union for 16-bit control cell header 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	_generic_Cell
	union for 128-bit LATp cell -- either control or data cell. More...
struct	_LATp_Cell
	LATp cell structure. 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 union _LATp_TXstats	LATp_TXstats
	typedef for union _LATp_TXstats
typedef union _LATp_RXstats	LATp_RXstats
	typedef for union _LATp_RXstats
typedef union _rspErr	rspErr
	typedef for union _rspErr
typedef struct _gResponse	gResponse
	Typedef for struct _gResponse.
typedef union __cellHeader	cellHeader
	typedef for union _cellHeader
typedef struct _LATp_ControlCell	LATp_ControlCell
	typedef for struct _LATp_ControlCell
typedef struct _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.

References _LOG1, G_OK, and ODD_PARITY.

Referenced by gReadRsp(), and sendLATpCell().

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.

References G_OK, GERR_BAD_PARAM, _gnat::m_invertCellBodyParity, and VERIFY_HANDLE.

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.

References G_OK, GERR_BAD_PARAM, _gnat::m_invertCellHeaderParity, and VERIFY_HANDLE.

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()

References _LATp_Interface::addr, G_OK, _gnat::m_latpIntr, and VERIFY_HANDLE.

Referenced by gGetHardwareInfo().

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.

References G_OK, GERR_BAD_PARAM, _gnat::m_latpIntr, _LATp_Interface::proto, and VERIFY_HANDLE.

Referenced by gSendLAM().

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()

References G_OK, GERR_BAD_PARAM, _gnat::m_latpIntr, _LATp_Interface::rxStats, _LATp_RXstats::ui, and VERIFY_HANDLE.

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()

References G_OK, GERR_BAD_PARAM, _gnat::m_latpIntr, _LATp_Interface::txStats, _LATp_TXstats::ui, and VERIFY_HANDLE.

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.

References _LOG, _LOG1, _LOG2B, _LATp_Interface::addr, G_OK, LAST_CELL, _gnat::m_invertCellHeaderParity, _gnat::m_latpIntr, MORE_CELLS, ODD_PARITY, _LATp_Interface::proto, and sendLATpCell().

Referenced by gSendPacket().

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.

References __errDump(), _LOG1, _LOG2, __cellHeader::bf, _rspErr::bf, _LATp_RXstats::bf, calcParity(), CELL_ANNOUNCE_MASK, _LATp_RXstatsBF::cell_parity, CELL_PARITY_MASK, CELL_TRUNCATE_MASK, CELL_TYPE_MASK, CELL_WORDS, G_OK, gEnableRF(), GERR_HANDLE_NOT_ACTIVE, GERR_LATP_CELL_ANNOUNCE, GERR_RSP_BUF_OVERFLOW, gFlushRF(), gIsEmptyRF(), gnat_irqDelay, gReadRF32(), gWaitPacketIRQ(), _LATp_RXstatsBF::header_parity, LATP_COUNTER_MAX, _gnat::m_active, _gnat::m_curBuf, _BFrspErr::m_err, _BFrspErr::m_errCellParity, _BFrspErr::m_errHeaderParity, _BFrspErr::m_errTrunc, _gnat::m_latpIntr, _gResponse::m_rspBuffer, _gnat::m_rspBuffer, _gResponse::m_rspErr, _gResponse::m_rspSize, ODD_PARITY, __BFcellHeader::parity, _LATp_RXstatsBF::rx_ctrl, _LATp_RXstatsBF::rx_data, _LATp_Interface::rxStats, and __cellHeader::ui.

Referenced by gSendPacket().

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()

References G_OK, _gnat::m_latpIntr, _LATp_Interface::rxStats, _LATp_Interface::txStats, _LATp_RXstats::ui, _LATp_TXstats::ui, and VERIFY_HANDLE.

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.

References _LAMpayload, G_OK, gGetProtocol(), gSendPacket(), gSetProtocol(), and VERIFY_HANDLE.

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.

References __dumpFIFO(), _CHECK, G_OK, gCommReady(), gEnablePF(), gEnableRF(), GERR_BAD_PARAM, GERR_RSP_FIFO_NOT_EMPTY, gFlushPF(), gFlushRF(), gIsEmptyRF(), gLoadPacket(), gReadRsp(), gStartPB(), and VERIFY_HANDLE.

Referenced by gSendLAM().

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()

References _LATp_Interface::addr, G_OK, _gnat::m_latpIntr, and VERIFY_HANDLE.

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.

References _regControl::bf, _BFregControl::dataChn, G_OK, GERR_BAD_PARAM, _gnat::m_baseAddr, _regBlock::m_ctrlReg, MAX_CHANNEL, _regControl::ui, and VERIFY_HANDLE.

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".

References _regControl::bf, G_OK, _gnat::m_baseAddr, _regBlock::m_ctrlReg, _BFregControl::mode, _regControl::ui, and VERIFY_HANDLE.

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.

References G_OK, _gnat::m_latpIntr, _LATp_Interface::proto, and VERIFY_HANDLE.

Referenced by gSendLAM().

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()

References G_OK, GERR_BAD_PARAM, _gnat::m_latpIntr, _LATp_Interface::rxStats, _LATp_RXstats::ui, and VERIFY_HANDLE.

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

References G_OK, _gnat::m_latpIntr, _LATp_Interface::timeout, and VERIFY_HANDLE.

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()

References G_OK, GERR_BAD_PARAM, _gnat::m_latpIntr, _LATp_Interface::txStats, _LATp_TXstats::ui, and VERIFY_HANDLE.

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().

References G_OK, GERR_RSP_TIMEOUT, _gnat::m_latpIntr, _LATp_Interface::timeout, and VERIFY_HANDLE.

Referenced by gReadRsp().

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.

References G_OK, _gnat::m_invertCellBodyParity, and VERIFY_HANDLE.

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.

References G_OK, _gnat::m_invertCellHeaderParity, and VERIFY_HANDLE.

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.

References G_OK, _gnat::m_nSkipRsp, and VERIFY_HANDLE.