Class: Origen::Registers::BitCollection

Inherits:
Array show all
Includes:
Netlist::Connectable, SubBlocks::Path
Defined in:
lib/origen/registers/bit_collection.rb

Overview

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

Direct Known Subclasses

Ports::BitCollection

Constant Summary collapse

DONT_CARE_CHAR =
'X'
OVERLAY_CHAR =
'V'
STORE_CHAR =
'S'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Netlist::Connectable

#connect_to

Methods included from SubBlocks::Path

#abs_path=, #path, #path=

Methods inherited from Array

#dups, #dups?, #dups_with_index, #ids, #include_hash?, #include_hash_with_key?

Constructor Details

#initialize(reg, name, data = []) ⇒ BitCollection

:nodoc:



22
23
24
25
26
27
28
29
# File 'lib/origen/registers/bit_collection.rb', line 22

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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object

All other methods send to bit 0



681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
# File 'lib/origen/registers/bit_collection.rb', line 681

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.(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

Instance Attribute Details

#nameObject Also known as: id

Returns the value of attribute name



19
20
21
# File 'lib/origen/registers/bit_collection.rb', line 19

def name
  @name
end

Class Method Details

.dummy(reg, name = nil, options = {}) ⇒ Object

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.



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
# File 'lib/origen/registers/bit_collection.rb', line 252

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

Instance Method Details

#[](*indexes) ⇒ Object Also known as: bits, bit



44
45
46
47
48
49
50
51
52
53
54
55
56
57
# File 'lib/origen/registers/bit_collection.rb', line 44

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

#abs_pathObject



83
84
85
# File 'lib/origen/registers/bit_collection.rb', line 83

def abs_path
  first.abs_path
end

#access(value = nil) ⇒ Object

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



200
201
202
203
204
205
206
207
# File 'lib/origen/registers/bit_collection.rb', line 200

def access(value = nil)
  if value.nil?
    first.access
  else # set access
    each { |b| b.set_access(value) }
    self
  end
end

#access!Object

Like access but will raise an error if not all bits in the collection have the same access value



211
212
213
214
215
216
217
# File 'lib/origen/registers/bit_collection.rb', line 211

def access!
  val = access
  if any? { |b| b.access != val }
    fail 'Not all bits the collection have the same access value!'
  end
  val
end

#add_name(name) ⇒ Object

:nodoc:



667
668
669
670
671
672
673
674
# File 'lib/origen/registers/bit_collection.rb', line 667

def add_name(name) # :nodoc:
  if @name == :unknown
    @name = name
  elsif ![name].flatten.include?(name)
    @name = [@name, name].flatten
  end
  self
end

#append_overlays(value) ⇒ Object

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"


654
655
656
657
658
659
# File 'lib/origen/registers/bit_collection.rb', line 654

def append_overlays(value)
  each do |bit|
    bit.overlay(bit.overlay_str + value) if bit.has_overlay?
  end
  self
end

#bind(live_parameter) ⇒ Object



40
41
42
# File 'lib/origen/registers/bit_collection.rb', line 40

def bind(live_parameter)
  parent.bind(name, live_parameter)
end

#bit_orderObject

Returns the bit order of the parent register



32
33
34
# File 'lib/origen/registers/bit_collection.rb', line 32

def bit_order
  parent.bit_order
end

#bit_value_descriptions(_bitname = nil) ⇒ Object



240
241
242
243
244
245
246
247
# File 'lib/origen/registers/bit_collection.rb', line 240

def bit_value_descriptions(_bitname = nil)
  options = _bitname.is_a?(Hash) ? _bitname : {}
  if name == :unknown
    []
  else
    @reg.bit_value_descriptions(name, options)
  end
end

#clear_flagsObject

Calls the clear_flags method on all bits, see Bit#clear_flags for more details



478
479
480
481
# File 'lib/origen/registers/bit_collection.rb', line 478

def clear_flags
  each(&:clear_flags)
  self
end

#clear_startObject

Clear any start set bits back to 0



824
825
826
827
# File 'lib/origen/registers/bit_collection.rb', line 824

def clear_start
  each(&:clear_start)
  self
end

#clear_w1cObject

Clear any w1c set bits back to 0



818
819
820
821
# File 'lib/origen/registers/bit_collection.rb', line 818

def clear_w1c
  each(&:clear_w1c)
  self
end

#clr_only(value) ⇒ Object

Modify clr_only for bits in collection



799
800
801
802
# File 'lib/origen/registers/bit_collection.rb', line 799

def clr_only(value)
  shift_out_with_index { |bit, i| bit.clr_only = (value[i] == 0b1) }
  self
end

#contains_bits?Boolean

Returns:

  • (Boolean)


268
269
270
# File 'lib/origen/registers/bit_collection.rb', line 268

def contains_bits?
  true
end

#copy_all(reg) ⇒ Object

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.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
# File 'lib/origen/registers/bit_collection.rb', line 168

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

#dataObject Also known as: val, value

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


285
286
287
288
289
290
291
292
# File 'lib/origen/registers/bit_collection.rb', line 285

def data
  data = 0
  shift_out_with_index do |bit, i|
    return undefined if bit.is_a?(Origen::UndefinedClass)
    data |= bit.data << i
  end
  data
end

#data_bObject

Returns the inverse of the data value held by the collection



297
298
299
300
# File 'lib/origen/registers/bit_collection.rb', line 297

def data_b
  # (& operation takes care of Bignum formatting issues)
  ~data & ((1 << size) - 1)
end

#data_reverseObject Also known as: reverse_data

Returns the reverse of the data value held by the collection



303
304
305
306
307
308
309
310
# File 'lib/origen/registers/bit_collection.rb', line 303

def data_reverse
  data = 0
  reverse_shift_out_with_index do |bit, i|
    return undefined if bit.is_a?(Origen::UndefinedClass)
    data |= bit.data << i
  end
  data
end

#deleteObject

Delete the contained bits from the parent Register



662
663
664
665
# File 'lib/origen/registers/bit_collection.rb', line 662

def delete
  @reg.delete_bits(self)
  self
end

#description(bitname = nil, options = {}) ⇒ Object

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)



224
225
226
227
228
229
230
231
# File 'lib/origen/registers/bit_collection.rb', line 224

def description(bitname = nil, options = {})
  bitname, options = nil, bitname if bitname.is_a?(Hash)
  if name == :unknown
    []
  else
    @reg.description(name, options)
  end
end

#enable_mask(operation) ⇒ Object

Returns a value representing the bit collection / register where a bit value of 1 means the bit is enabled for the given operation.



367
368
369
370
371
372
373
374
375
376
377
378
379
# File 'lib/origen/registers/bit_collection.rb', line 367

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

#enabled?Boolean

Returns:

  • (Boolean)


782
783
784
# File 'lib/origen/registers/bit_collection.rb', line 782

def enabled?
  all?(&:enabled?)
end

#featureObject Also known as: features



751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
# File 'lib/origen/registers/bit_collection.rb', line 751

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

#full_name(bitname = nil, options = {}) ⇒ Object



233
234
235
236
237
238
# File 'lib/origen/registers/bit_collection.rb', line 233

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

#has_feature_constraint?(name = nil) ⇒ Boolean Also known as: enabled_by_feature?

Return true if there is any feature associated with these bits

Returns:

  • (Boolean)


773
774
775
776
777
778
779
# File 'lib/origen/registers/bit_collection.rb', line 773

def has_feature_constraint?(name = nil)
  if !name
    any?(&:has_feature_constraint?)
  else
    any? { |bit| bit.enabled_by_feature?(name) }
  end
end

#has_known_value?Boolean

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.

Returns:

  • (Boolean)


707
708
709
# File 'lib/origen/registers/bit_collection.rb', line 707

def has_known_value?
  all?(&:has_known_value?)
end

#has_overlay?(name = nil) ⇒ Boolean

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

Returns:

  • (Boolean)


500
501
502
# File 'lib/origen/registers/bit_collection.rb', line 500

def has_overlay?(name = nil)
  any? { |bit| bit.has_overlay?(name) }
end

#inspectObject



272
273
274
# File 'lib/origen/registers/bit_collection.rb', line 272

def inspect
  "<#{self.class}:#{object_id}>"
end

#is_readable?Boolean Also known as: readable?

Returns true if any bits in the collection are readable

Returns:

  • (Boolean)


793
794
795
# File 'lib/origen/registers/bit_collection.rb', line 793

def is_readable?
  any?(&:readable?)
end

#is_to_be_read?Boolean

Returns true if any bits have the read flag set - see Bit#is_to_be_read? for more details.

Returns:

  • (Boolean)


461
462
463
# File 'lib/origen/registers/bit_collection.rb', line 461

def is_to_be_read?
  any?(&:is_to_be_read?)
end

#is_to_be_stored?Boolean

Returns true if any bits have the store flag set - see Bit#is_to_be_stored? for more details.

Returns:

  • (Boolean)


467
468
469
# File 'lib/origen/registers/bit_collection.rb', line 467

def is_to_be_stored?
  any?(&:is_to_be_stored?)
end

#is_writable?Boolean Also known as: writable?

Returns true if any bits in the collection are writable

Returns:

  • (Boolean)


787
788
789
# File 'lib/origen/registers/bit_collection.rb', line 787

def is_writable?
  any?(&:writable?)
end

#nvm_depObject

Return nvm_dep value held by collection



811
812
813
814
815
# File 'lib/origen/registers/bit_collection.rb', line 811

def nvm_dep
  nvm_dep = 0
  shift_out_with_index { |bit, i| nvm_dep |= bit.nvm_dep << i }
  nvm_dep
end

#overlay(value) ⇒ Object

Attaches the supplied overlay string to all bits

Example

reg(:data).overlay(“data_val”)



384
385
386
387
# File 'lib/origen/registers/bit_collection.rb', line 384

def overlay(value)
  each { |bit| bit.overlay(value) }
  self
end

#overlay_strObject

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"


510
511
512
513
514
515
516
# File 'lib/origen/registers/bit_collection.rb', line 510

def overlay_str
  result = ''
  each do |bit|
    result = bit.overlay_str if bit.has_overlay?
  end
  result.to_s
end

#ownerObject



676
677
678
# File 'lib/origen/registers/bit_collection.rb', line 676

def owner
  first.owner
end

#parentObject



61
62
63
# File 'lib/origen/registers/bit_collection.rb', line 61

def parent
  @reg
end

#path_varObject



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# File 'lib/origen/registers/bit_collection.rb', line 65

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

#positionObject

Returns the LSB position of the collection



277
278
279
# File 'lib/origen/registers/bit_collection.rb', line 277

def position
  first.position
end

#preserve_flagsObject

At the end of the given block, the status flags of all bits will be restored to the state that they were upon entry to the block



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
# File 'lib/origen/registers/bit_collection.rb', line 148

def preserve_flags
  orig = []
  each do |bit|
    orig << [bit.overlay_str, bit.is_to_be_read?, bit.is_to_be_stored?]
  end
  yield
  each do |bit|
    bit.clear_flags
    flags = orig.shift
    bit.overlay(flags[0])
    bit.read if flags[1]
    bit.store if flags[2]
  end
  self
end

#read(value = nil, options = {}) ⇒ Object Also known as: assert

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.



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
# File 'lib/origen/registers/bit_collection.rb', line 345

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, force: true)
  end
  if options[:mask]
    shift_out_with_index { |bit, i| bit.read if options[:mask][i] == 1 }
    shift_out_with_index { |bit, i| bit.clear_read_flag if options[:mask][i] == 0 }
  else
    each(&:read)
  end
  self
end

#read!(value = nil, options = {}) ⇒ Object Also known as: assert!

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


538
539
540
541
542
543
544
545
546
# File 'lib/origen/registers/bit_collection.rb', line 538

def read!(value = nil, options = {})
  value, options = nil, value if value.is_a?(Hash)
  read(value, options) unless block_given?
  if block_given?
    yield size == @reg.size ? @reg : self
  end
  @reg.request(:read_register, options)
  self
end

#readable(value) ⇒ Object

Modify readable for bits in collection



746
747
748
749
# File 'lib/origen/registers/bit_collection.rb', line 746

def readable(value)
  shift_out_with_index { |bit, i| bit.readable = (value[i] == 0b1); bit.set_access_from_rw }
  self
end

#resetObject

Resets all bits, this clears all flags and assigns the data value back to the reset state



391
392
393
394
# File 'lib/origen/registers/bit_collection.rb', line 391

def reset
  each(&:reset)
  self
end

#reset_data(value = nil) ⇒ Object Also known as: reset_val, reset_value, reset_data=, reset_val=, reset_value=

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


719
720
721
722
723
724
725
726
727
728
729
730
731
732
# File 'lib/origen/registers/bit_collection.rb', line 719

def reset_data(value = nil)
  # This method was originally setup to set the reset value by passing an argument
  if value
    shift_out_with_index { |bit, i| bit.reset_val = value[i] }
    self
  else
    data = 0
    shift_out_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

#respond_to?(*args) ⇒ Boolean

Recognize that BitCollection responds to some Bit methods via method_missing

Returns:

  • (Boolean)


699
700
701
702
# File 'lib/origen/registers/bit_collection.rb', line 699

def respond_to?(*args) # :nodoc:
  sym = args.first
  first.respond_to?(sym) || super(sym)
end

#reverse_shift_out(&block) ⇒ Object

Yields each bit in the register, MSB first.



450
451
452
# File 'lib/origen/registers/bit_collection.rb', line 450

def reverse_shift_out(&block)
  reverse_each(&block)
end

#reverse_shift_out_with_index(&block) ⇒ Object

Yields each bit in the register and its index, MSB first.



455
456
457
# File 'lib/origen/registers/bit_collection.rb', line 455

def reverse_shift_out_with_index(&block)
  reverse_each.with_index(&block)
end

#set_only(value) ⇒ Object

Modify set_only for bits in collection



805
806
807
808
# File 'lib/origen/registers/bit_collection.rb', line 805

def set_only(value)
  shift_out_with_index { |bit, i| bit.set_only = (value[i] == 0b1) }
  self
end

#setting(value) ⇒ Object

Returns the value you would need to write to the register to put the given value in these bits



485
486
487
488
489
490
491
# File 'lib/origen/registers/bit_collection.rb', line 485

def setting(value)
  result = 0
  shift_out_with_index do |bit, i|
    result |= bit.setting(value[i])
  end
  result
end

#shift_left(data = 0) ⇒ Object

Shifts the data in the collection left by one place. The data held by the rightmost bit will be set to the given value (0 by default).

Examples:

myreg.data          # => 0b1111
myreg.shift_left
myreg.data          # => 0b1110
myreg.shift_left
myreg.data          # => 0b1100
myreg.shift_left(1)
myreg.data          # => 0b1001
myreg.shift_left(1)
myreg.data          # => 0b0011


901
902
903
904
905
906
907
908
909
# File 'lib/origen/registers/bit_collection.rb', line 901

def shift_left(data = 0)
  prev_bit = nil
  reverse_shift_out do |bit|
    prev_bit.write(bit.data) if prev_bit
    prev_bit = bit
  end
  prev_bit.write(data)
  self
end

#shift_out(&block) ⇒ Object

Yields each bit in the register, LSB first.



440
441
442
# File 'lib/origen/registers/bit_collection.rb', line 440

def shift_out(&block)
  each(&block)
end

#shift_out_leftObject

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


404
405
406
407
408
409
410
# File 'lib/origen/registers/bit_collection.rb', line 404

def shift_out_left
  if bit_order == :msb0
    each { |bit| yield bit }
  else
    reverse_each { |bit| yield bit }
  end
end

#shift_out_left_with_indexObject

Same as Reg#shift_out_left but includes the index counter



413
414
415
416
417
418
419
# File 'lib/origen/registers/bit_collection.rb', line 413

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
end

#shift_out_rightObject

Same as Reg#shift_out_left but starts from the MSB



422
423
424
425
426
427
428
# File 'lib/origen/registers/bit_collection.rb', line 422

def shift_out_right
  if bit_order == :msb0
    reverse_each { |bit| yield bit }
  else
    each { |bit| yield bit }
  end
end

#shift_out_right_with_indexObject

Same as Reg#shift_out_right but includes the index counter



431
432
433
434
435
436
437
# File 'lib/origen/registers/bit_collection.rb', line 431

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
end

#shift_out_with_index(&block) ⇒ Object

Yields each bit in the register and its index, LSB first.



445
446
447
# File 'lib/origen/registers/bit_collection.rb', line 445

def shift_out_with_index(&block)
  each_with_index(&block)
end

#shift_right(data = 0) ⇒ Object

Shifts the data in the collection right by one place. The data held by the leftmost bit will be set to the given value (0 by default).

Examples:

myreg.data          # => 0b1111
myreg.shift_right
myreg.data          # => 0b0111
myreg.shift_right
myreg.data          # => 0b0011
myreg.shift_right(1)
myreg.data          # => 0b1001
myreg.shift_right(1)
myreg.data          # => 0b1100


924
925
926
927
928
929
930
931
932
# File 'lib/origen/registers/bit_collection.rb', line 924

def shift_right(data = 0)
  prev_bit = nil
  shift_out do |bit|
    prev_bit.write(bit.data) if prev_bit
    prev_bit = bit
  end
  prev_bit.write(data)
  self
end

#status_str(operation, options = {}) ⇒ Object

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

Examples:


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"


855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
# File 'lib/origen/registers/bit_collection.rb', line 855

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

#sticky_overlay(set = true) ⇒ Object Also known as: sticky_overlays

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


564
565
566
567
# File 'lib/origen/registers/bit_collection.rb', line 564

def sticky_overlay(set = true)
  each { |bit| bit.sticky_overlay = set }
  self
end

#sticky_store(set = true) ⇒ Object

Similar to sticky_overlay this method affects how the store flags are treated by Reg#clear_flags.
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


578
579
580
581
# File 'lib/origen/registers/bit_collection.rb', line 578

def sticky_store(set = true)
  each { |bit| bit.sticky_store = set }
  self
end

#store(options = {}) ⇒ Object

Marks all bits to be stored



584
585
586
587
# File 'lib/origen/registers/bit_collection.rb', line 584

def store(options = {})
  each(&:store)
  self
end

#store!(options = {}) ⇒ Object

Marks all bits to be stored and then calls read!



590
591
592
593
594
# File 'lib/origen/registers/bit_collection.rb', line 590

def store!(options = {})
  store(options)
  read!(options)
  self
end

#store_overlay_bits(options = {}) ⇒ Object

Sets the store flag on all bits that already have the overlay flag set



606
607
608
609
610
611
612
613
# File 'lib/origen/registers/bit_collection.rb', line 606

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

#store_overlay_bits!(options = {}) ⇒ Object

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



598
599
600
601
602
603
# File 'lib/origen/registers/bit_collection.rb', line 598

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

#sync(size = nil, options = {}) ⇒ Object Also known as: sync!

Update the register contents with the live value from the device under test.

The current tester needs to be an OrigenLink driver. Upon calling this method a request will be made to read the given register, the read data will be captured and the register model will be updated.

The register parent register object is returned, this means that calling .sync on a register or bitcollection object will automatically update it and the display the register in the console.

Normally this method should be called from a breakpoint during pattern debug, and it is not intended to be inserted into production pattern logic.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# File 'lib/origen/registers/bit_collection.rb', line 105

def sync(size = nil, options = {})
  size, options = nil, size if size.is_a?(Hash)
  if tester.respond_to?(:capture)
    preserve_flags do
      v = tester.capture do
        store!(sync: true)
      end
      if v.first
        # Serial shift
        if v.size == 1
          reverse_shift_out_with_index do |bit, i|
            bit.instance_variable_set('@updated_post_reset', true)
            bit.instance_variable_set('@data', v.first[i])
          end
        # Parallel shift
        else
          reverse_shift_out_with_index do |bit, i|
            bit.instance_variable_set('@updated_post_reset', true)
            bit.instance_variable_set('@data', v[i].to_i)
          end
        end
      else
        Origen.log.warning "No data was captured when attempting to sync register #{owner.name}, this is probably because the current read_register driver method does not implement store requests"
      end
    end
    if size
      puts "#{parent.address.to_s(16).upcase}: " + data.to_s(16).upcase.rjust(Origen.top_level.memory_width / 4, '0')
      if size > 1
        step = Origen.top_level.memory_width / 8
        Origen.top_level.mem(parent.address + step).sync(size - 1)
      end
      nil
    else
      parent
    end
  else
    Origen.log.warning 'Sync is not supported on the current tester driver, register not updated'
  end
end

#terminal?Boolean

Returns:

  • (Boolean)


36
37
38
# File 'lib/origen/registers/bit_collection.rb', line 36

def terminal?
  true
end

#unique_overlays {|current_overlay, length, data| ... } ⇒ Object

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

Yields:

  • (current_overlay, length, data)


622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
# File 'lib/origen/registers/bit_collection.rb', line 622

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

#update_required?Boolean

Returns true if any bits have the update_required flag set - see Bit#update_required? for more details.

Returns:

  • (Boolean)


473
474
475
# File 'lib/origen/registers/bit_collection.rb', line 473

def update_required?
  any?(&:update_required?)
end

#whole_reg?Boolean

Returns true if the collection contains all bits in the register

Returns:

  • (Boolean)


319
320
321
# File 'lib/origen/registers/bit_collection.rb', line 319

def whole_reg?
  size == parent.size
end

#writable(value) ⇒ Object

Modify writable for bits in collection



740
741
742
743
# File 'lib/origen/registers/bit_collection.rb', line 740

def writable(value)
  shift_out_with_index { |bit, i| bit.writable = (value[i] == 0b1); bit.set_access_from_rw }
  self
end

#write(value, options = {}) ⇒ Object Also known as: data=, value=, val=

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.



325
326
327
328
329
330
331
332
333
334
335
336
337
338
# File 'lib/origen/registers/bit_collection.rb', line 325

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')

  size.times do |i|
    self[i].write(value[i], options)
  end
  self
end

#write!(value = nil, options = {}) ⇒ Object

Write the bit value on silicon. This method will update the data value of the bits and then call $top.write_register passing the owning register as the first argument. This method is expected to handle writing the current state of the register to silicon.



522
523
524
525
526
527
528
529
530
# File 'lib/origen/registers/bit_collection.rb', line 522

def write!(value = nil, options = {})
  value, options = nil, value if value.is_a?(Hash)
  write(value, options) if value
  if block_given?
    yield size == @reg.size ? @reg : self
  end
  @reg.request(:write_register, options)
  self
end