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

Constituent: lcbd     Tag: sun-gcc

Interface   Data Structures   File List   Data Fields   Globals  

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"

Include dependency graph for LCBD_rst.c:

Include dependency graph

Data Structures

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


Typedefs

typedef _LCBD_rst_err_maps LCBD_rst_err_maps
 Typedef for struct _LCBD_rst_err_maps.


Functions

unsigned int fork (void *que, LCBD_xcb *xcb)
 Simple dispatch routine to use a FORK to a user callback.

unsigned int post (void *head, LCBD_xcb *xcb)
 Simple dispatch routine to post a result.

unsigned int wake (TASK_block_handle tbh, LCBD_xcb *xcb)
 Simple synchronization callback.

unsigned int retire (LCBD_rst_ccb *ccb, LCBD_xcb *xcb)
 Returns the LCB request descriptor FIFO resource.

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.

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_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_alloc (unsigned int nbytes)
 Allocates an LCBD result list for the specified number of bytes.

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.

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.

__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

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

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

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

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.

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

Here is the call graph for this function:

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.

Here is the call graph for this function:

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

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.

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.

Here is the call graph for this function:

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.

Here is the call graph for this function:

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 Fri Sep 30 21:03:48 2005 by doxygen 1.3.3