class Origen::Registers::Bit

Models bits within Reg objects

Constants

ACCESS_CODES

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?).

Attributes

access[RW]

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

base_access[R]

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.

clr_only[W]

Allow modify of clr_only flag, bit can only be cleared (made 0)

data[R]

Current the data value currently held by the bit, 0 or 1

feature[R]

Any feature associated with the bit/bits

meta[RW]

Returns any application-specific meta-data attatched to the given bit

meta_data[RW]

Returns any application-specific meta-data attatched to the given bit

metadata[RW]

Returns any application-specific meta-data attatched to the given bit

mod_write_value[R]

Returns mod_write_value - what write value modification occurs when written

nvm_dep[R]

Returns true if bit depends on initial state of NVM in some way

overlay[R]

Returns any overlay string attached to the bit

owner[R]

Returns the Reg object that owns the bit

position[R]

Returns the integer position of the bit within the register

read_action[R]

Returns read_action - whether anything happens to the bit when read

read_data_matches_write[R]

If the bit does not read back with the same data as is written to it then this will return true. This property can be assigned durgin the register instantiation, e.g.

add_reg :control,    0x00,    :mode    => { :pos => 8, :bits => 8 },
                              :status  => { :pos => 4, :bits => 2, :read_data_matches_write => false }
readable[W]

Allow modify of readable flag, bit is readable by read method

reset_data[RW]

Returns the reset value of the bit

reset_val[RW]

Returns the reset value of the bit

reset_value[RW]

Returns the reset value of the bit

set_only[W]

Allow modify of set_only flag, bit can only be set (made 1)

start[R]

Returns true if bit is critical to starting an important operation (like a state machine) so that it can be made not writable during basic register checks

sticky_overlay[RW]

Returns true if this bit has the sticky_overlay flag set, see Reg#sticky_overlay for a full description. This is true by default.

sticky_store[RW]

Returns true if this bit has the sticky_store flag set, see Reg#sticky_store for a full description. This is false by default.

unknown[RW]

Can be set to indicate that the current state of the bit is unknown, e.g. after reading X from a simulation

w1c[RW]

Sets or returns the status of “write-one-to-clear”

writable[W]

Allow modify of writable flag, bit is writeable by write method

Public Class Methods

new(owner, position, options = {}) click to toggle source
# File lib/origen/registers/bit.rb, line 103
def initialize(owner, position, options = {})
  options = {
    start:                   false,        # whether bit starts a state machine so be careful
    read_data_matches_write: true,
    read:                    false,
    overlay:                 false,
    store:                   false,
    sticky_overlay:          true,
    sticky_store:            false,
    nvm_dep:                 false        # whether is an NVM dependent bit
  }.merge(options)
  @owner = owner
  @position = position
  @undefined = options.delete(:undefined)
  @reset_val = (options.delete(:res) || options.delete(:reset) || options.delete(:data) || 0)
  if @reset_val.is_a?(Symbol)
    @data = 0
  else
    @reset_val &= 1 unless @reset_val.is_a?(Symbol)
    @data = @reset_val
  end

  access_code = options.delete(:access)
  # If access has been defined then none of these other attributes can be
  if access_code
    conflicts = [:readable, :writable, :clr_only, :set_only, :w1c]
    if conflicts.any? { |k| options.key?(k) }
      puts 'The following attributes cannot be set in combination with :access'
      puts "  #{conflicts.join(', ')}"
      puts ''
      puts 'Use :access to defined the required behavior, the above attributes will be deprecated in future.'
      puts ''
      fail 'Conflicting access!'
    end
    set_access(access_code)
  else
    options = {
      writable: true,         # whether bit is writable
      readable: true,         # whether bit is readable
      clr_only: false,        # whether bit is clear only
      set_only: false,        # whether bit is set only
      w1c:      false        # whether bit is w1c (when written to 1 immediately becomes 0)
    }.merge(options)
    @readable = options.delete(:readable)
    @writable = options.delete(:writable)
    @clr_only = options.delete(:clr_only)
    @set_only = options.delete(:set_only)
    @w1c = options.delete(:w1c)
    set_access_from_rw
  end
  # Would like to get this integrated with access as well
  @read_data_matches_write = options.delete(:read_data_matches_write)

  @feature = options.delete(:feature)
  if !!feature && @writable
    @writable = enabled?
  end
  @path     = options.delete(:path)
  @abs_path = options.delete(:abs_path)
  @start = options.delete(:start)
  @read = options.delete(:read)
  @overlay = options.delete(:overlay)
  @store = options.delete(:store)
  @update_required = false
  @sticky_store = options.delete(:sticky_store)
  @sticky_overlay = options.delete(:sticky_overlay)
  @nvm_dep = (options.delete(:nvm_dep) ? 1 : 0)
  # Delete some other noise that can be left over...
  options.delete(:bits)
  options.delete(:pos)
  options.delete(:position)
  options.delete(:data)
  # Whatever is left must be custom application meta-data
  @meta = (default_bit_metadata).merge(options)
end

Public Instance Methods

abs_path() click to toggle source
# File lib/origen/registers/bit.rb, line 226
def abs_path
  @abs_path
end
access_codes() click to toggle source
# File lib/origen/registers/bit.rb, line 179
def access_codes
  ACCESS_CODES
end
assert(value = nil, _options = {})
Alias for: read
clear_flags() click to toggle source

Clears the read, store, overlay and update_required flags of this bit. The store and overlay flags will not be cleared if the the bit’s sticky_store or sticky_overlay attributes are set respectively.

# File lib/origen/registers/bit.rb, line 388
def clear_flags
  @read = false
  @store = false unless @sticky_store
  @overlay = false unless @sticky_overlay
  @update_required = false
  self
end
clear_read_flag() click to toggle source

Clears the read flag of this bit.

# File lib/origen/registers/bit.rb, line 397
def clear_read_flag
  @read = false
  self
end
clear_start() click to toggle source

Clears any start bits that are set

# File lib/origen/registers/bit.rb, line 448
def clear_start
  if @start && set?
    @data = 0
  end
  self
end
clear_w1c() click to toggle source

Clears any w1c bits that are set

# File lib/origen/registers/bit.rb, line 440
def clear_w1c
  if @w1c && set?
    @data = 0
  end
  self
end
data_in_position() click to toggle source

Returns the data shifted by the bit position

# File lib/origen/registers/bit.rb, line 435
def data_in_position
  data << position
end
default_bit_metadata() click to toggle source

Returns any application specific metadata that has been inherited by the given bit. This does not account for any overridding that may have been applied to this bit specifically however, use the meta method to get that.

# File lib/origen/registers/bit.rb, line 240
def default_bit_metadata
  if owner
    Origen::Registers.default_bit_metadata.merge(
      Origen::Registers.bit_metadata[owner.owner.class] || {}
    )
  else
    Origen::Registers.default_bit_metadata
  end
end
delete() click to toggle source

Make this bit disappear, make it unwritable with a data value of 0

# File lib/origen/registers/bit.rb, line 260
def delete
  @sticky_overlay = false
  @sticky_store = false
  clear_flags
  @data = 0
  @writable = false
  self
end
enabled?() click to toggle source
# File lib/origen/registers/bit.rb, line 510
def enabled?
  if feature
    value = false
    current_owner = self
    if feature.class == Array
      feature.each do |f|
        current_owner = self
        loop do
          if current_owner.respond_to?(:owner)
            current_owner = current_owner.owner
            if current_owner.respond_to?(:has_feature?)
              if current_owner.has_feature?(f)
                value = true
                break
              end
            end
          else # if current owner does not have a owner
            value = false
            break
          end
        end # loop end
        unless value
          if Origen.top_level && \
             Origen.top_level.respond_to?(:has_feature?) && \
             Origen.top_level.has_feature?(f)
            value = true
            unless value
              break
            end
          end
        end
        unless value
          break # break if feature not found and return false
        end
      end # iterated through all features in array
      value
    else # if feature.class != Array
      loop do
        if current_owner.respond_to?(:owner)
          current_owner = current_owner.owner
          if current_owner.respond_to?(:has_feature?)
            if current_owner.has_feature?(feature)
              value = true
              break
            end
          end
        else # if current owner does not have a owner
          value = false
          break
        end
      end # loop end
      unless value
        if Origen.top_level && \
           Origen.top_level.respond_to?(:has_feature?) && \
           Origen.top_level.has_feature?(feature)
          value = true
        end
      end
      value
    end
  else
    true
  end
end
enabled_by_feature?(name = nil) click to toggle source

Returns true if the bit is constrained by the given/any feature

# File lib/origen/registers/bit.rb, line 492
def enabled_by_feature?(name = nil)
  if !name
    !!feature
  else
    if feature.class == Array
      feature.each do |f|
        if f == name
          return true
        end
      end
      false
    else
      feature == name
    end
  end
end
Also aliased as: has_feature_constraint?
extract_meta_data(method, *args) click to toggle source
# File lib/origen/registers/bit.rb, line 474
def extract_meta_data(method, *args)
  method = method.to_s.sub('?', '')
  if method =~ /=/
    instance_variable_set("@#{method.sub('=', '')}", args.first)
  else
    instance_variable_get("@#{method}") || meta[method.to_sym]
  end
end
has_feature_constraint?(name = nil)
Alias for: enabled_by_feature?
has_known_value?() click to toggle source

Returns true if the value of the bit is known. The value will be 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.

# File lib/origen/registers/bit.rb, line 295
def has_known_value?
  !@unknown && (!@reset_val.is_a?(Symbol) || @updated_post_reset)
end
has_overlay?(name = nil) click to toggle source

Returns true if the overlay attribute is set, optionally supply an overlay name and this will only return true if the overlay attribute matches that name

# File lib/origen/registers/bit.rb, line 366
def has_overlay?(name = nil)
  if name
    name.to_s == @overlay.to_s
  else
    !!@overlay
  end
end
inspect() click to toggle source
# File lib/origen/registers/bit.rb, line 250
def inspect
  "<#{self.class}:#{object_id}>"
end
is_readable?() click to toggle source
# File lib/origen/registers/bit.rb, line 380
def is_readable?
  @readable
end
Also aliased as: readable?
is_to_be_read?() click to toggle source

Returns true if the bit’s read flag is set

# File lib/origen/registers/bit.rb, line 355
def is_to_be_read?
  @read
end
is_to_be_stored?() click to toggle source

Returns true if the bit’s store flag is set

# File lib/origen/registers/bit.rb, line 360
def is_to_be_stored?
  @store
end
is_writable?() click to toggle source

Returns true if the bit is writable

# File lib/origen/registers/bit.rb, line 375
def is_writable?
  @writable
end
Also aliased as: writable?
mask() click to toggle source

Returns a bit mask for this bit, that is a 1 shifted into the position corresponding to this bit’s position. e.g. A bit with position 4 would return %1_0000

# File lib/origen/registers/bit.rb, line 405
def mask
  mask_val = 1
  mask_val << @position
end
meta_data_method?(method) click to toggle source

@api private

# File lib/origen/registers/bit.rb, line 461
def meta_data_method?(method)
  attr_name = method.to_s.gsub(/\??=?/, '').to_sym
  if default_bit_metadata.key?(attr_name)
    if method.to_s =~ /\?/
      [true, false].include?(default_bit_metadata[attr_name])
    else
      true
    end
  else
    false
  end
end
overlay_str() click to toggle source

Returns the overlay attribute

# File lib/origen/registers/bit.rb, line 350
def overlay_str
  @overlay
end
path_var() click to toggle source
# File lib/origen/registers/bit.rb, line 222
def path_var
  @path
end
read(value = nil, _options = {}) click to toggle source

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.

# File lib/origen/registers/bit.rb, line 322
def read(value = nil, _options = {})
  # First properly assign the args if value is absent...
  if value.is_a?(Hash)
    options = value
    value = nil
  end
  write(value) if value
  @read = true if @readable && @read_data_matches_write
  self
end
Also aliased as: assert
readable?()
Alias for: is_readable?
reset() click to toggle source

Resets the data value back to the reset value and calls Bit#clear_flags

# File lib/origen/registers/bit.rb, line 275
def reset
  if @reset_val.is_a?(Symbol)
    @data = 0
  else
    @data = @reset_val
  end
  @updated_post_reset = false
  clear_flags
  self
end
set?() click to toggle source

Returns true if the bit is set (holds a data value of 1)

# File lib/origen/registers/bit.rb, line 270
def set?
  @data == 1 ? true : false
end
set_access(value) click to toggle source
# File lib/origen/registers/bit.rb, line 183
def set_access(value)
  unless ACCESS_CODES.keys.include?(value)
    puts 'Invalid access code, must be one of these:'
    ACCESS_CODES.each do |code, meta|
      puts "  :#{code}".ljust(10) + " - #{meta[:description]}"
    end
    puts ''
    fail 'Invalid access code!'
  end
  @access = value

  # 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_from_rw() click to toggle source

Set @access based on @readable and @writable

# File lib/origen/registers/bit.rb, line 206
def set_access_from_rw
  if @w1c
    @access = :w1c
  elsif @clr_only
    @access = :wc
  elsif @set_only
    @access = :ws
  elsif @readable && @writable
    @access = :rw
  elsif @readable
    @access = :ro
  elsif @writable && @access != :worz
    @access = :wo
  end
end
setting(value) click to toggle source

Returns the value you would need to write to the register to put the given value in this bit

# File lib/origen/registers/bit.rb, line 417
def setting(value)
  value = value & 1 # As this bit can only hold one bit of data force it
  value << @position
end
shift_out_left() { |self| ... } click to toggle source

With only one bit it just returns itself

# File lib/origen/registers/bit.rb, line 430
def shift_out_left
  yield self
end
size() click to toggle source

Always returns 1 when asked for size, a BitCollection on the other hand will return something higher

# File lib/origen/registers/bit.rb, line 255
def size
  1
end
store() click to toggle source

Sets the store flag attribute

# File lib/origen/registers/bit.rb, line 335
def store
  @store = true
  self
end
undefined?() click to toggle source

Returns true if the bit object is a placeholder for bit positions that have not been defined within the parent register

# File lib/origen/registers/bit.rb, line 288
def undefined?
  @undefined
end
update_required?() click to toggle source

Returns true if the bit’s update_required flag is set, typically this will be the case when a write has changed the data value of the bit but a BitCollection#write! method has not been called yet to apply it to silicon

# File lib/origen/registers/bit.rb, line 425
def update_required?
  @update_required
end
writable?()
Alias for: is_writable?
write(value, options = {}) click to toggle source

Set the data value of the bit to the given value (1 or 0) If the bit is read-only, the value of the bit can be forced with ‘force: true’

# File lib/origen/registers/bit.rb, line 301
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)
    overlay(value[1])
    value = value[0]
  end
  if (@data != value & 1 && @writable) ||
     (@data != value & 1 && options[:force] == true)
    if ((set?) && (!@set_only)) ||
       ((!set?) && (!@clr_only))
      @data = value & 1
      @update_required = true
      @updated_post_reset = true
    end
  end
  self
end