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

Constituent: lcbd     Tag: linux-gcc

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

LCBD_rst.h File Reference

Defines public aspects of the command/result unit of the LCB driver. More...

#include "LCBD/LCB.h"
#include "PBS/FORK.h"

Include dependency graph for LCBD_rst.h:

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


Data Structures

union  _LCBD_xcb_que
 Union of the possible data structures the LCBD_xcb can be linked to. More...
struct  _LCBD_xcb_sys
 The system portion of the transaction control block. More...
struct  _LCBD_xcb_usr
 The user portion of the XCB. More...
struct  _LCBD_xcb
 The transaction control block. More...
struct  _LCBD_rst_null_cbp
 Binds an null descriptor call back routine with its parameter. More...

Defines

#define LCBD_OK   0
 Success return code, note that this is not an LCBD message code, but may be used as one.
#define LCBD_EXP_DSC_COMPOSE(_cl, _clLen, _lcl2pci)   (((unsigned int)(_cl) + (_lcl2pci)) | (_clLen))
 Composes a command list export descriptor.
#define LCBD_EXP_DSC_REPLACE_LEN(_export, _clLen)   (((_export) & ~(LCB_REQUEST_LIST_ALIGN - 1)) | (_clLen))
 Replaces the length field in the specified export descriptor.
#define LCBD_RST_K_DEFAULT_PRIORITY   -1
 Instructs the result service task creation routine LCBD_rst_handler_create to use a system defined default priority.

Typedefs

typedef _LCBD_xcb LCBD_xcb
 Typedef for struct _LCBD_xcb.
typedef enum _LCBD_SEQ LCBD_SEQ
 Typedef for enum _LCBD_SEQ.
typedef LI_head LCBD_post_head
 Typedef for the type of list head that LCBD_post_remove uses.
typedef enum _LCBD_RST_FATE_M LCBD_RST_FATE_M
 Typedef for enum _LCBD_RST_FATE_M.
typedef unsigned int(* LCBD_rst_cb )(void *prm, LCBD_xcb *xcb)
 Driver supplied callback routine for LCBD result processing.
typedef _LCBD_xcb_que LCBD_xcb_que
 Typedef for union _LCBD_xcb_que.
typedef _LCBD_xcb_sys LCBD_xcb_sys
 Typedef for struct _LCBD_xcb_sys.
typedef _LCBD_xcb_usr LCBD_xcb_usr
 Typedef for struct _LCBD_xcb_usr.
typedef unsigned int(* LCBD_rst_null_cb )(void *prm, LCBD lcb)
 Typedef for LCBD NULL descriptor handling callback routine.
typedef _LCBD_rst_null_cbp LCBD_rst_null_cbp
 Typedef for struct _LCBD_rst_null_cbp.

Enumerations

enum  _LCBD_SEQ {
  LCBD_SEQ_SUCCESS = 0,
  LCBD_SEQ_ORDER = 1,
  LCBD_SEQ_UNKNOWN = 2,
  LCBD_SEQ_EMPTY = 3,
  LCBD_SEQ_CNT = 4
}
 Enumerates the sequencing status of command lists. More...
enum  _LCBD_RST_FATE_M {
  LCBD_RST_FATE_M_NO_MORE = (1 << 0),
  LCBD_RST_FATE_M_NO_REARM = (1 << 1)
}
 Bit masks defining the options available on the return values of the result callback routine. More...

Functions

unsigned int LCBD_rst_handler_create (LCBD lcb, int priority)
 Creates the result service task.
unsigned int LCBD_rst_null_cb_set (LCBD lcb, LCBD_rst_null_cb cb, void *prm)
 Establish callback for handling null result descriptors.
LCBD_rst_null_cbp LCBD_rst_null_cbp_get (LCBD lcb)
 Returns the callback routine for the null result descriptor handler plus its parameter.
unsigned int LCBD_rst_que_install (LCBD lcb, FORK_que *que)
 Installs queue from fcb as the ISR -> task message queue for result traffic.
unsigned int LCBD_rst_rcv_err_map (unsigned int err)
 Maps a receive error to a standard LCB message code.
unsigned int LCBD_rst_xfr_err_map (unsigned int err)
 Maps a generalize result error to a standard LCB message code.
LCBD_cl * LCBD_cl_alloc (unsigned int nbytes)
 Allocates an LCBD command list for the specified number of bytes.
LCBD_rl * LCBD_rl_alloc (unsigned int nbytes)
 Allocates an LCBD result list for the specified number of bytes.
LCBD_cl * LCBD_cl_alloc8 (unsigned int n8bytes)
 Allocates an LCBD command list consisting of n8bytes of command items. This routine adds on any overhead above the command list items.
LCBD_rl * LCBD_rl_alloc8 (unsigned int n8bytes)
 Allocates an LCBD result list consisting of n8bytes of result items. This routine adds on the overhead to the request.
static __inline unsigned short
int 		LCBD__cl_len (unsigned int nbytes)
 Calculates the number of 8-byte cells in the specified number of bytes.
static __inline unsigned short
int 		LCBD__cl_dlen (const void *beg, const void *end)
 Calculates the length, in 8-byte cells, between the specified beginning and ending pointers.
static __inline unsigned short
int 		LCBD__rl_len (unsigned int nbytes)
 Calculates the number of 8-byte cells in the specified number of bytes.
static __inline unsigned short
int 		LCBD__rl_dlen (const void *beg, const void *end)
 Calculates the length, in 8-byte cells, between the specified beginning and ending pointers.
LCBD_xcb * LCBD_bind (const LCBD lcb, unsigned short int clLen, LCBD_cl *cl, unsigned short int rlLen, LCBD_rl *rl, LCBD_rst_cb cb, void *prm, void *user0, void *user1, void *user2, void *user3)
 Binds the XCB with everything needed to submit it to the LCB.
unsigned int LCBD_qioW (LCBD lcb, unsigned short int clLen, LCBD_cl *cl, LCBD_rl *rl)
 A convenience routine to synchronously submit, execute and wait for the completion of the specified command list..
unsigned int LCBD_submit (LCBD_xcb *xcb)
 Submits the command request.
unsigned int LCBD_submitW (LCBD_xcb *xcb)
 Submits the command request and waits for completion.
LCBD_xcb * LCBD_fork_bind (LCBD lcb, unsigned short int clLen, LCBD_cl *cl, unsigned short int rlLen, LCBD_rl *rl, FORK_que *que, FORK_cb_rtn rtn, void *user0, void *user1, void *user2, void *user3)
 Completes a transaction block using the FORK dispatch routines as the synchronization mechanism.
LCBD_xcb * LCBD_post_bind (LCBD lcb, unsigned short int clLen, LCBD_cl *cl, unsigned short int rlLen, LCBD_rl *rl, LCBD_post_head *head, void *user0, void *user1, void *user2, void *user3)
 Completes a transaction block that uses a queue as the synchronization mechanism.
unsigned int LCBD_post_create (LCBD_post_head *head)
 Creates and initializes the head of the list that the LCBD_post routines use.
unsigned int LCBD_post_destroy (LCBD_post_head *head)
 Destroys the head of the list created by LCBD_post_create.
LCBD_xcb * LCBD_post_pendW (LCBD_post_head *head)
 Removes, with a wait, the next XCB posted to the indicated list head.

Detailed Description

Defines public aspects of the command/result unit of the LCB driver.

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

JJRussell -- russell@slac.stanford.edu

  CVS $Id

Overview
This defines the interface to the LCB driver's command/result unit. Unfortunately here the naming convention of prefixing objects (functions, structures, enums, typedefs, #define's) with the file name or some close deriviative breaks down. It breaks down for two reasons
  1. This unit really is composed of two subpieces, the command submission unit and the result processing unit, with a set of objects spanning both subpieces.
  2. Sticking to the naming convention resulted in impossibly long names

Where possible, the naming convention was used.

Define Documentation

#define LCBD_EXP_DSC_COMPOSE (  _cl,
_clLen,
_lcl2pci   )     (((unsigned int)(_cl) + (_lcl2pci)) | (_clLen))
 

Composes a command list export descriptor.

Returns:
The export descriptor as an unsigned 32-bit value
Parameters:
_cl Properly align command list address
_clLen Length of the command list in 8 byte cells
_lcl2pci Address translation value, local CPU address to PCI address
Note:
The _lcl2pci value can be accessed via the LCBD_dib structure. It is permissiable to lookup and cache this value. It is constant throughout the boot of the machine.
Warning:
It is the caller's responsibility to ensure _cl is being properly aligned.

#define LCBD_EXP_DSC_REPLACE_LEN (  _export,
_clLen   )     (((_export) & ~(LCB_REQUEST_LIST_ALIGN - 1)) | (_clLen))
 

Replaces the length field in the specified export descriptor.

Returns:
The modified export descriptor
Parameters:
_export The export descriptor
_clLen Length of the command list in 8 byte cells
aligned.

#define LCBD_RST_K_DEFAULT_PRIORITY   -1
 

Instructs the result service task creation routine LCBD_rst_handler_create to use a system defined default priority.

This value can be used instead of a fixed numerical value to the aforementioned routines so that the tasks are created with default priorities. Note that this is only a flag value and that the default priorities are owned by the LCBD code. This means that if a new version of the driver changes these values, all code using the default values will also change. In many cases, this is exactly the correct behaviour, but in a limited number of cases (peculiar test circumstances), the user may wish tighter control. In these cases, use a fixed numerical value between 0 and 255.

Typedef Documentation

unsigned int(* LCBD_rst_cb)(void *prm, LCBD_xcb *xcb)
 

Driver supplied callback routine for LCBD result processing.

Returns:
A bit list of options enumerated by LCBD_RST_FATE_M
Parameters:
prm Arbitrary User parameter
xcb Pointer to the result IO completion block
Return Options
Normally this routine should return 0, but for testing and debugging purposes, it may return a bit list of the options enumerated in LCBD_RST_FATE_M. The options currently include
  • LCBD_RST_FATE_M_NO_MORE, stop servicing the event que, whether it is empty or not
  • LCBD_RST_FATE_M_NO_REARM, don't rearm the interrupt

Warning:
All standard code should return 0, indicating that processing should continue. The other options are provided only for testing and debugging purposes.
Note:
There is a cute programming trick one can use to gracefully stop the processing on the result que and disable further processing. One can compose a Command List consisting of an beign command (say mark time) which, when it completes, returns the code NO_MORE | NO_REARM.

LCBD_RST_FATE_M
 

Typedef for enum _LCBD_RST_FATE_M.

Usage
The user can control the event processing loop in result handler by specifying the return value as a bit list of the options enumerated here. For the most part, their usage is likely confined to testing and debugging. Normally the result callback should just return 0.

unsigned int(* LCBD_rst_null_cb)(void *prm, LCBD lcb)
 

Typedef for LCBD NULL descriptor handling callback routine.

Returns:
Currently the return value is ignored, so return 0.
Parameters:
prm User provided parameter
lcb The LCBD driver handle

LCBD_SEQ
 

Typedef for enum _LCBD_SEQ.

The LCBD driver keeps track of command list transactions as they are submitted to the hardware. The LCBD driver expects that the hardware maintains a FIFO discipline, that is transaction are retired in the order they are submitted.

LCBD_SEQ enumerates the 3 possible scenerios when a result from the RESULT queue is being processed

  1. The result list is the expected list
  2. The result list is known to the LCBD driver, but it is received out of order
  3. The result list is unknown to the LCBD driver.
  4. The result queue was empty, so there is no way the result list could be found. This is really a variation of the previous, but is special enough that it is tracked separately.

LCBD_xcb
 

Typedef for struct _LCBD_xcb.

Warning:
This structure must be an an integral number of 8-cells in order to preserve the result list's alignment.

LCBD_xcb_que
 

Typedef for union _LCBD_xcb_que.

During its journey through submission to the driver and servicing by result completion handling task, the transaction control block gets posted to a variety of ques. This data structure is a union of all possible such ques. Since at any given time the XCB is on one and only one que, this storage area can be reused by each stage.
Warning:
The storage in these locations should be consider volatile, i.e. the user should not use these locations as permanent store. As the previous paragraph states, these locations may be used by the LCBD driver to maintain linkage information between any of its stages. Consequently, this information may be overwritten.

LCBD_xcb_sys
 

Typedef for struct _LCBD_xcb_sys.

Although, aside from completing the export descriptor, there is nothing terribly difficult in the user filling this area, it is more standard thatone of the bind routines (LCBD_bind, LCBD_post_bind, LCBD_fork_bind) would be used.
To help fill up the export descriptor see LCBD_EXP_DSC_COMPOSE. Note also that the result list address which gets stashed in the first 32 bits of the commmand list must be translated to its equivalent PCI address by adding on the local to PCI address offset found in the LCBD_dib structure. The code LCBD_bind can be used as a template on how to fill LCBD_xcb structure out.
Please do not use the two reserved words. These are there for future expansion.

LCBD_xcb_usr
 

Typedef for struct _LCBD_xcb_usr.

This the more public piece of the XCB, used to pass context from the thread submitting the transaction control block to the thread servicing the result.

Enumeration Type Documentation

enum _LCBD_RST_FATE_M
 

Bit masks defining the options available on the return values of the result callback routine.

See also:
LCBD_evt_cb
Enumerator:
LCBD_RST_FATE_M_NO_MORE  Stop processing transactions
LCBD_RST_FATE_M_NO_REARM  Don't rearm the interrupt

enum _LCBD_SEQ
 

Enumerates the sequencing status of command lists.

Enumerator:
LCBD_SEQ_SUCCESS  Result list expected and found
LCBD_SEQ_ORDER  Result list received out of order
LCBD_SEQ_UNKNOWN  Result list unknown to system
LCBD_SEQ_EMPTY  Result pending que is empty
LCBD_SEQ_CNT  Count of sequence error types

Function Documentation

static __inline unsigned short int LCBD__cl_dlen (  const void *  beg,
const void *  end
)  [static]
 

Calculates the length, in 8-byte cells, between the specified beginning and ending pointers.

Returns:
The length, in 8-byte cells, between the specified beginning and ending pointers
Parameters:
beg A pointer to the beginning of either the command list or the first command item.
end A pointer to (in the usual C fashion) to address one past the last command item (i.e. where the next command item would go if there were one).
Usage
Given the plethera of size units floating around in the LCB, this routine can be used to compute the clLen parameter in the various bind routines, thus ensuring the proper units.
This form of the calculation is useful when one is filling a variable length command list, where one knows the starting point and keeps filling the list by advancing a pointer to the next command item. When the last item is filled, one calculates the pointer to the next (mythical command item) and provides this as the ending address.
Warning:
Note that one can pass either the address of the beginning of the command list or the first command item. Passing the address of the command list will add 4 bytes to the size (the size of the pointer to the result list), but these 4 bytes will be lost when converting the size, in bytes, to the length in 8-byte cells.
Example
     LCBD_rl *rl = LCBD_rl_alloc (4096);
     LCBD_cl *cl = LCBD_cl_alloc (4096);
     LCB_ci  *ci = &cl->ci;
     LCB_ri  *ri = rl->rl.ri;

     ci = LCBC__mark_time_fill     (&ci->mark, 200);
     ri = LCBR__advance            ( ri, sizeof (LCB_ri_mark_time));

     ci = LCBC__csr_access_fill    (&ci->csr,  val, select, timeout);
     ri = LCBR__advance            ( ri, sizeof (LCB_ri_csr));

     ci = LCBC__mark_time_fill     (&ci->mark, 400);
     ri = LCBR__advance            ( ri, sizeof (LCB_ri_mark_time)):

     ci = LCBC__faults_access_fill (&ci->faults,  0, -1, timeout);
     ri = LCBR__advance            ( ri, sizeof (LCB_ri_faults));

     status = LCBD_post_bind (lcb,
                              LCBD_cl_dlen (cl,      ci), cl,
                              LCBD_rl_dlen (&rl->rl, ri), rl,
                              head, 0, 0, 0, 0);

     //.. or
     status = LCBD_post_bind (lcb,
                              LCBD_cl_dlen (&cl.ci,      ci), cl,
                              LCBD_rl_dlen (&rl->rl.ri,  ri), rl,
                              head, 0, 0, 0, 0);
Of course, this is a contrived example, as most are. Since this is all fixed length stuff known at compile time, a better implementation is found in the example in LCBD__cl_len

static __inline unsigned short int LCBD__cl_len (  unsigned int  nbytes  )  [static]
 

Calculates the number of 8-byte cells in the specified number of bytes.

Returns:
The number of 8-byte cells
Parameters:
nbytes The number of bytes to convert to 8-byte cells
Usage
Given the plethera of size units floating around in the LCB, this routine can be used to compute the clLen parameter in the various bind routines, thus ensuring the proper units.
Warning:
Technically the nbytes should represent the length, in bytes, of only the command items. However, since the low three bits are discarded, one could equally as well pass the size of the entire command list, including the pointer to the result list. This would add 4 bytes to the size of the command items, which would promptly be discarded when shifting the number of bytes down by three.

Please absorb the import of the warning above, issued here again, the low three bits are discarded. This routine believes that nbytes represents a legitimate length.

Example
    // Define the command items
    typedef struct _MyCmdItems
    {
       LCB_ci_mark_time mark1;
       LCB_ci_csr         csr;
       LCB_ci_mark_time mark2;
       LCB_ci_faults   faults;
     }
     MyCmdItems;

     // Assemble into a command list
     typedef struct _MyCmdList
     {
        unsigned int *result;
        MyCmdItems        ci;
     }
     MyCmdList;

     // Define the corresponding result items
     typedef struct _MyRstItems
     {
       LCB_ri_mark_time mark1;
       LCB_ri_csr         csr;
       LCB_ci_mark_time mark2;
       LCB_ci_faults   faults;
     }
     MyRstItems;

     // Assemble into a hardward result list
     typedef struct _LcbRstList
     {
       unsigned int *command;
       MyRstItems         ri;
     }
     LcbRstList;

     // Tack on the XCB that the driver needs
     typedef struct MyRstList
     {
       LCBD_xcb    xcb;
       LcbRstList   rl;
     }
     MyRstList;


     MyCmdList *cl = LCBD_cl_alloc (sizeof (MyCmdList);
     MyRstList *rl = LCBD_rl_alloc (sizeof (MyRstList);

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

     xcb = LCBD_post_bind (lcb,
                           LCBD_cl_len (sizeof (*cl)),     cl,
                           LCBD_rl_len (sizeof (&rl->rl)), rl,
                           head, 0, 0, 0, 0);

static __inline unsigned short int LCBD__rl_dlen (  const void *  beg,
const void *  end
)  [static]
 

Calculates the length, in 8-byte cells, between the specified beginning and ending pointers.

Returns:
The length, in 8-byte cells, between the specified beginning and ending pointers
Parameters:
beg A pointer to the beginning of either the result list (make sure it is the start of the hardward result list, not the result list + XCB) or the first result item (the safer, less ambigious thing to use).
end A pointer to (in the usual C fashion) to address one past the last result item (i.e. where the next resultitem would go if there were one).
Usage
This function can be used to fill in the rlLen parameter in the various bind routines. However, truth be told, this value has absolutely no hardware implications; it is merely stored in the XCB for the convenience of the user. In effect, the user is free to store anything that will fit into 16 bits in this value.
This form is most useful when the length result items is being calculated dynamically.
Example
See the example in LCBD_cl_dlen.

static __inline unsigned short int LCBD__rl_len (  unsigned int  nbytes  )  [static]
 

Calculates the number of 8-byte cells in the specified number of bytes.

Returns:
The number of 8-byte cells
Parameters:
nbytes The number of bytes to convert to 8-byte cells
Usage
This function can be used to fill in the rlLen parameter in the various bind routines. However, truth be told, this value has absolutely no hardware implications; it is merely stored in the XCB for the convenience of the user. In effect, the user is free to store anything that will fit into 16 bits in this value.
Example
See the example in LCBD_cl_len.

LCBD_xcb * LCBD_bind (  const LCBD  lcb,
unsigned short int  clLen,
LCBD_cl *  cl,
unsigned short int  rlLen,
LCBD_rl *  rl,
LCBD_rst_cb  cb,
void *  prm,
void *  user0,
void *  user1,
void *  user2,
void *  user3
) 
 

Binds the XCB with everything needed to submit it to the LCB.

Returns:
Pointer to the completely bound transaction control block or NULL upon error.
See also:
LCBD_qioW

LCBD_bind

LCBD_submit

LCBD_submitW

LCBD_bind_post

LCBD_bind_fork

LCBD__cl_len

LCBD__cl_dlen

Parameters:
lcb The LCB driver handle
cl The command list address
clLen The length of the command items in units of 8-byte cells see LCBD__cl_len and LCBD__cl_dlen for help in calculating this value.
rl The address of the result list
rlLen The length of the result items in units of 8-byte cells see LCBD__rl_len and LCBD__rl_dlen for help in calculating this value.
cb The callback routine
prm The callback prameter
user0 User parameter 0
user1 User parameter 1
user2 User parameter 2
user3 User parameter 3
This binds together the following objects
  • A target LCB device
  • A command list
  • A result list
  • Callback + callback parameter
  • User parameters
in a transaction block which can be submitted to for execution by the LCB using LCBD_submit.
Note:
The parameters clLen and rlLen are technically the length, in units of 8-byte cells, of the command items and result items. However, the size of a hardware command list and result list in terms of 8-byte cells, is exactly the same. A word of caution though, pay attention to the words the size of a hardware result list. This means do not include the size of the XCB in this calculation
However, truth be told, this parameter rlLen has absolutely no hardware implications; it is merely stored in the XCB for the convenience of the user. In effect, the user is free to store anything that will fit into 16 bits in this value.

LCBD_cl * LCBD_cl_alloc (  unsigned int  nbytes  ) 
 

Allocates an LCBD command list for the specified number of bytes.

Return values:
Non-NULL,a pointer to the an LCBD_cl
NULL,the allocation failed
Parameters:
nbytes The number of bytes to allocate for the entire list
What's really returned/what's really allocated?
The return value is a pointer to the start of an LCBD_cl structure. Note that while logically speaking, this structure is always an odd number of 4-byte integers, the request size will be honored as is. The caller should include the overhead size of the LCBD_cl (currently none) and the request descriptor in amount.
Where is this useful?
This form of the allocation is most useful when one has a compile time definition of the command list in hand. For example
  typedef struct _RequestCsrStallFaults
  {
    LCB_cl_dsc          dsc; // Result list descriptor
    LCB_ci_csr          csr; // Result item for CSR access
    LCB_ci_mark_time  stall; // Result item a mark time command
    LCB_ci_faults    faults; // Result list for FAULT register access
  }
  RequestCsrStallFaults;

  LCBC_cl = LCBD_cl_alloc (sizeof (RequestCsrStallFaults);

LCBD_cl * LCBD_cl_alloc8 (  unsigned int  n8bytes  ) 
 

Allocates an LCBD command list consisting of n8bytes of command items. This routine adds on any overhead above the command list items.

Return values:
Non-NULL,a pointer to the an LCBD_rl
NULL,the allocation failed
Parameters:
n8bytes The number of 8 byte cells to allocate.for the command items only.
What's really returned/what's really allocated?
The return value is a pointer to the start of an LCBD_cl structure. Currently the only overhead added is for the size of the command list's export descriptor.
Where is this useful?
This form of the routine is most useful in a dynamic programming environment, where one knows that he needs a command list of N 8 byte cells. For example
   LCBD_cl *cl;  // Generic command list
   LCBD_ci *ci;  // Generic command item

   cl = LCBD_cl_alloc8 (n_8byte_cells);  // Need @e n 8 byte cells
   ci = &cl->cl.ci;                      // Locate the first command item
   fill (ci...)                          // Start filling them

LCBD_xcb * LCBD_fork_bind (  LCBD  lcb,
unsigned short int  clLen,
LCBD_cl *  cl,
unsigned short int  rlLen,
LCBD_rl *  rl,
FORK_que *  que,
FORK_cb_rtn  rtn,
void *  user0,
void *  user1,
void *  user2,
void *  user3
) 
 

Completes a transaction block using the FORK dispatch routines as the synchronization mechanism.

Returns:
A pointer to the transaction control block or NULL on error.
See also:
LCBD_bind

LCBD_submit

LCBD_submitW

LCBD_bind_post

LCBD_bind_fork

LCBD__cl_len

LCBD__cl_dlen

Parameters:
lcb Pointer to private LCBD structure
clLen The length of the command list in units of 8-byte cells, see LCBD__cl_len and LCBD__cl_dlen for help in calculating this value.
cl The command list
rlLen The length of the result list in units of 8-byte cells, see LCBD__cl_len and LCBD__cl_dlen for help in calculating this value.
rl The result list
*que The target FORK que
rtn The FORK dispatch routine
user0 User parameter 0
user1 User parameter 1
user2 User parameter 2
user3 User parameter 3
This binds together the following objects
  • A target LCB device
  • A command list
  • A result list
  • A FORK que
  • A FORK Callback + callback parameter
  • User parameters
in a transaction block which can be submitted for execution by the LCB using LCBD_submit. Although the user could do all everything in this routine himself, using this routine provides an easy and consistent method of using a FORK callback routine as the synchronization mechanism.
The message received in the FORK callback routine is essentially the XCB.
Note:
The parameters clLen and rlLen are technically the length, in units of 8-byte cells, of the command items and result items. However, the size of a hardware command list and result list in terms of 8-byte cells, is exactly the same. A word of caution though, pay attention to the words the size of a hardware result list. This means do not include the size of the XCB in this calculation
However, truth be told, this parameter rlLen has absolutely no hardware implications; it is merely stored in the XCB for the convenience of the user. In effect, the user is free to store anything that will fit into 16 bits in this value.

LCBD_xcb * LCBD_post_bind (  LCBD  lcb,
unsigned short int  clLen,
LCBD_cl *  cl,
unsigned short int  rlLen,
LCBD_rl *  rl,
LCBD_post_head *  head,
void *  user0,
void *  user1,
void *  user2,
void *  user3
) 
 

Completes a transaction block that uses a queue as the synchronization mechanism.

Returns:
A pointer to the transaction control block or NULL on error.
See also:
LCBD_qioW

LCBD_bind

LCBD_submit

LCBD_fork_bind

Parameters:
lcb Pointer to private LCBD structure
clLen The length of the command items in units of 8-byte cells
cl The command list
rlLen The length of the result items in units of 8-byte cells
rl The result list
*head The target list head
user0 User parameter 0
user1 User parameter 1
user2 User parameter 2
user3 User parameter 3
This binds together the following objects
  • A target LCB device
  • A command list
  • A result list
  • A LCBD_post_head que
  • User parameters
in a transaction block which can be submitted for execution by the LCB using LCBD_submit. Although the user could do all everything in this routine himself, using this routine provides an easy and consistent method of using a queue as the synchronization mechanism.
The node returned by LCBD_post_pendW is the XCB.
Note:
The parameters clLen and rlLen are technically the length, in units of 8-byte cells, of the command items and result items. However, the size of a hardware command list and result list in terms of 8-byte cells, is exactly the same. A word of caution though, pay attention to the words the size of a hardware result list. This means do not include the size of the XCB in this calculation
However, truth be told, this parameter rlLen has absolutely no hardware implications; it is merely stored in the XCB for the convenience of the user. In effect, the user is free to store anything that will fit into 16 bits in this value.

unsigned int LCBD_post_create (  LCBD_post_head *  head  ) 
 

Creates and initializes the head of the list that the LCBD_post routines use.

Returns:
Status
Parameters:
head The list head to initialize

unsigned int LCBD_post_destroy (  LCBD_post_head *  head  ) 
 

Destroys the head of the list created by LCBD_post_create.

Returns:
Status
Parameters:
head The list head to destroy

LCBD_xcb * LCBD_post_pendW (  LCBD_post_head *  head  ) 
 

Removes, with a wait, the next XCB posted to the indicated list head.

Returns:
Pointer to the removed XCB
Parameters:
head The list head to remove from

unsigned int LCBD_qioW (  LCBD  lcb,
unsigned short int  clLen,
LCBD_cl *  cl,
LCBD_rl *  rl
) 
 

A convenience routine to synchronously submit, execute and wait for the completion of the specified command list..

Returns:
The status of the IO portion of the operation. The user is obligated to check the result descriptor and the result list just as if one of the asynchronous submission methods had been used.
Return values:
LCBD_CLTOOBIG,the command/request list was too big for the LCB too handle
LCBD_CLMISALN,the command/request list was not properly aligned.
See also:
LCBD_bind

LCBD_submit

LCBD_submitW

LCBD_bind_post

LCBD_bind_fork

LCBD__cl_len

LCBD__cl_dlen

Parameters:
lcb Pointer to private LCBD structure
clLen The length of the command items in units of 8-byte cells see LCBD__cl_len and LCBD__cl_dlen for help in calculating this value.
cl The command list
rl The result list
Because this is a synchronous operation, many of the parameters associated with controlling the asychronous aspects are unnecessary. Note that the list of unnecessary parameters includes the length of the result list.

Note:
Technically the parameter clLen is the length of only the command items in the command list. However, the length of the command list, in terms of 8-byte cells, and the command items, in terms of 8-byte cells, is exactly the same.
Warning:
In this case, the user portion of the XCB is not filled in. In the synchronous case, the caller knows all this information already, so there is no need to pass this trhough to the result handler.

LCBD_rl * LCBD_rl_alloc (  unsigned int  nbytes  ) 
 

Allocates an LCBD result list for the specified number of bytes.

Return values:
Non-NULL,a pointer to the an LCBD_rl
NULL,the allocation failed
Parameters:
nbytes The number of bytes to allocate for the entire list
The return value is a pointer to the start of an LCBD_rl structure. Note that while logically speaking, this structure is always an odd number of 4-byte integers, the request will be honored as is. The caller should include the overhead size of the LCBD_xcb and the request descriptor in amount.
This form of the allocation is most useful when one has a compile time definition of the result list in hand. For example
   typedef struct _ResultCsrStallFaults
   {
     LCBD_xcb            xcb; // Include the transaction control block
     LCB_rl_hdr          hdr; // Result list header
     LCB_ri_csr          csr; // Result item for CSR access
     LCB_ri_mark_time  stall; // Result item a mark time command
     LCB_ri_faults    faults; // Result list for FAULT register access
   }
   ResultCsrStallFaults;

   LCBC_rl *rl = LCBD_rl_alloc (sizeof (ResultCsrStallFaults);

LCBD_rl * LCBD_rl_alloc8 (  unsigned int  n8bytes  ) 
 

Allocates an LCBD result list consisting of n8bytes of result items. This routine adds on the overhead to the request.

Return values:
Non-NULL,a pointer to the an LCBD_rl
NULL,the allocation failed
Parameters:
n8bytes The number of 8 byte cells to allocate.for the result items only.
What's really returned/what's really allocated?
The return value is a pointer to the start of an LCBD_rl structure. The overhead for LCBD_xcb plus size of the command list's export descriptor is added to the request size.
Where is this useful?
This form of the routine is most useful in a dynamic programming environment, where one knows that he needs a result list of N 8 byte cells. For example
   LCBD_cl *rl;  // Generic command list
   LCBD_ci *ri;  // Generic command item

   rl = LCBD_rl_alloc8 (n_8byte_cells);  // Need @e n 8 byte cells
   ri = &rl->rl.ri;                      // Locate the first command item
   fill (ci...)                          // Start filling them

unsigned int LCBD_rst_handler_create (  LCBD  lcb,
int  priority
) 
 

Creates the result service task.

Returns:
Status
Parameters:
lcb The LCBD driver handle
priority The priority of the task. If specified as 0, a default value is used.

unsigned int LCBD_rst_null_cb_set (  LCBD  lcb,
LCBD_rst_null_cb  cb,
void *  prm
) 
 

Establish callback for handling null result descriptors.

Return values:
LCBD_OK 
Parameters:
lcb The LCB driver handle
cb The LCB null result descriptor handler
prm The LCB null result descriptor parameter

LCBD_rst_null_cbp LCBD_rst_null_cbp_get (  LCBD  lcb  ) 
 

Returns the callback routine for the null result descriptor handler plus its parameter.

Returns:
The callback routine plus it parameter
Parameters:
lcb The LCB driver handle

unsigned int LCBD_rst_que_install (  LCBD  lcb,
FORK_que *  que
) 
 

Installs queue from fcb as the ISR -> task message queue for result traffic.

Parameters:
lcb Pointer to private LCBD structure
que The FORK que to use
Return values:
LCBD_OK,on success; currently there is no failure mode
Example
  TASK_attr attributes;


  // Fill out the task attribute information
  attributes.options    = 0;
  attributes.stack_addr = 0;
  attributes.stack_size = 0;
  attributes.name       = "tLCBDresult";
  attributes.priority   = 60;


  // Allocate enough memory to support the FORK task
  fcb  = (FORK_fcb *)MBA_alloc(FORK_fcb_sizeof(1));


  // Create FORK queue
  status = FORK_create(fcb,            // fork control block
                       &attributes,    // use task attributes
                       NULL,           // default callback
                       lcb,            // callback parm
                       NULL,           // timeout callback parm
                       TOC_FOREVER,    // timeout
                       1,              // define a single que
                       NULL,           // No queue configuration
                       0,              // No system messages
                       NULL,           // No system messages
                       0);             // No system messages


  // Locate the que to use and install it
  que    = FORK_que_get (0);
  status = LCBD_rst_que_install (lcb, que);

unsigned int LCBD_rst_rcv_err_map (  unsigned int  err  ) 
 

Maps a receive error to a standard LCB message code.

Returns:
The LCB message code
Parameters:
err The receive error to map
For result items, the error code is defined as a 16-bit value, although only 3-bits currently have definitions. If the error code received falls outside this range, it is mapped to LCBD_RUNDX.

unsigned int LCBD_rst_xfr_err_map (  unsigned int  err  ) 
 

Maps a generalize result error to a standard LCB message code.

Returns:
The LCB message code
Parameters:
err The result transfer error code.
The generalized result transfer error code consists of the 1-bit direction flag and the 3-bit error code found in the result descriptor. This value is returned to the user in the result callback routine.

unsigned int LCBD_submit (  LCBD_xcb *  xcb  ) 
 

Submits the command request.

Returns:
Status
Parameters:
xcb The completely bound transaction control block

unsigned int LCBD_submitW (  LCBD_xcb *  xcb  ) 
 

Submits the command request and waits for completion.

Returns:
Status
Parameters:
xcb The completely bound transaction control block
This is a convenience routine to execute the specified transaction block in a synchronous fashion.
Note:
The result callback routine and callback parameters in the xcb are saved and restored by this routine, so it is safe to execute a transaction block using this routine without destroying the original context.

Generated on Tue Dec 13 21:16:33 2005 by  doxygen 1.4.4