GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> LCBD / V1-5-1 > lcbd / sun-gcc


Interface   Data Structures   File List   Data Fields   Globals  

LCBC.h File Reference

Definitions of the LCB command structures. More...

#include "LCBD/LCB_cr.h"
#include "LCBD/LCBD_cr.h"
#include "PBI/Attribute.h"
#include "PBI/Inline.h"

Defines

#define LCBC_MAP_TYPE_BY_OPCODE
 Defines a 32-bit integer that functions as a map of the command type indexed by opcode.
#define LCBC_TYPE_BY_OPCODE_FULL(_map, _opcode)
 Maps an opcode to a command item type.
#define LCBC_TYPE_BY_OPCODE(_opcode)   LCBC_TYPE_BY_OPCODE_FULL(LCBC_MAP_TYPE_BY_OPCODE, _opcode)
 Maps an opcode to a result item type.

Typedefs

typedef enum _LCBC_TYPE LCBC_TYPE
 Typedef for enum _LCBC_TYPE.
typedef unsigned int LCBC_processor (void *prm, const LCB_ci *ci)
 Callback routine for LCBC_process.

Enumerations

enum  _LCBC_TYPE {
  LCBC_TYPE_UNDEFINED = 0,
  LCBC_TYPE_SIMPLE = 1,
  LCBC_TYPE_REGISTER = 2,
  LCBC_TYPE_COMMAND = 3,
  LCBC_TYPE_EVENT = 4
}
 Enumerates the four defined command item types + one undefined type. More...

Functions

LCBC__EXP_PROTO
const void * 
LCBC__advance (const LCB_ci *ci, int nbytes) ATTR_UNUSED_OK
 Advances the pointer ci by the specified number of bytes.
LCBC__EXP_PROTO
const LCB_ci
LCBC__next (const LCB_ci *ci) ATTR_UNUSED_OK
 Advances the pointer ci to the next command item.
LCBC__EXP_PROTO LCB_ciLCBC__mark_time_fill (LCB_ci_mark_time *ci, unsigned short int stall) ATTR_UNUSED_OK
 Constructs a mark time LCB command.
LCBC__EXP_PROTO LCB_ciLCBC__event_fill (LCB_ci_event *ci, unsigned int latp_adr, unsigned int proto, unsigned int len32, unsigned short int stall) ATTR_UNUSED_OK
 Constructs event transmit command, without a response.
LCBC__EXP_PROTO LCB_ciLCBC__cmd_xmit_fill (LCB_ci_cmd *ci, const LCB_ci_cmd_payload *payload, unsigned short int stall) ATTR_UNUSED_OK
 Constructs transmit command, without a response.
LCBC__EXP_PROTO LCB_ciLCBC__lat_reset_fill (LCB_ci_lat_reset *ci, unsigned short int stall) ATTR_UNUSED_OK
 Constructs a LAT reset LCB command.
LCBC__EXP_PROTO LCB_ciLCBC__cmdr_xmit_fill (LCB_ci_cmdr *ci, const LCB_ci_cmd_payload *payload, unsigned short int timeout) ATTR_UNUSED_OK
 Constructs transmit command, with a response.
LCBC__EXP_PROTO LCB_ciLCBC__csr_access_fill (LCB_ci_csr *ci, unsigned int value, unsigned int field_select, unsigned short int stall) ATTR_UNUSED_OK
 Constructs a LCB CSR register access command.
LCBC__EXP_PROTO LCB_ciLCBC__faults_access_fill (LCB_ci_faults *ci, unsigned int value, unsigned int field_select, unsigned short int stall) ATTR_UNUSED_OK
 Constructs a LCB FIFO FAULTS register access command.
LCBC__EXP_PROTO LCB_ciLCBC__rxstats_access_fill (LCB_ci_rxstats *ci, unsigned int value, unsigned int field_select, unsigned short int stall) ATTR_UNUSED_OK
 Constructs a LCB Receive Statistics/Status register access command.
LCB_ciLCBC_mark_time_fill (LCB_ci_mark_time *ci, unsigned short int stall)
 Constructs a mark time LCB command.
LCB_ciLCBC_event_fill (LCB_ci_event *ci, unsigned int latp_adr, unsigned int proto, unsigned int len32, unsigned short int stall)
 Constructs event transmit command.
LCB_ciLCBC_lat_reset_fill (LCB_ci_lat_reset *ci, unsigned short int stall)
 Constructs a LAT reset LCB command.
LCB_ciLCBC_csr_access_fill (LCB_ci_csr *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
 Constructs a LCB CSR register access command.
LCB_ciLCBC_faults_access_fill (LCB_ci_faults *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
 Constructs a LCB FIFO FAULTS register access command.
LCB_ciLCBC_rxstats_access_fill (LCB_ci_rxstats *ci, unsigned int value, unsigned int field_select, unsigned short int stall)
 Constructs a LCB RECEIVE STATISTICS/STATUS register access command.
unsigned int LCBC_process (const LCB_ci *ci, const LCB_ci *end, LCBC_processor rtn, void *prm)
 Executes the user specified handler for each command item in the range ci to end.
void LCBC_show (unsigned int options, const LCB_ci *beg, const LCB_ci *end)
 Dumps the result items to stdout.
unsigned int LCBC_cmd_xmit (LCBD lcb, const LCB_ci_cmd_payload *payload, unsigned short int stall)
 Utility routine to compose and submit a command with no response command (department of redundancy department?).
unsigned int LCBC_mark_time (LCBD lcb, unsigned short int stall)
 Utility routine to compose and execute an LCB mark time command.
unsigned int LCBC_lat_reset (LCBD lcb, unsigned short int stall)
 Utility routine to compose and execute an LCB LAT reset command.
unsigned int LCBC_cmdr_xmit (LCBD lcb, const LCB_ci_cmd_payload *ci_payload, unsigned short int timeout, LCB_ri_cmd_payload *ri_payload)
 Utility routine to compose and submit a command with response command (department of redundancy department?).
unsigned int LCBC_csr_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)
 Utility routine to compose and execute an access command to LCB's CSR register.
unsigned int LCBC_faults_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)
 Utility routine to compose and execute an access command to LCB's FIFO FAULTS register.
unsigned int LCBC_rxstats_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *old_val, unsigned int *cur_val)
 Utility routine to compose and execute an access command to LCB's RECEIVE STATISTICS/STATS register.


Detailed Description

Definitions of the LCB command structures.

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

JJRussell -- russell@slac.stanford.edu

  CVS $Id

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


Define Documentation

#define LCBC_MAP_TYPE_BY_OPCODE

Value:

Defines a 32-bit integer that functions as a map of the command type indexed by opcode.

The 32-bit integer functions as a map of the command type indexed by opcode. Each command type consumes 3 bits. Given that there are 16 potential opcodes, it takes 48 bits to define the map. This means the map cannot be contained in a 32 bit integer. Ah, but wait, only the first ten opcodes are actually defined. So we can cheat, and only define the first ten. Indexing by greater than 32 will produce a 0.

     type = opcode <= 10
          ? ((LCBC_MAP_TYPE_BY_OPCODE >> (3 * opcode)) & 0x3)
          : LCBC_TYPE_UNDEFINED;

There are 16 opcodes, that map to 5 descriptor types

#define LCBC_TYPE_BY_OPCODE ( _opcode   )     LCBC_TYPE_BY_OPCODE_FULL(LCBC_MAP_TYPE_BY_OPCODE, _opcode)

Maps an opcode to a result item type.

Parameters:
_opcode The opcode to map

#define LCBC_TYPE_BY_OPCODE_FULL ( _map,
_opcode   ) 

Maps an opcode to a command 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 LCBC_processor

Callback routine for LCBC_process.

Returns:
Status, an non-zero status will cause LCBC_process to quit processing items
Parameters:
prm Arbitrary user parameter passed to this routine
ci The command item to process
This routine gets called by LCBC_process once for each command item. The routine processes the command item and then may return either 0, indicating to continue or non-zero, indicating to stop processing


Enumeration Type Documentation

enum _LCBC_TYPE

Enumerates the four defined command item types + one undefined type.

Enumerator:
LCBC_TYPE_UNDEFINED  Type is undefined
LCBC_TYPE_SIMPLE  Type is of a simple command
LCBC_TYPE_REGISTER  Type is a register access command
LCBC_TYPE_COMMAND  Type is a transmit command command
LCBC_TYPE_EVENT  Type is a transmit event


Function Documentation

LCBC__EXP_FNC const void * LCBC__advance ( const LCB_ci ci,
int  nbytes 
)

Advances the pointer ci by the specified number of bytes.

Returns:
The advanced pointer
Parameters:
ci Thehe command item pointer to advance
nbytes The number of bytes to advance the pointer

LCBC__EXP_FNC LCB_ci * LCBC__cmd_xmit_fill ( LCB_ci_cmd ci,
const LCB_ci_cmd_payload payload,
unsigned short int  stall 
)

Constructs transmit command, without a response.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
payload The transmit command's payload. This consists of a LATp header plus a highly encoded bit pattern which determines further routing and the action to be taken at the destination
stall The stall period, in units of 20MHz clock ticks

LCBC__EXP_FNC LCB_ci * LCBC__cmdr_xmit_fill ( LCB_ci_cmdr ci,
const LCB_ci_cmd_payload payload,
unsigned short int  timeout 
)

Constructs transmit command, with a response.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
payload The transmit command's payload. This consists of a LATp header plus a highly encoded bit pattern which determines further routing and the action to be taken at the destination
timeout The timeout perion, in units of 20MHz clock ticks

LCBC__EXP_FNC LCB_ci * LCBC__csr_access_fill ( LCB_ci_csr ci,
unsigned int  field_select,
unsigned int  value,
unsigned short int  stall 
)

Constructs a LCB CSR register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time, in units of 20MHz clock ticks

LCBC__EXP_FNC LCB_ci * LCBC__event_fill ( LCB_ci_event ci,
unsigned int  latp_adr,
unsigned int  proto,
unsigned int  len32,
unsigned short int  stall 
)

Constructs event transmit command, without a response.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The event transmit command item to be filled.
latp_adr The destination LATp address
proto The protocol
len32 The length of the data to be transformed in 32 bit words. This must be a multiple of 4, since the LCB transfer engine works in units of 16-byte cells. This length must include the LATP packet header word.
stall The stall period, in units of 20MHz clock ticks
Usage
The filling an event transmit command is not as easy as the other commands because of the variable length of the data. A trivial example of its usage is given here. This routine does not dictate when the data must be filled (it could be before or after the call to LCBC__event_fill. This freedom is necessary because in some cases one may not know the length until afterthe data has been moved into the event transmit command item. For example, an on-the-fly compression algorithm. In this example, the call to LCBC__event_fill could be on either side of the memcpy.
   #define LATP_ADR 22
   #define PROTO     2
   #define STALL    10
   fill (LCB_ci_event *ci, unsigned int *dst, int len32)
   {

       unsigned short *dst = ci->data;
       memcpy (dst, src, len32 * sizeof (int));


       len32 += 1;                 // Add on the length of the LATP_pckt_hdr
       len32  = (len32 + 3) & ~03; // Round to a multiple of 4 integers
       return LCBC__event_fill (ci, 22, LATP_ADR, PROTO, len32, STALL);
   }

LCBC__EXP_FNC LCB_ci * LCBC__faults_access_fill ( LCB_ci_faults ci,
unsigned int  field_select,
unsigned int  value,
unsigned short int  stall 
)

Constructs a LCB FIFO FAULTS register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time, in units of 20MHz clock ticks

LCBC__EXP_FNC LCB_ci * LCBC__lat_reset_fill ( LCB_ci_lat_reset ci,
unsigned short int  stall 
)

Constructs a LAT reset LCB command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
stall The stall time, in units of 20MHz clock ticks

LCBC__EXP_FNC LCB_ci * LCBC__mark_time_fill ( LCB_ci_mark_time ci,
unsigned short int  stall 
)

Constructs a mark time LCB command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
stall The stall time, in units of 20MHz clock ticks

LCBC__EXP_FNC const LCB_ci * LCBC__next ( const LCB_ci ci  ) 

Advances the pointer ci to the next command item.

Returns:
A pointer to the next command item
Parameters:
ci The command item

LCBC__EXP_FNC LCB_ci * LCBC__rxstats_access_fill ( LCB_ci_rxstats ci,
unsigned int  field_select,
unsigned int  value,
unsigned short int  stall 
)

Constructs a LCB Receive Statistics/Status register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time, in units of 20MHz clock ticks

unsigned int LCBC_cmd_xmit ( LCBD  lcb,
const LCB_ci_cmd_payload payload,
unsigned short int  stall 
)

Utility routine to compose and submit a command with no response command (department of redundancy department?).

Returns:
Status
Parameters:
lcb The LCB driver handle
payload The payload of the command access command. The format of this beast is dependent on the target (PDU, TEM, GTFE) and is non-trivial. However, this routine does not concern itself with the formatting, deferring that as someone else's problem.
stall The stall time, in units of 20Mhz clock ticks

unsigned int LCBC_cmdr_xmit ( LCBD  lcb,
const LCB_ci_cmd_payload ci_payload,
unsigned short int  timeout,
LCB_ri_cmd_payload ri_payload 
)

Utility routine to compose and submit a command with response command (department of redundancy department?).

Returns:
Status
Parameters:
lcb The LCB driver handle
ci_payload The payload of the command access command. The format of this beast is dependent on the target (PDU, TEM, GTFE) and is non-trivial. However, this routine does not concern itself with the formatting, deferring that as someone else's problem.
timeout The LCB timeout period, in units of 20MHz clock ticks to wait for a response to be returned.
ri_payload The resulting (returned) payload. As is in the case of the command item payload, ci_payload, the format of this payload is highly dependent on the target. However, this routine merely returns the payload results to the user, again adopting the philosopy of not my problem,

unsigned int LCBC_csr_access ( LCBD  lcb,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall,
unsigned int *  old_val,
unsigned int *  cur_val 
)

Utility routine to compose and execute an access command to LCB's CSR register.

Returns:
Status
Parameters:
lcb The LCB driver handle
value The value to write. Only bits matching those in the field_select parameter will actually be written.
field_select Pattern of those bits in value to write
stall The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
old_val Pointer to receive the value of the register before modification. This may be NULL.
cur_val Pointer to receive the value of the register after modification. This may be NULL.

LCB_ci* LCBC_csr_access_fill ( LCB_ci_csr ci,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall 
)

Constructs a LCB CSR register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time, in units of 20MHz clock ticks

LCB_ci * LCBC_event_fill ( LCB_ci_event ci,
unsigned int  latp_adr,
unsigned int  proto,
unsigned int  len32,
unsigned short int  stall 
)

Constructs event transmit command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The event transmit command item to be filled.
latp_adr The destination LATp address
proto The protocol
len32 The length of the data to be transformed in 32 bit words. This must be a multiple of 4, since the LCB transfer engine works in units of 16-byte cells
stall The stall period, in units of 20MHz clock ticks
Usage
The filling an event transmit command is not as easy as the other commands because of the variable length of the data. A trivial example of its usage is given here. Note that there is no reason to move the data in before or after the LCBC__event_fill routine is called. In many cases, one may not know the length until after the data has been moved into the event transmit command item. For example, an on-the-fly compression algorithm. In this example, the call to LCBC__event_fill could be on either side of the memcpy.
   #define LATP_ADR 22
   #define PROTO     2
   #define STALL    10
   fill (LCB_ci_event *ci, unsigned int *dst, int len32)
   {

       unsigned short *dst = ci->data;
       memcpy (dst, src, len32 * sizeof (int));

       return LCBC_event_fill (ci, 22, LATP_ADR, PROTO, len32, STALL);
   }

unsigned int LCBC_faults_access ( LCBD  lcb,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall,
unsigned int *  old_val,
unsigned int *  cur_val 
)

Utility routine to compose and execute an access command to LCB's FIFO FAULTS register.

Returns:
Status
Parameters:
lcb The LCB driver handle
value The value to write. Only bits matching those in the field_select parameter will actually be written.
field_select Pattern of those bits in value to write
stall The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
old_val Pointer to receive the value of the register before modification. This may be NULL.
cur_val Pointer to receive the value of the register after modification. This may be NULL.

LCB_ci* LCBC_faults_access_fill ( LCB_ci_faults ci,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall 
)

Constructs a LCB FIFO FAULTS register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time in units of 20MHz clock ticks

unsigned int LCBC_lat_reset ( LCBD  lcb,
unsigned short int  stall 
)

Utility routine to compose and execute an LCB LAT reset command.

Returns:
Status
Parameters:
lcb The LCB driver handle
stall The stall time, in units of 20Mhz clock ticks
To be used only with great discretion; i.e. in case of emergency break glass.

LCB_ci* LCBC_lat_reset_fill ( LCB_ci_lat_reset ci,
unsigned short int  stall 
)

Constructs a LAT reset LCB command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
stall The stall time, in units of 20MHz clock ticks

unsigned int LCBC_mark_time ( LCBD  lcb,
unsigned short int  stall 
)

Utility routine to compose and execute an LCB mark time command.

Returns:
Status
Parameters:
lcb The LCB driver handle
stall The stall time, in units of 20Mhz clock ticks
The utility of a bare mark time command, outside the context of command list, is dubious, but is provided for completeness. With a minimal stall time, one could use effectively as a NOP.

LCB_ci* LCBC_mark_time_fill ( LCB_ci_mark_time ci,
unsigned short int  stall 
)

Constructs a mark time LCB command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled.
stall The stall time, in units of 20MHz clock ticks

unsigned int LCBC_process ( const LCB_ci ci,
const LCB_ci end,
LCBC_processor  rtn,
void *  prm 
)

Executes the user specified handler for each command item in the range ci to end.

Returns:
The status of the last processing call
Parameters:
ci The first command item to process
end One past the last command item to process
rtn User provided callback routine to process one item
prm User provided parameter passed to rtn

unsigned int LCBC_rxstats_access ( LCBD  lcb,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall,
unsigned int *  old_val,
unsigned int *  cur_val 
)

Utility routine to compose and execute an access command to LCB's RECEIVE STATISTICS/STATS register.

Returns:
Status
Parameters:
lcb The LCB driver handle
value The value to write. Only bits matching those in the field_select parameter will actually be written.
field_select Pattern of those bits in value to write
stall The stall time, in units of 20MHz clock ticks, for the LCB to wait for completion.
old_val Pointer to receive the value of the register before modification. This may be NULL.
cur_val Pointer to receive the value of the register after modification. This may be NULL.

LCB_ci* LCBC_rxstats_access_fill ( LCB_ci_rxstats ci,
unsigned int  value,
unsigned int  field_select,
unsigned short int  stall 
)

Constructs a LCB RECEIVE STATISTICS/STATUS register access command.

Returns:
Pointer to the next command item to be filled
Parameters:
ci The command item to be filled
field_select A word indicating the bits from value that will be written. For example, if 0, then no bits will be written, if -1, then all bits will be written.
value The value to be written
stall The stall time, in units of 20MHz clock ticks

void LCBC_show ( unsigned int  options,
const LCB_ci beg,
const LCB_ci 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 Aug 31 18:52:30 2010 by  doxygen 1.5.3