origen 0.34.3 → 0.52.0

data/lib/origen/ports/port.rb

@@ -68,6 +68,11 @@ module Origen
         end
       end
 
+      # Prevent infinite loop if a child bit collection checks bit_order
+      def bit_order
+        parent.bit_order
+      end
+
       def drive(value = nil, options = {})
         value, options = nil, value if value.is_a?(Hash)
         if options[:index]

data/lib/origen/registers.rb

@@ -140,6 +140,11 @@ module Origen
         @name = name
         @attributes = attributes
         @feature = attributes[:_feature] if attributes.key?(:_feature)
+
+        # Give reg.new a way to tell if coming from Placeholder
+        if attributes[:bit_info].is_a? Hash
+          attributes[:bit_info][:from_placeholder] = true
+        end
       end
 
       # Make this appear like a reg to any application code

data/lib/origen/registers/bit.rb

@@ -5,35 +5,41 @@ module Origen
       # The :access property of registers or bits can be set to any of the following
       # key values. Implemented refers to whether the behaviour is accurately modelled
       # by the Origen register model or not.
+      #
+      # :base is used in CrossOrigen to set the IP-XACT access type on export.
+      #
+      # :read and :write are used in CrossOrigen for IP-XACT export to cover 'readAction'
+      # and 'modifiedWriteValue' attributes in the IEEE 1685-2009 schema - they do not affect
+      # Origen Core functionality (yet?).
       ACCESS_CODES = {
-        ro:    { implemented: false, description: 'Read-Only' },
-        rw:    { implemented: true,  description: 'Read-Write' },
-        rc:    { implemented: false, description: 'Read-only, Clear-on-read' },
-        rs:    { implemented: false, description: "Set-on-read (all bits become '1' on read)" },
-        wrc:   { implemented: false, description: 'Writable, clear-on-read' },
-        wrs:   { implemented: false, description: 'Writable, Sets-on-read' },
-        wc:    { implemented: false, description: 'Clear-on-write' },
-        ws:    { implemented: false, description: 'Set-on-write' },
-        wsrc:  { implemented: false, description: 'Set-on-write, clear-on-read' },
-        wcrs:  { implemented: false, description: 'Clear-on-write, set-on-read' },
-        w1c:   { implemented: false, description: "Write '1' to clear bits" },
-        w1s:   { implemented: false, description: "Write '1' to set bits" },
-        w1t:   { implemented: false, description: "Write '1' to toggle bits" },
-        w0c:   { implemented: false, description: "Write '0' to clear bits" },
-        w0s:   { implemented: false, description: "Write '0' to set bits" },
-        w0t:   { implemented: false, description: "Write '0' to toggle bits" },
-        w1src: { implemented: false, description: "Write '1' to set and clear-on-read" },
-        w1crs: { implemented: false, description: "Write '1' to clear and set-on-read" },
-        w0src: { implemented: false, description: "Write '0' to set and clear-on-read" },
-        w0crs: { implemented: false, description: "Write '0' to clear and set-on-read" },
-        wo:    { implemented: false, description: 'Write-only' },
-        woc:   { implemented: false, description: "When written sets the field to '0'. Read undeterministic" },
-        worz:  { implemented: false, description: 'Write-only, Reads zero' },
-        wos:   { implemented: false, description: "When written sets all bits to '1'. Read undeterministic" },
-        w1:    { implemented: false, description: 'Write-once. Next time onwards, write is ignored. Read returns the value' },
-        wo1:   { implemented: false, description: 'Write-once. Next time onwards, write is ignored. Read is undeterministic' },
-        dc:    { implemented: false, description: 'RW but no check' },
-        rowz:  { implemented: false, description: 'Read-only, value is cleared on read' }
+        ro:    { implemented: false, base: 'read-only',      write: nil,            read: nil,      writable: false, readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Read-Only' },
+        rw:    { implemented: true,  base: 'read-write',     write: nil,            read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Read-Write' },
+        rc:    { implemented: false, base: 'read-only',      write: nil,            read: 'clear',  writable: false, readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Read-only, Clear-on-read' },
+        rs:    { implemented: false, base: 'read-only',      write: nil,            read: 'set',    writable: false, readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Set-on-read (all bits become '1' on read)" },
+        wrc:   { implemented: false, base: 'read-write',     write: nil,            read: 'clear',  writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Writable, clear-on-read' },
+        wrs:   { implemented: false, base: 'read-write',     write: nil,            read: 'set',    writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Writable, Sets-on-read' },
+        wc:    { implemented: false, base: 'read-write',     write: 'clear',        read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: true,  description: 'Clear-on-write' },
+        ws:    { implemented: false, base: 'read-write',     write: 'set',          read: nil,      writable: true,  readable: true,  w1c: false, set_only: true,   clr_only: false, description: 'Set-on-write' },
+        wsrc:  { implemented: false, base: 'read-write',     write: 'set',          read: 'clear',  writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Set-on-write, clear-on-read' },
+        wcrs:  { implemented: false, base: 'read-write',     write: 'clear',        read: 'set',    writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Clear-on-write, set-on-read' },
+        w1c:   { implemented: false, base: 'read-write',     write: 'oneToClear',   read: nil,      writable: true,  readable: true,  w1c: true,  set_only: false,  clr_only: false, description: "Write '1' to clear bits" },
+        w1s:   { implemented: false, base: 'read-write',     write: 'oneToSet',     read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '1' to set bits" },
+        w1t:   { implemented: false, base: 'read-write',     write: 'oneToToggle',  read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '1' to toggle bits" },
+        w0c:   { implemented: false, base: 'read-write',     write: 'zeroToClear',  read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '0' to clear bits" },
+        w0s:   { implemented: false, base: 'read-write',     write: 'zeroToSet',    read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '0' to set bits" },
+        w0t:   { implemented: false, base: 'read-write',     write: 'zeroToToggle', read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '0' to toggle bits" },
+        w1src: { implemented: false, base: 'read-write',     write: 'oneToSet',     read: 'clear',  writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '1' to set and clear-on-read" },
+        w1crs: { implemented: false, base: 'read-write',     write: 'oneToClear',   read: 'set',    writable: true,  readable: true,  w1c: true,  set_only: false,  clr_only: false, description: "Write '1' to clear and set-on-read" },
+        w0src: { implemented: false, base: 'read-write',     write: 'zeroToSet',    read: 'clear',  writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '0' to set and clear-on-read" },
+        w0crs: { implemented: false, base: 'read-write',     write: 'zeroToClear',  read: 'set',    writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: "Write '0' to clear and set-on-read" },
+        wo:    { implemented: false, base: 'write-only',     write: nil,            read: nil,      writable: true,  readable: false, w1c: false, set_only: false,  clr_only: false, description: 'Write-only' },
+        woc:   { implemented: false, base: 'write-only',     write: 'clear',        read: nil,      writable: true,  readable: false, w1c: false, set_only: false,  clr_only: true,  description: "When written sets the field to '0'. Read undeterministic" },
+        worz:  { implemented: false, base: 'write-only',     write: nil,            read: nil,      writable: true,  readable: false, w1c: false, set_only: false,  clr_only: false, description: 'Write-only, Reads zero' },
+        wos:   { implemented: false, base: 'write-only',     write: 'set',          read: nil,      writable: true,  readable: false, w1c: false, set_only: true,   clr_only: false, description: "When written sets all bits to '1'. Read undeterministic" },
+        w1:    { implemented: false, base: 'read-writeOnce', write: nil,            read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Write-once. Next time onwards, write is ignored. Read returns the value' },
+        wo1:   { implemented: false, base: 'writeOnce',      write: nil,            read: nil,      writable: true,  readable: false, w1c: false, set_only: false,  clr_only: false, description: 'Write-once. Next time onwards, write is ignored. Read is undeterministic' },
+        dc:    { implemented: false, base: 'read-write',     write: nil,            read: nil,      writable: true,  readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'RW but no check' },
+        rowz:  { implemented: false, base: 'read-only',      write: nil,            read: 'clear',  writable: false, readable: true,  w1c: false, set_only: false,  clr_only: false, description: 'Read-only, value is cleared on read' }
       }
 
       # Returns the Reg object that owns the bit
@@ -72,6 +78,10 @@ module Origen
       attr_writer :clr_only
       # Allow modify of set_only flag, bit can only be set (made 1)
       attr_writer :set_only
+      # Returns read_action - whether anything happens to the bit when read
+      attr_reader :read_action
+      # Returns mod_write_value - what write value modification occurs when written
+      attr_reader :mod_write_value
       # Returns true if bit depends on initial state of NVM in some way
       attr_reader :nvm_dep
       # Returns true if bit is critical to starting an important operation (like a state machine)
@@ -84,6 +94,11 @@ module Origen
       # Returns the access method for the given bit (a symbol), see the ACCESS_CODES constant for
       # the possible values this can have and their meaning
       attr_accessor :access
+      # Returns the basic access string for a given access method.  Possible values: read-write, read-only,
+      # write-only, writeOnce, read-writeOnce.  Used primarily by CrossOrigen IP-XACT import/export.
+      attr_reader :base_access
+      # Can be set to indicate that the current state of the bit is unknown, e.g. after reading X from a simulation
+      attr_accessor :unknown
 
       def initialize(owner, position, options = {}) # rubocop:disable MethodLength
         options = {
@@ -161,6 +176,10 @@ module Origen
         @meta = (default_bit_metadata).merge(options)
       end
 
+      def access_codes
+        ACCESS_CODES
+      end
+
       def set_access(value)
         unless ACCESS_CODES.keys.include?(value)
           puts 'Invalid access code, must be one of these:'
@@ -172,30 +191,15 @@ module Origen
         end
         @access = value
 
-        # Set readable & writable based on access
-        if @access == :ro
-          @readable = true
-          @writable = false
-        elsif @access == :wo || @access == :worz
-          @writable = true
-          @readable = false
-        elsif @access == :w1c
-          @w1c = true
-          @writable = true
-          @readable = true  # Is this always valid?
-        elsif @access == :wc
-          @clr_only = true
-          @writable = true
-          @readable = true  # Is this always valid?
-        elsif @access == :ws
-          @set_only = true
-          @writable = true
-          @readable = true  # Is this always valid?
-        # Catch all for now until the behavior of this class is based around @access
-        else
-          @writable = true
-          @readable = true
-        end
+        # Set access attributes by pulling key-value pairs from ACCESS_CODES[<access>]
+        @readable = ACCESS_CODES[@access][:readable]
+        @writable = ACCESS_CODES[@access][:writable]
+        @w1c = ACCESS_CODES[@access][:w1c]
+        @set_only = ACCESS_CODES[@access][:set_only]
+        @clr_only = ACCESS_CODES[@access][:clr_only]
+        @base_access = ACCESS_CODES[@access][:base]
+        @read_action = ACCESS_CODES[@access][:read]
+        @mod_write_value = ACCESS_CODES[@access][:write]
       end
 
       # Set @access based on @readable and @writable
@@ -288,7 +292,7 @@ module Origen
       # unknown in cases where the reset value is undefined or determined by a memory location
       # and where the bit has not been written or read to a specific value yet.
       def has_known_value?
-        !@reset_val.is_a?(Symbol) || @updated_post_reset
+        !@unknown && (!@reset_val.is_a?(Symbol) || @updated_post_reset)
       end
 
       # Set the data value of the bit to the given value (1 or 0)

data/lib/origen/registers/bit_collection.rb

@@ -15,16 +15,18 @@ module Origen
       DONT_CARE_CHAR = 'X'
       OVERLAY_CHAR = 'V'
       STORE_CHAR = 'S'
+      UNKNOWN_CHAR = '?'
 
       attr_accessor :name
       alias_method :id, :name
 
-      def initialize(reg, name, data = []) # :nodoc:
+      def initialize(reg, name, data = [], options = {}) # :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
+        @with_bit_order = options[:with_bit_order] || :lsb0
         [data].flatten.each { |item| self << item }
       end
 
@@ -33,6 +35,31 @@ module Origen
         parent.bit_order
       end
 
+      # Returns the bit numbering order to use when interpreting indeces
+      def with_bit_order
+        @with_bit_order
+      end
+
+      # Allow bit number interpreting to be explicitly set to msb0
+      def with_msb0
+        @with_bit_order = :msb0
+        self
+      end
+
+      # Allow bit number interpreting to be explicitly set to lsb0
+      def with_lsb0
+        if block_given?
+          # run just the code block with lsb0 numbering (for internal methods)
+          saved_wbo = @with_bit_order
+          @with_bit_order = :lsb0
+          yield
+          @with_bit_order = saved_wbo
+        else
+          @with_bit_order = :lsb0
+          self
+        end
+      end
+
       def terminal?
         true
       end
@@ -41,6 +68,24 @@ module Origen
         parent.bind(name, live_parameter)
       end
 
+      # Access bits by index
+      #
+      # **Note** This method behaves differently depending on the setting of @with_bit_order
+      #
+      # If @with_bit_order == :lsb0 (default) index 0 refers to the lsb of the bit collection
+      # If @with_bit_order == :msb0 index 0 refers to the msb of the bit collection
+      #
+      # ==== Example
+      #   dut.reg(:some_reg).bits(:some_field).with_msb0[0..1] # returns 2 most significant bits
+      #   dut.reg(:some_reg).bits(:some_field)[0..1]           # returns 2 least significant bits
+      #
+      # **Note**  Internal methods should call this method using a with_lsb0 block around the code
+      # or alternatively use the shift_out methods
+      # ==== Example
+      #   with_lsb0 do
+      #     saved_bit = [index]
+      #     [index] = some_new_bit_or_operation
+      #   end
       def [](*indexes)
         return self if indexes.empty?
         b = BitCollection.new(parent, name)
@@ -52,7 +97,8 @@ module Origen
         if b.size == 1
           b.first
         else
-          b
+          # maintain downstream bit numbering setting
+          @with_bit_order == :msb0 ? b.with_msb0 : b
         end
       end
       alias_method :bits, :[]
@@ -174,16 +220,18 @@ module Origen
             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?
+          # safely handle collections with differing with_bit_order settings
+          with_lsb0 do
+            reg.shift_out_with_index do |source_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
-          end
+          end # of with_lsb0
         else
           write(reg)
           clear_flags
@@ -331,8 +379,10 @@ module Origen
         end
         value = value.data if value.respond_to?('data')
 
-        size.times do |i|
-          self[i].write(value[i], options)
+        with_lsb0 do
+          size.times do |i|
+            self[i].write(value[i], options)
+          end
         end
         self
       end
@@ -340,6 +390,11 @@ module Origen
       alias_method :value=, :write
       alias_method :val=, :write
 
+      # Sets the unknown attribute on all contained bits
+      def unknown=(val)
+        each { |bit| bit.unknown = val }
+      end
+
       # 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:
@@ -402,38 +457,26 @@ module Origen
       #       bist_shift(bit)
       #   end
       def shift_out_left
-        if bit_order == :msb0
-          each { |bit| yield bit }
-        else
-          reverse_each { |bit| yield bit }
-        end
+        # This is functionally equivalent to reverse_shift_out
+        reverse_each { |bit| yield bit }
       end
 
       # Same as Reg#shift_out_left but includes the index counter
       def shift_out_left_with_index
-        if bit_order == :msb0
-          each.with_index { |bit, i| yield bit, i }
-        else
-          reverse_each.with_index { |bit, i| yield bit, i }
-        end
+        # This is functionally equivalent to reverse_shift_out_with_index
+        reverse_each.with_index { |bit, i| yield bit, i }
       end
 
-      # Same as Reg#shift_out_left but starts from the MSB
+      # Same as Reg#shift_out_left but starts from the LSB
       def shift_out_right
-        if bit_order == :msb0
-          reverse_each { |bit| yield bit }
-        else
-          each { |bit| yield bit }
-        end
+        # This is functionally equivalent to shift_out, actually sends LSB first
+        each { |bit| yield bit }
       end
 
       # Same as Reg#shift_out_right but includes the index counter
       def shift_out_right_with_index
-        if bit_order == :msb0
-          reverse_each.with_index { |bit, i| yield bit, i }
-        else
-          each_with_index { |bit, i| yield bit, i }
-        end
+        # This is functionally equivalent to shift_out_with_index
+        each_with_index { |bit, i| yield bit, i }
       end
 
       # Yields each bit in the register, LSB first.
@@ -865,7 +908,11 @@ module Origen
               if bit.has_overlay? && options[:mark_overlays]
                 str += OVERLAY_CHAR
               else
-                str += bit.data.to_s
+                if bit.has_known_value?
+                  str += bit.data.to_s
+                else
+                  str += UNKNOWN_CHAR
+                end
               end
             else
               str += DONT_CARE_CHAR
@@ -876,13 +923,17 @@ module Origen
             if bit.has_overlay? && options[:mark_overlays]
               str += OVERLAY_CHAR
             else
-              str += bit.data.to_s
+              if bit.has_known_value?
+                str += bit.data.to_s
+              else
+                str += UNKNOWN_CHAR
+              end
             end
           end
         else
           fail "Unknown operation (#{operation}), must be :read or :write"
         end
-        make_hex_like(str, size / 4)
+        make_hex_like(str, (size / 4.0).ceil)
       end
 
       # Shifts the data in the collection left by one place. The data held
@@ -935,11 +986,11 @@ module Origen
 
       # 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)
+      #      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 = '^(.?.?.?.)'
+        (size_in_nibbles - 1).times { regex += '(....)' }
         regex += '$'
         Regexp.new(regex) =~ regval
 
@@ -950,13 +1001,13 @@ module Origen
 
         nibbles.each_with_index do |nibble, i|
           # If contains any special chars...
-          if nibble =~ /[#{DONT_CARE_CHAR}#{STORE_CHAR}#{OVERLAY_CHAR}]/
+          if nibble =~ /[#{UNKNOWN_CHAR}#{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})"
+              outstr += "[#{nibble.downcase}]"
             end
           # Otherwise if all 1s and 0s...
           else
@@ -985,7 +1036,13 @@ module Origen
             ixs << index
           end
         end
-        ixs.flatten.sort
+        ixs.flatten!
+        # ixs.sort!
+        # convert msb0 numbering (if provided) to lsb0 numbering to get the correct bits
+        if @with_bit_order == :msb0
+          ixs.each_index { |i| ixs[i] = size - ixs[i] - 1 }
+        end
+        ixs.sort
       end
     end
   end

data/lib/origen/registers/msb0_delegator.rb

@@ -0,0 +1,47 @@
+module Origen
+  module Registers
+    require 'delegate'
+
+    # Thin wrapper around register objects to modify bit number interpretation
+    #
+    # This is provided as a convenience to make user code more readable
+    class Msb0Delegator < ::Delegator
+      def initialize(reg_object, bits)
+        @reg_object = reg_object
+        @bits = bits
+      end
+
+      def __getobj__
+        @reg_object
+      end
+
+      def __object__
+        @reg_object
+      end
+
+      def __setobj__(obj)
+        @reg_object = obj
+      end
+
+      def inspect(options = {})
+        options[:with_bit_order] = :msb0
+        @reg_object.inspect(options)
+      end
+
+      def method_missing(method, *args, &block)
+        if args.last.is_a?(Hash)
+          args.last[:with_bit_order] = :msb0
+        else
+          args << { with_bit_order: :msb0 }
+        end
+        @reg_object.method_missing(method, *args, &block)
+      end
+
+      def bit(*args)
+        @reg_object.bit(args, with_bit_order: :msb0)
+      end
+      alias_method :bits, :bit
+      alias_method :[], :bit
+    end
+  end
+end