GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > LCBD / V1-4-1

Constituent: lcbd     Tag: rad750

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » DRV » source » LCBD » V1-4-1 » LCBD

LCBD_drv.h File Reference

Defines global aspects of the LCBD driver. More...

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


Data Structures

struct  _LCBD_load_cbp
 Callback routine and parameter for LCBD_load asychronous completion. More...
struct  _LCBD_dib
 LCBD Device information block. More...

Defines

#define LCBD_OK   0
 Success return code, note that this is not an LCBD message code, but may be used as one.
#define LCBD_K_EVENT_BASE_IGNORE   (unsigned int *)(-1)
 Instructs LCBD_load to ignore setting the event base address.
#define LCBD_K_EVENT_BASE_ALLOCATE   (unsigned int *)( 0)
 Instructs LCBD_load to automatically allocate an event buffer and assign the starting address as the event base.

Typedefs

typedef enum _LCBD_LOAD_OPTIONS_M LCBD_LOAD_OPTIONS_M
 Typedef for enum _LCBD_LOAD_OPTIONS_M.
typedef void(* LCBD_load_cb )(void *prm, LCBD lcb, unsigned int status)
 Callback for LCBD_load asynchronous completion.
typedef _LCBD_load_cbp LCBD_load_cbp
 Typedef for struct _LCBD_load_cbp.
typedef enum _LCBD_CLK_EDGE_OPTIONS_M LCBD_CLK_EDGE_OPTIONS_M
 Typedef for enum _LCBD_CLK_EDGE_OPTIONS_M.
typedef enum _LCBD_STATE LCBD_STATE
 Typedef for enum LCBD_STATE.
typedef enum _LCBD_STATE LCBD_state
 Typedef for enum LCBD_state.
typedef enum _LCBD_STATE_M LCBD_STATE_M
 Typedef for enum LCBD_STATE_M.
typedef enum _LCBD_QUES_M LCBD_QUES_M
 Typedef for enum _LCBD_QUES_M.
typedef enum _LCBD_FPGA_SUP_K LCBD_FPGA_SUP_K
 Typedef for enum _LCBD_FPGA_SUP_K.
typedef _LCBD_dib LCBD_dib
 Typedef for struct _LCBD_dib.
typedef enum _LCBD_M_ENABLE_DISABLE LCBD_M_ENABLE_DISABLE
 Typedef for enum _LCBD_M_ENABLE_DISABLE.
typedef enum _LCBD_WIDTH_K LCBD_WIDTH_K
 Typedef for enum _LCBD_WIDTH_K.
typedef enum _LCBD_FABRIC_K LCBD_FABRIC_K
 Typedef for enum _LCBD_fabric_select.

Enumerations

enum  _LCBD_LOAD_OPTIONS_M {
  LCBD_LOAD_OPTIONS_M_FABRIC_ASIS = 0,
  LCBD_LOAD_OPTIONS_M_FABRIC_PRIMARY = COMPOSE(FABRIC, 0),
  LCBD_LOAD_OPTIONS_M_FABRIC_REDUNDANT = COMPOSE(FABRIC, 1),
  LCBD_LOAD_OPTIONS_M_INTERRUPT_DEFAULT = 0,
  LCBD_LOAD_OPTIONS_M_INTERRUPT_PCI = COMPOSE (INTERRUPT,0),
  LCBD_LOAD_OPTIONS_M_INTERRUPT_PID = COMPOSE (INTERRUPT,1),
  LCBD_LOAD_OPTIONS_M_ICLK_ASIS = 0,
  LCBD_LOAD_OPTIONS_M_ICLK_LEADING_EDGE = COMPOSE(ICLK, 0),
  LCBD_LOAD_OPTIONS_M_ICLK_TRAILING_EDGE = COMPOSE(ICLK, 1),
  LCBD_LOAD_OPTIONS_M_OCLK_ASIS = 0,
  LCBD_LOAD_OPTIONS_M_OCLK_LEADING_EDGE = COMPOSE(OCLK, 0),
  LCBD_LOAD_OPTIONS_M_OCLK_TRAILING_EDGE = COMPOSE(OCLK, 1),
  LCBD_LOAD_OPTIONS_M_BOARD_ID_ASIS = 0,
  LCBD_LOAD_OPTIONS_M_LATP8_ASIS = 0,
  LCBD_LOAD_OPTIONS_M_LATP8_BIT = COMPOSE(LATP8, 0),
  LCBD_LOAD_OPTIONS_M_LATP8_BYTE = COMPOSE(LATP8, 1),
  LCBD_LOAD_OPTIONS_M_CSR
}
 Defines the load options word. More...
enum  _LCBD_CLK_EDGE_OPTIONS_M {
  LCBD_CLK_EDGE_OPTIONS_M_ICLK_IGNORE = 0x0,
  LCBD_CLK_EDGE_OPTIONS_M_ICLK_LEADING = COMPOSE (ICLK, 0),
  LCBD_CLK_EDGE_OPTIONS_M_ICLK_TRAILING = COMPOSE (ICLK, 1),
  LCBD_CLK_EDGE_OPTIONS_M_OCLK_IGNORE = 0x0,
  LCBD_CLK_EDGE_OPTIONS_M_OCLK_LEADING = COMPOSE (OCLK, 0),
  LCBD_CLK_EDGE_OPTIONS_M_OCLK_TRAILING = COMPOSE (OCLK, 1)
}
 Defines the options word of LCBD_clk_edge_set. More...
enum  _LCBD_STATE {
  LCBD_STATE_ERROR = -1,
  LCBD_STATE_ONLINE = 0,
  LCBD_STATE_OFFLINE = 1,
  LCBD_STATE_UNINITIALIZED = 2,
  LCBD_STATE_UNLOADING = 3
}
 The state of the LCB driver. More...
enum  _LCBD_STATE_M {
  LCBD_STATE_M_ONLINE = (1 << LCBD_STATE_ONLINE),
  LCBD_STATE_M_OFFLINE = (1 << LCBD_STATE_OFFLINE),
  LCBD_STATE_M_UNINITIALIZED = (1 << LCBD_STATE_UNINITIALIZED),
  LCBD_STATE_M_UNLOADING = (1 << LCBD_STATE_UNLOADING)
}
 The state of the LCB driver as a bit value. More...
enum  _LCBD_QUES_M {
  LCBD_QUES_M_RESULT = 1,
  LCBD_QUES_M_EVENT = 2,
  LCBD_QUES_M_BOTH = (LCBD_QUES_M_RESULT | LCBD_QUES_M_EVENT)
}
 Enumerates the LCBD ques as a bit mask selection. More...
enum  _LCBD_FPGA_SUP_K {
  LCBD_FPGA_SUP_K_MIN = -1,
  LCBD_FPGA_SUP_K_NOT = -1,
  LCBD_FPGA_SUP_K_GOLDEN = 0,
  LCBD_FPGA_SUP_K_BACKWARD = 1,
  LCBD_FPGA_SUP_K_USER = 2,
  LCBD_FPGA_SUP_K_CNT = 4
}
 Enumerates the possible driver FPGA support levels. More...
enum  _LCBD_M_ENABLE_DISABLE {
  LCBD_M_ENABLE_RESULT = (1 << 0),
  LCBD_M_ENABLE_EVENT = (1 << 1),
  LCBD_M_ENABLE_CLK_ON = (1 << 2),
  LCBD_M_ENABLE_CLK_OFF = (1 << 3),
  LCBD_M_ENABLE_CLKS = (LCBD_M_ENABLE_CLK_ON | LCBD_M_ENABLE_CLK_OFF),
  LCBD_M_ENABLE_ALL,
  LCBD_M_DISABLE_RESULT = (1 << (0+4)),
  LCBD_M_DISABLE_EVENT = (1 << (1+4)),
  LCBD_M_DISABLE_CLK_ON = (1 << (2+4)),
  LCBD_M_DISABLE_CLK_OFF = (1 << (3+4)),
  LCBD_M_DISABLE_CLKS,
  LCBD_M_DISABLE_ALL,
  LCBD_M_ENABLE_CBUF = (1 << 12),
  LCBD_M_DISABLE_CBUF = (1 << 13)
}
 Enumerates the IRQ enable/disable/pending bits. More...
enum  _LCBD_WIDTH_K {
  LCBD_WIDTH_K_BIT = 0,
  LCBD_WIDTH_K_BYTE = 1
}
 Enumeration of the two possible values of the event fabric data width, either bit-wide or byte-wide. More...
enum  _LCBD_FABRIC_K {
  LCBD_FABRIC_K_PRIMARY = 0,
  LCBD_FABRIC_K_REDUNDANT = 1
}
 Value of the parameter to LCBD_fabric_select routine. More...

Functions

unsigned int LCBD_allow (unsigned char pci_version, unsigned char latp_version)
 Adds the specified PCI and LATP version number combination as being supported by this driver.
LCBD LCBD_create (LCBD lcb)
 Preinitializes the LCBD device control block.
LCBD LCBD_get (void)
 Returns a pointer to the driver control structute.
unsigned int LCBD_load (LCBD lcb, unsigned int options, unsigned int *event_base)
 Initializes the LCB hardware and LCBD software.
unsigned int LCBD_load_cancel (LCBD lcb)
 Cancels the Waiting for the LCBD_load_init completion.
unsigned int LCBD_load_init (LCBD lcb, unsigned int options, unsigned int *event_base, LCBD_load_cb notify, void *prm)
 Initializes the LCB hardware and LCBD software.
void LCBD_load_notify (void *semaphore, LCBD lcb, unsigned int status)
 Pre-canned LCBD load notification callback routine.
unsigned int LCBD_load_wait (LCBD lcb)
 Waits for the LCBD_load_init completion.
unsigned int LCBD_unload (LCBD lcb)
 Unloads the LCB driver.
unsigned int LCBD_board_id_set (LCBD lcb, int new_board_id, int *org_board_id)
 Sets the LATp board Id, returning the orginal board id.
unsigned int LCBD_clk_edge_set (LCBD lcb, unsigned int new_options, unsigned int *old_options)
 Sets the clock options.
unsigned int LCBD_width_set (LCBD lcb, int new_width, int *org_width)
 Sets the LATp event fabric data path width, returning the original data path width setting.
unsigned int LCBD_fabric_read (LCBD lcb)
 Reads the fabric select register.
unsigned int LCBD_fabric_select (LCBD lcb, unsigned int fabric)
 Sets the fabric to specified value.
unsigned int LCBD_faults_read (LCBD lcb, unsigned int clear, unsigned int *prv, unsigned int *cur)
 Reads the LATp faults register and, optionally, clears the specified bits.
unsigned int LCBD_drain (LCBD lcb, int which)
 Drains the specified ques.
unsigned int LCBD_pci_cfg_status_clear (LCBD lcb)
 Clears the PCI configuration space status word.
const LCBD_dib * LCBD_dib_locate (const LCBD lcb)
 Returns a readonly pointer to the LCB's device information block.
void LCBD_dib_show (const LCBD_dib *dib)
 Shows (prints to the terminal) the Device Information Block.
unsigned int LCBD_enable (LCBD lcb, unsigned int enables)
 Sets the enable/disable flags controlling the EVENT and RESULT interrupts.
LCBD_state LCBD_state_get (LCBD lcb)
 Returns the current state of the driver.

Detailed Description

Defines global aspects of the LCBD driver.

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

JJRussell -- russell@slac.stanford.edu

  CVS $Id

Overview
The driver views the LCB, as nearly as possible, as three distinct units with a global or common supporting superstructure. The main files the user will deal with are the header files describing the interface and data structures of these three units plus the header file describing the global aspects of the LCB driver.
This header file defines the global aspects of the driver, dealing with loading, setting up and unloading the driver.
Example
A typical initialization sequence for users in the first class goes like
   unsigned int loadLcbd (unsigned int *circularBuffer)
   {

       // Get pre-initialized driver handle
       lcb     = LCBD_create ();

       // Load the driver
       status  = LCBD_load   (lcb,
                              LCBD_LOAD_OPTIONS_M_FABRIC_PRIMARY |
                              LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_DEFAULT
                              circularBuffer);

       // Install the result, event and notification service tasks
       // using the default priorities
       status  = LCBD_rst_handler_create (lcb, LCBD_RST_K_DEFAULT_PRIORITY);
       status  = LCBD_evt_handler_create (lcb, LCBD_EVT_K_DEFAULT_PRIORITY);
       status  = LCBD_nut_handler_create (lcb, LCBD_NUT_K_DEFAULT_PRIORITY);

       // Set the callback handler for the protocol #1
       status  = LCBD_evt_cb_set (lcb, 1, eventHander, eventParameter);

       // Set event interrupt conditions 50% on FIFO
       LCBD_evt_conds_set (lcb, LCBD_EVT_COND_50_FULL);


       // Enable the result and event interrupts
       status  = LCBD_enable  (lcb, LCBD_M_ENABLE_EVENT |
                                    LCBD_M_ENABLE_RESULT));

       // Enable the event flow into the LCB's circular buffer
       status  = LCBD_evt_enable (lcb, 1);

       return status;
   }

Typedef Documentation

LCBD_CLK_EDGE_OPTIONS_M
 

Typedef for enum _LCBD_CLK_EDGE_OPTIONS_M.

These are used to specify the options word on the LCBD_clk_edge_set routine. They are a set of OR'able values.
In general one
  1. Selects an option to be altered
  2. Specifies the value to be used
If one does not select an option, no action is taken. This is just dealing with the usual situation that an option can be
  1. Set
  2. Reset
  3. Ignored
The ignore words are 0, but they defined to help make the code more self documenting.
Example
To select the incoming clock to strobe on the trailing edge and the outgoing clokc to strobe on the leading edge
      status = LCBD_clk_edge_set (lcb,
                                  LCBD_CLK_EDGE_OPTIONS_M_ICLK_TRAILING |
                                  LCBD_CLK_EDGE_OPTIONS_M_ICLK_LEADING);

LCBD_dib
 

Typedef for struct _LCBD_dib.

This structure contains all the public exposed hardware information about the LCB device.
Note:
This structure contains a pointer the PCI register block. To deference this pointer, LCB.h must be included. If was felt that most people had no need to do this, so this include file was not burdened with exposing that definition.

LCBD_FPGA_SUP_K
 

Typedef for enum _LCBD_FPGA_SUP_K.

The driver maintains a list of pairs of PCI and LATp FPGA version numbers that it supports. This list is divided into three categories
  1. A golden version, this was the most recent pair of FPGAs at the time of the driver build
  2. A variable number of pairs of FPGAs know to be backwardly compatiable at the time driver build
  3. A list of user added pairs

The first two, as indicated, are compiled into the code (hardwired) at the time of the driver build. The last category covers the case when new versions of the FPGAs come out (presumably, backwardly compatible, for example, minor bug fixes), after the driver is built. Using LCBD_allow, such new versions can be added without rebuilding the driver.
However, since things like LCBD_allow have a tendency to get buried in scripts and other random pieces of code where they are quickly forgotten about, the driver classifies the support level and notes this in the LCBD_dib. LCBD_dib_show will display this support level, serving as a reminder to the user that something not completely standard is going on

LCBD_load_cb
 

Callback for LCBD_load asynchronous completion.

Parameters:
prm A user specified parameter
lcb The LCB handle
status The initialization completion status

LCBD_LOAD_OPTIONS_M
 

Typedef for enum _LCBD_LOAD_OPTIONS_M.

These are used to specify the options word on the LCBD_load routine. They are a set of OR'able values.
In general one
  1. Selects an option to be altered
  2. Specifies the value to be used
If one does not select an option, no action is taken. This is just dealing with the usual situation that an option can be
  1. Set
  2. Reset
  3. Ignored
The ignore words are 0, but they defined to help make the code more self documenting.
The list of options are
  • Fabric (primary/redundant)
  • Interrupt source (PCI/PID)
  • Incoming clock strobe (leading/trailing edge)
  • Outgoing clock strobe (trailing/leading edge)
  • Board id (5-bit number, excludes the master bit)
  • LATp interface width (bit/byte)
If one is going to set either of the first two (the fabric or the interrupt source it must be done by selecting it on the options word of the LCBD_load routine. The other 4, the two clock strobes, the board id and LATpinterface width are conveniences. If one knows this information at LCBD_load time, then this is the most convenient place to set it. However, if this information is not known at LCBD_load time, then the routines LCBD_board_id_set and/or LCBD_width_set can be used at anytime after the driver has been loaded. These latter parameters only need to be set before certain external operations are performed. They are not necessary for any of the LCBD's internal operations, and, in particular, are not needed during any part of the boot phase.
To select the redundant path, the PID as an interrupt source, the board id to 0x23 and the width to byte-wide. The value of the outgoing and incoming clock strobes is left as is.
      status = LCBD_load (lcb,
                          LCBD_LOAD_OPTIONS_M_FABRIC_REDUNDANT |
                          LCBD_LOAD_OPTIONS_M_INTERRUPT_PID    |
                          LCBD_LOAD_OPTIONS_M_ICLK_ASIS        |
                          LCBD_LOAD_OPTIONS_M_OCLK_ASIS        |
                          LCBD_LOAD_OPTIONS_M_BOARD_ID_N(23)   |
                          LCBD_LAOD_OPTIONS_M_LATP8_BYTE
                          eventBase);

LCBD_M_ENABLE_DISABLE
 

Typedef for enum _LCBD_M_ENABLE_DISABLE.

This defines the values of the enable parameter of LCBD_enable. There are 4 interrupts.
  1. 1 bit for the result interrupts
  2. 1 bit for the event interrupts
  3. 1 bit for the clock on interrupt (fires on transition of off->on)
  4. 1 bit for the clock off interrupt (fires on transition of on->off)
and two sets of masks
  1. A set to enable the interrupt
  2. A set to disable the interrupt
It is illegal to simoultaneously request the same interrupt to be both enable and disabled.

LCBD_WIDTH_K
 

Typedef for enum _LCBD_WIDTH_K.

This enumeration is generally used as the second argument to LCBD_width_set and as the return value in the pointer represented by the third argument.

Enumeration Type Documentation

enum _LCBD_CLK_EDGE_OPTIONS_M
 

Defines the options word of LCBD_clk_edge_set.

Enumerator:
LCBD_CLK_EDGE_OPTIONS_M_ICLK_IGNORE  Don't change incoming clock edge setting
LCBD_CLK_EDGE_OPTIONS_M_ICLK_LEADING  Clock on leading edge (incoming)
LCBD_CLK_EDGE_OPTIONS_M_ICLK_TRAILING  Clock on trailing edge (incoming)
LCBD_CLK_EDGE_OPTIONS_M_OCLK_IGNORE  Don't change outgoing clock edge setting
LCBD_CLK_EDGE_OPTIONS_M_OCLK_LEADING  Clock on leading edge (outgoing)
LCBD_CLK_EDGE_OPTIONS_M_OCLK_TRAILING  Clock on trailing edge (outgoing)

enum _LCBD_FABRIC_K
 

Value of the parameter to LCBD_fabric_select routine.

Enumerator:
LCBD_FABRIC_K_PRIMARY  Select the primary fabric
LCBD_FABRIC_K_REDUNDANT  Select the redundant fabric

enum _LCBD_FPGA_SUP_K
 

Enumerates the possible driver FPGA support levels.

Enumerator:
LCBD_FPGA_SUP_K_MIN  Minimum support value
LCBD_FPGA_SUP_K_NOT  Not supported
LCBD_FPGA_SUP_K_GOLDEN  Most recent version at build time
LCBD_FPGA_SUP_K_BACKWARD  Backwardly compatiable
LCBD_FPGA_SUP_K_USER  User allowed pair
LCBD_FPGA_SUP_K_CNT  Count of support levels

enum _LCBD_LOAD_OPTIONS_M
 

Defines the load options word.

Enumerator:
LCBD_LOAD_OPTIONS_M_FABRIC_ASIS  Effectively a nop, the fabric select register will not be altered
LCBD_LOAD_OPTIONS_M_FABRIC_PRIMARY  Set primary path
LCBD_LOAD_OPTIONS_M_FABRIC_REDUNDANT  Set redundant path
LCBD_LOAD_OPTIONS_M_INTERRUPT_DEFAULT  Use the default interrupt source for this board type
LCBD_LOAD_OPTIONS_M_INTERRUPT_PCI  Set the interrupt source to be the PCI
LCBD_LOAD_OPTIONS_M_INTERRUPT_PID  Set the interrupt source to be the PID, valid RAD750 only in flight crate
LCBD_LOAD_OPTIONS_M_ICLK_ASIS  Effectively a nop, ignore setting the incoming clock strobe point
LCBD_LOAD_OPTIONS_M_ICLK_LEADING_EDGE  Set incoming clock strobe point to be on the leading edge
LCBD_LOAD_OPTIONS_M_ICLK_TRAILING_EDGE  Set incoming clock strobe point to be on the trailing edge
LCBD_LOAD_OPTIONS_M_OCLK_ASIS  Effectively a nop, ignore setting the outgoing clock strobe point
LCBD_LOAD_OPTIONS_M_OCLK_LEADING_EDGE  Set outgoing clock strobe point to be on the leading edge
LCBD_LOAD_OPTIONS_M_OCLK_TRAILING_EDGE  Set outgoing clock strobe point to be on the trailing edge
LCBD_LOAD_OPTIONS_M_BOARD_ID_ASIS  Effectively a nop, ignore setting the board id
LCBD_LOAD_OPTIONS_M_LATP8_ASIS  Effectively a nop, the fabric select register will not be altered
LCBD_LOAD_OPTIONS_M_LATP8_BIT  Set primary path
LCBD_LOAD_OPTIONS_M_LATP8_BYTE  Set redundant path

enum _LCBD_M_ENABLE_DISABLE
 

Enumerates the IRQ enable/disable/pending bits.

Enumerator:
LCBD_M_ENABLE_RESULT  Enable the result interrupt, mask field
LCBD_M_ENABLE_EVENT  Enable the event interrupt, mask field
LCBD_M_ENABLE_CLK_ON  Enable the clock on interrupt, mask field
LCBD_M_ENABLE_CLK_OFF  Enable the clock off interrupt, mask field
LCBD_M_ENABLE_ALL  Enable both clock on and clock off interrupts
LCBD_M_DISABLE_RESULT  Enable all the interrupts, mask field Disable the result interrupt, mask field
LCBD_M_DISABLE_EVENT  Disable the event interrupt, mask field
LCBD_M_DISABLE_CLK_ON  Disable the clock on interrupt, mask field
LCBD_M_DISABLE_CLK_OFF  Disable the clock off interrupt, mask field
LCBD_M_ENABLE_CBUF  Enable the circular buffer interrupt
LCBD_M_DISABLE_CBUF  Disable the circular buffer interrupt

enum _LCBD_QUES_M
 

Enumerates the LCBD ques as a bit mask selection.

Enumerator:
LCBD_QUES_M_RESULT  Drain the result que
LCBD_QUES_M_EVENT  Drain the event que
LCBD_QUES_M_BOTH  Drain both the result and event ques

enum _LCBD_STATE
 

The state of the LCB driver.

Enumerator:
LCBD_STATE_ERROR  Not a real state, but used for err
LCBD_STATE_ONLINE  Driver is online
LCBD_STATE_OFFLINE  Driver is offline
LCBD_STATE_UNINITIALIZED  Driver is uninitialized
LCBD_STATE_UNLOADING  Driver is being unloaded

enum _LCBD_STATE_M
 

The state of the LCB driver as a bit value.

Enumerator:
LCBD_STATE_M_ONLINE  Driver is online, as a bit value
LCBD_STATE_M_OFFLINE  Driver is offline, as a bit value
LCBD_STATE_M_UNINITIALIZED  Driver is uninitialized, as a bit value
LCBD_STATE_M_UNLOADING  Driver is being unloaded, as a bit value

enum _LCBD_WIDTH_K
 

Enumeration of the two possible values of the event fabric data width, either bit-wide or byte-wide.

Enumerator:
LCBD_WIDTH_K_BIT  Specifies a bit-wide transfer width
LCBD_WIDTH_K_BYTE  Specifies a byte-wide transfer width

Function Documentation

unsigned int LCBD_allow (  unsigned char  pci_version,
unsigned char  latp_version
) 
 

Adds the specified PCI and LATP version number combination as being supported by this driver.

Return values:
LCBD_OK,if successfully added
LCBD_NOROOM,if there is no room to add this version combination
Parameters:
pci_version The PCI FPGA version to allow
latp_version The LATp FPGA version to allow
Warning:
This function is primarily meant to act as a stop gap measure to allow new versions of the firmware to be deemed temporarily OK for use by the driver. Once the FPGA code is declared official, these numbers should be added to the internal table. Also note that the verification is done as pair. It is not sufficient that the PCI FPGA versions matches and LATP FPGA version number; they must match as a pair.

unsigned int LCBD_board_id_set (  LCBD  lcb,
int  new_board_id,
int *  org_board_id
) 
 

Sets the LATp board Id, returning the orginal board id.

Return values:
Status 
Parameters:
lcb The LCB driver handle
new_board_id The new board id
org_board_id Returned as the value of the board id before it was changed. May be specified as NULL.
This function sets the LATP board id in the LAT side CSR, returning the old value
Since this function sets a field in the LAT side CSR register, it must use the command/response unit, not a simple PCI memory write. The function is written such that it will function if the result unit interrupts are enabled (in interrupt mode) or if they are disabled (polled mode). If this function is used in polled mode, the LCB result unit must be empty. Executing this function in this intermediate state is considered a programming error and the result is that not only will this function fail, but any pending results will also be lost.
This is not as onerous as the explanation would seem to imply. This function will must likely be called either before interrupts are enabled or after. It is unlikely that one will enable the result interrupt, submit some command/response transactions, then disable the result interrupt before the transactions complete.

unsigned int LCBD_clk_edge_set (  LCBD  lcb,
unsigned int  new_options,
unsigned int *  org_options
) 
 

Sets the clock options.

Return values:
Status 
Parameters:
lcb The LCB driver handle
new_options The new options
org_options Returned as the value of the options before they were changed. May be specified as NULL.
This function sets the clock edge of the data strobe. In systems with long cables, it is sometimes necessary to change the strobing of both incoming and outgoing data.
Since this function sets a field in the LAT side CSR register, it must use the command/response unit, not a simple PCI memory write. The function is written such that it will function if the result unit interrupts are enabled (in interrupt mode) or if they are disabled (polled mode). If this function is used in polled mode, the LCB result unit must be empty. Executing this function in this intermediate state is considered a programming error and the result is that not only will this function fail, but any pending results will also be lost.
This is not as onerous as the explanation would seem to imply. This function will must likely be called either before interrupts are enabled or after. It is unlikely that one will enable the result interrupt, submit some command/response transactions, then disable the result interrupt before the transactions complete.

LCBD LCBD_create (  LCBD  lcb  ) 
 

Preinitializes the LCBD device control block.

Returns:
Pointer to the preinitialize LCBD device control block
Parameters:
lcb Pointer to the LCBD device control block to preinitialize. If this is NULL, then the block is located using LCBD_get ()

const LCBD_dib* LCBD_dib_locate (  LCBD  lcb  ) 
 

Returns a readonly pointer to the LCB's device information block.

Returns:
A readonly pointer to the LCB's device information block.
Parameters:
lcb Pointer to private LCBD structure
The information dangling off the end of this pointer is not valid until after LCBD_init has been called

void LCBD_dib_show (  const LCBD_dib *  dib  ) 
 

Shows (prints to the terminal) the Device Information Block.

Parameters:
dib The Device Information Block to show

unsigned int LCBD_drain (  LCBD  lcb,
int  which
) 
 

Drains the specified ques.

Returns:
Status
Parameters:
lcb The LCBD driver handle
which Which ques to drain, a bit mask of LCBD_QUES_M_RESULT and LCBD_QUES_M_EVENT
The result que is drained first. If this succeeds, then the event que is drained. If the result que is fails to drain, the event que is not drained.

unsigned int LCBD_enable (  LCBD  lcb,
unsigned int  enables
) 
 

Sets the enable/disable flags controlling the EVENT and RESULT interrupts.

Return values:
LCBD_OK,on success
LCBD_ISRQUEUE,if one or both of the result/event being enabled does not have a service FORK task/que associated with it.
Parameters:
lcb Pointer to private LCBD structure
enables A bit mask of
  • LCBD_M_ENABLE_RESULT
  • LCBD_M_ENABLE_EVENT
  • LCBD_M_ENABLE_CLK_ON
  • LCBD_M_ENABLE_CLK_OFF
  • LCBD_M_DISABLE_RESULT
  • LCBD_M_DISABLE_EVENT
  • LCBD_M_DISABLE_CLK_ON
  • LCBD_M_DISABLE_CLK_OFF
It is an error to both ENABLE and DISABLE the same interrupt.

Note that unless explicitly stated, when enabling or disabling the event interrupt, the sub-interrupt condition of the circular buffer full will also be enabled or disabled. To explicitly prohibit this action, specify LCBD_M_CBUF_ENABLE or LCBD_M_CBUF_DISABLE.

unsigned int LCBD_fabric_read (  LCBD  lcb  ) 
 

Reads the fabric select register.

Returns:
The value of the fabric select register, this should be either 0 or 1, since that is all that is currently defined LCBD_FABRIC_REDUNDANT.
Parameters:
lcb Pointer to private LCBD structure

unsigned int LCBD_fabric_select (  LCBD  lcb,
unsigned int  fabric
) 
 

Sets the fabric to specified value.

Returns:
The previous value, i.e. one of LCBD_FABRIC_PRIMARY or LCBD_FABRIC_REDUNDANT.
Parameters:
lcb Pointer to private LCBD structure
fabric The value to set the fabric to, i.e. one of LCBD_FABRIC_PRIMARY or LCBD_FABRIC_REDUNDANT.

unsigned int LCBD_faults_read (  LCBD  lcb,
unsigned int  clear,
unsigned int *  prv,
unsigned int *  cur
) 
 

Reads the LATp faults register and, optionally, clears the specified bits.

Returns:
Status
Overview
The faults registers contains a number of bits which latch when an internal hardware constraint in the LCB is violated. This function is written such that one can read and optionally clear selective bits. Although one can clear selective bits, it is anticipated that the two must useful forms of calls to this function are
        // Just read the faults register
        status = LCBD_faults_read (lcb, 0, &faults, NULL);

        // Read and clear the faults register
        status = LCBD_faults_read (lcb, -1, &faults, NULL);

Note:
Since this function reads the LAT side CSR register, it must use the command/response unit, not a simple PCI memory write. The function is written such that it will function if the result unit interrupts are enabled (in interrupt mode) or if they are disabled (polled mode). If this function is used in polled mode, the LCB result unit must be empty. Executing this function in this intermediate state is considered a programming error and the result is that noy only will this function fail, but any pending results will also be lost.
This is not as onerous as the explanation would seem to imply. This function will must likely be called either before interrupts are enabled or after. It is unlikely that one will enable the result interrupt, submit some command/response transactions, then disable the result interrupt before the transactions complete.

LCBD LCBD_get (  void   ) 
 

Returns a pointer to the driver control structute.

Returns:
A pointer to the driver control structute
Except for testing purposes, this handle should be used instead of any user allocated LCBD handle.

unsigned int LCBD_load (  LCBD  lcb,
unsigned int  options,
unsigned int *  event_base
) 
 

Initializes the LCB hardware and LCBD software.

Returns:
Status.
  1. If the status is SUCCESS, then this function completed successfully
  2. If the status is ERROR, then an irrecoverable error occurred and the integrity of the CPU is in question
  3. If the status is WARNING, then call this routine again, it's job is not done. Two noteworthy cases are LCBD_NOCLK and LCBD_OFFLINE. In this case the user may register a CLOCK on transition callback to be notified when the clock shows up.
Parameters:
lcb The LCB device handle
options Selects various options. This is done as a select/value field. This are enumerated in LCBD_LOAD_OPTIONS_M.
event_base The bae address of the event buffer. Two special values can be used here
  • LCBD_K_EVENT_BASE_IGNORE
  • LCBD_K_EVENT_BASE_ALLOCATE If LCBD_K_EVENT_BASE_ALLOCATE is specified, an event buffer will be allocated. If specified as LCBD_K_EVENT_BASE_IGNORE (-1), then the event base address will not be set
Overview
This function loads the LCB driver. There are two configuration parameters, the fabric selection and the circular buffer address. Both these parameters can be specified with sentenial values allowing them to be ignored.
Options Word
This currently controls two options
  • The interrupt source
  • The fabric (path = primary/redundant
It is presented as a series of OR'able mask options
Fabric Selection
Fabric selection on the SIU is done by setting this parameter to either
  • LCBD_LOAD_OPTIONS_M_FABRIC_PRIMARY or
  • LCBD_LOAD_OPTIONS_M_FABRIC_REDUNDANT
The SIU can do this for 2 reasons
  1. Since it does not need the LCB during primary boot it does not need this parameter during primary boot
  2. The secondary boot code is allowed to select the value of this parameter from a writeable location in EEPROM. 1553 commands can be issued to change this value if necessary.

EPU Fabric Selection
The EPU is told its fabric selection by the SIU. Therefore, this parameter should be given the value
  • LCBD_LOAD_OPTIONS_M_FABRIC_IGNORE

The value of this is 0, so it technically unnecessary, but it does serve to document the code.
Since the EPU does need this value during primary boot and its only communication path is via the LCB (i.e. it does not have the luxury of a backdoor 1553 connection), it must be told this value before booting. After the SIU applies power to EPU, it can issue a command on the command/response fabric to the EPU's LATp-side CSR register to set this value.
Interrupt Source
This option selects the interrrupt source. Only to RAD750 boards that live in flight crates obey this option, all others default to PCI source.
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_PCI
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_PID
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_DEFAULT

unsigned int LCBD_load_cancel (  LCBD  lcb  ) 
 

Cancels the Waiting for the LCBD_load_init completion.

Return values:
LCBD_OK,operation was cancelled
LCBD_AIBCOM,operation was not cancelled because initialization is already completed.
Parameters:
lcb The LCB driver handle

unsigned int LCBD_load_init (  LCBD  lcb,
unsigned int  options,
unsigned int *  event_base,
LCBD_load_cb  notify,
void *  prm
) 
 

Initializes the LCB hardware and LCBD software.

Returns:
Status.
  1. If the status is SUCCESS, then this function completed successfully
  2. If the status is ERROR, then an irrecoverable error occurred and the integrity of the CPU is in question
  3. If the status is WARNING, then call this routine again, it's job is not done. Two noteworthy cases are LCBD_NOCLK and LCBD_OFFLINE. In this case the user may register a CLOCK on transition callback to be notified when the clock shows up.
Parameters:
lcb The LCB device handle
options Selects various options. This is done as a select/value field. This are enumerated in LCBD_LOAD_OPTIONS_M.
event_base The bae address of the event buffer. Two special values can be used here
  • LCBD_K_EVENT_BASE_IGNORE
  • LCBD_K_EVENT_BASE_ALLOCATE If LCBD_K_EVENT_BASE_ALLOCATE is specified, an event buffer will be allocated. If specified as LCBD_K_EVENT_BASE_IGNORE (-1), then the event base address will not be set
notify A routine to be called back when the driver is fully initialized. The call signature is 
                           foid notify (void           *prm,
                                        LCBD            lcb,
                                        unsigned int status)
where status is the LCBD_load completion status.
prm An arbitrary user parameter passed to the notify routine.
Overview
This function loads the LCB driver. There are two configuration parameters, the fabric selection and the circular buffer address. Both these parameters can be specified with sentenial values allowing them to be ignored.
Options Word
This currently controls two options
  • The interrupt source
  • The fabric (path = primary/redundant
It is presented as a series of OR'able mask options
Fabric Selection
Fabric selection on the SIU is done by setting this parameter to either
  • LCBD_LOAD_OPTIONS_M_FABRIC_PRIMARY or
  • LCBD_LOAD_OPTIONS_M_FABRIC_REDUNDANT
The SIU can do this for 2 reasons
  1. Since it does not need the LCB during primary boot it does not need this parameter during primary boot
  2. The secondary boot code is allowed to select the value of this parameter from a writeable location in EEPROM. 1553 commands can be issued to change this value if necessary.

EPU Fabric Selection
The EPU is told its fabric selection by the SIU. Therefore, this parameter should be given the value
  • LCBD_LOAD_OPTIONS_M_FABRIC_IGNORE

The value of this is 0, so it technically unnecessary, but it does serve to document the code.
Since the EPU does need this value during primary boot and its only communication path is via the LCB (i.e. it does not have the luxury of a backdoor 1553 connection), it must be told this value before booting. After the SIU applies power to EPU, it can issue a command on the command/response fabric to the EPU's LATp-side CSR register to set this value.
Interrupt Source
This option selects the interrrupt source. Only to RAD750 boards that live in flight crates obey this option, all others default to PCI source.
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_PCI
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_PID
  • LCBD_LOAD_OPTIONS_M_SET_INTERRUPT_DEFAULT

Notify
LCBD_load_init will initialize the LCB up to the point where the remainding initialization needs the LATp-side clock. These clocks may or may not be present when this point is reached. To deal with the situation when the clocks are not present, the remainder of the initialization occurs in a separate task. At this point control is returned to the user.
When the clocks do appear the CLK_ON interrupt wakes this task and the remainder of the initialization takes place. The user can provide a synchronization routine that will be called after the remainder of the initialization takes place. This is the notify parameter along with its context parameter, prm.
The user has three options
  1. Specify NULL, then the LCBD_load_init will wait internally. This option is provided as a convenience and is not recommended for general use
  2. Specify LCBD_load_notify as the notification routine and use LCBD_load_wait to wait for completion. These routines are provided as a convenience to the user, representing pre-canned versions of the general notification/wait routine
  3. Specify your own notification routine. In this case the user is responsible for coding his own wait routine, or he may use LCBD_load_notify in conjunction with LCBD_load_wait.
Example
In this example, the pre-canned routines LCBD_load_notify and LCBD_load_wait are used.
       status = LCBD_load_init (lcb,
                                options,
                                event_base,
                                LBCD_load_notify,
                                NULL);

       // The only errors are catastophic
       if (status != LCBD_OK) return status;

       // Now do a bunch of other stuff....
       call_a_bunch_of_other_stuff (lots_of_parameters);

       // Done doing other stuff, now wait till the driver is fully initialized
       status = LCBD_load_wait (lcb);
       if (status != LCBD_OK) return status;

       .

void LCBD_load_notify (  void *  semaphore,
LCBD  lcb,
unsigned int  status
) 
 

Pre-canned LCBD load notification callback routine.

Parameters:
semaphore The synchronizing semaphore
lcb The LCB driver handle
status The completion status
This routine is a pre-canned LCBD load notification callback routine. If the user choses to use as the notify parameter in LCBD_load_init call, he must use its synchronizing mate, LCBD_load_wait

unsigned int LCBD_load_wait (  LCBD  lcb  ) 
 

Waits for the LCBD_load_init completion.

Returns:
The completion status
Parameters:
lcb The LCB driver handle
Works as the wait half of LCBD_load_notify.

unsigned int LCBD_pci_cfg_status_clear (  LCBD  lcb  ) 
 

Clears the PCI configuration space status word.

Return values:
status 
Parameters:
lcb Pointer to private LCBD structure

LCBD_state LCBD_state_get (  LCBD  lcb  ) 
 

Returns the current state of the driver.

Returns:
The current state of the driver
Parameters:
lcb The LCB driver handle
Warning:
As with most query functions of this ilk, the only guarantee that can be made is that at the time of the call the driver was in this state. The state of the driver may change at anytime thereafter. As they say, let the buyer beware.

unsigned int LCBD_unload (  LCBD  lcb  ) 
 

Unloads the LCB driver.

Returns:
Status.
About Shutting Down the Driver
It is the responsibility of the user to make sure that the LCB is in a quiet state, i.e. that all traffic on both the command/response and event fabrics have stopped.

unsigned int LCBD_width_set (  LCBD  lcb,
int  new_width,
int *  org_width
) 
 

Sets the LATp event fabric data path width, returning the original data path width setting.

Return values:
Status. 
Parameters:
lcb The LCB driver handle
new_width The new data width, this should be specified as either
  • LCBD_WIDTH_K_BIT (0) or
  • LCBD_WIDTH_K_BYTE (1)
org_width Returned as the value of the data path width before it was changed. May be specified as NULL. The returned value will be either
  • LCBD_WIDTH_K_BIT (0) or
  • LCBD_WIDTH_K_BYTE (1)

This function sets the data path width as either byte wide or bit-wide in the LAT side CSR, returning the old value
Since this function sets a field in the LAT side CSR register, it must use the command/response unit, not a simple PCI memory write. The function is written such that it will function if the result unit interrupts are enabled (in interrupt mode) or if they are disabled (polled mode). If this function is used in polled mode, the LCB result unit must be empty. Executing this function in this intermediate state is considered a programming error and the result is that not only will this function fail, but any pending results will also be lost.
This is not as onerous as the explanation would seem to imply. This function will must likely be called either before interrupts are enabled or after. It is unlikely that one will enable the result interrupt, submit some command/response transactions, then disable the result interrupt before the transactions complete.

Generated on Tue Dec 13 21:47:07 2005 by  doxygen 1.4.4