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

Constituent: lcbd     Tag: rad750

Interface   Data Structures   File List   Data Fields   Globals  

_LCBD.dox File Reference

Overview of the LCBD Driver. More...

Detailed Description

Overview of the LCBD Driver.

Author:
JJRussell -- russell@slac.stanford.edu
Overview of the LCBD Driver
The API presented by the driver tries to maintain the view of the LCB as three distinct units. These are
Inevitably there are rough spots where these three units are not completely orthogonal. Ideally one could choose to independently load any combination of these, ignoring the others. The rough spots surface when ensuring that units not of interest are in a quiet state.
File Organization
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 properties of the LCB driver. In addition there are number of support files.
A brief summary of these files is presented in the following table. They are presented roughly in order of usage and importance.
LCBD Driver Files
Functional Unit What it does Header Files Source Files

Driver Driver load/unload plus interrupt connection and enables LCBD_drv.h LCBD_drv.c

Clock Signals transitions of the 20MHz LATp-side clock LCBD_clk.h LCBD_clk.c

Notification Asynchronous notification of driver state transitions LCBD_nut.h LCBD_nut.c

Command/Response Submits command lists and handles result lists LCBD_rst.h LCBD_rst.c

Event Handles incoming traffic on the event fabric LCBD_evt.h LCBD_evt.c

Statistics Fetching and displaying of driver statistics LCBD_stats.h LCBD_stats.c

Driver Command/Result Lists Lays out LCBD structure for both command & result lists LCBD_cr.h - none -

Command Utilities Simple filling, parsing and synchronous execution of command lists and items LCBC.h LCBC.c

Result Utilities Parsing and traversing of result lists and items LCBR.h LCBR.c

MSG Codes MSG message code definitions LCBD_msgs.h - none -
LCB Hardware Definitions
Hardware Unit What it does Header Files

LCB Definitions Defines global LCB hardware properties LCB.h

LCB Command/Result List & Items Defines command and result lists and items plus opcodes LCB_cr.h

LATP LAT protocal definitions LATP.h
Driver
LCBD_drv defines and implements global properties and functions of the driver
Driver Routines
Function Description

LCBD_allow Allows additional to accept additional PCI/LATp FPGA versions

LCBD_create Creation and software pre-initialization of the drive handle, one-time only call

LCBD_get Returns a pointer to the driver handle

LCBD_load Loads the driver

LCBD_unload Unloads the driver

LCBD_enable Enables/Disables the various interrupt sources

LCBD_state_get Gets the current state of the driver

LCBD_drain Drains the result and/or event queues (non-interrupt mode)

LCBD_pci_cfg_status_clear Clears the status bits in the PCI configuration status register

LCBD_dib_locate Returns a pointer to the Device Information Block

LCBD_dib_show Displays the contents of the Device Information Block
Clock Transition Unit
LCBD_clk unit is primarily of concern to the system programmer. The clock here is the 20MHz LAT system wide clock, not the 33MHz PCI clock. Without this clock, the LCB cannot access most of its LATp side functionality.
The LCB hardware contains two related interrupts, one indicating the transition from the clock being off to the clock being on, and one indicating the opposite transition from the clock being on to the clock being on. It is expected that the system will install appropriate callback routines to handle these transitions. But these callback routines are very primitive, really meant for debugging and development purposes. A higher level facility based on the clock interrupts is provided, the Notification of the User of state Transitions (NUT) facility.
Clock Routines
Function Description

LCBD_clk_off_cb_set Seeds the clock off callback routine + parameter

LCBD_clk_off_cbp_get Returns the clock off callback routine + parameter

LCBD_clk_on_cb_set Seeds the clock on callback routine + parameter

LCBD_clk_off_cbp_get Returns the clock on callback routine + parameter

Notification of the User of state Transitions
The LCBD_nut facility provides the user with a means of being asynchonously notified when the state of the driver reaches a target state specified by the user. For example, the user may wish to know when the driver goes ONLINE. Using the LCBD_nut facility, the user would register a notification callback routine to be called when the driver goes ONLINE.
NUT Basic Routines
Function Description

LCBD_nut_handler_create Convenience routine to create the NUT service task and set the FORK_que

LCBD_nut_que_install Installs the NUT FORK que

LCBD__nut_fill Convenience routine to fill a notification request

LCBD_nut_notify Ques a notification request

LCBD_nut_cancel Cancels a notification request
NUT pre-canned notification callback/synchronization routines
Function Description

LCBD_nut_notifyW Ques a notification request and waits for till it is satisfied

LCBD_nut_head_create Creates a pending list head to use with LCBD_nut_post and LCBD_nut_pendW

LCBD_nut_head_destroy Destroys the specified nut post head created with LCBD_nut_head_create

LCBD_nut_post Ques a notification request and ques the satisfied request to the specified posting head

LCBD_nut_pendW Pends of a NUT post head for the next satisfied notification request

LCBD_nut_fork Ques a notification request and ques the satisfied request to the specified FORK que

Command/Response
LCBD_rst is the main unit that the application programmer interacts with. It is really two units, one used to submit command lists to the LCB for execution and one to field the responses/results. Because the transactions are tied together, in the sense that the LCB will not execute a new command list until it completely services prior lists, the driver also ties these two units together, using this First In First Out processing of command lists and reception of result lists as an integrity check on the transactions.
For those truly interested, while the LCB obeys a FIFO principle of operations, it is highly buffered and pipelined. The LCB can have operations pending in a variety of states within it. While the counting is not exact, the LCB could have on the order of 8-10 command lists in or waiting for execution. One of the simplications of the LCB hardware was to not provide a cancel function. Once an operation has been successfully submitted to the LCB hardware, it cannot be recalled.
RST Basic Routines
Function Description

LCBD_rst_handler_create Convenience routine to create the RST service task and set the FORK_que

LCBD_rst_que_install Installs the RST FORK que

LCBD_rst_null_cb_set Seeds the NULL result descriptor handler + parameter

LCBD_rst_null_cbp_get Returns the NULL result descriptor handler + parameter

LCBD_bind Binds the parameters of an LCBD_xcb to the XCB

LCBD_submit Submits a bound LCBD_xcb to the LCB for execution
RST Utilitiy Routines
Function Description

LCBD_rst_rcv_err_map Translates a result list receive error code to a standard MSG code

LCBD_rst_xfr_err_map Translates a result list transfer error code to a standard MSG code

LCBD_cl_alloc Command list allocator, by bytes

LCBD_rl_alloc Result list allocator, by bytes

LCBD_cl_alloc8 Command list allocator, by 8 byte cells

LCBD_rl_alloc8 Result list allocator, by 8 byte cells

LCBD__cl_len Converts a command list length in bytes to 8-byte cells, i.e. something suitable to passing to one of the LCBD_bind routines

LCBD__cl_dlen Converts a command list specified by it's beginning and ending pointers to 8-byte cells, i.e. something suitable to passing to one of the LCBD_bind routines

LCBD__rl_len Converts a result list length in bytes to 8-byte cells, i.e. something suitable to passing to one of the LCBD_bind routines

LCBD__rl_dlen Converts a result list specified by it's beginning and ending pointers to 8-byte cells, i.e. something suitable to passing to one of the LCBD_bind routines
RST Pre-canned Callback/Sychrnonization Routines
Function Description

LCBD_qioW Convenience routine to que a command list to the LCB and wait for its completion, combines LCBD_bind and LCBD_submitW

LCBD_submitW Submits a bound LCBD_xcb to the LCB and waits for its completed execution

LCBD_fork_bind Binds the parameters to an LCBD_xcb using a dispatch to a FORK que as its synchronization method.

LCBD_post_create Creates a posting list head that can be used by LCBD_post_bind and LCBD_post_pendW

LCBD_post_destroy Destroys the posting list head created by LCBD_post_create

LCBD_post_bind Binds the parameters of the LCBD_xcb to an XCB using a dispatch to a posting list head as its synchronization method.

LCBD_post_pendW Waits for the next completed LCBD_xcb on the specified posting list head
RST Macros
Macro Description

LCBD_EXP_DSC_COMPOSE Composes a command export descriptor
Event
LCBD_evt controls and services traffic of the event fabric. The architecture of the transactions on the LATp event fabric is such that most users view traffic on this fabric as simply data that arrives asynchronously into a user provided callback. In this model, the application programmer has little interaction with the driver itself. He may install callback routines to service the four LCB provided protocols, but beyond that he is limited to perhaps calling some convenience service routines to help in packet reassembly and packet freeing.
Outbound traffic, e.g. a LCB-to-LCB message, is really part of the command/response unit, not the event unit. To the receiver, such transactions are a part of the event unit, but to the transmitter they are handled by the command/response unit.
EVT Routines
Function Description

LCBD_evt_handler_create Convenience routine to create the EVT service task and set the FORK_que

LCBD_evt_que_install Installs the EVT FORK que

LCBD_evt_cb_set Seeds the event callback handler + parameter for a specified protocol

LCBD_evt_cbp_get Returns the event callback handler + parameter for a specified protocol

LCBD_evt_err_cb_set Seeds the event error handler + parameter for a specified

LCBD_evt_err_cbp_get Returns the event error handler + parameter

LCBD_evt_conds_set Sets the event que and event buffer interrupt conditions, returning the old ones, see LCBD_EVT_COND

LCBD_evt_enable Enables the flow of events into the event circular buffer, returns the original flow state

LCBD_evt_tickle Tickles the event handler to check if there are any events to be serviced.

LCBD_evt_free Frees the specified event

LCBD_evt_rcv_err_map Translates a event receive error code to a standard MSG code

LCBD_evt_xfr_err_map Translates a event transfer error code to a standard MSG code
EVT Macros
Macro Description

Loading/Initializing the Driver
A lot of work has gone into eliminating driver configuration constants and simplying the loading of the driver. There are only two configuration constants that absolulted must be specified to load the driver
Special sentinel values allow both parameters to be ignored, that is the LCB will not attempt to set them. Correct use of the fabric select parameter is highly dependent on whether the LCB is residing in a SIU or EPU crate.
SIU Fabric Selection
Fabric selection on the SIU should be done by specifying the appropriate path,
to LCBD_load. Because the primary boot code does not use the LCB, this value is not needed until secondary boot. The secondary boot code should use the EEPROM to store this value. If fail-over is needed, then a 1553 command will be issued to change it.
EPU Fabric Select
Fabric selection on the EPU cannot use this method because it needs the LCB, and hence the path selection, during primary boot. (There is no method of passing parameters to the primary boot code.) The EPU depends on the SIU to remotely set this value by assessing the EPU's LATp-side CSR as a slave register on the command/response fabric and setting the path selection bit there to the desired value. Consequently EPU code will always specify
Event Base
This parameter allows the system architect to set the address of the event fabric's circular buffer. Two sentinel values are defined
The former instructs LCBD_load to leave the event base register as is. This may be valuable in test code. The latter instructs LCBD_load to internally allocate a buffer and use its address as the event base. Buffers automatically allocated will be freed when the driver is unloaded. Clean-up of user specificed buffers is the responsibility of the user.
Other parameters
There are 4 other parameters that can be specified by the options of LCBD_load. They are

See the enum LCBD_LOAD_OPTIONS_M and the macro LCBD_LOAD_OPTIONS_M_BOARD_ID_N for details.
Specifying these parameters in this way is only a convenience. The loading of the does not depend on these parameters in any way. Because it is not absolutely necessary to load these parameters at this time and because it is possible that the application does not know the value of these parameters at LCBD_load time, they can be set at anytime before they are needed (general rule here is before any external LCBD operations are attempted such as issuing a message to another CPU or talking to a TEM), there are convenience routines to set them at a later point. These are

Note:
These really are merely convenience routines. For the bit-twiddlers, one can set all these parameters by specifying the appropriate arguments to LCBD_csr_access.
Driver Simplification - Overview
In trying to simplify driver loading, LCBD separate its clients into two classes
  1. Users who just want to get the driver loaded and get going
  2. Users who operate in a very formal environment where complete control is paramount.
The first class of users are test code writers and prototypers. The second class of users are those installing the driver in a deliverable product. Needlessly to say, satisfying both groups simoultaneously is difficult.
Driver Simplification - Service Tasks and Ques
One of the big steps in removing configuration constants from the driver was in the divorcing of the service task management. Properly speaking, the LCBD driver is not concerned with service tasks; all it really needs to know is the FORK que associated with each of the three handlers (notification, result and event).
For user's in the second class, LCBD provides three routines to register these ques with the driver
Naturally, the user is responsible for creating the FORK task and identifying the target que. With this responsibility comes the freedom to do almost anything one pleases. For example, one could create one FORK task with 3 ques, handing a different que to each installation routine. (Would not recommend this.)
For user's in the first class, a simplified set of routines to create a FORK task and install a FORK que are provided. (These routines may be stripped from the final production driver; they consume are fair amount of code space.) These routines are
The priority can be specified with a sentinel values
If so, LCBD will assign a handler specific priority to each FORK task.
With this simplication, one loses control of almost every parameter of the FORK task (except the priority). If special attributes, such as a larger stack, the floating point unit, more ques, etc, are needed, the user must create the FORK task and install the que using the previously described method.
Unloading the Driver
For debugging and development purposes, the driver is built so that it can be unloaded (see LCBD_unload). The NUT facility allows user code to be notified of this rather jarring event. It is up to the user to clean-up his own house first, for example, by stopping the submission of new requests to LCBD and servicing all currently outstanding requests. The unload process will
  1. Disable all the interrupt sources
  2. Disconnect the driver from the PCI interrupt itself
  3. Return all resources it garnered during the load phase
As a convenience to the user, any service tasks created using convenience routines (e.g. LCBD_rst_handler_create) will be destroyed. It is the user's responsibility to manage the tasks associated with, e.g. LCBD_rst_que_install; afterall the LCBD que may be only one of many ques associated with this task. As mentioned before, if the event circular buffer is allocated by the driver, it will also be freed by LCBD_unload operation.
Initialization Example 1
A typical initialization sequence for users in the first class goes like
   unsigned int startLcbd (unsigned int         options,
                           unsigned int *circularBuffer)
   {

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


       // Load the driver,
       // Options is used to select the path and the interrupt source
       // See LCBD_LOAD_OPTIONS_M  for details
       status  = LCBD_load   (lcb, options, 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 25% on FIFO */
       LCBD_evt_conds_set (lcb, LCBD_EVT_COND_25_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;
   }
Initialization Example 2
A formal initialization sequence for users is presented here. It is not meant to be complete, but gives you the rough idea of how one would go about starting the driver up in a bullet-proof fashion
   unsigned int startLcbd (unsigned int         options,
                           unsigned int *circularBuffer,
                           FORK_que            *evt_que,
                           FORK_que            *nut_que,
                           FORK_que            *rst_que)
   {

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


       // Load the driver
       // Options is used to select the path and the interrupt source
       // See LCBD_LOAD_OPTIONS_M  for details
       init_status  = LCBD_load (lcb, options, circularBuffer);


       // Check for success errors
       if (_msg_error (init_status) return init_status;


       // Install the result, event and notification ques
       status  = LCBD_rst_que_install (lcb, rst_que);
       status  = LCBD_evt_que_install (lcb, evt_que);
       status  = LCBD_nut_que_install (lcb, nut_que);


       // Enable the clock on interrupt
       // The only possible error is if one tries to simoultaneously set
       // both the ENABLE and DISABLEs, clearly not happening here
       LCBD_enable (lcb, LCBD_M_ENABLE_CLK_ON);


       // Check if possibly have no clock 
       if (init_status == LCBD_NOCLK)
       {
           LCBD_state state;

           // Wait for the driver to come online
           // Once ONLINE the driver has been successfully initialized
           // Keep in mind it may on OFFLINE at any time in the future,
           // but in terms of initialization, it's done.
           state = LCBD_nut_notifyW (lcb, LCBD_STATE_M_ONLINE);

       }

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


       // Set event interrupt conditions 25% on FIFO full
       LCBD_evt_conds_set (lcb, LCBD_EVT_COND_25_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);


       // Check driver state, not necessary, but just to illustrate
       return (LCBD_state_get (lcb) == LCBD_STATE_ONLINE) ? status : ERROR;
   }
Command/Response Usage
Once past this menagerie of setup and initialization routines. the user's primary interaction with the LCB using this version of the driver is through the transaction control block, called an LCBD_xcb. LCBD_xcb is described in detail below.
LCBD_xcb - Overview
The driver main interaction with the user is filling and managing the XCB as it moves from one queue to another. The XCB contains all the necessary information needed to describe the transaction, e.g. the addresses and lengths of the command lists and result lists, plus bookkeeping information to manage the transaction once it has been submitted to the hardware. Given that the LCB is an asynchronous device, with the queing of the IO occuring in one thread of execution and the servicing of the results possibly happening in another thread of execution, the XCB acts as the communication vehicle between these two threads.
Command / Response - Usage
The design goals of the Command / Response portion of the driver were
  1. Limit the driver's scope to submitting command lists and managing responses
  2. Allow the users to construct, allocate and fill command lists at compile time or run time
The second item is a corollary of the first. Here is an example of a statically defining the command list and dynamically allocating and filling it
  @par Example
  @code

    // Define the command items
    typedef struct _MyCmdItems
    {
       LCB_ci_mark_time mark1;  // Issue a mark time command
       LCB_ci_csr         csr;  // Read the LATp-side CSR
       LCB_ci_mark_time mark2;  // Issue another mark time command
       LCB_ci_faults   faults;  // Read the LATp-side FAULTs register
     }
     MyCmdItems;

     // Assemble into a command list
     typedef struct _MyCmdList
     {
        unsigned int *result;   // Reserved for the result list address 
        MyCmdItems        ci;   // The command items
     }
     MyCmdList;

     // Define the corresponding result items
     typedef struct _MyRstItems
     {
       LCB_ri_mark_time mark1;   // Result item for mark time command 1
       LCB_ri_csr         csr;   // Result item for CSR access
       LCB_ci_mark_time mark2;   // Result item for mark time command 2
       LCB_ci_faults   faults;   // Result item for FAULTS register access
     }
     MyRstItems;

     // Assemble into a hardward result list
     typedef struct _LcbRstList
     {
       unsigned int *command;    // Reserved for the command list address
       MyRstItems         ri;    // The result items
     }
     LcbRstList;

     // Tack on the XCB that the driver needs
     typedef struct MyRstList
     {
       LCBD_xcb    xcb;          // The XCB control structure
       LcbRstList   rl;          // The LCB result list
     }
     MyRstList;

     LCBD_post_head head;        // Synchronizing que head
     LCBD_xcb       *xcb;


     // Allocate these 
     // This could also be done off the stack (obeying proper alignment)
     MyCmdList *cl = LCBD_cl_alloc (sizeof (MyCmdList);
     MyRstList *rl = LCBD_rl_alloc (sizeof (MyRstList);


     // Use the inlines to fill the commands although the structures of
     // each command are exposed, so you could 'do it yourself'
     LCBC__mark_time_fill     (&cl.ci.mark1,  200);
     LCBC__csr_access_fill    (&cl.ci.csr,     val, select, timeout);
     LCBC__mark_time_fill     (&cl.ci.mark2,  400);
     LCBC__faults_access_fill (&cl.ci.cfaults,   0, -1, timeout);

     LCBD_post_create (lcb, &head)

     // Bind these parameters to a posting que synchronization method
     xcb  = LCBD_post_bind (lcb, 
                            LCBD__cl_len (sizeof (*cl)),     cl,
                            LCBD__rl_len (sizeof (&rl->rl)), rl,
                            &head, 0, 0, 0, 0);

     // Submit the transaction
     LCBD_submit (lcb, &xcb);

     // Wait for completion...
     xcb  = LCBD_post_pendW (lcb, &head);
Statistics
LCBD_stats is the facitlity the LCBD driver uses to keep track of various counters in each of three major sections
The nature of the statistics is explained in detail in LCBD_stats.h. From a more global perspective, the statistics are almost completely interlocked. That is there are consistency checks that can be performed without shutting down the driver.
Statistics Routines
Function Description

LCBD_stats_clr Clears the statistics counters

LCBD_stats_get Gets a copy of the statistics counters

LCBD_stats_sub Subtracts two sets of statistics counters

LCBD_stats_isr_show Displays the ISR statistics counters

LCBD_stats_evt_show Displays the EVENT statistics counters

LCBD_stats_rst_show Displays the RESULT statistics counters

LCBD_stats_show Displays the all the statistics counters
Driver Specific definitions of Command/Result Lists & Items
LCBD_cr contains result list definitions and information that is dependent of this incarnation of the driver. Because of the way the LCB works, any driver make available some additional information that is used to keep track of the result list from the time it is submitted to the LCB hardware until the time the result list completes. More than anything else, the method of tying this information with a command/result list pair is what distinguishes one driver implementation from another.
Command Utilities
LCBC contains the prototypes and inline functions used to build individual command items and assemble them into command lists. It also contains aids in parsing both command items and command lists. From a purist's viewpoint, this should not be part of the driver, but, to avoid a small shareable containing only this and the related material in LCBR.h, it has been included with LCBD.
There are four groups of routines

LCBC Command Routines, Command Parsing
Function Description

LCBC_process Convenience routine to execute a user callback routine for each command item

LCBC_show Convenience routine to display each command item
LCBC Command Routines, Synchronous Execution
Function Description

LCBC_mark_time Convenience routine to fill a mark time command item

LCBC_cmd_xmit Convenience routine to fill a LAT reset command item

LCBC_lat_reset Convenience routine to fill a command transmit with no response command item

LCBC_cmdr_xmit Convenience routine to fill a command transmit with response command item

LCBC_csr_access Convenience routine to fill a LATp-side CSR access command item

LCBC_faults_access Convenience routine to fill a LATp-side FAULTS register access command item
LCBC Command Fill Routines, Callable versions
Function Description

LCBC_mark_time_fill Convenience routine to fill a mark time command item

LCBC_event_fill Convenience routine to fill a event transmit command item

LCBC_cmd_xmit_fill Convenience routine to fill a LAT reset command item

LCBC_lat_reset_fill Convenience routine to fill a command transmit with no response command item

LCBC_cmdr_xmit_fill Convenience routine to fill a command transmit with response command item

LCBC_csr_access_fill Convenience routine to fill a LATp-side CSR access command item

LCBC_faults_access_fill Convenience routine to fill a LATp-side FAULTS register access command item
LCBC Command Fill Routines, Inline versions
Function Description

LCBC__mark_time_fill Convenience routine to fill a mark time command item

LCBC__event_fill Convenience routine to fill a event transmit command item

LCBC__cmd_xmit_fill Convenience routine to fill a LAT reset command item

LCBC__lat_reset_fill Convenience routine to fill a command transmit with no response command item

LCBC__cmdr_xmit_fill Convenience routine to fill a command transmit with response command item

LCBC__csr_access_fill Convenience routine to fill a LATp-side CSR access command item

LCBC__faults_access_fill Convenience routine to fill a LATp-side FAULTS register access command item
LCBC Macros
LCBC contains a number of macros useful in transversing and interpreting the command items in a command list. Mainly these map an OPCODE into
Note that one of the command types is LCBC_TYPE_UNDEFINED. This can be used to validate the opcode. Since the length is explicitly stored in a command item, there are no macros to translate an OPCODE to a length.
The mapping macros come in two flavors, depending on whether on explicitly specifies the mapping word or lets the macro implicitly reference it. The latter is more efficient when the mapping word is used many times, saves reloading it each time, the former is just more convenient. Note that one must use LCBC in relation to command items, not result items. The type or length of a command item is not necessarily the same as the type or length of its corresponding result item.
LCBC Macros
Macro Description

LCBC_TYPE_BY_OPCODE_FULL Translates an opcode to a command item type, mapping word is specified

LCBC_TYPE_BY_OPCODE_FULL Translates an opcode to a command item type, mapping word is implicit
Result (Response) Utilities
LCBR is a collection of utilities to aid in the construction and parsing of the result lists and result items. These are really just convenience routines. The user has enough information to write these himself.
The driver wishes to maintain its distance from dealing with the individual result items. The routines in LCBR were written because they provide functionality of widespread interest. They were bundled in with the LCBD package for lack of a better place. (They are really not part of the driver, but they have no other good home.) Note that one must use LCBR in relation to result items, not command items. The type or length of a result item is not necessarily the same as the type or length of its corresponding command item.
LCBR Result Routines, Result List/Item Parsing
Function Description

LCBR_check Convenience routine to check each result item for errors

LCBR_error_get Convenience routine to get the error word for a result item

LCBR_process Convenience routine to execute a user callback routine for each result item

LCBR_show Convenience routine to display each result item
LCBR Macros
LCBR contains a number of macros useful in transversing and interpreting the result items in a result list. Mainly these map an OPCODE into
Note that one of the result types is LCBR_TYPE_UNDEFINED. This can be used to validate the opcode.
The mapping macros come in two flavors, depending on whether on explicitly specifies the mapping word or lets the macro implicitly reference it. The latter is more efficient when the mapping word is used many times, saves reloading it each time, the former is just more convenient.
LCBR Macros
Macro Description

LCBR_TYPE_BY_OPCODE_FULL Translates an opcode to a command item type, mapping word specified

LCBR_TYPE_BY_OPCODE_FULL Translates an opcode to a result item type, mapping word is implicit

LCBR_N8BYTES_BY_OPCODE_FULL Translates an opcode to a result item length in 8-byte cells, mapping word is specified

LCBR_N8BYTES_BY_OPCODE Translates an opcode to a result item length in 8-byte cells, mapping word is implicit
MSG codes
LCBD_msgs is the standard include generated by the MSG utility containing all the LCBD return code values.
LCB Definitions
LCB.h is almost a 'C' transcription of Mike Huffer's LCB document, LAT-TD-0860. Details of the command/response unit have been isolated to LCB_cr because of their shear size.
LCB Macros
Macros Description

Command & Result Lists and Item LCB Definitions
LCB_cr contains the hardware ddefinitions of all command items/lists and result items/lists. It also contains macros that can be used to build your own command export descriptors and initialize command items. It is split off from LCB.h simply because of shear size, the combination of the two is fairly massive.
LCB_cr Macros
Macro Description

LCB_CI_HDR Composes the command item header word

LCB_CI_CMD Composes the a transmit command item initializing data statement

LCB_CI_MARK_TIME Composes the a mark command item initializing data statement

LCB_CI_LAT_RESET Composes the a lat reset command item initializing data statement

LCB_CI_CSR Composes the a csr access command item data statement

LCB_CI_FAULTS Composes the a faults command item data statement

LCB_CI_EVENT_LEN_32 Rounds a specified number of integers to the next highest LATP number of cells, returning the answer in integers. Useful for specifying the length to a Event Transfer Command

LAT Protocol Definitions
LATP contains the various LATp definitions. This is almost a 'C' transcription from the hardware documentation.
Generated on Wed May 4 20:44:28 2005 by doxygen 1.3.3