---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > LCBD / V1-3-2

Constituent: lcbd     Tag: sun-gcc

---

         

---

LCBD_drv.c File Reference

LCBD initialization and setup routines. More...

#include <string.h>
#include "LCBD/LCBD_drv.h"
#include "LCBD/LCBD_pci.h"
#include "LCBD/LCBD_msgs.h"
#include "LCBD/LCB.h"
#include "LCBD/LCB_cr.h"
#include "LCBD/LCBC.h"
#include "LCBD_p.h"
#include "PBI/Attribute.h"
#include "PBS/L.ih"
#include "PBS/FORK.h"
#include "PBS/MBA.h"
#include "PBS/SPIN.h"
#include "PBS/RW.ih"
#include "PBS/RW_protos.h"
#include "PBS/INT.ih"
#include <stdio.h>

Include dependency graph for LCBD_drv.c:

Data Structures
struct	_FpgaList
	Structure defining the list of supported Fpgas. More...
Defines
#define	FABRIC_SELECT_TIMEOUT   10000
	The timeout period, in nanoseconds, that one is willing to wait for the clock to show up after doing a fabric select.
Typedefs
typedef _FpgaList	FpgaList
	Typedef for struct _FpgaList.
Functions
unsigned int	connect (LCBD lcb, unsigned int options)
	Connects the LCBD to the interrupt source.
unsigned int	disconnect (LCBD lcb)
	Disconnects the LCBD from the interrupt source.
unsigned int	clk_handler (void *unused, LCBD lcb)
	Default clock off -> on and clock on -> off handler.
unsigned int	evt_def_handler (void *unused, unsigned int ed, LCBD_evt *evt)
	Default event handler.
unsigned int	init_pci (LCBD lcb)
	Initializes the LCBD structure -- probes the PCI bus.
unsigned int	init_latp (LCBD lcb, unsigned int options, unsigned int *event_base, LCBD_load_cb notify, void *prm)
	Laundry list of LCBD initializations to do on the LATp side.
unsigned int	init_latp_clk_on (LCBD lcb, unsigned int options, unsigned int *event_base)
	Complete LCBD initializations of LATp side.
unsigned int	init_latp_clk_on_isr (SEM semaphore, LCBD lcb) ATTR_UNUSED_OK
	Clock interrupt callback routine to complete LATp-side initialization.
unsigned int	init_latp_clk_on_entry (LCBD lcb) ATTR_UNUSED_OK
	The asynchronous LATp-side initialization call back handler.
unsigned int	init_circ (LCBD lcb, unsigned int *event_base, int fill)
	Allocates memory for and sets it up to be used as the circular buffer.
unsigned int	init_sw (LCBD lcb)
	Laundry list of LCBD initializations to do on the software side.
unsigned int	destroy_sw (LCBD lcb)
	Laundry list of LCBD shutdowns to do on the software side.
unsigned int	drain_result (LCBD lcb)
	Drains the result FIFOs.
unsigned int	drain_event (LCBD lcb)
	Drains the event FIFOs.
unsigned int	check (unsigned int rd, unsigned int error, const char *name)
	Checks for and reports both IO and ITEM errors.
unsigned int	poll (LCBD lcb, unsigned int nsecs, int iterations)
	Polls the RESULT FIFO every nsecs for @ iterations.
unsigned int	destroy_handler (LCBD_hcb *hcb, unsigned int failure)
	Destroys a FORK processing task, iff it was created by the LCBD driver.
void	select_fabric (unsigned int volatile *fabric, unsigned int select)
	Accesses the fabric select register, writing the fabric select bit and waits for either the clock to show up or a timeout period to expire.
unsigned int	submit (LCBD lcb, unsigned int request)
	Submits the specified request list to the LCB for execution.
unsigned int	poll_reg_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *prv, unsigned int *cur, unsigned int header)
	Performs an access to the LATP register.
unsigned int	poll_csr_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *prv, unsigned int *cur)
	Performs an access to the LATP CSR register.
unsigned int	poll_faults_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *prv, unsigned int *cur)
	Performs an access to the LATP FAULTS register.
unsigned int	clear_faults (LCBD lcb, unsigned short int stall)
	Clears the FIFO faults register.
void	lcbd_isr (LCBD lcb)
	Central ISR that dispatches LCB result descriptors.
unsigned int	lcbd_csr_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *prv, unsigned int *cur)
	Utility routine to compose and execute an access command to LCB's CSR register independent of whether the driver is offline or online.
unsigned int	lcbd_faults_access (LCBD lcb, unsigned int value, unsigned int field_select, unsigned short int stall, unsigned int *prv, unsigned int *cur)
	Utility routine to compose and execute an access command to LCB's FAULTS register independent of whether the driver is offline or online.
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.
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 *org_options)
	Sets the clock options.
LCBD	LCBD_create (LCBD lcb)
	Preinitializes the LCBD device control block.
const LCBD_dib *	LCBD_dib_locate (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_drain (LCBD lcb, int which)
	Drains the specified ques.
unsigned int	LCBD_enable (LCBD lcb, unsigned int enables)
	Sets the enable/disable flags controlling the EVENT and RESULT interrupts.
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.
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_pci_cfg_status_clear (LCBD lcb)
	Clears the PCI configuration space status word.
LCBD_state	LCBD_state_get (LCBD lcb)
	Returns the current state of the driver.
unsigned int	LCBD_unload (LCBD lcb)
	Unloads the LCB driver.
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.
__inline unsigned int	init_dib (LCBD_dib *dib)
	Initializes the Device Information Block Status.
__inline unsigned int	check_pci_version (const FpgaList *fpga, unsigned char pci_version)
	Checks if the pci version is in the list of acceptable versions.
__inline unsigned int	check_fpgas_version (const FpgaList *fpga, unsigned char pci_version, unsigned char latp_version)
	Checks if the combined PCI/LATP versions is in the list of acceptable versions.
__inline void	init_evt_cbp (LCBD_evt_cbp evt[LCBD_EVT_PROTO_CNT], LCBD_evt_cb defaultHandler, void *defaultParameter)
	Initializes all event fabric protocol handlers to a default callback and parameter.
__inline unsigned int	init_evt_fcb (LCBD_evt_fcb *fcb, unsigned int *event_base)
	Initializes the event free control block.
__inline int	init_ucb (LCBD_ucb *ucb, LCBD lcb)
	Initializes the Unit Control block.
__inline int	destroy_ucb (LCBD_ucb *ucb, LCBD lcb)
	Shutsdown the Unit(s) Control block.
__inline unsigned int	destroy_result_handler (LCBD lcb)
	Destroys the result que service task, iff it was created by the LCBD driver.
__inline unsigned int	destroy_event_handler (LCBD lcb)
	Destroys the event que service task, iff it was created by the LCBD driver.
unsigned int	lcbd_create_handler (LCBD_hcb *hcb, const char *name, int priority, LCBD lcb, int que_cnt, const FORK_que_cfg *que_cfg, int que_id, unsigned int failure)
	Creates a FORK processing task.
__inline unsigned int	handle_clks (LCBD_clk_ucb *clk, LCBD_stats_isr *stats, LCBD lcb, unsigned int clock, unsigned int pending, unsigned int enabled)
	Handles the clock interrupts.
Variables
FpgaList	Fpga
	List of correlated PCI,LATP FPGA versions that this driver is compatiable with.
_LCBD	Lcb
	The actual storage for the driver control block.

---

Detailed Description

LCBD initialization and setup routines.

Author:

Curt Brune -- curt@slac.stanford.edu

JJRussell -- russell@slac.stanford.edu

  CVS $Id

Initialization of the LCB driver and hardware

The initialization of the LCB is complicated by the following facts

1. There is a PCI initialization phase
2. There is a LATp initialization phase
3. There is a software initialiation phase
4. What gets done in these phases is somewhat dependent on whether one is an commander (SIU) or a responder (EPU)

PCI Initialization Phase

The main parts to this phase are

1. Prepare the LCB driver control block for initialization
2. Locate the LCB on the PCI buSs
3. Check that the LCB's PCI FPGA version number matches a version supported by this driver
4. Discover the LOCAL <-> PCI address space translation offets.
5. Quiet any potential LCB activity by touching the CSR and IRQ enable register on the PCI side.
6. Setup the event data circular buffer

The next step is to drain the FIFOs, but this depends on whether the LCB is a commander or a responder

• If the LCB is a commander, both the RESULT and EVENT FIFOs can be drained.
• If the LCB is a responder, only the EVENT FIFO can be drained.

Problems associated with the draining of each FIFOs must be considered separately.

EVENT FIFO DRAINING

The draining of the EVENT FIFO is either extremely difficult or extremely easy, depending on your philosophical bend. If one finds an entry in the EVENT FIFO, all bets are off because this means data was DMA'd into some random portion of the CPUs memory. The only recourse is to reboot.

The condition for success is that no descriptor is found once the circular buffer has been setup. So the sequence should be

• Setup the circular buffer
• Check if there is nothing in the EVENT FIFO
• If successful, one can proceed
• If there is something in the EVENT FIFO, the EVENT FIFO must be drained and a reboot requested.

RESULT FIFO DRAINING

The draining of the RESULT FIFO must take into account the fact that a previously executing list could still be executing and will finish at some random time. The calculated longest execution time in the result FIFO is approximately 3 seconds. Again if one finds a result descriptor in the RESULT FIFO, a reasonable attempt is made to drain the FIFO, but after that, a reboot must be requested since data going into the result list could have been DMAd into some random piece of memory.

Instead of setting a timeout on this, an internal command is queued to the command list executer. When this command completes and is received back in the result queue, one knows that all previous commands have been cleared.

If the LCB is being used as a responder, then it is very possible that one will find a result item sent by the commander (SIU) that contains the board address to assign to this LCB. This is also a signal that the LCB LATp side clock is now running, so one can now perform operations to the LATp side (ie proceed with the LATp side initialization phase.

Setting the BOARD ID, COMMANDER/RESPONDER and PRIMARY/REDUNDANT paths

There is nothing in the driver about setting these up, since this is not a driver responsibility. Since these quantities are relevant only when one begins to talk to the rest of the LAT, it is the responsibility of the so-called plumbing code to set this information up.

As a point of information only, on path and command/responder selection mechanism is not in the LCB at all, but in the CRU.

The setting of the BOARD ID is the responsibility of SIU in all cases. The SIU must set his own BOARD ID by accessing his LATp-side CSR using a direct LCB CSR ACCESS command. In addition, the SIU must set the EPUs BOARD ID by accessing the EPU's LATp-side CSR as a slave register using a LATP CMD TRANSMIT (with or without response.) This is because the only the SIU has knowledge of the system configuration; the EPUs must receive this knowledge from the SIU.

ISR

This file implements routines and interfaces for dealing with the interrupt aspects of the LCB. This includes the actual ISR (Interrupt Service Routine) along with various connect and enable routines. The task level service routines for the result and event units are in LCBD_rst.c and LCBD_evt.c. The clock unit is handle directly at ISR level, so its service routine lives in this file.

---

Define Documentation

#define FABRIC_SELECT_TIMEOUT   10000

The timeout period, in nanoseconds, that one is willing to wait for the clock to show up after doing a fabric select. According the LCB board designed, it can take up to something short of a microsecond after the fabric select bit has been strobed to find the new clock value in the CSR.

---

Function Documentation

unsigned int check (  unsigned int  rd, unsigned int  error, const char *  name )  [static]

Checks for and reports both IO and ITEM errors. Return values: 0,If  OK !=0,An  LCB message code if not OK Parameters: rd  The result descriptor error  The item error field name  The name of the calling function.

Here is the call graph for this function:

static __inline LCBD_FPGA_SUP_K check_fpgas_version (  const FpgaList *  fpga, unsigned char  pci_version, unsigned char  latp_version )  [static]

Checks if the combined PCI/LATP versions is in the list of acceptable versions. Returns: The support level, if < 0, not supported

static __inline unsigned int check_pci_version (  const FpgaList *  fpga, unsigned char  pci_version )  [static]

Checks if the pci version is in the list of acceptable versions. Returns: The support level Parameters: fpga  The counted list of acceptable correlated PCI/LATp FPGAs to scan pci_version  The PCI FPGA version number

unsigned int clear_faults (  LCBD  lcb, unsigned short int  stall )  [static]

Clears the FIFO faults register. Returns: Status Parameters: lcb  The LCB driver handle stall  A stall value (in units of LATp clocks)

Here is the call graph for this function:

unsigned int clk_handler (  void *  unused, LCBD  lcb )  [static]

Default clock off -> on and clock on -> off handler. Return values: 0,always  Parameters: unused  Not used lcb  The LCBD control structure This is the default clock transition handler. It is currently a NOOP, so, since it does nothing, can handle either the ON -> OFF transition or the OFF -> ON transition.

unsigned int connect (  LCBD  lcb, unsigned int  options )  [static]

Connects the LCBD to the interrupt source. Returns: LCBD_OK on success Parameters: lcb  Pointer to private LCBD structure options  The connect options See also: disconnect() This function connects the LCB driver to the PCI or PID interrupt. In general, interrupts should not be enabled at this time, but, while not necessary, logically, one would have installed the event and result callback FORK tasks and ques. The next logical step in this process would be to enable the interupts. Note: The connection to a PID interrupt is available only on a RAD750 in a flight crate. Also note that BAE did not provide a disconnect, leaving one with only a pidIntDisable as a pseudo-disconnect.

Here is the call graph for this function:

static __inline unsigned int destroy_event_handler (  LCBD  lcb  )  [static]

Destroys the event que service task, iff it was created by the LCBD driver. Returns: Status Parameters: lcb  The LCBD driver handle

Here is the call graph for this function:

unsigned int destroy_handler (  LCBD_hcb *  hcb, unsigned int  failure )  [static]

Destroys a FORK processing task, iff it was created by the LCBD driver. Returns: Status Parameters: hcb  The LCBD handler control block, upon success, this is filled in with information about the newly created FORK task. failure  Status code to use in case of failure

static __inline unsigned int destroy_result_handler (  LCBD  lcb  )  [static]

Destroys the result que service task, iff it was created by the LCBD driver. Returns: Status Parameters: lcb  The LCBD driver handle

Here is the call graph for this function:

unsigned int destroy_sw (  LCBD  lcb  )  [static]

Laundry list of LCBD shutdowns to do on the software side. Returns: LCBD_OK, or a status code Parameters: lcb  A previously PCI/LATp initialized LCBD handle

Here is the call graph for this function:

static __inline int destroy_ucb (  LCBD_ucb *  ucb, LCBD  lcb )  [static]

Shutsdown the Unit(s) Control block. Parameters: ucb  The dispatch control block lcb  The LCB driver handle

unsigned int disconnect (  LCBD  lcb  )  [static]

Disconnects the LCBD from the interrupt source. Parameters: lcb  Pointer to private LCBD structure Returns: LCBD_OK on success See also: connect() This function disconnects the LCB from interrupt source. After this function is called the LCB will no longer interrupt. Note that this is a different function than LCBD_enable/disable which merely disables interrupts from being delivered.

Here is the call graph for this function:

unsigned int drain_event (  LCBD  lcb  )  [static]

Drains the event FIFOs. Return values: 0  if successfully drained Returns: LCB message code it had errors Parameters: lcb  Initialized LCBD handle The EVENT FIFO is drained by reading it until dry or for a maximum of 1024. Note that, as opposed to the RESULT FIFO where no transactions are being launched (they are all solicited, except for the BOARD ID transaction and that is just a fly-in-the-ointment), the EVENT FIFO can be continually filled by external agents. This why the loop is capped.

Here is the call graph for this function:

unsigned int drain_result (  LCBD  lcb  )  [static]

Drains the result FIFOs. Return values: 0  if successfully drained Returns: LCB message code it had errors Parameters: lcb  Initialized LCBD handle The result buffer is drained by launching an internal command and waiting for the transaction to arrive back in the result FIFO. If -#. An error occurs on the sweeping transaction or The sweeping transaction does not complete in roughly .3msec or Another, rogue, transaction is encountered an error is declared. In the last case, an attempt is made to clear an remaining transactions. Could one get into trouble here be taking too long. Don't think so. The request FIFO can only execute 2 commands at a time so the only way there could be a lot of transactions to dispose of is if they are already in the result que. The result FIFO is a maximum of 4Kbytes or 1K transactions in length, Therefore the maximum time will be something like 1K * 2 usecs (the 2 usecs being a generous estimate of the PCI read of the result FIFO.) + the time of complete of the sweeping transaction (something like 10usecs) for a total of about .2msecs. The function almost completely ignores NULL descriptors. The reason it does not completely ignore NULL descriptors is to handle the situation where there may be an infinite supply of NULL descriptors. It is not hard to imagine a scenerio where a hardware failure repeatedly delivers NULL descriptor after NULL descriptor. Therefore, while the number of NULL descriptors is factored out when checking if there are any rogue descriptors, they still count against the overall limit (currently 1024) of descriptors that this routine is willing to try to drain.

Here is the call graph for this function:

unsigned int evt_def_handler (  void *  unused, unsigned int  ed, LCBD_evt *  evt )  [static]

Default event handler. Return values: 0,i.e,just  free the event Parameters: unused  The user parameter ed  The event descriptor evt  The event This is the default event handler. It just returns 0, indicating to free the event and continue normal processing of anymore events

static __inline unsigned int handle_clks (  LCBD_clk_ucb *  clk, LCBD_stats_isr *  stats, LCBD  lcb, unsigned int  clock, unsigned int  pending, unsigned int  enabled )  [static]

Handles the clock interrupts. Return values: The  value to or into the source mask to remove the clock interrupts Parameters: clk  Pointer to the clock control structure stats  ISR statistics block lcb  The LCBD driver handle clock  The current state of the 20MHz clock pending  Which clock interrupts are currently pending enabled  Which clock interrupts are currently enabled Clock Interrupts This routine handles the interrupts due to the LATp clock transitioning form ON -> OFF and OFF -> ON. Because the software in no way controls the state of the clock, one is confronted with two problems What to do if both the ON -> OFF and OFF -> ON interrupts are set. In this case, not only does one not know which interrupt went off first, one has no idea how many times these transitions where made. What to do if the actual current state of the clock does not match the transition. The design decision here is to take the interrupt as only a hint. The interrupt will be dispatched to the handler consistent with the current state. This dispatching will be done if and only if the interrupt source is enabled.

Here is the call graph for this function:

unsigned int init_circ (  LCBD  lcb, unsigned int *  event_base, int  fill )  [static]

Allocates memory for and sets it up to be used as the circular buffer. Return values: LCBD_OK  If successful LCBD_INSEBUF  If insufficient memory to allocate event buffer LCBD_INVEBUF  If invalid event buffer (misaligned) Parameters: lcb  The LCBD driver handle event_base  The bae address of the event buffer. If NULL, an event buffer will be allocated. fill  Flag indicating whether to fill the buffer

Here is the call graph for this function:

static __inline unsigned int init_dib (  LCBD_dib *  dib  )  [static]

Initializes the Device Information Block Status. Parameters: dib  The Device Information Block to nitialize

static __inline void init_evt_cbp (  LCBD_evt_cbp  evt[LCBD_EVT_PROTO_CNT], LCBD_evt_cb  defaultHandler, void *  defaultParameter )  [static]

Initializes all event fabric protocol handlers to a default callback and parameter. Returns: Nothing, its a void Parameters: evt  The array of event fabric protocol handlers defaultHandler  The default handler defaultParameter  The default parameter

static __inline unsigned int init_evt_fcb (  LCBD_evt_fcb *  fcb, unsigned int *  event_base )  [static]

Initializes the event free control block. Return values: LCBD_OK,if  OK, LCBD_FCBMTXI,if  failed to create locking mutex Parameters: fcb  Pointer to the event free control block event_base  The event base pointer

unsigned int init_latp (  LCBD  lcb, unsigned int  options, unsigned int *  event_base, LCBD_load_cb  notify, void *  prm )  [static]

Laundry list of LCBD initializations to do on the LATp side. Return values: LCBD_OK  LCBD_NOCLK  A  status code Parameters: lcb  A previously PCI initialized LCBD handle options  The options word. Currently this routine examines the path selection event_base  The base address of the event buffer. LCBD_K_EVENT_BASE_IGNORE, don't set the event base register LCBD_K_EVENT_BASE_ALLOCATE, allocate the event buffer from the MBA pool, and use this as the event base address Anything else, will be used as the event base Parameters: notify  The notification callback prm  The notification parameter To be successful, the clocks on the LATp need to be running.

Here is the call graph for this function:

unsigned int init_latp_clk_on (  LCBD  lcb, unsigned int  options, unsigned int *  event_base )  [static]

Complete LCBD initializations of LATp side. Return values: LCBD_OK  LCBD_NOCLK  A  status code Parameters: lcb  A previously PCI initialized LCBD handle options  The options word. Currently this routine examines the path selection event_base  The base address of the event buffer. LCBD_K_EVENT_BASE_IGNORE, don't set the event base register LCBD_K_EVENT_BASE_ALLOCATE, allocate the event buffer from the MBA pool, and use this as the event base address Anything else, will be used as the event base This does all the initialization after the clocks are found to be on.

Here is the call graph for this function:

unsigned int init_pci (  LCBD  lcb  )  [static]

Initializes the LCBD structure -- probes the PCI bus. Returns: LCBD_OK for success, LCBD_PCIFAIL is the board cannot be found. Parameters: lcb  Pointer to private LCBD structure This routine initializes the PCI portion of the lcb handle. If the @ lcb handle is specified as NULL, the internal handle available by calling LCBD_get, is used. The steps are Probe the PCI bus looking for the LCB. When the board is found store the mapping for the PCI Memory space. Both the mapping LOCAL -> PCI and PCI -> LOCAL are stored. Disable interrupts Select the primary/redundant command path

Here is the call graph for this function:

unsigned init_sw (  LCBD  lcb  )  [static]

Laundry list of LCBD initializations to do on the software side. Returns: LCBD_OK, or a status code Parameters: lcb  A previously PCI/LATp initialized LCBD handle

Here is the call graph for this function:

static __inline unsigned int init_ucb (  LCBD_ucb *  ucb, LCBD  lcb )  [static]

Initializes the Unit Control block. Returns: Status Parameters: ucb  The unit(s) control block lcb  The LCB driver handle The unit(s) control block contains information that stretches across the ISR and the various units. These include the two clock transition interrupts (ON -> OFF and OFF -> ON), the result queue and the event queue interrupts.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

unsigned int lcbd_create_handler (  LCBD_hcb *  hcb, const char *  name, int  priority, LCBD  lcb, int  que_cnt, const FORK_que_cfg *  que_cfg, int  que_id, unsigned int  failure )

Creates a FORK processing task. Returns: Status Parameters: hcb  The LCBD handler control block, upon success, this is filled in with information about the newly created FORK task. name  The name of the FORK task priority  The priority of the task lcb  Used as the callback parameter to the handler que_cnt  The number of queues to configure que_cfg  The configuration of each que que_id  The que id to use for the handler failure  Status code to use in case of failure

unsigned int lcbd_csr_access (  LCBD  lcb, unsigned int  value, unsigned int  field_select, unsigned short int  stall, unsigned int *  prv, unsigned int *  cur )

Utility routine to compose and execute an access command to LCB's CSR register independent of whether the driver is offline or online. 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 period, in units of 20MHz clock ticks, for the LCB to wait for completion. prv  Pointer to receive the value of the register before modification. This may be NULL. cur  Pointer to receive the value of the register after modification. This may be NULL.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

Here is the call graph for this function:

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.

Here is the call graph for this function:

unsigned int lcbd_faults_access (  LCBD  lcb, unsigned int  value, unsigned int  field_select, unsigned short int  stall, unsigned int *  prv, unsigned int *  cur )

Utility routine to compose and execute an access command to LCB's FAULTS register independent of whether the driver is offline or online. 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. prv  Pointer to receive the value of the register before modification. This may be NULL. cur  Pointer to receive the value of the register after modification. This may be NULL.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

void lcbd_isr (  LCBD  lcb  )  [static]

Central ISR that dispatches LCB result descriptors. Parameters: lcb  Pointer to private LCBD structure Returns: void

Here is the call graph for this function:

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

Initializes the LCB hardware and LCBD software. Returns: Status. If the status is SUCCESS, then this function completed successfully If the status is ERROR, then an irrecoverable error occurred and the integrity of the CPU is in question 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 Since it does not need the LCB during primary boot it does not need this parameter during primary boot 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

Here is the call graph for this function:

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. If the status is SUCCESS, then this function completed successfully If the status is ERROR, then an irrecoverable error occurred and the integrity of the CPU is in question 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 Since it does not need the LCB during primary boot it does not need this parameter during primary boot 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 Specify NULL, then the LCBD_load_init will wait internally. This option is provided as a convenience and is not recommended for general use 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 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; .

Here is the call graph for this function:

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

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

unsigned int poll (  LCBD  lcb, unsigned int  nsecs, int  iterations )  [static]

Polls the RESULT FIFO every nsecs for @ iterations. Returns: The result descriptor Parameters: lcb  The LCBD driver handle nsecs  The polling rate iterations  The number of polling iterations Typical turnaround times (DMA to transfer the list, do the transaction and DMA the result back are around 6.0 usecs. A polling time of around 2.5 usecs is very reasonable. If one is looking to drain the FIFO, one must consider that the longest tranaction could take up to 3 secs. (It would a pretty bizzare list, but it is possible.)

Here is the call graph for this function:

unsigned int poll_csr_access (  LCBD  lcb, unsigned int  value, unsigned int  field_select, unsigned short int  stall, unsigned int *  prv, unsigned int *  cur )  [static]

Performs an access to the LATP CSR register. Returns: The new value of the CSR register or if > 256, an LCB message code Parameters: lcb  The LCBD driver handle value  The 32 value to write to the csr field_select  A bit mask indicating which fields should be written stall  A stall value (in units of LATp clocks) prv  Pointer to return the old CSR value in, may be NULL cur  Pointer to return the new CSR value in, may be NULL

Here is the call graph for this function:

unsigned int poll_faults_access (  LCBD  lcb, unsigned int  value, unsigned int  field_select, unsigned short int  stall, unsigned int *  prv, unsigned int *  cur )  [static]

Performs an access to the LATP FAULTS register. Returns: The new value of the CSR register or if > 256, an LCB message code Parameters: lcb  The LCBD driver handle value  The 32 value to write to the csr field_select  A bit mask indicating which fields should be written stall  A stall value (in units of LATp clocks) prv  Pointer to return the old FAULTS value in, may be NULL cur  Pointer to return the new FAULTS value in, may be NULL

Here is the call graph for this function:

unsigned int poll_reg_access (  LCBD  lcb, unsigned int  value, unsigned int  field_select, unsigned short int  stall, unsigned int *  prv, unsigned int *  cur, unsigned int  header )  [static]

Performs an access to the LATP register. Returns: The new value of the register or if > 256, an LCB message code Parameters: lcb  The LCBD driver handle value  The 32 value to write to the csr field_select  A bit mask indicating which fields should be written stall  A stall value (in units of LATp clocks) prv  Pointer to return the old register value in, may be NULL cur  Pointer to return the new register value in, may be NULL header  The command header

Here is the call graph for this function:

void select_fabric (  unsigned int volatile *  fabric, unsigned int  select )  [static]

Accesses the fabric select register, writing the fabric select bit and waits for either the clock to show up or a timeout period to expire. Parameters: fabric  The address of the PCI fabric select register select  The value (0 or 1) to set it to.

Here is the call graph for this function:

unsigned int submit (  LCBD  lcb, unsigned int  request )  [static]

Submits the specified request list to the LCB for execution. Return values: LCBD_OK,if  successfull LCBD_REQFULL,if  the transaction could not be submitted because the request que is full Parameters: lcb  The LCBD driver handle request  A pointer to a properly built (address | length) request. The transformation for local to PCI space is done in this routine.

Here is the call graph for this function:

---

Variable Documentation

static FpgaList Fpga [static]

Initial value: { 9, 9, { FPGA (0x80, 0x80), FPGA (0x2c, 0x5e), FPGA (0x2c, 0x5d), FPGA (0x2c, 0x5c), FPGA (0x2b, 0x5c), FPGA (0x2a, 0x5c), FPGA (0x2c, 0x5b), FPGA (0x2b, 0x5b), FPGA (0x2a, 0x5b), 0,0, 0,0,0,0 } } List of correlated PCI,LATP FPGA versions that this driver is compatiable with.

struct _LCBD Lcb [static]

The actual storage for the driver control block. See also: LCBD_get to get a pointer to this handle

---