Package cbsw

Class CsrBitSet

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable
    public class CsrBitSet
extends java.util.BitSet
implements java.lang.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

    • Method Summary

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

      • Methods inherited from class java.util.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 java.lang.Object

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

    • Method Detail

      • clone

        public java.lang.Object clone()
        Overrides:
        clone in class java.util.BitSet

      • getRoBits

        public java.util.BitSet getRoBits()

      • getCsrSize

        public int getCsrSize()

        Returns the CSR size

        Returns:
        The size

      • getDescriptors

        public java.util.ArrayList<RegisterDescriptor> getDescriptors()

        Returns the bit-field descriptor list

        Returns:
        The list

      • getMap

        public java.util.HashMap<java.lang.String,​RegisterDescriptor> getMap()

        Returns the descriptor map

        Returns:
        The map

      • streamRegisterDescriptors

        public java.util.stream.Stream<RegisterDescriptor> streamRegisterDescriptors()

        Returns a Collection stream.

        Returns:
        The stream

      • get

        public java.lang.String get​(java.lang.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 java.lang.String get​(java.lang.String key,
                            java.util.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 java.lang.String get​(java.lang.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​(java.io.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​(java.io.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​(java.io.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​(java.io.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 java.lang.String valueOf​(java.lang.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 java.lang.String getPrefsValue​(java.lang.String key,
                                      java.util.prefs.Preferences prefs,
                                      java.lang.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​(java.lang.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​(java.lang.String key,
                    java.util.prefs.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​(java.lang.String key,
                     java.lang.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 java.util.stream.Stream<RegisterDescriptor> stream​(java.lang.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 java.util.stream.Stream<RegisterDescriptor> stream​(java.lang.String regex,
                                                          java.lang.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 java.util.stream.Stream<RegisterDescriptor> streamComplement​(java.lang.String regex,
                                                                    java.lang.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​(java.lang.String key)

        Returns the RegisterDescriptor for the given key

        Parameters:
        key - The bit-field key
        Returns:
        The register descriptor

      • getBytes

        @Deprecated
public byte[] getBytes​(java.lang.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​(java.util.BitSet bits)

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

        Parameters:
        bits - The CSR bits.