Class CsrBitSet

java.lang.Object

java.util.BitSet

cbsw.CsrBitSet

All Implemented Interfaces:

Serializable, Cloneable

public class CsrBitSet
extends BitSet
implements Cloneable

Bit-oriented register descriptor collection

Hardware interfaces are typically manipulated through a set of addressable byte-oriented registers. This class is intended to simplify bit-oriented access to such registers. It encapsulates a collection of descriptors for fields containing consecutive bits. Each field is assigned a key, a bit offset from the start of the register array and the length of consecutive bits belonging to the field. Internally, the class maintains a copy of the current register settings as a BitSet. Application code can manipulate the contents of the cache using get() and set() methods. Writing the hardware is achieved through the put() methods using the RegisterIo interface.

The class unmarshalls the collection of bitfields from an XML file. An example bit-field descriptor might appear like this in the XML:

<register name="gt.0.precursor" offset="536" length="5">GT TX precursor value</register>

The name attribute is used as the HashMap key.

Several of the methods are generic. Where the generic vaue represents a bit-field value, the types Integer, Boolean or String are allowed. All others result in the method throwing a RuntimeException.

To support triplicated registers (such as used by the GBTX ASIC), the offset attribute may be a comma-separated list of (usually 3) offsets. The bit-field values are replicated to each offset in the list.

See Also:

• RegisterDescriptor
• RegisterIo
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
(package private) int	csrSize
(package private) ArrayList<RegisterDescriptor>	descriptors
(package private) HashMap<String, RegisterDescriptor>	map
(package private) BitSet	roBits

Constructor Summary

Constructors

Constructor	Description
CsrBitSet(int csrSize, ArrayList<RegisterDescriptor> descriptors, HashMap<String, RegisterDescriptor> map)
CsrBitSet(int csrSize, ArrayList<RegisterDescriptor> descriptors, HashMap<String, RegisterDescriptor> map, File cf)

Method Summary

Modifier and Type	Method	Description
Object	clone()
void	decode()	Displays the values of all bit-fields on System.out
void	decode(BitSet bits)	Displays the values of all bit-fields on System.out
String	get(String key)	Gets hex string representation of bit-field
String	get(String key, byte[] regs)	Gets hex string representation of bit-field
String	get(String key, BitSet bits)	Gets hex string representation of bit-field
byte[]	getBytes(String key, int arrayOffset)	Deprecated.
int	getCsrSize()	Returns the CSR size
ArrayList<RegisterDescriptor>	getDescriptors()	Returns the bit-field descriptor list
HashMap<String, RegisterDescriptor>	getMap()	Returns the descriptor map
(package private) static String	getPrefsValue(String key, Preferences prefs, Object defaultValue)	Converts a value from a Preference into String representation
RegisterDescriptor	getRegisterDescriptor(String key)	Returns the RegisterDescriptor for the given key
BitSet	getRoBits()
void	saveToBinaryFile()
void	saveToBinaryFile(File file)
void	set(byte[] buf)	Initialises the CsrBitSet from a byte array
void	set(File cf)	Initialises the CsrBitSet from binary file
void	set(File cf, int skip)	Initialises the CsrBitSet from a binary file.
void	set(FileReader fr)	Read the register settings from file and update CsrBitSet.
<T> void	set(String key, Preferences prefs, T defaultValue)	Sets the register bits from value stored in Java Preference
<T> void	set(String key, T value)	Sets bit-field
void	setRegex(String key, String val)	Writes the value to all register bit-fields matching a regular expression.
Stream<RegisterDescriptor>	stream(String regex)	Get a stream of registers whose name matches the supplied regex
Stream<RegisterDescriptor>	stream(String regex, String value)	Get a stream of registers whose name matches the supplied regex and content matches the supplied value.
Stream<RegisterDescriptor>	streamComplement(String regex, String value)	Get a stream of registers whose name matches the supplied regex and content does not match the supplied value.
Stream<RegisterDescriptor>	streamRegisterDescriptors()	Returns a Collection stream.
byte[]	toByteArray(int arrayOffset)	Returns a new byte array containing the register values
static String	valueOf(Object obj)	Converts value into String representation

Methods inherited from class BitSet

and, andNot, cardinality, clear, clear, clear, equals, flip, flip, get, get, hashCode, intersects, isEmpty, length, nextClearBit, nextSetBit, or, previousClearBit, previousSetBit, set, set, set, set, size, stream, toByteArray, toLongArray, toString, valueOf, valueOf, valueOf, valueOf, xor

Methods inherited from class Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

csrSize

int csrSize

descriptors

ArrayList<RegisterDescriptor> descriptors

map

HashMap<String, RegisterDescriptor> map

roBits

BitSet roBits

Constructor Details

CsrBitSet

public CsrBitSet(int csrSize,
 ArrayList<RegisterDescriptor> descriptors,
 HashMap<String, RegisterDescriptor> map)

CsrBitSet

public CsrBitSet(int csrSize,
 ArrayList<RegisterDescriptor> descriptors,
 HashMap<String, RegisterDescriptor> map,
 File cf)

Method Details

clone

public Object clone()

Overrides:

clone in class BitSet

getRoBits

public BitSet getRoBits()

getCsrSize

public int getCsrSize()

Returns the CSR size

Returns:

The size

getDescriptors

public ArrayList<RegisterDescriptor> getDescriptors()

Returns the bit-field descriptor list

Returns:

The list

getMap

public HashMap<String, RegisterDescriptor> getMap()

Returns the descriptor map

Returns:

The map

streamRegisterDescriptors

public Stream<RegisterDescriptor> streamRegisterDescriptors()

Returns a Collection stream.

Returns:

The stream

get

public String get(String key)

Gets hex string representation of bit-field

Parameters:

key - The bit-field key

Returns:

String containg hex representation of bit-field

get

public String get(String key,
 BitSet bits)

Gets hex string representation of bit-field

This variant allows a bit-field to be retrieved from a BitSet that is not necessarily the internally cached version.

Parameters:

key - The bit-field key

bits - A BitSet containing the register values

Returns:

String containg hex representation of bit-field

get

public String get(String key,
 byte[] regs)

Gets hex string representation of bit-field

This variant allows a bit-field to be retrieved from a byte array that is assumed to have the same shape as the register array described by this CsrBitSet.

Parameters:

key - The bit-field key

regs - A byte array containing the register values

Returns:

String containg hex representation of bit-field

set

public void set(File cf)

Initialises the CsrBitSet from binary file

The BitSet cache is initialised from the binary data. The previous content, is discarded.

Parameters:

cf - A File containing the binary data

set

public void set(File cf,
 int skip)

Initialises the CsrBitSet from a binary file.

Parameters:

cf - The configuration file.

skip - The number of csrSize blocks in the file to skip

set

public void set(FileReader fr)

Read the register settings from file and update CsrBitSet.

Parameters:

fr - The FileReader from where the values will be read

saveToBinaryFile

public void saveToBinaryFile(File file)

saveToBinaryFile

public void saveToBinaryFile()

set

public void set(byte[] buf)

Initialises the CsrBitSet from a byte array

The BitSet cache is initialised from the binary data. The previous content, is discarded.

Parameters:

buf - A byte array

valueOf

public static String valueOf(Object obj)

Converts value into String representation

Types String, Integer and Boolean are allowed. Throws a RuntimeException for any other type.

Parameters:

obj - The value

Returns:

The hex String representation

getPrefsValue

static String getPrefsValue(String key,
 Preferences prefs,
 Object defaultValue)

Converts a value from a Preference into String representation

Types String, Integer and Boolean are allowed. Throws a RuntimeException for any other type.

Parameters:

key - The key in the Preferences node

prefs - The Preferences node

defaultValue - The default value if the Preference does not exist

Returns:

The hex String representation

set

public <T> void set(String key,
 T value)

Sets bit-field

Type Parameters:

T - Type of the value to set

Parameters:

key - The bit-field key

value - The value to set

set

public <T> void set(String key,
 Preferences prefs,
 T defaultValue)

Sets the register bits from value stored in Java Preference

This is a convenience method for when the bit-field should be set according to a value stored as a Java Preference.

key is both the XML key and the preference key name

The default value is applied if no Preference is found.

Type Parameters:

T - Type of the value to set

Parameters:

key - The bit-field key

prefs - The Preferences node

defaultValue - Default value

setRegex

public void setRegex(String key,
 String val)

Writes the value to all register bit-fields matching a regular expression.

Parameters:

key - The register bit-field key name regular expression.

val - The value to write.

stream

public Stream<RegisterDescriptor> stream(String regex)

Get a stream of registers whose name matches the supplied regex

Parameters:

regex - The pattern to match with the bit-field key

Returns:

The stream

stream

public Stream<RegisterDescriptor> stream(String regex,
 String value)

Get a stream of registers whose name matches the supplied regex and content matches the supplied value.

Parameters:

regex - The pattern to match with the bit-field key

value - The value to match with the bit-field content

Returns:

The stream

streamComplement

public Stream<RegisterDescriptor> streamComplement(String regex,
 String value)

Get a stream of registers whose name matches the supplied regex and content does not match the supplied value.

Parameters:

regex - The pattern to match with the bit-field key

value - The value to match with the bit-field content

Returns:

The stream

toByteArray

public byte[] toByteArray(int arrayOffset)

Returns a new byte array containing the register values

The method creates an array of bytes containing the cached register values starting arrayOffset bytes from the start of the register array.

Parameters:

arrayOffset - Offset from register array start

Returns:

The register values

getRegisterDescriptor

public RegisterDescriptor getRegisterDescriptor(String key)

Returns the RegisterDescriptor for the given key

Parameters:

key - The bit-field key

Returns:

The register descriptor

getBytes

@Deprecated
public byte[] getBytes(String key,
 int arrayOffset)

Deprecated.

Returns a new byte array containing the value of the specified bit-field

The method creates an array of bytes containing the cached bit-field value. The value is offset arrayOffset bytes from the start of the returned array.

Parameters:

key - The bit-field key

arrayOffset - Offset from register array start

Returns:

The register values

decode

public void decode()

Displays the values of all bit-fields on System.out

decode

public void decode(BitSet bits)

Displays the values of all bit-fields on System.out

Parameters:

bits - The CSR bits.