Class: Udb::Portfolio

Inherits:
TopLevelDatabaseObject show all
Defined in:
lib/udb/obj/portfolio.rb

Overview

Holds information about a Portfolio (certificate or profile). The inherited “data” member is YAML data from the architecture for this portfolio object.

Direct Known Subclasses

ProcCertModel, Profile

Defined Under Namespace

Classes: ExtraNote, InScopeParameter, Recommendation, RevisionHistory

Instance Method Summary collapse

Constructor Details

#initialize(obj_yaml, yaml_path, arch)

Parameters:

  • data_path (String) —

    Path to yaml file

  • obj_yaml (Hash{String => Object}) —

    Contains contents of Portfolio yaml file (put in @data)

  • yaml_path (String, Pathname)
  • arch (ConfiguredArchitecture) —

    Entire database of RISC-V architecture standards



357
358
359
 
# File 'lib/udb/obj/portfolio.rb', line 357

def initialize(obj_yaml, yaml_path, arch)
  super # Calls parent class with same args I got
end

Instance Method Details

#all_in_scope_exts_with_param(param) ⇒ Array<Extension>

Returns Sorted list of all in-scope extensions that define this parameter in the database and the parameter is in-scope.

Parameters:

Returns:

  • (Array<Extension>) —

    Sorted list of all in-scope extensions that define this parameter in the database and the parameter is in-scope.



704
 
# File 'lib/udb/obj/portfolio.rb', line 704

def all_in_scope_exts_with_param(param) = []

#all_in_scope_exts_without_param(param) ⇒ Array<Extension>

Returns List of all in-scope extensions that define this parameter in the database but the parameter is out-of-scope.

Parameters:

Returns:

  • (Array<Extension>) —

    List of all in-scope extensions that define this parameter in the database but the parameter is out-of-scope.



709
 
# File 'lib/udb/obj/portfolio.rb', line 709

def all_in_scope_exts_without_param(param) = []

#all_in_scope_params ⇒ Array<InScopeParameter>

Returns List of parameters specified by any extension in portfolio.

Returns:

  • (Array<InScopeParameter>) —

    List of parameters specified by any extension in portfolio.



688
 
# File 'lib/udb/obj/portfolio.rb', line 688

def all_in_scope_params = []

#all_out_of_scope_params ⇒ Array<Parameter>

Returns Sorted list of parameters out of scope across all in scope extensions.

Returns:

  • (Array<Parameter>) —

    Sorted list of parameters out of scope across all in scope extensions.



695
 
# File 'lib/udb/obj/portfolio.rb', line 695

def all_out_of_scope_params = []

#base ⇒ Integer

Returns 32 or 64.

Returns:

  • (Integer) —

    32 or 64



368
 
# File 'lib/udb/obj/portfolio.rb', line 368

def base = @data["base"]

#csr_presence(csr_name) ⇒ String

Returns Given an CSR csr_name, return the presence as a string. If the CSR name isn’t found in the portfolio, return “-”.

Returns:

  • (String) —

    Given an CSR csr_name, return the presence as a string. If the CSR name isn’t found in the portfolio, return “-”.



466
467
468
469
470
471
472
473
474
 
# File 'lib/udb/obj/portfolio.rb', line 466

def csr_presence(csr_name)
  @csr_presence ||= {}

  return @csr_presence[csr_name] unless @csr_presence[csr_name].nil?

  presence_obj = csr_presence_obj(csr_name)

  @csr_presence[csr_name] = presence_obj.nil? ? "-" : presence_obj.to_s
end

#csr_presence_obj(csr_name) ⇒ Presence

Returns Given an CSR csr_name, return the presence. If the CSR name isn’t found in the portfolio, return nil.

Returns:

  • (Presence) —

    Given an CSR csr_name, return the presence. If the CSR name isn’t found in the portfolio, return nil.



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/udb/obj/portfolio.rb', line 435

def csr_presence_obj(csr_name)
  @csr_presence_obj ||= {}

  return @csr_presence_obj[csr_name] unless @csr_presence_obj[csr_name].nil?

  csr = arch.csr(csr_name)

  raise "Can't find CSR object '#{csr_name}' in arch class" if csr.nil?

  is_mandatory = mandatory_ext_reqs.any? do |ext_req|
    ext_versions = ext_req.satisfying_versions
    ext_versions.any? { |ext_ver| csr.defined_by_condition.possibly_satisfied_by?(ext_ver) }
  end

  is_optional = optional_ext_reqs.any? do |ext_req|
    ext_versions = ext_req.satisfying_versions
    ext_versions.any? { |ext_ver| csr.defined_by_condition.possibly_satisfied_by?(ext_ver) }
  end

  @csr_presence_obj[csr_name] =
    if is_mandatory
      Presence.new(Presence.mandatory)
    elsif is_optional
      Presence.new(Presence.optional)
    else
      nil
    end
end

#description ⇒ String

Returns Large enough to need its own heading (generally one level deeper than the “introduction”).

Returns:

  • (String) —

    Large enough to need its own heading (generally one level deeper than the “introduction”).



365
 
# File 'lib/udb/obj/portfolio.rb', line 365

def description = @data["description"]

#extension_note(ext_name) ⇒ String?

Returns:

  • (String) —

    The note associated with extension ext_name

  • (nil) —

    if there is no note for ext_name



509
510
511
512
513
514
515
 
# File 'lib/udb/obj/portfolio.rb', line 509

def extension_note(ext_name)
  # Get extension information from YAML for passed in extension name.
  ext_data = @data["extensions"][ext_name]
  raise "Cannot find extension named #{ext_name}" if ext_data.nil?

  return ext_data["note"] unless ext_data.nil?
end

#extension_presence(ext_name) ⇒ String

Returns Given an extension ext_name, return the presence as a string. If the extension name isn’t found in the portfolio, return “-”.

Returns:

  • (String) —

    Given an extension ext_name, return the presence as a string. If the extension name isn’t found in the portfolio, return “-”.



384
385
386
387
388
 
# File 'lib/udb/obj/portfolio.rb', line 384

def extension_presence(ext_name)
  presence_obj = extension_presence_obj(ext_name)

  presence_obj.nil? ? "-" : presence_obj.to_s
end

#extension_presence_obj(ext_name) ⇒ Presence

Returns Given an extension ext_name, return the presence. If the extension name isn’t found in the portfolio, return nil.

Returns:

  • (Presence) —

    Given an extension ext_name, return the presence. If the extension name isn’t found in the portfolio, return nil.



375
376
377
378
379
380
 
# File 'lib/udb/obj/portfolio.rb', line 375

def extension_presence_obj(ext_name)
  # Get extension information from YAML for passed in extension name.
  ext_data = @data["extensions"][ext_name]

  ext_data.nil? ? nil : Presence.new(ext_data["presence"])
end

#extra_notes ⇒ Object 



811
812
813
814
815
816
817
818
819
 
# File 'lib/udb/obj/portfolio.rb', line 811

def extra_notes
  return @extra_notes unless @extra_notes.nil?

  @extra_notes = []
  @data["extra_notes"]&.each do |extra_note|
    @extra_notes << ExtraNote.new(extra_note)
  end
  @extra_notes
end

#extra_notes_for_presence(desired_presence_obj) ⇒ String?

Parameters:

Returns:

  • (String) —

    Note for desired_presence

  • (nil) —

    No note for desired_presence

Raises:

  • (ArgumentError) 


824
825
826
827
828
 
# File 'lib/udb/obj/portfolio.rb', line 824

def extra_notes_for_presence(desired_presence_obj)
  raise ArgumentError, "Expecting Presence but got a #{desired_presence_obj.class}" unless desired_presence_obj.is_a?(Presence)

  extra_notes.select {|extra_note| extra_note.presence_obj == desired_presence_obj}
end

#in_scope_csrs(design) ⇒ Array<Csr>

Returns Unsorted list of all CSRs associated with extensions listed as mandatory or optional in portfolio. Uses CSRs provided by the minimum version of the extension that meets the extension requirement.

Parameters:

  • design (Design) —

    The design

Returns:

  • (Array<Csr>) —

    Unsorted list of all CSRs associated with extensions listed as mandatory or optional in portfolio. Uses CSRs provided by the minimum version of the extension that meets the extension requirement.

Raises:

  • (ArgumentError) 


621
622
623
624
625
626
627
628
 
# File 'lib/udb/obj/portfolio.rb', line 621

def in_scope_csrs(design)
  raise ArgumentError, "Require an PortfolioDesign object but got a #{design.class} object" unless design.is_a?(PortfolioDesign)

  return @in_scope_csrs unless @in_scope_csrs.nil?

  @in_scope_csrs =
    in_scope_min_satisfying_extension_versions.map {|ext_ver| ext_ver.in_scope_csrs(design) }.flatten.uniq
end

#in_scope_exception_codes(design) ⇒ Array<ExceptionCode>

TODO: See github.com/riscv-software-src/riscv-unified-db/issues/291 TODO: Still needs work and haven’t created in_scope_interrupt_codes yet. TODO: Extensions should provide conditional information (“when” statements?)

that we evaluate here to determine if a particular exception code can
actually be generated in a design.
Also, probably shouldn't be calling "ext?" since that doesn't the in_scope lists of extensions.

Parameters:

  • design (Design) —

    The design

Returns:

  • (Array<ExceptionCode>) —

    Unsorted list of all in-scope exception codes.

Raises:

  • (ArgumentError) 


638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
 
# File 'lib/udb/obj/portfolio.rb', line 638

def in_scope_exception_codes(design)
  raise ArgumentError, "Require an PortfolioDesign object but got a #{design.class} object" unless design.is_a?(PortfolioDesign)

  return @in_scope_exception_codes unless @in_scope_exception_codes.nil?

  @in_scope_exception_codes =
    in_scope_min_satisfying_extension_versions.reduce([]) do |list, ext_version|
      ecodes = ext_version.ext.data["exception_codes"]
      next list if ecodes.nil?

      ecodes.each do |ecode|
        # Require all exception codes be unique in a given portfolio.
        raise "Duplicate exception code" if list.any? { |e| e.num == ecode["num"] || e.name == ecode["name"] || e.var == ecode["var"] }

        unless ecode.dig("when", "version").nil?
          # check version
          next unless design.ext?(ext_version.name.to_sym, [ecode["when"]["version"]])
        end
        list << ExceptionCode.new(ecode["name"], ecode["var"], ecode["num"], ext_version.ext)
      end
      list
    end
end

#in_scope_ext_reqs(desired_presence = nil) ⇒ Array<ExtensionRequirements>

If desired_presence is provided, only returns extensions with that presence. If desired_presence is a String, only the presence portion of an Presence is compared.

Parameters:

  • desired_presence (String, Hash, Presence) (defaults to: nil)

Returns:

  • (Array<ExtensionRequirements>) —

    Sorted list of extensions with their portfolio information.



525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File 'lib/udb/obj/portfolio.rb', line 525

def in_scope_ext_reqs(desired_presence = nil)
  in_scope_ext_reqs = []

  # Convert desired_present argument to Presence object if not nil.
  desired_presence_converted =
    desired_presence.nil?            ? nil :
    desired_presence.is_a?(String)   ? desired_presence :
    desired_presence.is_a?(Presence) ? desired_presence :
                                       Presence.new(desired_presence)

  missing_ext = false

  @data["extensions"]&.each do |ext_name, ext_data|
    next if ext_name[0] == "$"

    # Does extension even exist?
    # If not, don't raise an error right away so we can find all of the missing extensions and report them all.
    ext = arch.extension(ext_name)
    if ext.nil?
      puts "Extension #{ext_name} for #{name} not found in database"
      missing_ext = true
    else
      actual_presence = ext_data["presence"]    # Could be a String or Hash
      raise "Missing extension presence for extension #{ext_name}" if actual_presence.nil?

      # Convert presence String or Hash to object.
      actual_presence_obj = Presence.new(actual_presence)

      match =
        if desired_presence.nil?
          true # Always match
        else
          actual_presence_obj == desired_presence_converted
        end

      if match
        in_scope_ext_reqs <<
          if ext_data.key?("version")
            ExtensionRequirement.new(
              ext_name, ext_data["version"], arch: @arch,
              presence: actual_presence_obj, note: ext_data["note"], req_id: "REQ-EXT-#{ext_name}")
          else
            ExtensionRequirement.new(
              ext_name, [], arch: @arch,
              presence: actual_presence_obj, note: ext_data["note"], req_id: "REQ-EXT-#{ext_name}")
          end
      end
    end
  end

  raise "One or more extensions referenced by #{name} missing in database" if missing_ext

  in_scope_ext_reqs.sort_by!(&:name)
end

#in_scope_extensions ⇒ Array<Extension>

Returns Sorted list of all mandatory or optional extensions in portfolio. Each extension can have multiple versions (contains ExtensionVersion array).

Returns:

  • (Array<Extension>) —

    Sorted list of all mandatory or optional extensions in portfolio. Each extension can have multiple versions (contains ExtensionVersion array).



582
583
584
585
586
587
588
589
590
 
# File 'lib/udb/obj/portfolio.rb', line 582

def in_scope_extensions
  return @in_scope_extensions unless @in_scope_extensions.nil?

  @in_scope_extensions = in_scope_ext_reqs.map do |ext_req|
    ext_req.extension
  end.reject(&:nil?)  # Filter out extensions that don't exist yet.

  @in_scope_extensions.sort_by!(&:name)
end

#in_scope_instructions(design) ⇒ Array<Instruction>

Returns Sorted list of all instructions associated with extensions listed as mandatory or optional in portfolio. Uses instructions provided by the minimum version of the extension that meets the extension requirement.

Parameters:

  • design (Design) —

    The design

Returns:

  • (Array<Instruction>) —

    Sorted list of all instructions associated with extensions listed as mandatory or optional in portfolio. Uses instructions provided by the minimum version of the extension that meets the extension requirement.

Raises:

  • (ArgumentError) 


608
609
610
611
612
613
614
615
 
# File 'lib/udb/obj/portfolio.rb', line 608

def in_scope_instructions(design)
  raise ArgumentError, "Require an PortfolioDesign object but got a #{design.class} object" unless design.is_a?(PortfolioDesign)

  return @in_scope_instructions unless @in_scope_instructions.nil?

  @in_scope_instructions =
    in_scope_min_satisfying_extension_versions.map {|ext_ver| ext_ver.in_scope_instructions(design) }.flatten.uniq.sort
end

#in_scope_interrupt_codes(design) ⇒ Array<InterruptCode>

TODO: Actually implement this to use Design. See in_scope_exception_codes() above.

Parameters:

  • design (Design) —

    The design

Returns:

  • (Array<InterruptCode>) —

    Unsorted list of all in-scope interrupt codes.



665
 
# File 'lib/udb/obj/portfolio.rb', line 665

def in_scope_interrupt_codes(design) = arch.interrupt_codes

#in_scope_min_satisfying_extension_versions ⇒ ExtensionVersion

Returns List of all mandatory or optional extensions listed in portfolio. The minimum version of each extension that satisfies the extension requirements is provided.

Returns:

  • (ExtensionVersion) —

    List of all mandatory or optional extensions listed in portfolio. The minimum version of each extension that satisfies the extension requirements is provided.



594
595
596
597
598
599
600
601
602
 
# File 'lib/udb/obj/portfolio.rb', line 594

def in_scope_min_satisfying_extension_versions
  return @in_scope_min_satisfying_extension_versions unless @in_scope_min_satisfying_extension_versions.nil?

  @in_scope_min_satisfying_extension_versions = in_scope_ext_reqs.map do |ext_req|
    ext_req.satisfying_versions.min
  end.reject(&:nil?)  # Filter out extensions that don't exist yet.

  @in_scope_min_satisfying_extension_versions
end

#in_scope_params(ext_req) ⇒ Array<InScopeParameter>

Returns Sorted list of extension parameters from portfolio for given extension.

Parameters:

Returns:

  • (Array<InScopeParameter>) —

    Sorted list of extension parameters from portfolio for given extension.



692
 
# File 'lib/udb/obj/portfolio.rb', line 692

def in_scope_params(ext_req) = []

#instruction_presence(inst_name) ⇒ String

Returns Given an instruction inst_name, return the presence as a string. If the instruction name isn’t found in the portfolio, return “-”.

Returns:

  • (String) —

    Given an instruction inst_name, return the presence as a string. If the instruction name isn’t found in the portfolio, return “-”.



423
424
425
426
427
428
429
430
431
 
# File 'lib/udb/obj/portfolio.rb', line 423

def instruction_presence(inst_name)
  @instruction_presence ||= {}

  return @instruction_presence[inst_name] unless @instruction_presence[inst_name].nil?

  presence_obj = instruction_presence_obj(inst_name)

  @instruction_presence[inst_name] = presence_obj.nil? ? "-" : presence_obj.to_s
end

#instruction_presence_obj(inst_name) ⇒ Presence

Returns Given an instruction inst_name, return the presence. If the instruction name isn’t found in the portfolio, return nil.

Returns:

  • (Presence) —

    Given an instruction inst_name, return the presence. If the instruction name isn’t found in the portfolio, return nil.



392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/udb/obj/portfolio.rb', line 392

def instruction_presence_obj(inst_name)
  @instruction_presence_obj ||= {}

  return @instruction_presence_obj[inst_name] unless @instruction_presence_obj[inst_name].nil?

  inst = arch.instruction(inst_name)

  raise "Can't find instruction object '#{inst_name}' in arch class" if inst.nil?

  is_mandatory = mandatory_ext_reqs.any? do |ext_req|
    ext_versions = ext_req.satisfying_versions
    ext_versions.any? { |ext_ver| inst.defined_by_condition.possibly_satisfied_by?(ext_ver) }
  end

  is_optional = optional_ext_reqs.any? do |ext_req|
    ext_versions = ext_req.satisfying_versions
    ext_versions.any? { |ext_ver| inst.defined_by_condition.possibly_satisfied_by?(ext_ver) }
  end

  @instruction_presence_obj[inst_name] =
    if is_mandatory
      Presence.new(Presence.mandatory)
    elsif is_optional
      Presence.new(Presence.optional)
    else
      nil
    end
end

#introduction ⇒ String

Returns Small enough (~1 paragraph) to be suitable immediately after a higher-level heading.

Returns:

  • (String) —

    Small enough (~1 paragraph) to be suitable immediately after a higher-level heading.



362
 
# File 'lib/udb/obj/portfolio.rb', line 362

def introduction = @data["introduction"]

#mandatory_ext_reqs ⇒ Object 



517
 
# File 'lib/udb/obj/portfolio.rb', line 517

def mandatory_ext_reqs = in_scope_ext_reqs(Presence.mandatory)

#optional_ext_reqs ⇒ Object 



518
 
# File 'lib/udb/obj/portfolio.rb', line 518

def optional_ext_reqs = in_scope_ext_reqs(Presence.optional)

#optional_type_ext_reqs ⇒ Object 



519
 
# File 'lib/udb/obj/portfolio.rb', line 519

def optional_type_ext_reqs = in_scope_ext_reqs(Presence.optional)

#out_of_scope_params(ext_name) ⇒ Array<Parameter>

Returns Sorted list of parameters that are out of scope for named extension.

Parameters:

  • ext_name (String) —

    Extension name

Returns:

  • (Array<Parameter>) —

    Sorted list of parameters that are out of scope for named extension.



699
 
# File 'lib/udb/obj/portfolio.rb', line 699

def out_of_scope_params(ext_name) = []

#recommendations ⇒ Object 



842
843
844
845
846
847
848
849
850
 
# File 'lib/udb/obj/portfolio.rb', line 842

def recommendations
  return @recommendations unless @recommendations.nil?

  @recommendations = []
  @data["recommendations"]&.each do |recommendation|
    @recommendations << Recommendation.new(recommendation)
  end
  @recommendations
end

#revision_history ⇒ Object 



786
787
788
789
790
791
792
793
794
 
# File 'lib/udb/obj/portfolio.rb', line 786

def revision_history
  return @revision_history unless @revision_history.nil?

  @revision_history = []
  @data["revision_history"].each do |rev|
    @revision_history << RevisionHistory.new(rev)
  end
  @revision_history
end

#uses_optional_types? ⇒ Boolean

Returns Does the profile differentiate between different types of optional.

Returns:

  • (Boolean) —

    Does the profile differentiate between different types of optional.



668
669
670
671
672
673
674
675
676
677
678
679
680
 
# File 'lib/udb/obj/portfolio.rb', line 668

def uses_optional_types?
  return @uses_optional_types unless @uses_optional_types.nil?

  @uses_optional_types = false

  in_scope_ext_reqs(Presence.optional)&.each do |ext_req|
    if ext_req.presence.uses_optional_types?
      @uses_optional_types = true
    end
  end

  @uses_optional_types
end

#version ⇒ Gem::Version

Returns Semantic version of the Portfolio.

Returns:

  • (Gem::Version) —

    Semantic version of the Portfolio



371
 
# File 'lib/udb/obj/portfolio.rb', line 371

def version = Gem::Version.new(@data["version"])

#version_greatest_presence(ext_name, ext_versions) ⇒ Array<String>

Returns the greatest presence string for each of the specified versions.

Parameters:

Returns:

  • (Array<String>) 


480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
 
# File 'lib/udb/obj/portfolio.rb', line 480

def version_greatest_presence(ext_name, ext_versions)
  presences = []

  # See if any extension requirement in this profile lists this version as either mandatory or optional.
  ext_versions.map do |v|
    greatest_presence = nil

    in_scope_ext_reqs.each do |ext_req|
      if ext_req.satisfied_by?(v)
        presence = extension_presence_obj(ext_name)

        unless presence.nil?
          if greatest_presence.nil?
            greatest_presence = presence
          elsif presence > greatest_presence
            greatest_presence = presence
          end
        end
      end
    end

    presences << (greatest_presence.nil? ? "-" : greatest_presence.to_s_concise)
  end

  presences
end