list.h File Reference

Routines for the sizing and allocation of command and homogeneous (all items the same size) result lists. More...

#include <LEM/list_macros.h>

Functions
size_t	LEM_sizeofCmdList (unsigned nItems)
	Get the size of a command list.
size_t	LEM_sizeofRspList (unsigned nItems)
	Get the size of a read result list.
size_t	LEM_sizeofRsplsList (unsigned nItems)
	Get the size of a load result list.
size_t	LEM_sizeofDcdList (unsigned nItems)
	Get the size of a decode list.
void *	LEM_allocCmdList (unsigned nItems)
	Allocate a command list.
void *	LEM_allocRspList (unsigned nItems)
	Allocate a read result list.
void *	LEM_allocRsplsList (unsigned nItems)
	Allocate a load result list.
void *	LEM_allocDcdList (unsigned nItems)
	Allocate a decode list.
void	LEM_initCmdRsp (LEM_micr *cr, unsigned nItems, void *cmdList, void *rspList, void *dcdList)
	Initialize a command/result block.
unsigned	LEM_allocCmdRsp (LEM_micr *cr, unsigned nItems)
	Allocate a complete set of command/result lists.
unsigned	LEM_setupCmdRsp (LEM_micr *cr, void *lists, int lsize)
	Set up a complete set of command/result lists.
void	LEM_freeCmdRsp (LEM_micr *cr)
	Free a set of command/result lists.
LEM_micr *	LEM_newMICR (void)
	Allocate a complete set of command/result lists.
void	LEM_deleteMICR (LEM_micr *cr)
	Free a complete set of comand/result lists.
void	LEM_dumpMICR (LEM_micr *cr)
	Print out the command and result lists.
unsigned	LEM_queueWait (LEM_micr *cr)
	Queue a list of commands to the LCB and wait for completion.
unsigned	LEM_handleLoadErrors (LEM_micr *cr)
	Handle any load errors.
unsigned	LEM_handleReadErrors (LEM_micr *cr)
	Handle any read errors.
unsigned	LEM_decode (LEM_micr *cr)
	Decode read items.
void	LEM_errorIgnore (unsigned error, unsigned index, void *param)
	Ignore errors in result lists.

---

Detailed Description

Routines for the sizing and allocation of command and homogeneous (all items the same size) result lists.

Author:

James Swain & Owen Saxton

$Id: list.h,v 1.4 2011/03/25 18:51:52 apw Exp $

---

Function Documentation

void* LEM_allocCmdList

(

unsigned

nItems

)

Allocate a command list.

This routine allocates a correctly aligned block of memory that will contain a command list with the specified number of items.

Parameters:

nItems

Number of items in the command list.

Returns:

The address of the command list, or NULL if insufficient memory was available.

References LEM_sizeofCmdList().

Referenced by LEM_allocCmdRsp().

unsigned LEM_allocCmdRsp	(	LEM_micr *	cr,
		unsigned	nItems
	)

Allocate a complete set of command/result lists.

This routine allocates correctly aligned memory for a command list, a read result list, and a decode list, all containing the specified number of items, and initializes the supplied command/result block.

Parameters:

	cr	Pointer to the command/result block.
	nItems	The number of items in each of the lists.

Return values:

	LEM_SUCCESS	Success.
	LEM_MEMERR	Insufficient memory.

References LEM_allocCmdList(), LEM_allocDcdList(), LEM_allocRspList(), and LEM_initCmdRsp().

Referenced by LEM_newMICR().

void* LEM_allocDcdList

(

unsigned

nItems

)

Allocate a decode list.

This routine allocates a correctly aligned block of memory that will contain a decode list with the specified number of items.

Parameters:

nItems

Number of items in the decode list.

Returns:

The address of the decode list, or NULL if insufficient memory was available.

References LEM_sizeofRsplsList().

Referenced by LEM_allocCmdRsp().

void* LEM_allocRspList

(

unsigned

nItems

)

Allocate a read result list.

This routine allocates a correctly aligned block of memory that will contain a read result list with the specified number of items.

Parameters:

nItems

Number of items in the result list.

Returns:

The address of the result list, or NULL if insufficient memory was available.

References LEM_sizeofRspList().

Referenced by LEM_allocCmdRsp().

void* LEM_allocRsplsList

(

unsigned

nItems

)

Allocate a load result list.

This routine allocates a correctly aligned block of memory that will contain a load result list with the specified number of items.

Parameters:

nItems

Number of items in the result list.

Returns:

The address of the result list, or NULL if insufficient memory was available.

References LEM_sizeofRsplsList().

unsigned LEM_decode

(

LEM_micr *

cr

)

Decode read items.

This routine assumes that the command list is a homogeneous list of read commands, so iterates over the responseful version of the result list calling each item's decode routine and checking for any errors.

If a result item has an error, and an error handling routine has been specified, then the error handling routine is called instead of the decoder. The LEM_errorIgnore routine can be used to ignore errors. If there is no error handling routine, the first error found is reported and processing is discontinued.

Parameters:

cr

Pointer to the command/result block to be processed.

Return values:

	LEM_SUCCESS	Success.
	LCBD_xxxx	An error occurred during reading.

References LATpResponse::cell, LATpCommand::cell, LEM_micl::ci, LEM_micr::cl, LATpCell::data, LEM_di::des, LEM_micr::efn, LEM_rsp_ri::err, LEM_di::fn, LATpCell::header, LEM_CURR_RI, LEM_micr::lem_di, LEM_micr::nf, LEM_micr::nr, LEM_micr::par, LEM_rsp_ri::payload, and LEM_ci::payload.

void LEM_deleteMICR

(

LEM_micr *

cr

)

Free a complete set of comand/result lists.

This routine frees the lists and command/result block previously allocated using LEM_newMICR.

Parameters:

cr

Pointer to the command/result block.

References LEM_freeCmdRsp().

void LEM_dumpMICR

(

LEM_micr *

cr

)

Print out the command and result lists.

This routine prints the lists for a command/result block in some nice formatted manner.

Parameters:

cr

Pointer to an initialised command/result block.

References LEM_micl::ci, LEM_micr::cl, dumpBlock(), LEM_micr::el, LEM_rsp_mirl::hdr, LEM_micl::hdr, LEM_micr::nf, LEM_micr::ni, LEM_micr::nr, LEM_cmd_mirl::ri, LEM_rsp_mirl::ri, LEM_micr::rl, and LEM_rsp_mirl::xcb.

void LEM_errorIgnore	(	unsigned	error,
		unsigned	index,
		void *	param
	)

Ignore errors in result lists.

This routine can be used as an error handler for processing result lists, and simply does nothing.

Parameters:

	error	Error field of the result item
	index	Position of the result list of the failed item
	param	User defined parameter

void LEM_freeCmdRsp

(

LEM_micr *

cr

)

Free a set of command/result lists.

This routine frees the memory allocated to a set of command/result lists, and clears the command/result block.

Parameters:

cr

Pointer to a command/result block initialized using LEM_allocCmdRsp.

References LEM_micr::lcbd_cl, LEM_micr::lcbd_rl, LEM_micr::lem_di, and LEM_initCmdRsp().

Referenced by LEM_deleteMICR().

unsigned LEM_handleLoadErrors

(

LEM_micr *

cr

)

Handle any load errors.

This routine assumes that the command list is a homogeneous list of load commands so iterates over the responseless version of the result list and checks for any errors.

If a result item has an error, and an error handling routine has been specified, then the error handling routine is called. The LEM_errorIgnore routine can be used to ignore errors. If there is no error handling routine, the first error found is reported and processing is discontinued.

Parameters:

cr

Pointer to the command/result block to be processed.

Return values:

	LEM_SUCCESS	Success.
	LCBD_xxxx	An error occurred during loading.

References LEM_micr::efn, LEM_cmd_ri::err, LEM_CURR_EI, LEM_micr::nf, LEM_micr::nr, and LEM_micr::par.

unsigned LEM_handleReadErrors

(

LEM_micr *

cr

)

Handle any read errors.

This routine assumes that the command list is a homogeneous list of read commands so iterates over the responseful version of the result list and checks for any errors.

If a result item has an error, and an error handling routine has been specified, then the error handling routine is called. The LEM_errorIgnore routine can be used to ignore errors. If there is no error handling routine, the first error found is reported and processing is discontinued.

Parameters:

cr

Pointer to the command/result block to be processed.

Return values:

	LEM_SUCCESS	Success.
	LCBD_xxxx	An error occurred during reading.

References LEM_micr::efn, LEM_rsp_ri::err, LEM_CURR_RI, LEM_micr::nf, LEM_micr::nr, and LEM_micr::par.

void LEM_initCmdRsp	(	LEM_micr *	cr,
		unsigned	nItems,
		void *	cmdList,
		void *	rspList,
		void *	dcdList
	)

Initialize a command/result block.

This routine initializes the fields of a command/result block with the supplied list addresses.

Parameters:

	cr	Pointer to the command/result block.
	nItems	Number of items in each of the lists.
	cmdList	Address of the command (request) list.
	rspList	Address of the read or load result list.
	dcdList	Address of the decode list.

References LEM_micr::cl, LEM_micr::efn, LEM_micr::el, LEM_micr::lcbd_cl, LEM_micr::lcbd_rl, LEM_micr::lem_di, LEM_micr::nf, LEM_micr::ni, LEM_micr::nr, LEM_micr::par, and LEM_micr::rl.

Referenced by LEM_allocCmdRsp(), LEM_freeCmdRsp(), and LEM_setupCmdRsp().

LEM_micr* LEM_newMICR

(

void

)

Allocate a complete set of command/result lists.

This routine allocates a command/result block, along with a set of maximum-length command, result and decode lists, and fills it in.

Returns:

Pointer to the initialised command/result block, or NULL if not enough memory was available.

References LEM_allocCmdRsp(), and LEM_MAX_CI.

unsigned LEM_queueWait

(

LEM_micr *

cr

)

Queue a list of commands to the LCB and wait for completion.

This routine queues a list of commands to the LCB and waits for its completion.

Parameters:

cr

Pointer to the command/result block for the command and result lists to be processed.

Return values:

	LEM_SUCCESS	Success.
	LCBD_xxxx	An error occurred during processing.

References LEM_micr::lcbd_cl, LEM_micr::lcbd_rl, LEM_REQUEST_SIZE, LEM_micr::nf, LEM_micr::ni, and LEM_micr::nr.

unsigned LEM_setupCmdRsp	(	LEM_micr *	cr,
		void *	lists,
		int	lsize
	)

Set up a complete set of command/result lists.

This routine optimally assigns portions of a supplied region to a set of command, read result and decode lists, and initializes the supplied command/result list block.

Because of RAD750 hardware restrictions, the assigned command list, rounded down to a cache line boundary (32-byte aligned) then extended by six cache lines (192 bytes), must not be accessed by the CPU while the operation is in progress. The result list, on the other hand, cannot have simultaneous CPU acces of the first six cache lines beyond the beginning of the list proper. These restrictions mean that the effective length of these lists is increased when determining whether they fit within the supplied region, but impose no extra restrictions on the relative arrangement of the three lists within the region.

Parameters:

	cr	The address of the command/result block to be filled.
	lists	The address of the region to be used.
	lsize	The length of the region to be used.

Return values:

	LEM_SUCCESS	Success.
	LEM_LISTSML	Region too small for any lists.

CDR

CRD

DCR

DRC

RCD

RDC

References LEM_initCmdRsp(), and LEM_MAX_CI.

size_t LEM_sizeofCmdList

(

unsigned

nItems

)

Get the size of a command list.

This routine returns the size of a command list containing the specified number of items.

Parameters:

nItems

Number of items in the command list.

Returns:

The size of the command list.

References CHECK_SIZE, and LEM_REQUEST_SIZE.

Referenced by LEM_allocCmdList().

size_t LEM_sizeofDcdList

(

unsigned

nItems

)

Get the size of a decode list.

This routine returns the size of a decode list containing the specified number of items.

Parameters:

nItems

Number of items in the decode list.

Returns:

The size of the decode list.

References CHECK_SIZE, and LEM_DECODE_SIZE.

size_t LEM_sizeofRspList

(

unsigned

nItems

)

Get the size of a read result list.

This routine returns the size of a read result list containing the specified number of items.

Parameters:

nItems

Number of items in the result list.

Returns:

The size of the result list.

References CHECK_SIZE, and LEM_RESPONSE_SIZE.

Referenced by LEM_allocRspList().

size_t LEM_sizeofRsplsList

(

unsigned

nItems

)

Get the size of a load result list.

This routine returns the size of a load result list containing the specified number of items.

Parameters:

nItems

Number of items in the result list.

Returns:

The size of the result list.

References CHECK_SIZE, and LEM_RESPONSELESS_SIZE.

Referenced by LEM_allocDcdList(), and LEM_allocRsplsList().