Doxygen Page for LCBD / V1-5-0 / lcbd / rad750

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


Classes
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_CL_ALIGN LCB_COMMAND_LIST_ALIGN
	Necessary byte alignment for a command list. See Command and Result Lists, General Principles.
#define	LCBD_CL_PAD LCB_COMMAND_LIST_PAD
	The size of the padding, in bytes, needed to ensure that command list is protected against CPU accesses during the DMA operation. See Command and Result Lists, General Principles.
#define	LCBD_CL_SIZE(_nbytes) (LCBD_RNDDOWN_TO_CACHELINE (_nbytes) + LCBD_CL_PAD)
	Computes the number of bytes needed to properly pad a command list of _nbytes to protect against CPU memory accesses while the DMA transfer is in progress. See Command and Result Lists, General Principles.
#define	LCBD_RL_ALIGN LCB_RESULT_LIST_ALIGN
	Necessary byte alignment for a result list See Command and Result Lists, General Principles.
#define	LCBD_RL_MIN (LCB_RESULT_LIST_MIN + sizeof (LCBD_xcb))
	The minimum size, in bytes, needed to ensure that result list is protected against CPU accesses during the DMA operation. See Command and Result Lists, General Principles.
#define	LCBD_RL_SIZE(_nbytes)
	Computes the number of bytes needed to properly pad a result list of _nbytes to provide protected against CPU memory accesses while the DMA transfer is in progress. See Command and Result Lists, General Principles.
#define	LCBD_RNDDOWN_TO_CACHELINE(_nbytes)
	Utility macro used to round _nbytes down to the nearest multiple of a cache line.
#define	LCBD_RNDUP_TO_CACHELINE(_nbytes)
	Utility macro used to round _nbytes up to the nearest multiple of a cache line.
#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 struct _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 union _LCBD_xcb_que	LCBD_xcb_que
	Typedef for union _LCBD_xcb_que.
typedef struct _LCBD_xcb_sys	LCBD_xcb_sys
	Typedef for struct _LCBD_xcb_sys.
typedef struct _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 struct _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 a DMA-safe LCBD command list for the specified number of bytes. See Command and Result Lists, General Principles.
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.
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_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_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_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_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.
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.
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.
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.
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

Define Documentation

#define LCBD_CL_SIZE ( _nbytes ) (LCBD_RNDDOWN_TO_CACHELINE (_nbytes) + LCBD_CL_PAD)

Computes the number of bytes needed to properly pad a command list of _nbytes to protect against CPU memory accesses while the DMA transfer is in progress. See Command and Result Lists, General Principles.

Returns:: The number of bytes needed to ensure a fully protected command list

Parameters:

_nbytes

The actual number of bytes in the command list

: This macro should only be used if the size of the command list needs to be known at compile-time. If this is not the case, the routine LCBD_cl_size provides the same functionality, without incorporating the actual calculation into user code. Given that the proper way to compute the size of a command list has been through 3 iterations since inception, users of this routine will be protected against future changes.

#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. This may be achieved by either doing the allocation with

LCBD_cl_alloc (nbytes) or
MBA_align (LCBD_CL_ALIGN, nbytes);

#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_RL_MIN (LCB_RESULT_LIST_MIN + sizeof (LCBD_xcb))

The minimum size, in bytes, needed to ensure that result list is protected against CPU accesses during the DMA operation. See Command and Result Lists, General Principles.

Note:: Since all properly formed LCBD result lists are prefaced by a LCBD_xcb, this minimum value includes the size of a LCBD_xcb.

#define LCBD_RL_SIZE ( _nbytes )

Value:

({                                          \
                                int n =_nbytes;                           \
                                n = (n < LCBD_RL_MIN)                     \
                                  ?  LCBD_RL_MIN                          \
                                  :  LCBD_RNDUP_TO_CACHELINE (n);         \
                               })

Computes the number of bytes needed to properly pad a result list of _nbytes to provide protected against CPU memory accesses while the DMA transfer is in progress. See Command and Result Lists, General Principles.

Returns:: The number of bytes needed to ensure a fully protected result list

Parameters:

_nbytes

The actual number of bytes in the result list. Note that since all properly formed LCBD result lists are prefaced by an LCBD_xcb, the number of bytes is passed in is assumed to include the LCBD_xcb.

: This macro should only be used if the size of the result list needs to be known at compile-time. If this is not the case, the routine LCBD_rl_size provides the same functionality, without incorporating the actual calculation into user code. Given that the proper way to compute the size of a result list has been through 3 iterations since inception, users of this routine will be protected against future changes.

#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

The result list is the expected list
The result list is known to the LCBD driver, but it is received out of order
The result list is unknown to the LCBD driver.
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
     {
        LCB_cl           hdr;
        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 _MyRstList
     {
       unsigned int *command;
       MyRstItems         ri;
     }
     MyRstList;

     // Tack on the XCB that the driver needs
     typedef struct MyRstList
     {
       LCBD_xcb    xcb;
       MyRstList    rl;
     }
     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_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 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));

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

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

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.

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.

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:

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

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

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

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

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.

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.

LCBD_rst.h File Reference

Classes

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation