RIM.h File Reference

Public definitions for the RIM (Register In-Memory) facility. More...

#include <stdlib.h>

Classes

struct _Layer_addr

Address of a TFE/SPT node. More...

struct _ACD_addr

Address of a ARC/AFE node. More...

struct _TEM_addr

Address of a TEM/TIC/CCC/TCC/CRC/TRC/CFE node. More...

union _RIM_addr

Union of all the address structures and an array, used for hierarchical leaf identification throughout RIM. More...

struct _RIM_rqstInfo

Information describing a read request. More...

Typedefs

typedef unsigned RIM_type

Creates a new type used to identify components (TEM, TFE etc).

typedef struct RIM_ RIM

Forward declaration of the RIM structure.

typedef struct RIM_map_ RIM_map

Forward declaration of the RIM_map structure, a bit-map of all the LAT components.

typedef struct _Layer_addr Layer_addr

Address of a TFE/SPT node.

typedef struct _ACD_addr ACD_addr

Address of a ARC/AFE node.

typedef struct _TEM_addr TEM_addr

Address of a TEM/TIC/CCC/TCC/CRC/TRC/CFE node.

typedef union _RIM_addr RIM_addr

Union of all the address structures and an array, used for hierarchical leaf identification throughout RIM.

typedef struct _RIM_rqstInfo RIM_rqstInfo

Information describing a read request.

typedef void RIM_decodeFn (unsigned short *pkt, void *ptr, const RIM_rqstInfo *info)

Function that Decodes the response from one type of LAT register.

typedef unsigned RIM_loadFn (void *param, const RIM_addr *addr, unsigned regId, const void *value)

Function that Loads one type of LAT register.

typedef unsigned RIM_readFn (void *param, const RIM_addr *addr, unsigned regId, RIM_decodeFn *decodeFn, void *dst, const RIM_rqstInfo *info)

Function that Reads one type of LAT register.

typedef unsigned RIM_expRecdCB (void *parm, unsigned type, int leng)

Function called to start the export of a new record.

typedef unsigned RIM_expDataCB (void *parm, void *data, int leng)

Function called to export data for a record.

typedef unsigned RIM_impRecdCB (void *parm, unsigned *type, int *leng)

Function called to start the import of a new record.

typedef unsigned RIM_impDataCB (void *parm, int iShrt, void *data, int rLeng, int *leng)

Function called to import data for a record.

Enumerations

enum {
  LATC_MAJ = 15,
  LATC_MIN = 0
}

Current version numbers.

enum {
  RIM_OPT_SWAP = 0x01,
  RIM_OPT_CURR = 0x02
}

Import options. More...

enum { RIM_MEM_ALIGN = sizeof(unsigned long long) }

Memory alignment requirements on a memory block used for a RIM structure.

enum {
  RIM_BCAST_ADDR = 255,
  N_RIM_ADDR_CPTS = 4
}

Constant values associated with addressing LAT component instances.

enum { RIM_BAD_TYPE = -1 }

enum {
  UID_INDEX = 0x0ffff,
  UID_IGN_ERROR = 0x10000,
  UID_SPT_HIGH = 0x20000,
  UID_SPT_TFE = 0x40000,
  UID_SPT_LAST = 0x80000
}

Masks for fields in the read request uid value. More...

Functions

int RIM_checkBit (const RIM_map *map, RIM_type type, const RIM_addr *addr)

Check a bit in the map.

void RIM_checkSplit (short *ptr, unsigned long long value, unsigned int uid)

Decode a result item used to check a split.

void RIM_clear (RIM *rim)

Clear out the map and data portions of the RIM structure.

unsigned RIM_clearBit (RIM_map *map, RIM_type type, const RIM_addr *addr)

Clear a bit in the map.

void RIM_clearMap (RIM_map *map)

Clear the map.

int RIM_compare (const RIM *rim1, const RIM *rim2, RIM_map *map)

Compare all the nodes of rim1 and rim2, marking differences in map.

int RIM_compareType (const char *string, RIM_type type)

Compare string with the name of a type.

RIM * RIM_construct (void *buffer)

Initialise a block of memory as a RIM object.

RIM_map * RIM_constructMap (void *buffer)

Initialise the supplied memory as a RIM_map object.

unsigned RIM_contrast (const RIM *rim1, const RIM *rim2, const RIM_map *map, RIM_type *r_type, RIM_addr *r_addr)

Compare all the nodes of rim1 and rim2, that are not marked to be ignored.

void RIM_correct (RIM *orig, RIM *capt)

Copy select portions of an original RIM into a copy, to ensure that the subsequent comparison will succeed.

int RIM_countMap (const RIM_map *map, RIM_type type)

Count the number of set bits in the map.

void RIM_dataMasks (RIM *rim, unsigned int *dMask, unsigned int *eMask)

Get summary of data types present in a RIM.

unsigned RIM_export (RIM *rim, unsigned int typMask, RIM_expRecdCB recdRtn, RIM_expDataCB dataRtn, void *parm)

Export RIM data as a series of records.

unsigned RIM_exportMap (RIM_map *map, RIM_expRecdCB recdRtn, RIM_expDataCB dataRtn, void *parm)

Export RIM map data as a series of records.

unsigned RIM_get (const RIM *rim, RIM_type type, const RIM_addr *addr, int regId, void *value)

Put the contents of the requested register and field into value.

unsigned RIM_getAddress (RIM_addr *addr, unsigned int index, RIM_type type)

Convert flat addressing to hierarchical bit addressing.

unsigned RIM_getAddrRng (const char *string, RIM_addr *addr)

Finds the address range associated with the type identifed by the string.

unsigned RIM_getIndex (const RIM_addr *addr, unsigned int *index, RIM_type type)

Convert hierarchical bit addressing to flat addressing.

unsigned RIM_getLayerID (const char *name, unsigned int *layer)

Convert a layer name to a layer ID.

unsigned RIM_getLayerName (unsigned int layer, char *name)

Form the layer name from the layer ID.

unsigned RIM_import (RIM *rim, int optns, unsigned short *versn, RIM_impRecdCB recdRtn, RIM_impDataCB dataRtn, void *parm)

Import RIM data as a series of records.

unsigned RIM_importMap (RIM_map *map, int optns, unsigned short *versn, RIM_impRecdCB recdRtn, RIM_impDataCB dataRtn, void *parm)

Import RIM map data as a series of records.

unsigned RIM_load (RIM *rim, void *param, RIM_loadFn **loadFn)

Load the LAT with the configuration held in a RIM structure.

unsigned RIM_loadAfeConfig (RIM *rim, unsigned int mask, unsigned int value0, unsigned int value1, unsigned int rcMask, unsigned int feMask, void *param, RIM_loadFn **loadFn)

Load the AFE configuration register.

unsigned RIM_loadCfeConfig0 (RIM *rim, unsigned int mask, unsigned int value, void *param, RIM_loadFn **loadFn)

Load CFE configuration register 0.

unsigned RIM_loadCfeConfig1 (RIM *rim, unsigned int mask, unsigned int value0, unsigned int value1, unsigned int cMask, void *param, RIM_loadFn **loadFn)

Load CFE configuration register 1.

unsigned RIM_loadSplit (RIM *rim, int nLow, int nHigh, void *param, RIM_loadFn **loadFn)

Load TKR split values.

unsigned RIM_loadTfeDac (RIM *rim, unsigned int mask, unsigned int value, int nLow, int nHigh, void *param, RIM_loadFn **loadFn)

Load the TFE DAC register.

RIM_type RIM_lookupType (const char *string)

Hunt through the list of component types and return the index of the input string.

unsigned RIM_nameType (char *string, RIM_type type)

Place the four-character string describing this type into name.

unsigned RIM_nTypes (void)

Return the number of component types within the LAT register description.

unsigned RIM_read (RIM *rim, void *param, RIM_readFn **readFn, RIM_decodeFn **decodeFn)

Populate the RIM structure with the current state of the LAT.

unsigned RIM_set (RIM *rim, RIM_type type, const RIM_addr *addr, int regId, const void *value)

Set the value of a register.

unsigned RIM_setBit (RIM_map *map, RIM_type type, const RIM_addr *addr)

Set a bit in the map.

void RIM_setSplit (short *ptr, unsigned long long value, unsigned int uid)

Decode the result item used to populate a split.

size_t RIM_sizeof (void)

Calculate the footprint of the RIM structure.

size_t RIM_sizeofMap (void)

Calculate the total size of a RIM_map object.

Detailed Description

Public definitions for the RIM (Register In-Memory) facility.

Author:: James Swain & Owen Saxton

$Id: RIM.h,v 1.10 2011/03/27 05:54:08 saxton Exp $

Typedef Documentation

typedef struct _RIM_rqstInfo RIM_rqstInfo

Information describing a read request.

This is used mainly in handling read errors, but is also used when processing registers read during a read of the splits

This structure should really be private to RIM, since the information it contains is essentially held in escrow by LATC and returned in the event that the response to a read command contains an error. However, the additional scaffold required to support an opaque handle just seems like overkill.

Enumeration Type Documentation

anonymous enum

Import options.

Enumerator:

RIM_OPT_SWAP	Swap data bytes.
RIM_OPT_CURR	Allow only the current version.

anonymous enum

Masks for fields in the read request uid value.

Enumerator:

UID_INDEX	Index of component.
UID_IGN_ERROR	Ignore any read errors.
UID_SPT_HIGH	Set if high side split; otherwise low.
UID_SPT_TFE	Set if reading TFE; otherwise TRC.
UID_SPT_LAST	Set if last read of the group.

Function Documentation

int RIM_checkBit	(	const RIM_map *	map,
		RIM_type	type,
		const RIM_addr *	addr
	)

Check a bit in the map.

Parameters:

	map	Structure being manipulated
	type	Identifies map to manipulate
	addr	bit to check

Return values:

	0	if the bit is clear
	1	if the bit is set

References checkBit(), and mapIndex().

void RIM_checkSplit	(	short *	ptr,
		unsigned long long	value,
		unsigned int	uid
	)

Decode a result item used to check a split.

The read value of a TFE mode register is compared with the expected value and the split value set to indicate an error if it doesn't match

Parameters:

	ptr	Pointer to split registers instance
	value	Value read from the TFE mode register
	uid	The unique ID of the TFE mode register

References _Layer_addr::fe, _RIM_addr::lyr, RIM_getAddress(), UID_INDEX, and UID_SPT_HIGH.

void RIM_clear ( RIM * rim )

Clear out the map and data portions of the RIM structure.

Parameters:

rim

Pointer to the RIM object to clear

References RIM_clearMap(), and RIM_setReg().

unsigned RIM_clearBit	(	RIM_map *	map,
		RIM_type	type,
		const RIM_addr *	addr
	)

Clear a bit in the map.

Parameters:

	map	Structure being manipulated
	type	Identifies map to manipulate
	addr	bit to clear

Return values:

	RIM_SUCCESS	if everything goes well
	RIM_TYPEUNKN	if the type does not exist
	RIM_MAPNONE	if there is no sub-map corresponding to this type
	RIM_ADDRBCST	if the address contains a mixture of broadcast and singlecast addresses
	RIM_ADDRRNGE	if any component of the address is out of range
	RIM_ADDRINDX	if the final index exceeds the total number of bits in the map

References clearBit(), and mapIndex().

void RIM_clearMap ( RIM_map * map )

Clear the map.

Parameters:

map

Structure being manipulated

References clearMap().

Referenced by RIM_clear().

int RIM_compare	(	const RIM *	rim1,
		const RIM *	rim2,
		RIM_map *	map
	)

Compare all the nodes of rim1 and rim2, marking differences in map.

If a node is NULL, then the default node is used.

Parameters:

	rim1	First in-memory configuration structure
	rim2	Second in-memory configuration structure
	map	Indicates which nodes are different

Returns:: Number of different nodes

References checkBit(), compareCpt(), RIM_cptDesc(), RIM_number(), and setBit().

int RIM_compareType	(	const char *	string,
		RIM_type	type
	)

Compare string with the name of a type.

Parameters:

	string	Name of a component type
	type	Type to compare to

Return values:

	-1	If the type is unknown (exceeds the range of acceptable types)
	0	If the type is known, and the name matches the string
	1	If the type is known, and the name does not match the string

RIM* RIM_construct ( void * buffer )

Initialise a block of memory as a RIM object.

Parameters:

buffer

Pointer to uninitialised memory to use for the RIM structure

Returns:: The address of the initialised RIM structure, or NULL if the buffer is misaligned

References align(), RIM_constructMap(), RIM_cptDesc(), RIM_number(), RIM_setReg(), sizeofCpt(), and sizeofStore().

RIM_map* RIM_constructMap ( void * buf )

Initialise the supplied memory as a RIM_map object.

Parameters:

buf

Block of memory, at least as large as RIM_sizeofMap, to initalise as a RIM_map object

Returns:: Pointer to an initialised RIM_map object

References sizeofMap().

Referenced by RIM_construct().

unsigned RIM_contrast	(	const RIM *	rim1,
		const RIM *	rim2,
		const RIM_map *	ign,
		RIM_type *	r_type,
		RIM_addr *	r_addr
	)

Compare all the nodes of rim1 and rim2, that are not marked to be ignored.

If a node is NULL then the default node is used.

Parameters:

	rim1	First in memory configuration model
	rim2	Second in memory configuration model
	ign	Pointer to a bit-map of sections of the LAT to ignore
	r_type	Location to fill with the type of the first different node (can be NULL if not interested)
	r_addr	Pointer to an address structure to populate with the first different node (can be NULL if not interested)

Return values:

	RIM_SUCCESS	If the two in-memory models are functionally identical
	RIM_DIFFER	If the two in-memory models are different

References checkBit(), compareCpt(), RIM_cptDesc(), RIM_getAddress(), and RIM_number().

void RIM_correct	(	RIM *	orig,
		RIM *	capt
	)

Copy select portions of an original RIM into a copy, to ensure that the subsequent comparison will succeed.

Parameters:

	orig	Orignal RIM
	capt	New copy of the RIM (probably captured from the LAT)

References checkBit(), RIM_getReg(), and RIM_setReg().

int RIM_countMap	(	const RIM_map *	map,
		RIM_type	type
	)

Count the number of set bits in the map.

Parameters:

	map	Structure being manipulated
	type	Identifies map to count

Returns:: Number of bits set in the map, or -1 for an illegal type

Referenced by RIM_export().

void RIM_dataMasks	(	RIM *	rim,
		unsigned int *	dMask,
		unsigned int *	eMask
	)

Get summary of data types present in a RIM.

This routine returns two bitmasks indicating what kinds of data are present in the specified RIM structure. The first indicates the types with default data present, while the second indicates which types have exception data. The principle use of this routine is to avoid creating empty sets of exported data.

Parameters:

	rim	Pointer to the in-memory model data
	dMask	The address of an integer to receive the bitmask of types with default data present.
	eMask	The address of an integer to receive the bitmask of types with exception data present.

unsigned RIM_export	(	RIM *	rim,
		unsigned int	typMask,
		RIM_expRecdCB	recdRtn,
		RIM_expDataCB	dataRtn,
		void *	parm
	)

Export RIM data as a series of records.

This routine provides a general way to export the data from a RIM structure. The data are presented as a series of records to the supplied callback routines. One routine is called at the start of each record to receive the record type and length of the data in the record. The second routine is called to receive data for the record, and is called as many times as necessary to receive all the data.

Parameters:

	rim	RIM structure to use as a source
	typMask	Mask of component types to write out. If the default (DFT) bit is set, the default data for all types is exported in addition to the data indicated by the other type bits.
	recdRtn	Routine to be called at the start of each record to be exported.
	dataRtn	Routine to be called for each block of data to be exported.
	parm	Parameter to pass to the callback routines.

Return values:

RIM_SUCCESS

if all goes well

References checkBit(), exportData(), RIM_countMap(), RIM_cptDesc(), RIM_number(), RIM_RT_DFT, RIM_RT_EXCP, RIM_RT_MAP, sizeofCpt(), and sizeofMap().

unsigned RIM_exportMap	(	RIM_map *	map,
		RIM_expRecdCB	recdRtn,
		RIM_expDataCB	dataRtn,
		void *	parm
	)

Export RIM map data as a series of records.

This routine provides a general way to export the data from a RIM map structure. The data are presented as a series of records to the supplied callback routines. One routine is called at the start of each record to receive the record type and length of the data in the record. The second routine is called to receive data for the record, and is called as many times as necessary to receive all the data.

Parameters:

	map	RIM map structure to use as a source
	recdRtn	Routine to be called at the start of each record to be exported.
	dataRtn	Routine to be called for each block of data to be exported.
	parm	Parameter to pass to the callback routines.

Return values:

RIM_SUCCESS

if all goes well

References exportData(), RIM_RT_MAP, and sizeofMap().

unsigned RIM_get	(	const RIM *	rim,
		RIM_type	type,
		const RIM_addr *	addr,
		int	regId,
		void *	value
	)

Put the contents of the requested register and field into value.

Parameters:

	rim	In memory configuration structure to be interogated
	type	Type of data sought
	addr	Address of the leaf requested
	regId	Register to get, as LAT hardware ID
	value	Location to put the contents of the target field

Return values:

	RIM_SUCCESS	if all the parameters are in bounds and the data is successfully retrieved.
	RIM_TYPEUNKN	if type is not a valid RIM_type
	RIM_CPTNONE	if the requested type has no real data
	RIM_ADDRBCST	if the address contains a mixture of broadcast and unicast components
	RIM_ADDRRNGE	if any component of the address is outside the allowable range for this type
	RIM_BADREGID	if regId is outside the acceptable range of register IDs for this type
	RIM_NOTSET	if the requested node has not been previously set
	RIM_BADREGID	The register ID was unrecognized

References CHECK_TYPE, checkBit(), RIM_getIndex(), RIM_getReg(), RIM_number(), and RIM_regEnum().

unsigned RIM_getAddress	(	RIM_addr *	addr,
		unsigned int	index,
		RIM_type	type
	)

Convert flat addressing to hierarchical bit addressing.

Note that GTFEs are usually referred to as being part of an X or Y layer. This identification is converted to an absolute layer number and stored in the rc space by addr->rc = (layerNumber << 1) | isYlayer. This conversion is performed by the XLM->RIM converter, but is documented here since it is a storage convention.

Parameters:

	addr	Address corresponding to index
	index	Index to convert
	type	Type of address to convert

Return values:

	RIM_SUCCESS	Success
	RIM_TYPEUNKN	The component type is unknown
	RIM_ADDRRNGE	The index is outside the allowable range for this type

References _RIM_addr::cpt.

Referenced by RIM_checkSplit(), and RIM_contrast().

unsigned RIM_getAddrRng	(	const char *	string,
		RIM_addr *	addr
	)

Finds the address range associated with the type identifed by the string.

Parameters:

	string	Identifies the address range required
	addr	Pointer to address stucture to populate with the address range

Return values:

	RIM_SUCCESS	If the string is a good type name.
	RIM_TYPESTR	If the string does not match a known type

References _RIM_addr::cpt, and RIM_lookupType().

unsigned RIM_getIndex	(	const RIM_addr *	addr,
		unsigned int *	index,
		RIM_type	type
	)

Convert hierarchical bit addressing to flat addressing.

Note that GTFEs are usually referred to as being part of an X or Y layer. This identification is converted to an absolute layer number and stored in the rc space by addr->rc = (layerNumber << 1) | isYlayer. This conversion is performed by the XLM->binary converter, but is documented here since it is a storage convention.

Parameters:

	addr	Address to convert
	index	Index corresponding to address
	type	Type of address to convert

Return values:

	RIM_SUCCESS	Success
	RIM_TYPEUNKN	The component type is unknown
	RIM_ADDRBCST	The address contains a mixture of broadcast and unicast components
	RIM_ADDRRNGE	A component of the address is outside the allowable range for this type

References _RIM_addr::cpt.

Referenced by mapIndex(), RIM_deleteData(), RIM_get(), and RIM_set().

unsigned RIM_getLayerID	(	const char *	name,
		unsigned int *	layer
	)

Convert a layer name to a layer ID.

A three-character layer name of the form [sign][xory][index] is converted to a layer ID.

Parameters:

	name	The address of the three-byte layer name.
	layer	Location to store the layer ID

Return values:

	RIM_SUCCESS	If the layer ID was successfully found
	RIM_ADDRLSIG	If the layer sign is nonsensical
	RIM_ADDRLXY	If the layer xy value is nonsensical
	RIM_ADDRLIND	If the layer index is nonsensical

unsigned RIM_getLayerName	(	unsigned int	layer,
		char *	name
	)

Form the layer name from the layer ID.

The name has the form [sign][xory][index], e.g. +y5, -x1.

Parameters:

	layer	ID of the layer to name
	name	The address of a 4-byte array to hold the layer name (3 bytes) plus the trailing null.

Return values:

	RIM_SUCCESS	If the layer is located
	RIM_ADDRLAYR	If the layer is out of range

References N_LAYER.

unsigned RIM_import	(	RIM *	rim,
		int	optns,
		unsigned short *	versn,
		RIM_impRecdCB	recdRtn,
		RIM_impDataCB	dataRtn,
		void *	parm
	)

Import RIM data as a series of records.

This routine provides a general way to import data into a RIM structure. The data are received as a series of records from the supplied callback routines. One routine is called to position at the start of the next record to be imported and supplies the record type and data length. The second routine is called to retrieve data for the record, and is called as many times as necessary to retrieve all the data.

Parameters:

	rim	RIM structure to use as a repository.
	optns	An options word, consisting of the logical OR of the following possible values: RIM_OPT_SWAP Swap the bytes of the imported data from big-endian to machine order. RIM_OPT_CURR Allow only the current version of the data.
	versn	The address of a two-element array containing the major and minor version numbers of the data being imported.
	recdRtn	Routine to be called at the start of each record to be imported.
	dataRtn	Routine to be called for each block of data to be imported.
	parm	Parameter to pass to the callback routines.

Return values:

	RIM_SUCCESS	Success
	RIM_BADVERSN	The supplied version number is invalid
	RIM_RTYPUNKN	Received a record with invalid record type
	RIM_TYPEUNKN	Received a record with invalid RIM type

References checkBit(), importData(), RIM_cptDesc(), RIM_number(), RIM_OPT_CURR, RIM_OPT_SWAP, RIM_RT_DFT, RIM_RT_EXCP, RIM_RT_MAP, RIM_RT_MASK, sizeofCpt(), and sizeofMap().

unsigned RIM_importMap	(	RIM_map *	map,
		int	optns,
		unsigned short *	versn,
		RIM_impRecdCB	recdRtn,
		RIM_impDataCB	dataRtn,
		void *	parm
	)

Import RIM map data as a series of records.

This routine provides a general way to export the data from a RIM map structure. The data are presented as a series of records to the supplied callback routines. One routine is called at the start of each record to receive the record type and length of the data in the record. The second routine is called to receive data for the record, and is called as many times as necessary to receive all the data.

Parameters:

	map	RIM map structure to use as a source
	optns	An options word, consisting of the logical OR of the following possible values: RIM_OPT_SWAP Swap the bytes of the imported data from big-endian to machine order. RIM_OPT_CURR Allow only the current version of the data.
	versn	The address of a two-element array containing the major and minor version numbers of the data being imported.
	recdRtn	Routine to be called at the start of each record to be exported.
	dataRtn	Routine to be called for each block of data to be exported.
	parm	Parameter to pass to the callback routines.

Return values:

	RIM_SUCCESS	Success
	RIM_BADVERSN	The supplied version number is invalid
	RIM_RTYPUNKN	Received a record with invalid record type
	RIM_TYPEUNKN	Received a record with invalid RIM type

References importData(), RIM_OPT_CURR, RIM_OPT_SWAP, RIM_RT_MAP, RIM_RT_MASK, and sizeofMap().

unsigned RIM_load	(	RIM *	rim,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load the LAT with the configuration held in a RIM structure.

Parameters:

	rim	Pointer to the RIM structure to populate from the LAT
	param	Pointer passed through to the loadRegFn
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References LoadParm::loadFn, LoadParm::param, RIM_cptDesc(), and RIM_loadSplit().

unsigned RIM_loadAfeConfig	(	RIM *	rim,
		unsigned int	mask,
		unsigned int	value0,
		unsigned int	value1,
		unsigned int	rcMask,
		unsigned int	feMask,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load the AFE configuration register.

The AFE configuration register is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	rim	Pointer to the cached in-memory model of the LATC registers
	mask	Mask of bits to be changed from the configuration.
	value0	The value to be masked and merged with the configuration value for front-ends not selected by the RC and FE masks.
	value1	The value to be masked and merged with the configuration value for front-ends selected by the RC and FE masks.
	rcMask	Mask of bits, one per RC, specifying which RCs are selected.
	feMask	Mask of bits, one per FE, specifying which FEs within selected RCs are selected.
	param	Parameter to be passed to the load routine.
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References _RIM_addr::acd, checkBit(), _ACD_addr::fe, _ACD_addr::rc, CptDescription::rd, RegDescription::regId, RIM_addrRng(), RIM_cptDesc(), and RIM_getReg().

unsigned RIM_loadCfeConfig0	(	RIM *	rim,
		unsigned int	mask,
		unsigned int	value,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load CFE configuration register 0.

CFE configuration register 0 is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	rim	Pointer to the cached in-memory model of the LATC registers
	mask	Mask of bits to be changed from the configuration.
	value	The value to be masked and merged with the configuration value.
	param	Parameter to be passed to the load routine.
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References _TEM_addr::cc, checkBit(), _TEM_addr::fe, _TEM_addr::rc, CptDescription::rd, RegDescription::regId, RIM_addrRng(), RIM_cptDesc(), RIM_getReg(), _RIM_addr::tem, and _TEM_addr::to.

unsigned RIM_loadCfeConfig1	(	RIM *	rim,
		unsigned int	mask,
		unsigned int	value0,
		unsigned int	value1,
		unsigned int	cMask,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load CFE configuration register 1.

CFE configuration register 1 is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	rim	Pointer to the cached in-memory model of the LATC registers
	mask	Mask of bits to be changed from the configuration.
	value0	The value to be masked and merged with the configuration value for front-ends whose bit is clear in the column mask.
	value1	The value to be masked and merged with the configuration value for front-ends whose bit is set in the column mask.
	cMask	Mask of bits, one per column, specifying which value is to be used for loading the config register.
	param	Parameter to be passed to the load routine.
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References _TEM_addr::cc, checkBit(), _TEM_addr::fe, _TEM_addr::rc, CptDescription::rd, RegDescription::regId, RIM_addrRng(), RIM_cptDesc(), RIM_getReg(), _RIM_addr::tem, and _TEM_addr::to.

unsigned RIM_loadSplit	(	RIM *	rim,
		int	nLow,
		int	nHigh,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load TKR split values.

The tracker RC and FE registers are loaded to reflect the given split values.

Parameters:

	rim	RIM structure containing the values to load onto the LAT
	nLow	Number of TFEs to talk on the low side, or -1 if the configured values are to be used.
	nHigh	Number of TFEs to talk on the high side, or -1 if the configured values are to be used.
	param	Parameter to be passed to the load function.
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References checkBit(), _Layer_addr::la, _RIM_addr::lyr, RIM_addrRng(), RIM_getReg(), and _Layer_addr::to.

Referenced by RIM_load().

unsigned RIM_loadTfeDac	(	RIM *	rim,
		unsigned int	mask,
		unsigned int	value,
		int	nLow,
		int	nHigh,
		void *	param,
		RIM_loadFn **	loadFn
	)

Load the TFE DAC register.

The TFE DAC register is loaded with a modified version of the value from the LAT configuration, with the specified bits replaced.

Parameters:

	rim	Pointer to the cached in-memory model of the LATC registers
	mask	Mask of bits to be changed from the configuration.
	value	The value to be masked and merged with the configuration value.
	nLow	Number of TFEs talking on the low side, or -1 if the configured values are being used.
	nHigh	Number of TFEs talking on the high side, or -1 if the configured values are being used.
	param	Parameter to be passed to the load routine.
	loadFn	Type ordered array of pointers to functions that load the LAT registers

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References checkBit(), _Layer_addr::fe, _Layer_addr::la, _RIM_addr::lyr, CptDescription::rd, RegDescription::regId, RIM_addrRng(), RIM_cptDesc(), RIM_getReg(), RIM_layerHigh(), RIM_layerLow(), _RIM_addr::tem, and _Layer_addr::to.

RIM_type RIM_lookupType ( const char * string )

Hunt through the list of component types and return the index of the input string.

Parameters:

string

String corresponding to one of the component types used in the LAT register description

Returns:: integer corresponding to the type identified by string or RIM_BAD_TYPE if the string does not match any on the list

Referenced by RIM_getAddrRng().

unsigned RIM_nameType	(	char *	string,
		RIM_type	type
	)

Place the four-character string describing this type into name.

Parameters:

	type	Type to be named
	string	Location to place name

Return values:

	RIM_SUCCESS	If the type is known to RIM
	RIM_TYPEUNKN	If the type is unknown

unsigned RIM_nTypes ( void )

Return the number of component types within the LAT register description.

Returns:: Number of component types

unsigned RIM_read	(	RIM *	rim,
		void *	param,
		RIM_readFn **	readFn,
		RIM_decodeFn **	decodeFn
	)

Populate the RIM structure with the current state of the LAT.

Parameters:

	rim	Pointer to the RIM structure to populate from the LAT
	param	Pointer passed through to the readRegFn
	readFn	Type ordered array of pointers to functions that read the LAT registers
	decodeFn	Type ordered array of pointers to functions that decode the register responses

Return values:

	RIM_SUCCESS	if all goes well
	LEM_*	if there is an error arising from one of the register load commands

References ReadParm::decodeFn, ReadParm::param, ReadParm::readFn, RIM_cptDesc(), and RIM_number().

unsigned RIM_set	(	RIM *	rim,
		RIM_type	type,
		const RIM_addr *	addr,
		int	regId,
		const void *	value
	)

Set the value of a register.

Parameters:

	rim	In memory configuration structure to manipulated
	type	Type of data sought
	addr	Address of the leaf requested
	regId	Register to set, as a LAT hardware ID
	value	Ptr to value to set the register field to

Return values:

	RIM_SUCCESS	if all the parameters are in bounds and the data is successfully retrieved.
	RIM_TYPEUNKN	if type is not a valid RIM_type
	RIM_CPTNONE	if the requested type has no real data
	RIM_ADDRBCST	if the address contains a mixture of broadcast and unicast components
	RIM_ADDRRNGE	if any component of the address is outside the allowable range for this type
	RIM_BADREGID	if regId is outside the acceptable range of register IDs for this type

References CHECK_TYPE, RIM_getIndex(), RIM_number(), RIM_regEnum(), RIM_setReg(), and setBit().

unsigned RIM_setBit	(	RIM_map *	map,
		RIM_type	type,
		const RIM_addr *	addr
	)

Set a bit in the map.

Parameters:

	map	Structure being manipulated
	type	Identifies map to manipulate
	addr	bit to set

Return values:

	RIM_SUCCESS	if everything goes well
	RIM_TYPEUNKN	if the type does not exist
	RIM_MAPNONE	if there is no sub-map corresponding to this type
	RIM_ADDRBCST	if the address contains a mixture of broadcast and unicast addresses
	RIM_ADDRRNGE	if any component of the address is out of range
	RIM_ADDRINDX	if the final index exceeds the total number of bits in the map

References mapIndex(), and setBit().

void RIM_setSplit	(	short *	ptr,
		unsigned long long	value,
		unsigned int	uid
	)

Decode the result item used to populate a split.

The value from the TRC register is converted and assigned to the appropriate split register.

Parameters:

	ptr	Pointer to split registers instance
	value	Value read from the TRC register
	uid	The unique ID of the SPT register

References RIM_addrRng(), and UID_SPT_HIGH.

size_t RIM_sizeof ( void )

Calculate the footprint of the RIM structure.

Returns:: Amount of memory required to hold the RIM structure

References RIM_sizeofMap(), roundUp(), and sizeofStore().

size_t RIM_sizeofMap ( void )

Calculate the total size of a RIM_map object.

Returns:: Amount of memory required to accomodate a RIM_map object

References sizeofMap().

Referenced by RIM_sizeof().


Classes
struct	_Layer_addr
	Address of a TFE/SPT node. More...
struct	_ACD_addr
	Address of a ARC/AFE node. More...
struct	_TEM_addr
	Address of a TEM/TIC/CCC/TCC/CRC/TRC/CFE node. More...
union	_RIM_addr
	Union of all the address structures and an array, used for hierarchical leaf identification throughout RIM. More...
struct	_RIM_rqstInfo
	Information describing a read request. More...
Typedefs
typedef unsigned	RIM_type
	Creates a new type used to identify components (TEM, TFE etc).
typedef struct RIM_	RIM
	Forward declaration of the RIM structure.
typedef struct RIM_map_	RIM_map
	Forward declaration of the RIM_map structure, a bit-map of all the LAT components.
typedef struct _Layer_addr	Layer_addr
	Address of a TFE/SPT node.
typedef struct _ACD_addr	ACD_addr
	Address of a ARC/AFE node.
typedef struct _TEM_addr	TEM_addr
	Address of a TEM/TIC/CCC/TCC/CRC/TRC/CFE node.
typedef union _RIM_addr	RIM_addr
	Union of all the address structures and an array, used for hierarchical leaf identification throughout RIM.
typedef struct _RIM_rqstInfo	RIM_rqstInfo
	Information describing a read request.
typedef void	RIM_decodeFn (unsigned short pkt, void ptr, const RIM_rqstInfo *info)
	Function that Decodes the response from one type of LAT register.
typedef unsigned	RIM_loadFn (void param, const RIM_addr addr, unsigned regId, const void *value)
	Function that Loads one type of LAT register.
typedef unsigned	RIM_readFn (void param, const RIM_addr addr, unsigned regId, RIM_decodeFn decodeFn, void dst, const RIM_rqstInfo *info)
	Function that Reads one type of LAT register.
typedef unsigned	RIM_expRecdCB (void *parm, unsigned type, int leng)
	Function called to start the export of a new record.
typedef unsigned	RIM_expDataCB (void parm, void data, int leng)
	Function called to export data for a record.
typedef unsigned	RIM_impRecdCB (void parm, unsigned type, int *leng)
	Function called to start the import of a new record.
typedef unsigned	RIM_impDataCB (void parm, int iShrt, void data, int rLeng, int *leng)
	Function called to import data for a record.
Enumerations
enum	{ LATC_MAJ = 15, LATC_MIN = 0 }
	Current version numbers.
enum	{ RIM_OPT_SWAP = 0x01, RIM_OPT_CURR = 0x02 }
	Import options. More...
enum	{ RIM_MEM_ALIGN = sizeof(unsigned long long) }
	Memory alignment requirements on a memory block used for a RIM structure.
enum	{ RIM_BCAST_ADDR = 255, N_RIM_ADDR_CPTS = 4 }
	Constant values associated with addressing LAT component instances.
enum	{ RIM_BAD_TYPE = -1 }
enum	{ UID_INDEX = 0x0ffff, UID_IGN_ERROR = 0x10000, UID_SPT_HIGH = 0x20000, UID_SPT_TFE = 0x40000, UID_SPT_LAST = 0x80000 }
	Masks for fields in the read request uid value. More...
Functions
int	RIM_checkBit (const RIM_map map, RIM_type type, const RIM_addr addr)
	Check a bit in the map.
void	RIM_checkSplit (short *ptr, unsigned long long value, unsigned int uid)
	Decode a result item used to check a split.
void	RIM_clear (RIM *rim)
	Clear out the map and data portions of the RIM structure.
unsigned	RIM_clearBit (RIM_map map, RIM_type type, const RIM_addr addr)
	Clear a bit in the map.
void	RIM_clearMap (RIM_map *map)
	Clear the map.
int	RIM_compare (const RIM rim1, const RIM rim2, RIM_map *map)
	Compare all the nodes of rim1 and rim2, marking differences in map.
int	RIM_compareType (const char *string, RIM_type type)
	Compare string with the name of a type.
RIM *	RIM_construct (void *buffer)
	Initialise a block of memory as a RIM object.
RIM_map *	RIM_constructMap (void *buffer)
	Initialise the supplied memory as a RIM_map object.
unsigned	RIM_contrast (const RIM rim1, const RIM rim2, const RIM_map map, RIM_type r_type, RIM_addr *r_addr)
	Compare all the nodes of rim1 and rim2, that are not marked to be ignored.
void	RIM_correct (RIM orig, RIM capt)
	Copy select portions of an original RIM into a copy, to ensure that the subsequent comparison will succeed.
int	RIM_countMap (const RIM_map *map, RIM_type type)
	Count the number of set bits in the map.
void	RIM_dataMasks (RIM rim, unsigned int dMask, unsigned int *eMask)
	Get summary of data types present in a RIM.
unsigned	RIM_export (RIM rim, unsigned int typMask, RIM_expRecdCB recdRtn, RIM_expDataCB dataRtn, void parm)
	Export RIM data as a series of records.
unsigned	RIM_exportMap (RIM_map map, RIM_expRecdCB recdRtn, RIM_expDataCB dataRtn, void parm)
	Export RIM map data as a series of records.
unsigned	RIM_get (const RIM rim, RIM_type type, const RIM_addr addr, int regId, void *value)
	Put the contents of the requested register and field into value.
unsigned	RIM_getAddress (RIM_addr *addr, unsigned int index, RIM_type type)
	Convert flat addressing to hierarchical bit addressing.
unsigned	RIM_getAddrRng (const char string, RIM_addr addr)
	Finds the address range associated with the type identifed by the string.
unsigned	RIM_getIndex (const RIM_addr addr, unsigned int index, RIM_type type)
	Convert hierarchical bit addressing to flat addressing.
unsigned	RIM_getLayerID (const char name, unsigned int layer)
	Convert a layer name to a layer ID.
unsigned	RIM_getLayerName (unsigned int layer, char *name)
	Form the layer name from the layer ID.
unsigned	RIM_import (RIM rim, int optns, unsigned short versn, RIM_impRecdCB recdRtn, RIM_impDataCB dataRtn, void *parm)
	Import RIM data as a series of records.
unsigned	RIM_importMap (RIM_map map, int optns, unsigned short versn, RIM_impRecdCB recdRtn, RIM_impDataCB dataRtn, void *parm)
	Import RIM map data as a series of records.
unsigned	RIM_load (RIM rim, void param, RIM_loadFn **loadFn)
	Load the LAT with the configuration held in a RIM structure.
unsigned	RIM_loadAfeConfig (RIM rim, unsigned int mask, unsigned int value0, unsigned int value1, unsigned int rcMask, unsigned int feMask, void param, RIM_loadFn **loadFn)
	Load the AFE configuration register.
unsigned	RIM_loadCfeConfig0 (RIM rim, unsigned int mask, unsigned int value, void param, RIM_loadFn **loadFn)
	Load CFE configuration register 0.
unsigned	RIM_loadCfeConfig1 (RIM rim, unsigned int mask, unsigned int value0, unsigned int value1, unsigned int cMask, void param, RIM_loadFn **loadFn)
	Load CFE configuration register 1.
unsigned	RIM_loadSplit (RIM rim, int nLow, int nHigh, void param, RIM_loadFn **loadFn)
	Load TKR split values.
unsigned	RIM_loadTfeDac (RIM rim, unsigned int mask, unsigned int value, int nLow, int nHigh, void param, RIM_loadFn **loadFn)
	Load the TFE DAC register.
RIM_type	RIM_lookupType (const char *string)
	Hunt through the list of component types and return the index of the input string.
unsigned	RIM_nameType (char *string, RIM_type type)
	Place the four-character string describing this type into name.
unsigned	RIM_nTypes (void)
	Return the number of component types within the LAT register description.
unsigned	RIM_read (RIM rim, void param, RIM_readFn readFn, RIM_decodeFn decodeFn)
	Populate the RIM structure with the current state of the LAT.
unsigned	RIM_set (RIM rim, RIM_type type, const RIM_addr addr, int regId, const void *value)
	Set the value of a register.
unsigned	RIM_setBit (RIM_map map, RIM_type type, const RIM_addr addr)
	Set a bit in the map.
void	RIM_setSplit (short *ptr, unsigned long long value, unsigned int uid)
	Decode the result item used to populate a split.
size_t	RIM_sizeof (void)
	Calculate the footprint of the RIM structure.
size_t	RIM_sizeofMap (void)
	Calculate the total size of a RIM_map object.