origen 0.0.1 → 0.0.2

data/lib/origen/registers/bit_collection.rb

@@ -0,0 +1,787 @@
+module Origen
+  module Registers
+    # This is a regular Ruby array that is used to store collections of Bit objects, it has additional
+    # methods added to allow interaction with the contained bits.
+    # All Ruby array methods are also available - http://www.ruby-doc.org/core/classes/Array.html
+    #
+    # A BitCollection is returned whenever a subset of bits is requested from a register. Also whenever
+    # any of these methods are called on a register object a BitCollection is created on the fly that
+    # contains all bits in the register. This means that when interacting with a Register, a single Bit,
+    # or a group of Bit objects, the same API can be used as described below.
+    class BitCollection < Array
+      include Origen::SubBlocks::Path
+
+      DONT_CARE_CHAR = 'X'
+      OVERLAY_CHAR = 'V'
+      STORE_CHAR = 'S'
+
+      attr_accessor :name
+
+      def initialize(reg, name, data = []) # :nodoc:
+        if reg.respond_to?(:has_bits_enabled_by_feature?) && reg.has_parameter_bound_bits?
+          reg.update_bound_bits unless reg.updating_bound_bits?
+        end
+        @reg = reg
+        @name = name
+        [data].flatten.each { |item| self << item }
+      end
+
+      def bind(live_parameter)
+        parent.bind(name, live_parameter)
+      end
+
+      def [](*indexes)
+        return self if indexes.empty?
+        b = BitCollection.new(parent, name)
+        expand_and_order(*indexes).each do |i|
+          b << fetch(i)
+        end
+        # When 1 bit requested just return that bit, this is consistent with the original
+        # behaviour before sub collections were added
+        if b.size == 1
+          b.first
+        else
+          b
+        end
+      end
+      alias_method :bits, :[]
+      alias_method :bit, :[]
+
+      def parent
+        @reg
+      end
+
+      def path_var
+        if first.path_var
+          if first.path_var =~ /^\./
+            base = parent.path(relative_to: parent.parent)
+            "#{base}#{first.path_var}"
+          else
+            first.path_var
+          end
+        else
+          base = parent.path(relative_to: parent.parent)
+          if size == 1
+            "#{base}[#{position}]"
+          else
+            "#{base}[#{position + size - 1}:#{position}]"
+          end
+        end
+      end
+
+      def abs_path
+        first.abs_path
+      end
+
+      Bit::ACCESS_CODES.each do |code, _meta|
+        define_method "#{code}?" do
+          all? { |b| b.undefined? || b.send("#{code}?") }
+        end
+      end
+
+      # Copies all data and flags from one bit collection (or reg) object to another
+      #
+      # This method will accept a dumb value as the argument, in which case it is essentially a write,
+      # however it will also clear all flags.
+      def copy_all(reg)
+        if reg.respond_to?(:contains_bits?) && reg.contains_bits?
+          unless reg.size == size
+            puts 'Bit collection copy must be performed on collections of the same size.'
+            puts 'You can fix this by calling copy on a subset of the bits you require, e.g.'
+            puts '  larger_bit_collection[3..0].copy_all(smaller_bit_collection)'
+            puts
+            fail 'Mismatched size for bit collection copy'
+          end
+          size.times do |i|
+            source_bit = reg.bit[i]
+            if source_bit
+              self[i].overlay(source_bit.overlay_str) if source_bit.has_overlay?
+              self[i].write(source_bit.data)
+
+              self[i].read if source_bit.is_to_be_read?
+              self[i].store if source_bit.is_to_be_stored?
+            end
+          end
+        else
+          write(reg)
+          clear_flags
+        end
+        self
+      end
+
+      # Returns the access attribute of the first contained bit, in most normal use cases
+      # the application will naturally guarantee that when this is called all of the bits
+      # in the collection have the same access value.
+      #
+      # If you are worried about hitting the case where some bits have different values then
+      # use access!, but this will be a bit less efficient
+      def access(value = nil)
+        if value.nil?
+          first.access
+        else # set access
+          each { |b| b.set_access(value) }
+          self
+        end
+      end
+
+      # Like access but will raise an error if not all bits in the collection have the same
+      # access value
+      def access!
+        val = access
+        if any? { |b| b.access != val }
+          fail 'Not all bits the collection have the same access value!'
+        end
+        val
+      end
+
+      # Returns the description of the given bit(s) if any, if none then an empty array
+      # will be returned
+      #
+      # **Note** Adding a description field will override any comment-driven documentation
+      # of a bit collection (ie markdown style comments)
+      def description(bitname = nil, options = {})
+        bitname, options = nil, bitname if bitname.is_a?(Hash)
+        if name == :unknown
+          []
+        else
+          @reg.description(name, options)
+        end
+      end
+
+      def full_name(bitname = nil, options = {})
+        bitname, options = nil, bitname if bitname.is_a?(Hash)
+        unless name == :unknown
+          @reg.full_name(name, options)
+        end
+      end
+
+      def bit_value_descriptions(_bitname = nil)
+        if name == :unknown
+          []
+        else
+          @reg.bit_value_descriptions(name)
+        end
+      end
+
+      # Returns a dummy bit collection that is populated with un-writable bits that will
+      # read back as 0. This can be useful for padding out spaces in registers with something that
+      # responds like conventional bits.
+      def self.dummy(reg, name = nil, options = {})
+        name, options = nil, name if name.is_a?(Hash)
+        options = {
+          size: 8,
+          pos:  0
+        }.merge(options)
+        collection = new(reg, name)
+        pos = options[:pos]
+        options[:size].times do
+          bit = Bit.new(reg, pos, writable: false, feature: :dummy_feature)
+          collection << bit
+          pos += 1
+        end
+        collection
+      end
+
+      def contains_bits?
+        true
+      end
+
+      def inspect
+        "<#{self.class}:#{object_id}>"
+      end
+
+      # Returns the LSB position of the collection
+      def position
+        first.position
+      end
+
+      # Returns the data value held by the collection
+      # ==== Example
+      #   reg(:control).write(0x55)
+      #   reg(:control).data         #  => 0x55, assuming the reg has the required bits to store that
+      def data
+        data = 0
+        each_with_index { |bit, i| data |= bit.data << i }
+        data
+      end
+      alias_method :val, :data
+      alias_method :value, :data
+
+      # Returns the inverse of the data value held by the collection
+      def data_b
+        # (& operation takes care of Bignum formatting issues)
+        ~data & ((1 << size) - 1)
+      end
+
+      # Supports reg.bit[0] and bitcollection.bit[0]
+      def bit
+        self
+      end
+
+      # Set the data value of the collection within the patgen, but not on silicon - i.e. calling
+      # write will not trigger a pattern write event.
+      def write(value, options = {})
+        # If an array is written it means a data value and an overlay have been supplied
+        # in one go...
+        if value.is_a?(Array) && !value.is_a?(BitCollection)
+          overlay(value[1])
+          value = value[0]
+        end
+        value = value.data if value.respond_to?('data')
+        each_with_index { |bit, i| bit.write(value[i], options) }
+        self
+      end
+      alias_method :data=, :write
+      alias_method :value=, :write
+      alias_method :val=, :write
+
+      # Will tag all bits for read and if a data value is supplied it
+      # will update the expected data for when the read is performed.
+      def read(value = nil, options = {}) # :nodoc:
+        # First properly assign the args if value is absent...
+        if value.is_a?(Hash)
+          options = value
+          value = nil
+        end
+        if value
+          value = Reg.clean_value(value)
+          write(value)
+        end
+        if options[:mask]
+          each_with_index { |bit, i| bit.read if options[:mask][i] == 1 }
+          each_with_index { |bit, i| bit.clear_read_flag if options[:mask][i] == 0 }
+        else
+          each(&:read)
+        end
+        self
+      end
+
+      # Returns a value representing the bit collection / register where a bit value of
+      # 1 means the bit is enabled for the given operation.
+      def enable_mask(operation)
+        str = ''
+        shift_out_left do |bit|
+          if operation == :store && bit.is_to_be_stored? ||
+             operation == :read && bit.is_to_be_read? ||
+             operation == :overlay && bit.has_overlay?
+            str += '1'
+          else
+            str += '0'
+          end
+        end
+        str.to_i(2)
+      end
+
+      # Attaches the supplied overlay string to all bits
+      # ==== Example
+      # reg(:data).overlay("data_val")
+      def overlay(value)
+        each { |bit| bit.overlay(value) }
+        self
+      end
+
+      # Resets all bits, this clears all flags and assigns the data value
+      # back to the reset state
+      def reset
+        each(&:reset)
+        self
+      end
+
+      # Shifts out a stream of bit objects corresponding to the size of the BitCollection. i.e. calling
+      # this on a 16-bit register this will pass back 16 bit objects.
+      # If there are holes in the given register then a dummy bit object will be returned that
+      # is not writable and which will always read as 0.
+      # ==== Example
+      #   reg(:data).shift_out_left do |bit|
+      #       bist_shift(bit)
+      #   end
+      def shift_out_left
+        reverse_each { |bit| yield bit }
+      end
+
+      # Same as Reg#shift_out_left but starts from the MSB
+      def shift_out_right
+        each { |bit| yield bit }
+      end
+
+      # Returns true if any bits have the read flag set - see Bit#is_to_be_read?
+      # for more details.
+      def is_to_be_read?
+        any?(&:is_to_be_read?)
+      end
+
+      # Returns true if any bits have the store flag set - see Bit#is_to_be_stored?
+      # for more details.
+      def is_to_be_stored?
+        any?(&:is_to_be_stored?)
+      end
+
+      # Returns true if any bits have the update_required flag set - see Bit#update_required?
+      # for more details.
+      def update_required?
+        any?(&:update_required?)
+      end
+
+      # Calls the clear_flags method on all bits, see Bit#clear_flags for more details
+      def clear_flags
+        each(&:clear_flags)
+        self
+      end
+
+      # Returns the value you would need to write to the register to put the given
+      # value in these bits
+      def setting(value)
+        result = 0
+        each_with_index do |bit, i|
+          result |= bit.setting(value[i])
+        end
+        result
+      end
+
+      # Returns true if any bits within are tagged for overlay, supply a specific name
+      # to require a specific overlay only
+      # ==== Example
+      #   myreg.overlay("data")
+      #   myreg.has_overlay?              # => true
+      #   myreg.has_overlay?("address")   # => false
+      #   myreg.has_overlay?("data")      # => true
+      def has_overlay?(name = nil)
+        any? { |bit| bit.has_overlay?(name) }
+      end
+
+      # Cycles through all bits and returns the last overlay value found, it is assumed therefore
+      # that all bits have the same overlay value when calling this method
+      # ==== Example
+      #   myreg.overlay("data")
+      #
+      #   myreg.overlay_str   # => "data"
+      def overlay_str
+        result = ''
+        each do |bit|
+          result = bit.overlay_str if bit.has_overlay?
+        end
+        result.to_s
+      end
+
+      # Write the bit value on silicon<br>
+      # This method will update the data value of the bits and then call $top.write_register
+      # passing the owngin register as the first argument.<br>
+      # This method is expected to handle writing the current state of the register to silicon.
+      def write!(value = nil, options = {})
+        value, options = nil, value if value.is_a?(Hash)
+        write(value, options) if value
+        @reg.request(:write_register, options)
+        self
+      end
+
+      # Similar to write! this method will perform the standard read method and then make
+      # a call to $top.read_register(self) with the expectation that this method will
+      # implement a read event in the pattern.
+      # ==== Example
+      #   reg(:data).read!         # Read register :data, expecting whatever value it currently holds
+      #   reg(:data).read!(0x5555) # Read register :data, expecting 0x5555
+      def read!(value = nil, options = {})
+        value, options = nil, value if value.is_a?(Hash)
+        read(value, options)
+        # launch a read reg
+        @reg.request(:read_register, options)
+        self
+      end
+
+      # Normally whenever a register is processed by the $top.read_register method
+      # it will call Reg#clear_flags to acknowledge that the read has been performed,
+      # which clears the read and store flags for the given bits. Normally however you
+      # want overlays to stick around such that whenever a given bit is written/read its
+      # data is always picked from an overlay.<br>
+      # Call this passing in false for a given register to cause the overlay data to also
+      # be cleared by Reg#clear_flags.
+      # ==== Example
+      #   reg(:data).overlay("data_val")
+      #   reg(:data).has_overlay?           # => true
+      #   reg(:data).clear_flags
+      #   reg(:data).has_overlay?           # => true
+      #   reg(:data).sticky_overlay(false)
+      #   reg(:data).clear_flags
+      #   reg(:data).has_overlay?           # => false
+      def sticky_overlay(set = true)
+        each { |bit| bit.sticky_overlay = set }
+        self
+      end
+      alias_method :sticky_overlays, :sticky_overlay
+
+      # Similar to sticky_overlay this method affects how the store flags are treated by
+      # Reg#clear_flags.<br>
+      # The default is that store flags will get cleared  by Reg#clear_flags, passing true
+      # into this method will override this and prevent them from clearing.
+      # ==== Example
+      #   reg(:data).sticky_store(true)
+      #   reg(:data).store
+      #   reg(:data).clear_flags         # Does not clear the request to store
+      def sticky_store(set = true)
+        each { |bit| bit.sticky_store = set }
+        self
+      end
+
+      # Marks all bits to be stored
+      def store
+        each(&:store)
+        self
+      end
+
+      # Marks all bits to be stored and then calls read!
+      def store!
+        store
+        read!
+        self
+      end
+
+      # Sets the store flag on all bits that already have the overlay flag set
+      # and then calls $top.read_register passing self as the first argument
+      def store_overlay_bits!(options = {})
+        store_overlay_bits(options)
+        @reg.request(:read_register, options) # Bypass the normal read method since we don't want to
+        # tag the other bits for read
+        self
+      end
+
+      # Sets the store flag on all bits that already have the overlay flag set
+      def store_overlay_bits(options = {})
+        options = { exclude: [],         # Pass in an array of any overlays that are to be excluded from store
+                  }.merge(options)
+        each do |bit|
+          bit.store if bit.has_overlay? && !options[:exclude].include?(bit.overlay_str)
+        end
+        self
+      end
+
+      # Will yield all unique overlay strings attached to the bits within the collection.
+      # It will also return the number of bits for the overlay (the length) and the current
+      # data value held in those bits.
+      # ==== Example
+      #   reg(:control).unique_overlays do |str, length, data|
+      #       do_something(str, length, data)
+      #   end
+      def unique_overlays
+        current_overlay = false
+        length = 0
+        data = 0
+        shift_out_right do |bit|
+          # Init the current overlay when the first one is encountered
+          current_overlay = bit.overlay_str if bit.has_overlay? && !current_overlay
+
+          if bit.has_overlay?
+            if bit.overlay_str != current_overlay
+              yield current_overlay, length, data if current_overlay
+              length = 0
+              data = 0
+            end
+
+            data = data | (bit.data << length)
+            length += 1
+          else
+            yield current_overlay, length, data if current_overlay
+            length = 0
+            data = 0
+            current_overlay = false
+          end
+        end
+        yield current_overlay, length, data if current_overlay
+      end
+
+      # Append a value, for example a block identifier, to all overlays
+      # ==== Example
+      #   reg(:data).overlay("data_val")
+      #   reg(:data).append_overlays("_0")
+      #   reg(:data).overlay_str           # => "data_val_0"
+      def append_overlays(value)
+        each do |bit|
+          bit.overlay(bit.overlay_str + value) if bit.has_overlay?
+        end
+        self
+      end
+
+      # Delete the contained bits from the parent Register
+      def delete
+        @reg.delete_bits(self)
+        self
+      end
+
+      def add_name(name) # :nodoc:
+        if @name == :unknown
+          @name = name
+        elsif ![name].flatten.include?(name)
+          @name = [@name, name].flatten
+        end
+        self
+      end
+
+      def owner
+        first.owner
+      end
+
+      # All other methods send to bit 0
+      def method_missing(method, *args, &block) # :nodoc:
+        if first.respond_to?(method)
+          if size > 1
+            if [:meta, :meta_data, :metadata].include?(method.to_sym) ||
+               first.meta_data_method?(method)
+              first.send(method, *args, &block)
+            else
+              fail "Error, calling #{method} on a multi-bit collection is not implemented!"
+            end
+          else
+            first.send(method, *args, &block)
+          end
+        else
+          fail "BitCollection does not have a method named #{method}!"
+        end
+      end
+
+      # Recognize that BitCollection responds to some Bit methods via method_missing
+      def respond_to?(sym) # :nodoc:
+        first.respond_to?(sym) || super(sym)
+      end
+
+      # Returns true if the values of all bits in the collection are known. The value will be
+      # unknown in cases where the reset value is undefined or determined by a memory location
+      # and where the register has not been written or read to a specific value yet.
+      def has_known_value?
+        all?(&:has_known_value?)
+      end
+
+      # Returns the reset value of the collection, note that this does not reset the register and the
+      # current data is maintained.
+      #
+      # ==== Example
+      #   reg(:control).write(0x55)
+      #   reg(:control).data         #  => 0x55
+      #   reg(:control).reset_data   #  => 0x11, assuming the reg was declared with a reset value of 0x11
+      #   reg(:control).data         #  => 0x55
+      def reset_data(value = nil)
+        # This method was originally setup to set the reset value by passing an argument
+        if value
+          each_with_index { |bit, i| bit.reset_val = value[i] }
+          self
+        else
+          data = 0
+          each_with_index do |bit, i|
+            return bit.reset_data if bit.reset_data.is_a?(Symbol)
+            data |= bit.reset_data << i
+          end
+          data
+        end
+      end
+      alias_method :reset_val, :reset_data
+      alias_method :reset_value, :reset_data
+      alias_method :reset_data=, :reset_data
+      alias_method :reset_val=, :reset_data
+      alias_method :reset_value=, :reset_data
+
+      # Modify writable for bits in collection
+      def writable(value)
+        each_with_index { |bit, i| bit.writable = (value[i] == 0b1); bit.set_access_from_rw }
+        self
+      end
+
+      # Modify readable for bits in collection
+      def readable(value)
+        each_with_index { |bit, i| bit.readable = (value[i] == 0b1); bit.set_access_from_rw }
+        self
+      end
+
+      def feature
+        feature = []
+        feature << fetch(0).feature
+        each { |bit| feature << bit.feature if bit.has_feature_constraint? }
+        feature = feature.flatten.uniq unless feature.empty?
+        feature.delete(nil) if feature.include?(nil)
+        if !feature.empty?
+          if feature.size == 1
+            return feature[0]
+          else
+            return feature.uniq
+          end
+        else
+          if Origen.config.strict_errors
+            fail 'No feature found'
+          end
+          return nil
+        end
+      end
+      alias_method :features, :feature
+
+      # Return true if there is any feature associated with these bits
+      def has_feature_constraint?(name = nil)
+        if !name
+          any?(&:has_feature_constraint?)
+        else
+          any? { |bit| bit.enabled_by_feature?(name) }
+        end
+      end
+      alias_method :enabled_by_feature?, :has_feature_constraint?
+
+      def enabled?
+        all?(&:enabled?)
+      end
+
+      # Returns true if any bits in the collection are writable
+      def is_writable?
+        any?(&:writable?)
+      end
+      alias_method :writable?, :is_writable?
+
+      # Returns true if any bits in the collection are readable
+      def is_readable?
+        any?(&:readable?)
+      end
+      alias_method :readable?, :is_readable?
+
+      # Modify clr_only for bits in collection
+      def clr_only(value)
+        each_with_index { |bit, i| bit.clr_only = (value[i] == 0b1) }
+        self
+      end
+
+      # Modify set_only for bits in collection
+      def set_only(value)
+        each_with_index { |bit, i| bit.set_only = (value[i] == 0b1) }
+        self
+      end
+
+      # Return nvm_dep value held by collection
+      def nvm_dep
+        nvm_dep = 0
+        each_with_index { |bit, i| nvm_dep |= bit.nvm_dep << i }
+        nvm_dep
+      end
+
+      # Clear any w1c set bits back to 0
+      def clear_w1c
+        each(&:clear_w1c)
+        self
+      end
+
+      # Clear any start set bits back to 0
+      def clear_start
+        each(&:clear_start)
+        self
+      end
+
+      # Provides a string summary of the bit collection / register state that would be
+      # applied to given operation (write or read).
+      # This is mainly intended to be useful when generating pattern comments describing
+      # an upcoming register transaction.
+      #
+      # This highlights not only bit values bit the status of any flags or overlays that
+      # are currently set.
+      #
+      # The data is presented in hex nibble format with individual nibbles are expanded to
+      # binary format whenever all 4 bits do not have the same status - e.g. if only one
+      # of the four is marked for read.
+      #
+      # The following symbols are used to represent bit state:
+      #
+      # X - Bit is don't care (not marked for read)
+      # V - Bit has been tagged with an overlay
+      # S - Bit is marked for store
+      #
+      # @example
+      #
+      #   myreg.status_str(:write)   # => "0000"
+      #   myreg.status_str(:read)    # => "XXXX"
+      #   myreg[7..4].read(5)
+      #   myreg.status_str(:read)    # => "XX5X"
+      #   myreg[14].read(0)
+      #   myreg.status_str(:read)    # => "(x0xx)X5X"
+      def status_str(operation, options = {})
+        options = {
+          mark_overlays: true
+        }.merge(options)
+        str = ''
+        if operation == :read
+          shift_out_left do |bit|
+            if bit.is_to_be_stored?
+              str += STORE_CHAR
+            elsif bit.is_to_be_read?
+              if bit.has_overlay? && options[:mark_overlays]
+                str += OVERLAY_CHAR
+              else
+                str += bit.data.to_s
+              end
+            else
+              str += DONT_CARE_CHAR
+            end
+          end
+        elsif operation == :write
+          shift_out_left do |bit|
+            if bit.has_overlay? && options[:mark_overlays]
+              str += OVERLAY_CHAR
+            else
+              str += bit.data.to_s
+            end
+          end
+        else
+          fail "Unknown operation (#{operation}), must be :read or :write"
+        end
+        make_hex_like(str, size / 4)
+      end
+
+      private
+
+      # Converts a binary-like representation of a data value into a hex-like version.
+      # e.g. input  => 010S0011SSSS0110   (where S, X or V represent store, don't care or overlay)
+      #      output => (010s)3S6    (i.e. nibbles that are not all of the same type are expanded)
+      def make_hex_like(regval, size_in_nibbles)
+        outstr = ''
+        regex = '^'
+        size_in_nibbles.times { regex += '(....)' }
+        regex += '$'
+        Regexp.new(regex) =~ regval
+
+        nibbles = []
+        size_in_nibbles.times do |n|                   # now grouped by nibble
+          nibbles << Regexp.last_match[n + 1]
+        end
+
+        nibbles.each_with_index do |nibble, i|
+          # If contains any special chars...
+          if nibble =~ /[#{DONT_CARE_CHAR}#{STORE_CHAR}#{OVERLAY_CHAR}]/
+            # If all the same...
+            if nibble[0] == nibble[1] && nibble[1] == nibble[2] && nibble[2] == nibble[3]
+              outstr += nibble[0, 1] # .to_s
+            # Otherwise present this nibble in 'binary' format
+            else
+              outstr += "(#{nibble.downcase})"
+            end
+          # Otherwise if all 1s and 0s...
+          else
+            outstr += '%1X' % nibble.to_i(2)
+          end
+        end
+        outstr
+      end
+
+      # Cleans up indexed references to pins, e.g. makes these equal:
+      #
+      #   bits(:data)[0,1,2,3]
+      #   bits(:data)[3,2,1,0]
+      #   bits(:data)[0..3]
+      #   bits(:data)[3..0]
+      def expand_and_order(*indexes)
+        ixs = []
+        indexes.flatten.each do |index|
+          if index.is_a?(Range)
+            if index.first > index.last
+              ixs << (index.last..index.first).to_a
+            else
+              ixs << index.to_a
+            end
+          else
+            ixs << index
+          end
+        end
+        ixs.flatten.sort
+      end
+    end
+  end
+end