GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> LCBD / dev > lcbd / rad750

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » DRV » source » LCBD » dev » src

LCBD_rst.c File Reference

Implements the LCB command/result unit routines. More...

#include <LCBD/LCBD_rst.h>
#include <LCBD/LCBD_cr.h>
#include <LCBD_p.h>
#include <LCBD/LCBD_msgs.h>
#include <PBS/L.ih>
#include <PBS/LI.ih>
#include <PBS/RW.ih>
#include <PBS/MBA.h>
#include <PBS/INT.ih>

Classes

struct  _LCBD_rst_err_maps
 Maps to take a result transfer/receive error/status value, into a standard message code. More...

Typedefs

typedef struct _LCBD_rst_err_maps LCBD_rst_err_maps
 Typedef for struct _LCBD_rst_err_maps.

Functions

static unsigned int fork (void *que, LCBD_xcb *xcb)
 Simple dispatch routine to use a FORK to a user callback.
static unsigned int post (void *head, LCBD_xcb *xcb)
 Simple dispatch routine to post a result.
static unsigned int wake (TASK_block_handle tbh, LCBD_xcb *xcb)
 Simple synchronization callback.
static unsigned int retire (LCBD_rst_ccb *ccb, LCBD_xcb *xcb)
 Returns the LCB request descriptor FIFO resource.
static int submit (LCBD lcb, LCBD_xcb *xcb)
 Attempts to gain access to the LCB request descriptor FIFO and submit the command request.
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.
FORK_que * LCBD_rst_que_get (LCBD lcb, int que_id)
 Returns a pointer to the result FORK que. This allows outside code to schedule work that is serialized with the event taking.
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.
__inline unsigned short int LCBD_cl_size (unsigned int nbytes)
 Computes the size needed for a command list of nbytes to protect it from the bridge chip hangs. See Command and Result Lists, General Principles.
__inline unsigned short int LCBD_rl_size (unsigned int nbytes)
 Computes the size needed for a result list of nbytes to protect it from the bridge chip hangs. See Command and Result Lists, General Principles.
__inline LCBD_cl * LCBD_cl_alloc (unsigned int nbytes)
 Allocates a DMA-safe LCBD command list for the specified number of bytes. See Command and Result Lists, General Principles.
__inline LCBD_cl * LCBD_cl_alloc_unprotected (unsigned int nbytes)
 Allocates a correctly aligned but minimally-sized LCBD command list for the specified number of bytes. See Command and Result Lists, General Principles.
LCBD_cl * LCBD_cl_alloc8 (unsigned int n8bytes)
 Allocates a DMA-safe LCBD command list consisting of n8bytes of command items. See Command and Result Lists, General Principles.
LCBD_cl * LCBD_cl_alloc8_unprotected (unsigned int n8bytes)
 Allocates a correctly aligned but minimally-sized LCBD command list for the specified number of n8bytes command items. See Command and Result Lists, General Principles.
__inline LCBD_rl * LCBD_rl_alloc (unsigned int nbytes)
 Allocates a DMA-safe LCBD result list for the specified number of bytes. See Command and Result Lists, General Principles.
__inline LCBD_rl * LCBD_rl_alloc_unprotected (unsigned int nbytes)
 Allocates a correctly aligned but minimally-sized LCBD result list for the specified number of bytes. See Command and Result Lists, General Principles.
LCBD_rl * LCBD_rl_alloc8 (unsigned int n8bytes)
 Allocates a DMA-safe LCBD result list consisting of n8bytes of result items. See Command and Result Lists, General Principles.
LCBD_rl * LCBD_rl_alloc8_unprotected (unsigned int n8bytes)
 Allocates a correctly aligned but minimally-sized LCBD result list for the specified number of n8byte result items. See Command and Result Lists, General Principles.
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.
static __inline LCBD_xcb * locate (unsigned int *rl)
 Given a result/response descriptor, locates the command request handle.
FORK_cb_status lcbd_rst_handler (FORK_cb_prm parameter, FORK_msg_hdr *fork_msg)
 The main LCBD descriptor dispatching routine.
FORK_cb_status lcbd_rst_flush_handler (FORK_cb_prm parameter, FORK_msg_hdr *fork_msg)
 The main LCBD descriptor dispatching routine.

Variables

static const LCBD_rst_err_maps LCBD_Rst_Err_Maps
 Realization of the LCB result error to message code mapping arrays.

Detailed Description

Implements the LCB command/result unit routines.

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

JJRussell -- russell@slac.stanford.edu 

  CVS $Id
This file implements routines for handling the traffic on the result fabric. As we did with the evt routines, both Curt and I struggled over what to name these routines. It would be nice to prefix them all with LCBD_rst, but the names started getting obscenely long. So the decision was a compromise.

Function Documentation

static unsigned int fork ( void *  que,
LCBD_xcb *  xcb 
) [static]

Simple dispatch routine to use a FORK to a user callback.

Return values:
0,indicating to the dispatcher to continue processing
Parameters:
que The FORK que to post to
xcb Pointer to the transaction control block
The fork message the LCBD_xcb

References _LCBD_xcb_que::msg, _LCBD_xcb::que, _LCBD_xcb_sys::rsvd, and _LCBD_xcb::sys.

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.

References _LCBD_xcb_usr::cl, _LCBD_xcb_usr::clLen, _LCBD_xcb_sys::export, _LCBD_xcb_sys::lcb, LCB_REQUEST_LIST_ALIGN, LCB_REQUEST_LIST_MAX, LCBD_EXP_DSC_COMPOSE, _LCBD_xcb_sys::prm, _LCBD_rl::rl, _LCBD_xcb_usr::rl, _LCBD_xcb_usr::rlLen, _LCBD_xcb_sys::rtn, _LCBD_xcb::sys, _LCBD_xcb_usr::user, _LCBD_xcb::usr, and _LCBD_rl::xcb.

Referenced by LCBD_fork_bind(), and LCBD_post_bind().

__inline LCBD_cl* LCBD_cl_alloc ( unsigned int  nbytes  ) 

Allocates a DMA-safe LCBD command list for the specified number of bytes. See Command and Result Lists, General Principles.

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. The caller should include the overhead size of the LCBD_cl (currently none) and the request descriptor in the amount. The allocation size is padded to avoid the RAD750s bridge chip hang. See Command and Result Lists, General Principles.
When not to use it
If, because of specialized knowledge of your code, you know that the CPU will not be referencing the memory within the pad area during the time the command list is being DMA'ed into the LCB. For example, if its result list is allocated immediately after the command list, there is no reason to pad the command list, since there is no reason why that vulnerable memory being occupied by the result list would be accessed until after the DMA completes. In this case, LCBD_cl_alloc_unprotected may be more appropriate.
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_hdr          hdr; // Command list header
    LCB_ci_csr          csr; // Command item for CSR access
    LCB_ci_mark_time  stall; // Command item a mark time command
    LCB_ci_faults    faults; // Command item for FAULT register access
  }
  RequestCsrStallFaults;

  LCBD_cl *cl = LCBD_cl_alloc (sizeof (RequestCsrStallFaults));

References LCBD_CL_ALIGN, and LCBD_cl_size().

Referenced by LCBD_cl_alloc8().

LCBD_cl* LCBD_cl_alloc8 ( unsigned int  n8bytes  ) 

Allocates a DMA-safe LCBD command list consisting of n8bytes of command items. See Command and Result Lists, General Principles.

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. The size is increased by of the size of a command list export descriptor plus the necessary padding to avoid the bridge chip hang problem. See Command and Result Lists, General Principles.
When not to use it
If, because of specialized knowledge of your code, you know that the CPU will not be referencing the memory within the pad area during the time the command list is being DMA'ed into the LCB. For example, if its result list is allocated immediately after the command list, there is no reason to pad the command list, since there is no reason why that vulnerable memory being occupied by the result list would be accessed until after the DMA completes. In this case, LCBD_cl_alloc8_unprotected may be more appropriate.
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
   LCB_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

References LCBD_cl_alloc().

LCBD_cl* LCBD_cl_alloc8_unprotected ( unsigned int  n8bytes  ) 

Allocates a correctly aligned but minimally-sized LCBD command list for the specified number of n8bytes command items. See Command and Result Lists, General Principles.

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.
Warning:
If the user wishes a DMA safe allocation use LCBD_cl_alloc8

References LCBD_cl_alloc_unprotected().

__inline LCBD_cl* LCBD_cl_alloc_unprotected ( unsigned int  nbytes  ) 

Allocates a correctly aligned but minimally-sized LCBD command list for the specified number of bytes. See Command and Result Lists, General Principles.

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
This routine applies the minimum number of rules necessary to allocate a valid LCBD_cl structure. In particular, only the memory alignment requirement is satisfied. The padding, necessary to protect the structure from CPU accesses during the time it is DMA'd into the LCB is not provided. The user assumes the responsibility of ensuring that no code touches this memory during the DMA operation. For example, if the result list associated with this command list is allocated in this memory, there would be not reason for the CPU to be accessing this memory during the DMA operation. See Command and Result Lists, General Principles.
If the user wishes to have a DMA-safe buffer allocated, use the routine LCBD_cl_alloc.

References LCBD_CL_ALIGN.

Referenced by LCBD_cl_alloc8_unprotected().

__inline unsigned short int LCBD_cl_size ( unsigned int  nbytes  ) 

Computes the size needed for a command list of nbytes to protect it from the bridge chip hangs. See Command and Result Lists, General Principles.

Returns:
The inflated safe size.
Parameters:
nbytes The active size, in bytes, of the command list.

References LCBD_CL_SIZE.

Referenced by LCBD_cl_alloc().

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.

References fork(), LCBD_bind(), _LCBD_xcb_sys::rsvd, _LCBD_xcb::sys, and _LCBD_rl::xcb.

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.

References LCBD_bind(), and post().

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.

References _LCBD_xcb_sys::export, _LCBD_xcb_sys::lcb, LCB_REQUEST_LIST_ALIGN, LCB_REQUEST_LIST_MAX, LCBD_submit(), _LCBD_xcb_sys::prm, _LCBD_rl::rl, _LCBD_xcb_sys::rtn, _LCBD_xcb::sys, wake(), and _LCBD_rl::xcb.

Referenced by LCBC_cmd_xmit(), and LCBC_cmdr_xmit().

__inline LCBD_rl* LCBD_rl_alloc ( unsigned int  nbytes  ) 

Allocates a DMA-safe LCBD result list for the specified number of bytes. See Command and Result Lists, General Principles.

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 the amount. The overall request is always padded by the necessary number of bytes to protect the structure from the bridge-chip hang problem. See Command and Result Lists, General Principles.
When not to use it
If, because of specialized knowledge of your code, you know that the CPU will not be referencing the memory within the pad area during the time the result list is being DMA'ed into the LCB. For example, if its command list is allocated immediately after the result list, there is no reason to pad the result list, since there is no reason why that vulnerable memory being occupied by the command list would be accessed until after the DMA completes. In this case, LCBD_rl_alloc_unprotected may be more appropriate.
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);

References LCBD_RL_ALIGN, and LCBD_rl_size().

Referenced by LCBD_rl_alloc8().

LCBD_rl* LCBD_rl_alloc8 ( unsigned int  n8bytes  ) 

Allocates a DMA-safe LCBD result list consisting of n8bytes of result items. See Command and Result Lists, General Principles.

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. The overall request is always padded by the necessary number of bytes to protect the structure from the bridge-chip hang problem. See Command and Result Lists, General Principles.
When not to use it
If, because of specialized knowledge of your code, you know that the CPU will not be referencing the memory within the pad area during the time the result list is being DMA'ed into the LCB. For example, if its command list is allocated immediately after the result list, there is no reason to pad the result list, since there is no reason why that vulnerable memory being occupied by the command list would be accessed until after the DMA completes. In this case, LCBD_rl_alloc8_unprotected may be more appropriate.
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_rl *rl;  // Generic result list
   LCB_ri  *ri;  // Generic result item

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

References LCBD_rl_alloc().

LCBD_rl* LCBD_rl_alloc8_unprotected ( unsigned int  n8bytes  ) 

Allocates a correctly aligned but minimally-sized LCBD result list for the specified number of n8byte result items. See Command and Result Lists, General Principles.

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.
Warning:
If the user wishes a DMA safe allocation, use LCBD_rl_alloc8

References LCBD_rl_alloc_unprotected().

__inline LCBD_rl* LCBD_rl_alloc_unprotected ( unsigned int  nbytes  ) 

Allocates a correctly aligned but minimally-sized LCBD result list for the specified number of bytes. See Command and Result Lists, General Principles.

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
Warning:
If the user wishes a DMA safe allocation, use LCBD_rl_alloc

References LCBD_RL_ALIGN.

Referenced by LCBD_rl_alloc8_unprotected().

__inline unsigned short int LCBD_rl_size ( unsigned int  nbytes  ) 

Computes the size needed for a result list of nbytes to protect it from the bridge chip hangs. See Command and Result Lists, General Principles.

Returns:
The inflated safe size.
Parameters:
nbytes The active size, in bytes, of the result list.

References LCBD_RL_SIZE.

Referenced by LCBD_rl_alloc().

FORK_cb_status lcbd_rst_flush_handler ( FORK_cb_prm  parameter,
FORK_msg_hdr *  fork_msg 
)

The main LCBD descriptor dispatching routine.

Parameters:
parameter lcb Pointer to private LCBD structure
fork_msg FORK system message
Returns:
FORK_C_CONTINUE This routine is the result flushing service. This routine gets called back in the context of the result handling task. When the driver goes offline, a message is queued to this routine containing a list head of all the transaction to dismiss.

References LCB_RST_ERR_XFR_IN_UNDEFINED_7, _LCBD_xcb_sys::prm, _LCBD_xcb_usr::rd, _LCBD_xcb_sys::rtn, _LCBD_xcb::sys, _LCB_rst_dsc::ui, and _LCBD_xcb::usr.

Referenced by handle_clks().

FORK_cb_status lcbd_rst_handler ( FORK_cb_prm  parameter,
FORK_msg_hdr *  fork_msg 
)

The main LCBD descriptor dispatching routine.

Parameters:
parameter lcb Pointer to private LCBD structure
fork_msg FORK system message
Returns:
FORK_C_CONTINUE This routine is the result queue servicing task, where the real work of reading the LCB RESULT Q and dispatching of descriptors is done.
The msg parameter could be use to indicate who "tickled" the processing. The usual suspects are the ISR or a user.

References _LCB_rst_dsc::bf, _LCB_rst_dsc::bfd, _LCBD_rst_ucb::ccb, _LCBD_stats_rst::cnts, _LCB_rst_dsc_bfd::dir, _LCB_prb::irq, LCB_PCI_IRQ_M_ENABLE_RESULT, LCB_RST_DSC_M_ADR, LCB_RST_ERR_XFR_OUT_Q_EMPTY, LCBD__pciLoad32(), LCBD__pciStore32(), LCBD_RST_FATE_M_NO_MORE, LCBD_RST_FATE_M_NO_REARM, locate(), msr_clr(), msr_get(), msr_put(), _LCBD_rst_ucb::null, _LCBD_stats_rst::null, _LCBD_xcb_sys::prm, _LCBD_rst_null_cbp::prm, _LCBD_xcb_usr::rd, _LCBD_rst_msg::rd, _LCB_prb::result_queue, retire(), _LCBD_xcb_sys::rtn, _LCBD_rst_null_cbp::rtn, _LCBD_stats_rst::seq, _LCBD_xcb::sys, _LCB_rst_dsc::ui, _LCBD_xcb::usr, and _LCB_rst_dsc_bf::xstatus.

Referenced by lcbd_isr().

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.

References lcbd_create_handler(), and LCBD_RST_K_DEFAULT_PRIORITY.

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

FORK_que * LCBD_rst_que_get ( LCBD  lcb,
int  que_id 
)

Returns a pointer to the result FORK que. This allows outside code to schedule work that is serialized with the event taking.

Parameters:
lcb Pointer to private LCBD structure
que_id The ID of the que to get. Currently LCBD is configured with only one que (que_id = 0), but a future enhancement may allow LCBD to be configured with a priority que.
Returns:
On success. a pointer to the result FORK que. This will be NULL if the FORK que has not yet been installed.
It is unlikely that this function is useful for anything but testing, but, for symmetry reasons (the event side has a similar function), it has been included.

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

References LCBD_OK.

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.

References _LCBD_rst_err_maps::rcv.

Referenced by check(), LCBC_cmd_xmit(), and LCBC_cmdr_xmit().

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.

References _LCBD_rst_err_maps::xfr.

Referenced by check().

unsigned int LCBD_submit ( LCBD_xcb *  xcb  ) 

Submits the command request.

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

References _LCBD_xcb_sys::lcb, LCBD_OK, LCBD_STATE_ONLINE, LCBD_STATS_RST_TX_PENDED, LCBD_STATS_RST_TX_POSTED, _LCBD_xcb_que::node, _LCBD_xcb::que, submit(), and _LCBD_xcb::sys.

Referenced by LCBD_qioW(), and LCBD_submitW().

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.

References LCBD_submit(), _LCBD_xcb_sys::prm, _LCBD_xcb_sys::rtn, _LCBD_xcb::sys, and wake().

LCBD_xcb * locate ( unsigned int *  rl  )  [static]

Given a result/response descriptor, locates the command request handle.

Returns:
Pointer to the transaction control block
Parameters:
rl Pointer to the result list

Referenced by lcbd_rst_handler().

static unsigned int post ( void *  head,
LCBD_xcb *  xcb 
) [static]

Simple dispatch routine to post a result.

Return values:
0,indicating to the dispatcher to continue processing
Parameters:
head The head of the list to post to
xcb Pointer to the transaction control block
Routine to post a completed transaction control block to a list head. The user should remove thest using LCBD_post_pendW using head as the list head.

References _LCBD_xcb_que::node, and _LCBD_xcb::que.

static unsigned int retire ( LCBD_rst_ccb *  ccb,
LCBD_xcb *  xcb 
) [static]

Returns the LCB request descriptor FIFO resource.

Parameters:
ccb The LCB command control structure
xcb The result descriptor to retire
Return values:
LCBD_SEQ_SUCCESS << 2, if successfully retired
LCBD_SEQ_ORDER << 2, if mismatch in what was expected to be retired and what is being retired.
LCBD_SEQ_UNKNOWN,<< 2 unknown transaction found
This routine is executed in an interlocked context. After the descriptor is retired, the queue of pending requests is probed. If there is one on the queue, an attempt is made to submit it to the hardware. If the attempt is successful, this process is repeated.

References _LCBD_xcb_sys::lcb, LCBD_OK, LCBD_SEQ_EMPTY, LCBD_SEQ_ORDER, LCBD_SEQ_SUCCESS, LCBD_SEQ_UNKNOWN, LCBD_STATE_ONLINE, LCBD_STATS_RST_TX_REMOVED, _LCBD_xcb_que::node, _LCBD_rst_ccb::pend, _LCBD_rst_ccb::post, post(), _LCBD_xcb::que, _LCBD_rst_ccb::reqCnt, _LCBD_rst_ccb::rw, submit(), and _LCBD_xcb::sys.

Referenced by lcbd_rst_handler().

static int submit ( LCBD  lcb,
LCBD_xcb *  xcb 
) [static]

Attempts to gain access to the LCB request descriptor FIFO and submit the command request.

Return values:
LCBD_OK,For success
-1,If the driver fails to que because the LCB hardware is fully queued.
Parameters:
lcb The LCBD control structure
xcb The transaction control block
Initiating a cmd/rsp request requires that two conditions be met:

  1. The total of current outstanding requests is less than 2.
  2. The total of current outstanding request bytes is less than 4KB.

This routine must be called in an interlocked context.

References _LCBD_xcb_sys::export, LCB_REQUEST_QUEUE_FULL, LCBD__pciLoad32(), LCBD__pciSynchStore32(), and _LCBD_xcb::sys.

static unsigned int wake ( TASK_block_handle  tbh,
LCBD_xcb *  xcb 
) [static]

Simple synchronization callback.

Return values:
Means continue processing
Parameters:
tbh The task blocking handle
xcb The completed transaction control block

Generated on Thu Mar 24 19:09:41 2011 by  doxygen 1.5.8