class Origen::Pins::PinCollection

A class that is used to wrap collections of one or more pins. Anytime a group of pins is fetched or returned by the Pin API it will be wrapped in a PinCollection.

Constants

ORG_FILE_INTERCEPTED_METHODS

Attributes

color[RW]
description[RW]
endian[RW]
group[RW]
group_str[RW]

Public Class Methods

new(owner, *pins) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 23
def initialize(owner, *pins)
  options = pins.last.is_a?(Hash) ? pins.pop : {}
  options = {
    endian: :big
  }.merge(options)
  @power_pins = options.delete(:power_pin) || options.delete(:power_pins)
  @ground_pins = options.delete(:ground_pin) || options.delete(:ground_pins)
  @virtual_pins = options.delete(:virtual_pin) || options.delete(:virtual_pins)
  @other_pins = options.delete(:other_pin) || options.delete(:other_pins)
  @endian = options[:endian]
  @rtl_name = options[:rtl_name]
  @description = options[:description] || options[:desc]
  @options = options
  @store = []
  pins.each_with_index do |pin, i|
    @store[i] = pin
  end
  on_init(owner, options)
end

Public Instance Methods

<<(pin, _options = {})
Alias for: add_pin
[](*indexes) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 152
def [](*indexes)
  if indexes.size > 1 || indexes.first.is_a?(Range)
    p = PinCollection.new(owner, @options)
    expand_and_order(indexes).each do |index|
      p << @store[index]
    end
    p
  else
    @store[indexes.first]
  end
end
[]=(index, pin) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 174
def []=(index, pin)
  @store[index] = pin
end
add_pin(pin, _options = {}) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 203
def add_pin(pin, _options = {})
  if pin.is_a?(PinCollection)
    # Need this to bypass the endianness aware iteration, the storing order
    # is always the same. So can't use each and co here.
    pin.size.times do |i|
      pin[i].invalidate_group_cache
      @store.push(pin[i])
    end
  else
    # Convert any named reference to a pin object
    if power_pins?
      pin = owner.power_pins(pin)
    elsif ground_pins?
      pin = owner.ground_pins(pin)
    elsif other_pins?
      pin = owner.other_pins(pin)
    elsif virtual_pins?
      pin = owner.virtual_pins(pin)
    else
      pin = owner.pins(pin)
    end
    unless @store.include?(pin)
      pin.invalidate_group_cache
      @store.push(pin)
    end
  end
end
Also aliased as: <<
assert(value, options = {}) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 373
def assert(value, options = {})
  value = clean_value(value)
  each_with_index do |pin, i|
    if !value.respond_to?('data')
      pin.assert(value[size - i - 1], options)
    elsif value[size - i - 1].is_to_be_read?
      pin.assert(value[size - i - 1].data, options)
    else
      pin.dont_care
    end
  end
  myself
end
Also aliased as: compare, expect, read
assert!(*args) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 390
def assert!(*args)
  assert(*args)
  cycle
end
Also aliased as: compare!, expect!, read!
assert_hi(options = {}) click to toggle source

Set all pins in the pin group to expect 1’s on future cycles

# File lib/origen/pins/pin_collection.rb, line 399
def assert_hi(options = {})
  each { |pin| pin.assert_hi(options) }
  myself
end
Also aliased as: expect_hi, compare_hi, read_hi
assert_hi!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 407
def assert_hi!
  assert_hi
  cycle
end
Also aliased as: expect_hi!, compare_hi!, read_hi!
assert_lo(options = {}) click to toggle source

Set all pins in the pin group to expect 0’s on future cycles

# File lib/origen/pins/pin_collection.rb, line 416
def assert_lo(options = {})
  each { |pin| pin.assert_lo(options) }
  myself
end
Also aliased as: expect_lo, compare_lo, read_lo
assert_lo!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 424
def assert_lo!
  assert_lo
  cycle
end
Also aliased as: expect_lo!, compare_lo!, read_lo!
capture() click to toggle source

Mark the (data) from all the pins in the pin group to be captured

# File lib/origen/pins/pin_collection.rb, line 339
def capture
  each(&:capture)
  myself
end
Also aliased as: store
capture!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 345
def capture!
  capture
  cycle
end
Also aliased as: store!
compare(value, options = {})
Alias for: assert
compare!(*args)
Alias for: assert!
compare_hi(options = {})
Alias for: assert_hi
compare_hi!()
Alias for: assert_hi!
compare_lo(options = {})
Alias for: assert_lo
compare_lo!()
Alias for: assert_lo!
comparing?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 447
def comparing?
  all?(&:comparing?)
end
comparing_mem?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 451
def comparing_mem?
  all?(&:comparing_mem?)
end
cycle() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 369
def cycle
  Origen.tester.cycle
end
data() click to toggle source

Returns the data value held by the collection

Example

pins(:porta).write(0x55)
pins(:porta).data         #  => 0x55
# File lib/origen/pins/pin_collection.rb, line 309
def data
  data = 0
  each_with_index { |pin, i| data |= pin.data << (size - i - 1) }
  data
end
Also aliased as: val, value
data_b() click to toggle source

Returns the inverse of the data value held by the collection

# File lib/origen/pins/pin_collection.rb, line 318
def data_b
  # (& operation takes care of Bignum formatting issues)
  ~data & ((1 << size) - 1)
end
delete(p) click to toggle source

Deletes all occurrences of a pin in a pin group

# File lib/origen/pins/pin_collection.rb, line 480
def delete(p)
  @store.delete(p)
end
delete!() click to toggle source

Delete this pingroup (myself)

# File lib/origen/pins/pin_collection.rb, line 504
def delete!
  owner.delete_pin(myself)
end
delete_at(index) click to toggle source

Deletes the pin at a particular numeric index within the pin group

# File lib/origen/pins/pin_collection.rb, line 485
def delete_at(index)
  @store.delete_at(index)
end
describe(display = :id) click to toggle source

Describe the pin group contents. Default is to display pin.id but passing in :name will display pin.name

# File lib/origen/pins/pin_collection.rb, line 180
def describe(display = :id)
  desc = ['********************']
  desc << "Group id: #{id}"
  desc << "\nDescription: #{description}" if description
  desc << "\nEndianness: #{endian}"

  unless size == 0
    desc << ''
    desc << 'Pins'
    desc << '-------'
    if display == :id
      desc << map(&:id).join(', ')
    elsif display == :name
      desc << map(&:name).join(', ')
    else
      fail 'Error: Argument options for describe method are :id and :name.  Default is :id'
    end
  end

  desc << '********************'
  puts desc.join("\n")
end
dont_care() click to toggle source

Set all pins in the pin group to X on future cycles

# File lib/origen/pins/pin_collection.rb, line 433
def dont_care
  each(&:dont_care)
  myself
end
dont_care!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 438
def dont_care!
  dont_care
  cycle
end
drive(val) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 232
def drive(val)
  value = clean_value(value)
  each_with_index do |pin, i|
    pin.drive(val[size - i - 1])
  end
  myself
end
Also aliased as: write
drive!(val) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 241
def drive!(val)
  drive(val)
  cycle
end
Also aliased as: write!
drive_hi() click to toggle source

Set all pins in pin group to drive 1’s on future cycles

# File lib/origen/pins/pin_collection.rb, line 248
def drive_hi
  each(&:drive_hi)
  myself
end
Also aliased as: write_hi
drive_hi!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 254
def drive_hi!
  drive_hi
  cycle
end
Also aliased as: write_hi!
drive_lo() click to toggle source

Set all pins in pin group to drive 0’s on future cycles

# File lib/origen/pins/pin_collection.rb, line 261
def drive_lo
  each(&:drive_lo)
  myself
end
Also aliased as: write_lo
drive_lo!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 267
def drive_lo!
  drive_lo
  cycle
end
Also aliased as: write_lo!
drive_mem() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 285
def drive_mem
  each(&:drive_mem)
  myself
end
drive_mem!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 290
def drive_mem!
  drive_mem
  cycle
end
drive_very_hi() click to toggle source

Set all pins in the pin group to drive a high voltage on future cycles (if the tester supports it). For example on a J750 high-voltage channel the pin state would be set to “2”

# File lib/origen/pins/pin_collection.rb, line 275
def drive_very_hi
  each(&:drive_very_hi)
  myself
end
drive_very_hi!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 280
def drive_very_hi!
  drive_very_hi
  cycle
end
driving?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 455
def driving?
  all?(&:driving?)
end
driving_mem?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 459
def driving_mem?
  all?(&:driving_mem?)
end
each() { |store| ... } click to toggle source

Overrides the regular Ruby array each to be endian aware. If the pin collection/group is defined as big endian then this will yield the least significant pin first, otherwise for little endian the most significant pin will come out first.

# File lib/origen/pins/pin_collection.rb, line 138
def each
  size.times do |i|
    if endian == :big
      yield @store[size - i - 1]
    else
      yield @store[i]
    end
  end
end
expect(value, options = {})
Alias for: assert
expect!(*args)
Alias for: assert!
expect_hi(options = {})
Alias for: assert_hi
expect_hi!()
Alias for: assert_hi!
expect_lo(options = {})
Alias for: assert_lo
expect_lo!()
Alias for: assert_lo!
expect_mem() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 295
def expect_mem
  each(&:expect_mem)
  myself
end
expect_mem!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 300
def expect_mem!
  expect_mem
  cycle
end
global_path_to() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 47
def global_path_to
  "dut.pins(:#{id})"
end
ground_pins?() click to toggle source

Returns true if the pin collection contains ground pins rather than regular pins

# File lib/origen/pins/pin_collection.rb, line 108
def ground_pins?
  @ground_pins
end
high_voltage?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 463
def high_voltage?
  all?(&:high_voltage?)
end
id() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 122
def id
  @id
end
id=(val) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 365
def id=(val)
  @id = val.to_sym
end
invalidate_vector_cache() click to toggle source

@api private

# File lib/origen/pins/pin_collection.rb, line 72
def invalidate_vector_cache
  @vector_formatted_value = nil
end
inverted?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 443
def inverted?
  all?(&:inverted?)
end
is_to_be_captured?()
Alias for: to_be_captured?
is_to_be_stored?()
Alias for: to_be_captured?
name() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 131
def name
  @name || id
end
name=(val) click to toggle source

Explicitly set the name of a pin group/collection

# File lib/origen/pins/pin_collection.rb, line 127
def name=(val)
  @name = val
end
org_file_intercepted_methods() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 51
def org_file_intercepted_methods
  ORG_FILE_INTERCEPTED_METHODS
end
other_pins?() click to toggle source

Returns true if the pin collection contains other pins rather than regular pins

# File lib/origen/pins/pin_collection.rb, line 118
def other_pins?
  @other_pins
end
pins(nick = :id) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 489
      def pins(nick = :id)
        Origen.deprecate <<-END
The PinCollection#pins method is deprecated, if you want to get a list of pin IDs
in the given collection just do pins(:some_group).map(&:id)
Note that the pins method (confusingly) also does a sort, to replicate that:
pins(:some_group).map(&:id).sort
        END
        if nick == :id
          @store.map(&:id).sort
        elsif nick == :name
          @store.map(&:name).sort
        end
      end
power_pins?() click to toggle source

Returns true if the pin collection contains power pins rather than regular pins

# File lib/origen/pins/pin_collection.rb, line 103
def power_pins?
  @power_pins
end
read(value, options = {})
Alias for: assert
read!(*args)
Alias for: assert!
read_hi(options = {})
Alias for: assert_hi
read_hi!()
Alias for: assert_hi!
read_lo(options = {})
Alias for: assert_lo
read_lo!()
Alias for: assert_lo!
repeat_previous=(bool) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 333
def repeat_previous=(bool)
  each { |pin| pin.repeat_previous = bool }
  myself
end
repeat_previous?() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 467
def repeat_previous?
  all?(&:repeat_previous?)
end
restore() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 361
def restore
  each(&:restore)
end
restore_state() { || ... } click to toggle source
# File lib/origen/pins/pin_collection.rb, line 351
def restore_state
  save
  yield
  restore
end
rtl_name() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 43
def rtl_name
  (@rtl_name || id).to_s
end
save() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 357
def save
  each(&:save)
end
size() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 148
def size
  @store.size
end
sort!(&block) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 164
def sort!(&block)
  @store = sort(&block)
  myself
end
sort_by!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 169
def sort_by!
  @store = sort_by
  myself
end
store()
Alias for: capture
store!()
Alias for: capture!
to_be_captured?() click to toggle source

Returns true if the (data) from the pin collection is marked to be captured

# File lib/origen/pins/pin_collection.rb, line 472
def to_be_captured?
  all?(&:to_be_captured?)
end
to_be_stored?()
Alias for: to_be_captured?
to_vector() click to toggle source

Returns the value held by the pin group as a string formatted to the current tester’s pattern syntax

@example

pin_group.drive_hi
pin_group.to_vector   # => "11111111"
pin_group.expect_lo
pin_group.to_vector   # => "LLLLLLLL"
# File lib/origen/pins/pin_collection.rb, line 63
def to_vector
  return @vector_formatted_value if @vector_formatted_value

  vals = map(&:to_vector)
  vals.reverse! if endian == :little
  @vector_formatted_value = vals.join('')
end
toggle() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 323
def toggle
  each(&:toggle)
  myself
end
toggle!() click to toggle source
# File lib/origen/pins/pin_collection.rb, line 328
def toggle!
  toggle
  cycle
end
val()
Alias for: data
value()
Alias for: data
vector_formatted_value=(val) click to toggle source

Set the values and states of the pin group’s pins from a string formatted to the current tester’s pattern syntax, this is the opposite of the to_vector method

@example

pin_group.vector_formatted_value = "LLLLLLLL"
pin_group[0].driving?                          # => false
pin_group[0].value                             # => 0
pin_group.vector_formatted_value = "HHHH1111"
pin_group[0].driving?                          # => true
pin_group[0].value                             # => 1
pin_group[7].driving?                          # => false
pin_group[7].value                             # => 1
# File lib/origen/pins/pin_collection.rb, line 89
def vector_formatted_value=(val)
  unless @vector_formatted_value == val
    unless val.size == size
      fail 'When setting vector_formatted_value on a pin group you must supply values for all pins!'
    end

    val.split(//).reverse.each_with_index do |val, i|
      myself[i].vector_formatted_value = val
    end
    @vector_formatted_value = val
  end
end
virtual_pins?() click to toggle source

Returns true if the pin collection contains virtual pins rather than regular pins

# File lib/origen/pins/pin_collection.rb, line 113
def virtual_pins?
  @virtual_pins
end
write(val)
Alias for: drive
write!(val)
Alias for: drive!
write_hi()
Alias for: drive_hi
write_hi!()
Alias for: drive_hi!
write_lo()
Alias for: drive_lo
write_lo!()
Alias for: drive_lo!

Private Instance Methods

clean_value(val) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 510
def clean_value(val)
  return val if val.respond_to?(:contains_bits?)

  val = val.data if val.respond_to?('data')
  if val.is_a?(String) || val.is_a?(Symbol)
    Origen::Value.new(val)
  else
    val
  end
end
expand_and_order(*indexes) click to toggle source

Cleans up indexed references to pins, e.g. makes these equal:

pins(:pb)[0,1,2,3]
pins(:pb)[3,2,1,0]
pins(:pb)[0..3]
pins(:pb)[3..0]
# File lib/origen/pins/pin_collection.rb, line 527
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
method_missing(method, *args, &block) click to toggle source
# File lib/origen/pins/pin_collection.rb, line 543
def method_missing(method, *args, &block)
  # Where the collection is only comprised of one pin delegate missing methods/attributes
  # to that pin
  if size == 1
    first.send(method, *args, &block)
  # Send all assignment methods to all contained pins
  elsif method.to_s =~ /.*=$/
    each do |pin|
      pin.send(method, *args, &block)
    end
  else
    if block_given?
      fail 'Blocks are not currently supported by pin collections containing multiple pins!'
    else
      # Allow getters if all pins are the same
      ref = first.send(method, *args)
      if myself.all? { |pin| pin.send(method, *args) == ref }
        ref
      else
        fail "The pins held by pin collection #{id} have different values for #{method}"
      end
    end
  end
end