2.4. Command/Response Interface

2.4.1.1.1. Memory Allocation

Memory allocation is left entirely to the user, i.e. the LCBD never allocates memory of its own. Memory must be allocated for the LIOX handle, the command list and the result list.

The LCB places constraints on the memory allocated for command lists and result lists. In particular the memory for the lists must be visible to the PCI bus and have the size and alignment attributes shown in Table 2-2.

All of the above objects could be pre-allocated to form object pools. The user could request an object from the object pool as needed.

The number of allocated lists is a function of the number of :

• Concurrently executing command lists, e.g. background housekeeping during other commanding.

• Command lists previously prepared, e.g. command lists containing default/baseline configuration commands.

It will be worthwhile for the LAT system software to offer memory allocators for different alignment requirements. These allocators could be part of the LAT FSW utility library.

After a result is received and the result is processed the user can return the objects to the appropriate object pool. Objects can be safely deallocated according to the following table:

It is unsafe to deallocate memory when the LIOX state is LIOX_PEND. The LCB will DMA the result into the result list whenever the result arrives. Once a LIOX is initiated the LCB "owns" the result list and command list memory until the transaction completes.

This means we cannot safely deallocate the memory for the result list or the command list until the transaction completes – if the transaction never completes we lose the memory associated with both lists and the memory for the LIOX handle.

2.4.1.1.2. Initializing a LIOX Handle

Initializing a LIOX handle requires the following steps:

• Allocate memory for the LIOX handle.

• Allocate memory for the command list.

• Declare the response handling function.

• Allocate memory for the result list (optional).

Allocating memory for the result list may be deferred until the command list is completely loaded, at which time the total amount of memory required for the result list is known. If, however, the LIOX will be used for synchronous operations ( see Section 2.4.2) the result memory must be supplied at initialization time.

The function prototypes for the response handling function and the initialization function appear below:

The following pseudo-code illustrates the initialization of a LIOX Handle.

// declare result processing callback and extra data
static   int myProcessResultFunc( LIOX lh, void *userData);
unsigned int myExtraData;

// allocate memory for command list and LIOX struct 
void            *pCmdList; // command list
void               *pLIOX; // LIOX    handle
unsigned  short    cmdLen; // command list length
LIOXHandle             lh;

// allocate memory for the command list -- suitably aligned
cmdLen = 4080;
pCmdList = mallocCommandList( cmdLen);

// allocate memory for the LIOX structure 
pLIOX = mallocLIOX( LIOX_SizeOfIOX());

// create opaque handle to LIOX -- note the result list length
// is zero and the result list pointer is NULL.  These will be
// provided later when the command list is queued.
lh = LIOX_Init( pLIOX, 
                cmdLen, pCmdList, 
                0, NULL,
                myProcessResultFunc,
                myExtraData);

// LIOXHandle lh is now initialized and ready for use 

            

The allocation of the result list memory is deferred until after the command list is completely filled. At that time the required size of the result list is completely determined and the exact amount of memory can be allocated. See Section 2.4.1.3.

After the LIOX handle is initialized the internal command pointer points to the first available command slot in the command list. A mechanism exists for reseting the command pointer so that a LIOX handle can be re-filled with a new list of commands.

2.4.1.2.1. Normal Command Items

The following illustrates the queueing of a normal command item.

Calling LIOX_qGCFEread with appropriate arguments would add a GCFE read command to the command list of the LIOX handle. The LIOX handle would update its internal command pointer to point at the next available command slot in the list. An example is shown below:

unsigned int    errVal;
LIOXHandle      lh; /* previously initialized */

/* queue the read command to the command list */
errVal = LIOX_qGCFEread( lh, temId, gcccId, gcrcId, gcfeId, DACregId);

This process is repeated, adding commands to the LIOX handle until the entire command sequence is loaded or the LIOX handle runs out of memory. Next the command list is queued to the LCB for execution.

2.4.1.2.2. Command Fabric Reset

A special command item exists that instructs the LCB to assert the hardware reset line of the command fabric. This resets all the nodes of the command fabric. This command generates a result item that will have the reset field of the error word set.

The fabric reset command must be the only command in the command list – queueing the fabric reset command will erase any previously entered command items in the command list. This is because the fabric reset command is implemented as a null command list of zero length.

2.4.1.2.3. Injected Time Markers

Quoting [huffer1]:

An application may need to specify an arbitrary amount of idle time between two export items, or to inject an accurate time marker in the RESULTS FIFO. Both of these requirements must be satisfied without actually transmitting a packet on a fabric ... A result is generated at a time determined by the stall/timeout field.

Queueing an injected marker command item takes the following form:

The stall/timeout is in units of sysclks, i.e. 50 nano-second increments.

Unlike the fabric reset, multiple markers may be queued per command list.

This command generates a result item when completed.

2.4.1.2.4. Sending Bulk Data on the Event Fabric

While the sending of bulk data occurs on the event fabric, the mechanism for queueing a bulk transfer looks like queueing a command item. Queueing a bulk LCB-to-LCB data transfer takes the following form:

For LCB-to-LCB the MSB of the 6-bit nodeId must be set, i.e. all LCBs have a nodeId with the high-order bit set. LIOX_qBulk() will fail if the nodeId is not of the proper format.

The proto parameter indicates which of the 3 LATp protocols to use.

Multiple bulk transfers may be queued in the same command list.

This command generates a result item when completed.

2.4.1.4.1. Navigating Result Lists

This section assumes that a result list has been successfully dispatched to the user application. Section 2.3 describes how results are dispatched.

The LCBD provides a basic mechanism for walking or iterating over the result list, item by item. The LIOX handle maintains a result pointer (see Figure 2-4) that points to the next available result item.

The LCBD provides the following functions for result list navigation:

The LIOX_nextResultItem() function returns a pointer to the next ResultItem and updates the result pointer for the LIOX. When no more result items exist the functions returns NULL. The LIOX_rewindResults() resets the results pointer to the beginning of the result list.

A user can iterate over a result list as follows:

int myRspCallBack( LIOXHandle lh, void *usrData) {

   int        status = LCB_OK;       
   ResultItem *pItem = NULL;
   
   // process result items
   while ( (pItem = LIOX_nextResultItem( lh))) {
   
       status = processItem( pItem, usrData);
   }

   // At this point it is the user's choice to free the LIOXHandle
   // and associated command list memory and result list memory.
   // You may want to keep it around for later execution.

   return status;
}

In the above example the while loop terminates when LIOX_nextResultItem returns NULL.

2.4.1.4.2. Decoding Result Items

As alluded to earlier two types of result items exist. The two types have some data fields in common while the "response" result type has more information and requires special decoding.

int myRspCallBack( LIOXHandle lh, void *usrData) {

  int                 status = LCB_OK;       
  ResultItem          *pItem = NULL;
  unsigned int        timeStamp;
  unsigned int        errorValue;
  unsigned short int  registerValue;

  /* fetch the first result item from the LIOX handle */
  pItem = LIOX_nextResultItem( lh);

  if ( pItem != NULL) {

    // get the time stamp value
    timeStamp = LIOX_riGetTimestamp( pItem);
  
    // get the error value 
    error = LIOX_riGetError( pItem);
  
    // test if this item has a result payload -- in this contrived
    // example we already know it does have a payload.
    if ( LIOX_riHasPayload( pItem)) {
  
      // By design this item is a 16 bit GCFE register
      registerValue = LIOX_riGetPayload16( pItem);
  
      // do something useful with register value
  
    }
  }

  return status;

}