LCBR.h File Reference

Definitions of the LCB response structures. More...

#include "LCBD/LATP.h"
#include "LCBD/LCB_cr.h"
#include "LCBD/LCB.h"
#include "PBI/Attribute.h"
#include "PBI/Inline.h"

Include dependency graph for LCBR.h:

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


Defines
#define	LCBR_MAP_TYPE_BY_OPCODE
	Defines a 32-bit integer that functions as a map of the response type indexed by opcode.
#define	LCBR_TYPE_BY_OPCODE_FULL(_map, _opcode) (((unsigned int)_map >> (2 * (_opcode))) & 0x3)
	Maps an opcode to a result item type.
#define	LCBR_TYPE_BY_OPCODE(_opcode) LCBR_TYPE_BY_OPCODE_FULL(LCBR_MAP_TYPE_BY_OPCODE, _opcode)
	Maps an opcode to a result item type.
#define	LCBR_MAP_N8BYTES_BY_OPCODE
	Defines a 32-bit integer that functions as a map of the response item size indexed by opcode.
#define	LCBR_N8BYTES_BY_OPCODE_FULL(_map, _opcode) (((unsigned int)_map >> (2 * (_opcode))) & 0x3)
	Maps an opcode to a response item size in units of 8 byte cells.
#define	LCBR_N8BYTES_BY_OPCODE(_opcode) LCBR_N8BYTES_BY_OPCODE_FULL(LCBR_MAP_N8BYTES_BY_OPCODE, _opcode)
	Maps an opcode to a response item size in units of 8 byte cells.
Typedefs
typedef enum _LCBR_TYPE	LCBR_TYPE
	Typedef for enum _LCBR_TYPE.
typedef unsigned int	LCBR_processor (void prm, const LCB_ri ri)
	Callback routine for LCBR_process.
Enumerations
enum	_LCBR_TYPE { LCBR_TYPE_UNDEFINED = 0, LCBR_TYPE_RESPONSE = 1, LCBR_TYPE_REGISTER = 2, LCBR_TYPE_COMMAND = 3 }
	Enumerates the three defined result item types + one undefined type. More...
Functions
LCBR__EXP_PROTO const void *	LCBR__advance (const LCB_ri *ri, int nbytes) ATTR_UNUSED_OK
	Advances the pointer ri by the specified number of bytes.
LCBR__EXP_PROTO const LCB_ri *	LCBR__next (const LCB_ri *ri) ATTR_UNUSED_OK
	Advances the pointer ri to the next result item.
LCBR__EXP_PROTO unsigned int	LCBR__data32_get (unsigned short *payload) ATTR_UNUSED_OK
	Returns the first 32-bit word of the payload of ri.
unsigned int	LCBR_process (const LCB_ri ri, const LCB_ri end, LCBR_processor rtn, void *prm)
	Executes the user specified handler for each result item in the range ri to end.
const LCB_ri *	LCBR_check (const LCB_ri ri, const LCB_ri end)
	Checks the specified range of result items for errors.
unsigned int	LCBR_error_get (const LCB_ri *ri)
	Returns the 16-bit error word of ri.
void	LCBR_show (unsigned int options, const LCB_ri beg, const LCB_ri end)
	Dumps the result items to stdout.

Detailed Description

Definitions of the LCB response structures.

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

  CVS $Id

These map out the data structure of response items. See chapter 3 & 4 of Mike Huffer's "LAT Communications Board -- Design Specification" for more details.

Define Documentation

#define LCBR_MAP_N8BYTES_BY_OPCODE

Value:
( \ (LCB_RI_N8BYTES_CMD << (2 * LCB_OPCODE_CMD )) | \ (LCB_RI_N8BYTES_MARK_TIME << (2 * LCB_OPCODE_MARK_TIME )) | \ (LCB_RI_N8BYTES_EVENT << (2 * LCB_OPCODE_EVENT )) | \ (LCB_RI_N8BYTES_LAT_RESET << (2 * LCB_OPCODE_LAT_RESET )) | \ (LCB_RI_N8BYTES_CMDR << (2 * LCB_OPCODE_CMDR )) | \ (LCB_RI_N8BYTES_CSR << (2 * LCB_OPCODE_CSR )) | \ (0 << (2 * LCB_OPCODE_6 )) | \ (LCB_RI_N8BYTES_FAULTS << (2 * LCB_OPCODE_FAULTS )) | \ (0 << (2 * LCB_OPCODE_8 )) | \ (LCB_RI_N8BYTES_RXSTATS << (2 * LCB_OPCODE_RXSTATS )) | \ (0 << (2 * LCB_OPCODE_A )) | \ (0 << (2 * LCB_OPCODE_B )) | \ (0 << (2 * LCB_OPCODE_C )) | \ (0 << (2 * LCB_OPCODE_D )) | \ (0 << (2 * LCB_OPCODE_E )) | \ (0 << (2 * LCB_OPCODE_F )) \ )
Defines a 32-bit integer that functions as a map of the response item size indexed by opcode.
The 32-bit integer functions as a map of the response item size, in 8 bytes cells, indexed by opcode. Since response items have sizes, in 8 byte cells, of 1, 2 or 3 it takes 2 bits to represent the size. A value of 0 acts as a flag value for unknown types. Thus with each response item size consuming 2 bits, the 16 opcodes take 32 bits.

#define LCBR_MAP_TYPE_BY_OPCODE

Value:
( \ (LCBR_TYPE_RESPONSE << (2 * LCB_OPCODE_CMD )) | \ (LCBR_TYPE_RESPONSE << (2 * LCB_OPCODE_MARK_TIME )) | \ (LCBR_TYPE_RESPONSE << (2 * LCB_OPCODE_EVENT )) | \ (LCBR_TYPE_RESPONSE << (2 * LCB_OPCODE_LAT_RESET )) | \ (LCBR_TYPE_COMMAND << (2 * LCB_OPCODE_CMDR )) | \ (LCBR_TYPE_REGISTER << (2 * LCB_OPCODE_CSR )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_6 )) | \ (LCBR_TYPE_REGISTER << (2 * LCB_OPCODE_FAULTS )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_8 )) | \ (LCBR_TYPE_REGISTER << (2 * LCB_OPCODE_RXSTATS )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_A )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_B )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_C )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_D )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_E )) | \ (LCBR_TYPE_UNDEFINED << (2 * LCB_OPCODE_F )) \ )
Defines a 32-bit integer that functions as a map of the response type indexed by opcode.
The 32-bit integer functions as a map of the response type indexed by opcode. Each response type consumes 2 bits. Given that there are 16 potential opcodes, it takes 32 bits to define the map. The map is indexed by shifing the map by 2 * opcode and masking off the low 2 bits. Once the 32-bit value is loaded into a register (2 instructions), onthe PowerPC this should be two instructions.

type = ((LCBR_MAP_TYPE_BY_OPCODE >> (2 * opcode)) & 0x3);
There are 16 opcodes, that map to 4 descriptor types Size Cells Bytes 0 LCB_OPCODE_CMD = LCBR_TYPE_RESPONSE 1 16 1 LCB_OPCODE_MARK_TIME = LCBR_TYPE_RESPONSE 1 8 2 LCB_OPCODE_EVENT = LCBR_TYPE_RESPONSE 1 8 3 LCB_OPCODE_LAT_RESET = LCBR_TYPE_RESPONSE 1 8 4 LCB_OPCODE_CMDW = LCBR_TYPE_COMMAND 3 0 5 LCB_OPCODE_CSR = LCBR_TYPE_REGISTER 2 16 6 LCB_OPCODE_6 = LCBR_TYPE_UNDEFINED 0 0 7 LCB_OPCODE_FAULTS = LCBR_TYPE_REGISTER 2 16 8 LCB_OPCODE_8 = LCBR_TYPE_UNDEFINED 0 0 9 LCB_OPCODE_RXSTATS = LCBR_TYPE_REGISTER 2 16 A LCB_OPCODE_A = LCBR_TYPE_UNDEFINED 0 0 B LCB_OPCODE_B = LCBR_TYPE_UNDEFINED 0 0 C LCB_OPCODE_C = LCBR_TYPE_UNDEFINED 0 0 D LCB_OPCODE_D = LCBR_TYPE_UNDEFINED 0 0 E LCB_OPCODE_E = LCBR_TYPE_UNDEFINED 0 0 F LCB_PPCODE_F = LCBR_TYPE_UNDEFINED 0 0

#define LCBR_N8BYTES_BY_OPCODE ( _opcode ) LCBR_N8BYTES_BY_OPCODE_FULL(LCBR_MAP_N8BYTES_BY_OPCODE, _opcode)

Maps an opcode to a response item size in units of 8 byte cells.

Parameters:

_opcode The opcode to map

#define LCBR_N8BYTES_BY_OPCODE_FULL ( _map,
_opcode ) (((unsigned int)_map >> (2 * (_opcode))) & 0x3)

Maps an opcode to a response item size in units of 8 byte cells.

Returns:
The response type

Parameters:

_map The mapping word.

_opcode The opcode to map

The _map must have the value LCBR_MAP_N8BYTES_BY_OPCODE. This form may be more efficient than LCBR_TYPE_BY_OPCODE, since the mapping word may be already in a register, saving (on the PowerPC) the two instructions to load it. For those instances when this is macro is only being used once within a function, LCBR_MAP_N8BYTES_BY_OPCODE is simpler.

#define LCBR_TYPE_BY_OPCODE ( _opcode ) LCBR_TYPE_BY_OPCODE_FULL(LCBR_MAP_TYPE_BY_OPCODE, _opcode)

Maps an opcode to a result item type.

Parameters:

_opcode The opcode to map

#define LCBR_TYPE_BY_OPCODE_FULL ( _map,
_opcode ) (((unsigned int)_map >> (2 * (_opcode))) & 0x3)

Maps an opcode to a result item type.

Returns:
The result type

Parameters:

_map The mapping word.

_opcode The opcode to map

The _map must have the value LCBR_TYPE_MAP_BY_OPCODE. This form may be more efficient than LCBR_TYPE_BY_OPCODE, since the mapping word may be already in a register, saving (on the PowerPC) the two instructions to load it. For those instances when this is macro is only being used once within a function, LCBR_TYPE_BY_OPCODE is is simpler.

Typedef Documentation

unsigned int LCBR_processor

Callback routine for LCBR_process.

Returns:
Status, an non-zero status will cause LCBR_process to quit processing items

Parameters:

prm Arbitrary user parameter passed to this routine

ri The result item to process

This routine gets called by LCBR_process once for each result item. The routine processes the result item and then may return either 0, indicating to continue or non-zero, indicating to stop processing

Enumeration Type Documentation

enum _LCBR_TYPE

Enumerates the three defined result item types + one undefined type.

Enumerator:

LCBR_TYPE_UNDEFINED Type is undefined

LCBR_TYPE_RESPONSE Type is of a simple response

LCBR_TYPE_REGISTER Type is a register response

LCBR_TYPE_COMMAND Type is a command response

Function Documentation

LCBR__EXP_FNC const void * LCBR__advance ( const LCB_ri * ri,

int nbytes

)

Advances the pointer ri by the specified number of bytes.

Returns:
The advanced pointer

Parameters:

ri The result item pointer to advance

nbytes The number of bytes to advance the pointer

LCBR__EXP_FNC unsigned int LCBR__data32_get ( unsigned short * payload )

Returns the first 32-bit word of the payload of ri.

Parameters:

payload Pointer to payload

See also:
LCBR_headerGet(), LCBR_payloadLocate ()
This is a convience method that returns the first 32-bits of the payload. It is assumed that payload points a valid payload. For example, calling LCBR_payloadLocate and properly checking the returned pointer will fulfill this constraint.

LCBR__EXP_FNC const LCB_ri * LCBR__next ( const LCB_ri * ri )

Advances the pointer ri to the next result item.

Returns:
A pointer to the next result item

Parameters:

ri The result item

Warning:
It is the responsibility of the user to verify that the ri has a valid opcode. If the opcode is invalid, the returned pointer will have the same value as the input pointer.

const LCB_ri * LCBR_check ( const LCB_ri * ri,

const LCB_ri * end

)

Checks the specified range of result items for errors.

Returns:
Pointer to the last item successfully checked. If successful, end should be returned.
A convience method to quickly scan a result list for any errors. If any result item has an error, a pointer to that result item is returned.
If anything of than a pointer to end is returned, then an error in the result list has occurred. There are two offending conditions

The error code in the result item is anything but successful
A result item has an undefined OPCODE making it impossible to advance.

The low 2 bits of the returned pointer contain the error syndrome. Currently only these two cases are defined

low 2 bits 0, error is from the error field in the result item
low 2 bits 1, error is because of a bad opcode.

unsigned int LCBR_error_get ( const LCB_ri * ri )

Returns the 16-bit error word of ri.

Parameters:

ri Pointer to result item structure

Returns:
The error code. If the opcode is not recognized, the value LCB_RCV_ERR_UNDEFINED_7 is returned.

unsigned int LCBR_process ( const LCB_ri * ri,

const LCB_ri * end,

LCBR_processor rtn,

void * prm

)

Executes the user specified handler for each result item in the range ri to end.

Returns:
The status of the last processing call

Parameters:

ri The first result item to process

end One past the last result item to process

rtn User provided callback routine to process one item

prm User provided parameter passed to rtn

void LCBR_show ( unsigned int options,

const LCB_ri * beg,

const LCB_ri * end

)

Dumps the result items to stdout.

Parameters:

options Show options

beg Pointer to the first result descriptor to show

end Pointer to one past the lst result descriptor to show

Returns:
void

Generated on Tue Dec 13 21:47:48 2005 by

1.4.4

LCBR.h File Reference

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation