udb-gen 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92f11f140e0d89cf83792ae8c4b426710967352ba39d226e979b65f1f06fed1c
+  data.tar.gz: 55d515c69db630f9d1ba0c15fd8271f808a663469ebb998c50d46e15b40402c3
+SHA512:
+  metadata.gz: 247ac625e6bf5362c903cd39255ec1627cb3caffb535954cf9d69bf0e6afb7171dceaa15a49c2078bbe0d5c59c6a612e22b77db266ba914eb0d3afda702c20be
+  data.tar.gz: e597dc22ab56635f8ea312a69fee7c9766068ec1a0c6bdeee0c679d4258832b0777af499445a3062aa86b7fc59248a6a3a5a3a1a91f3bd327601ec2196643484

data/LICENSE

@@ -0,0 +1,26 @@
+SPDX-License-Identifier: BSD-3-Clause-Clear
+
+Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+(subject to the limitations in the disclaimer below) provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions
+  and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of
+  conditions and the following disclaimer in the documentation and/or other materials provided
+  with the distribution.
+* Neither the name of Qualcomm Innovation Center, Inc. nor the names of its contributors may be used
+  to endorse or promote products derived from this software without specific prior written
+  permission.
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS
+SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/bin/udb-gen

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: false
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require "tty-table"
+
+# Auto-load all generators
+Dir[File.join(__dir__, "../lib/udb-gen/generators/*/generator.rb")].sort.each do |f|
+  require f
+end
+
+include TTY::Exit
+
+def subcommands
+  @subcommands ||=
+    UdbGen::Subcommand.subclasses.map do |cmd_klass|
+      if cmd_klass.name == "UdbGen::SubcommandWithCommonOptions"
+        cmd_klass.subclasses.map do |subcmd_klass|
+          subcmd_klass.new
+        end
+      else
+        cmd_klass.new
+      end
+    end.flatten.sort { |a, b| a.name <=> b.name }
+end
+
+def subcommand_table
+  t = TTY::Table.new
+  subcommands.each do |cmd|
+    t << [cmd.name, cmd.desc]
+  end
+  t
+end
+
+def usage
+  <<~USAGE
+    #{$PROGRAM_NAME} SUB-COMMAND [OPTIONS]
+
+    Subcommands:
+    #{subcommand_table.render(:basic, indent: 4, multiline: true, padding: [0, 2, 0, 0])}
+
+    Run `#{$PROGRAM_NAME}` SUB-COMMAND --help` for details
+  USAGE
+end
+
+if ARGV.empty? || subcommands.find { |cmd| cmd.name == ARGV[0] }.nil?
+  puts usage
+
+  exit_with(:usage_error)
+end
+
+subcmd = subcommands.find { |cmd| cmd.name == ARGV[0] }
+subcmd.run(ARGV[1..])

data/lib/udb-gen/adoc_helpers.rb

@@ -0,0 +1,83 @@
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module UdbGen
+  module AdocHelpers
+    extend T::Sig
+    include Kernel
+
+    # Returns the :revmark: attribute value for the given ExtensionVersion.
+    sig { params(version: Udb::ExtensionVersion).returns(String) }
+    def state_revmark(version)
+      case version.state
+      when "ratified"
+        <<~STATE
+          This document is in the http://riscv.org/spec-state[Ratified state] + \\
+          + \\
+          No changes are allowed. + \\
+          Any desired or needed changes can be the subject of a follow-on new extension. + \\
+          Ratified extensions are never revised. + \\
+        STATE
+      when "frozen"
+        <<~STATE
+          This document is in the http://riscv.org/spec-state[Frozen state]. + \\
+          + \\
+          Change is extremely unlikely. + \\
+          A high threshold will be used, and a change will only occur because of some truly + \\
+          critical issue being identified during the public review cycle. + \\
+          Any other desired or needed changes can be the subject of a follow-on new extension. + \\
+        STATE
+      when "development"
+        <<~STATE
+          This document is in the http://riscv.org/spec-state[Development state]. + \\
+          + \\
+          Change should be expected + \\
+        STATE
+      else
+        raise "Unknown state: #{version.state}"
+      end
+    end
+
+    # Returns the preamble [WARNING] admonition block for the given ExtensionVersion.
+    sig { params(version: Udb::ExtensionVersion).returns(String) }
+    def state_preamble_adoc(version)
+      case version.state
+      when "ratified"
+        <<~ADOC
+          [WARNING]
+          .This document is in the link:http://riscv.org/spec-state[Ratified state]
+          ====
+          No changes are allowed. Any desired or needed changes can be the subject of a
+          follow-on new extension. Ratified extensions are never revised
+          ====
+        ADOC
+      when "frozen"
+        <<~ADOC
+          [WARNING]
+          This document is in the http://riscv.org/spec-state[Frozen state].
+          ====
+          Change is extremely unlikely.
+          A high threshold will be used, and a change will only occur because of some truly
+          critical issue being identified during the public review cycle.
+          Any other desired or needed changes can be the subject of a follow-on new extension.
+          ====
+        ADOC
+      when "development"
+        <<~ADOC
+          [WARNING]
+          This document is in the http://riscv.org/spec-state[Development state].
+          ====
+          Change should be expected
+          ====
+        ADOC
+      else
+        raise "Unknown state: #{version.state}"
+      end
+    end
+  end
+end

data/lib/udb-gen/common_opts.rb

@@ -0,0 +1,51 @@
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "subcommand"
+
+module UdbGen
+  class SubcommandWithCommonOptions < Subcommand
+    extend T::Sig
+    include TTY::Option
+
+    sig { params(name: String, desc: String).void }
+    def initialize(name:, desc:)
+      super(name:, desc:)
+    end
+
+    option :cfg do
+      T.bind(self, TTY::Option::Parameter::Option)
+      short "-c"
+      long "--cfg=cfg_name"
+      default "_"
+    end
+
+    flag :help do
+      T.bind(self, TTY::Option::Parameter::Option)
+      short "-h"
+      long "--help"
+      desc "Print usage"
+    end
+
+    sig { returns(Udb::Resolver) }
+    def resolver
+      @resolver ||= Udb::Resolver.new
+    end
+
+    sig { returns(Udb::ConfiguredArchitecture) }
+    def cfg_arch
+      @cfg_arch ||=
+        resolver.cfg_arch_for(params[:cfg])
+    end
+
+    sig { override.params(argv: T::Array[String]).returns(T.noreturn) }
+    def run(argv)
+      raise "must override #run in #{self.class.name}"
+    end
+  end
+end

data/lib/udb-gen/defines.rb

@@ -0,0 +1,14 @@
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module UdbGen
+  extend T::Sig
+
+  sig { returns(Pathname) }
+  def self.root = (Pathname.new(__dir__) / ".." / "..").realpath
+end

data/lib/udb-gen/generators/ext_doc/generator.rb

@@ -0,0 +1,228 @@
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: true
+# frozen_string_literal: true
+
+require "tty-exit"
+
+require_relative "../../common_opts"
+require_relative "../../defines"
+require_relative "../../template_helpers"
+require_relative "helpers"
+
+require "udb/obj/extension"
+
+module UdbGen
+  class GenExtPdfOptions < SubcommandWithCommonOptions
+    include TTY::Exit
+    include TemplateHelpers
+    include ExtDocHelpers
+    include AdocHelpers
+
+    NAME = "ext-doc"
+
+    sig { void }
+    def initialize
+      super(name: NAME, desc: "Create documentation for an extension")
+    end
+
+    usage \
+      command: NAME,
+      desc:   "Generate documentation for an extension defined in UDB",
+      example: <<~EXAMPLE
+        Generate documentation for the Zba extension
+          $ #{File.basename($PROGRAM_NAME)} #{NAME} -o Zba.pdf Zba
+
+        Generate documentation for the B extension and all it's subextensions
+          $ #{File.basename($PROGRAM_NAME)} #{NAME} -o B.pdf B Zba Zbb Zbss
+
+        Generate documentation for the A extension version 2.1.0
+          $ #{File.basename($PROGRAM_NAME)} #{NAME} -o A.pdf A@2.1.0
+
+        Generate documentation for the A extension latest version
+          $ #{File.basename($PROGRAM_NAME)} #{NAME} -o A.pdf A@latest
+
+        Generate documentation for the A extension, all versions >= 2.1.0
+          $ #{File.basename($PROGRAM_NAME)} #{NAME} -o A.pdf "A@>=2.1.0"
+      EXAMPLE
+
+    argument :extension do
+      T.bind(self, TTY::Option::Parameter::Argument)
+      arity one_or_more
+      desc "Extension(s) to generate documentation for."
+      validate ->(e) { e =~ /^(([A-WY])|([SXZ][a-z0-9]+))(@([0-9]+)(?:\.([0-9]+)(?:\.([0-9]+)(?:-(pre))?)?)?)?$/ }
+      convert :list
+    end
+
+    flag :include_implies do
+      T.bind(self, TTY::Option::Parameter::Option)
+      short "-i"
+      long "--implied_insts"
+      desc "Include a list of implied instructions when describing extension(s)"
+    end
+
+    flag :exclude_csr_field_descriptions do
+      T.bind(self, TTY::Option::Parameter::Option)
+      long "--no-csr-field-desc"
+      desc "Do not generate a long descrption of each CSR field (just a summary table)"
+    end
+
+    option :pseudo do
+      T.bind(self, TTY::Option::Parameter::Option)
+      short "-p"
+      long "--p=type"
+      desc "Which pdeudocode(s) to include in the documentation"
+      permit ["sail", "idl", "both"]
+      default "idl"
+    end
+
+    option :format do
+      T.bind(self, TTY::Option::Parameter::Option)
+      short "-f"
+      long "--f=format"
+      desc "Output format"
+      permit ["pdf"]
+      default "pdf"
+    end
+
+    option :output_dir do
+      T.bind(self, TTY::Option::Parameter::Option)
+      required
+      short "-o"
+      long "--out=directory"
+      desc "Output directory"
+      convert :path
+    end
+
+    option :output_basename do
+      T.bind(self, TTY::Option::Parameter::Option)
+      desc "Basename of the output files. Default is the name of the first listed extension"
+      short "-b"
+      long "--output-basename=basename"
+    end
+
+    option :theme do
+      T.bind(self, TTY::Option::Parameter::Option)
+      desc "Theme file for asciidoctor-pdf"
+      long "--theme=path"
+      convert :path
+      default UdbGen.root / "riscv-docs-resources" / "themes" / "riscv-pdf.yml"
+    end
+
+    option :fonts do
+      T.bind(self, TTY::Option::Parameter::Option)
+      desc "Fonts directory"
+      long "--fonts=path"
+      convert :path
+      default UdbGen.root / "riscv-docs-resources" / "fonts"
+    end
+
+    option :images do
+      T.bind(self, TTY::Option::Parameter::Option)
+      desc "Images directory"
+      long "--images=path"
+      convert :path
+      default UdbGen.root / "riscv-docs-resources" / "images"
+    end
+
+    option :debug do
+      T.bind(self, TTY::Option::Parameter::Option)
+      desc "Set debug level"
+      long "--debug=level"
+      short "-d"
+      default "info"
+      permit ["debug", "info", "warn", "error", "fatal"]
+    end
+
+    def basename
+      params[:output_basename].nil? ? params[:extension][0] : params[:output_basename]
+    end
+
+    def gen_adoc
+      ext_reqs = T.let([], T::Array[Udb::ExtensionRequirement])
+      Udb.log_level = Udb::LogLevel.deserialize(params[:debug])
+      params[:extension].each do |ext_req_str|
+        ext_name, req = ext_req_str.split("@")
+        ext = cfg_arch.extension(ext_name)
+        exit_with(:data_err, "No extension named '#{ext_name}'\n") if ext.nil?
+        req =
+          case req
+          when nil
+            ">=0"
+          when "latest"
+            "=#{ext.versions.max}"
+          else
+            "=#{req}"
+          end
+        ext_reqs << cfg_arch.extension_requirement(ext_name, req)
+      end
+
+      primary_ext = ext_reqs.fetch(0).extension
+      max_version = ext_reqs.fetch(0).satisfying_versions.max
+
+      template_path = Pathname.new(Gem.loaded_specs["udb-gen"].full_gem_path) / "templates" / "ext_doc" / "ext_pdf.adoc.erb"
+      gen_filename = params[:output_dir] / "#{basename}.adoc"
+
+      erb = ERB.new(template_path.read, trim_mode: "-")
+      erb.filename = template_path.to_s
+
+      FileUtils.mkdir_p params[:output_dir]
+      File.write gen_filename, resolve_intermediate_links(cfg_arch, convert_monospace_to_links(cfg_arch, erb.result(binding)))
+
+    end
+
+    sig { void }
+    def gen_pdf
+      gen_adoc
+      adoc_filename = params[:output_dir] / "#{basename}.adoc"
+      pdf_filename = params[:output_dir] / "#{basename}.pdf"
+
+      Udb.logger.info "Running asciidoctor-pdf"
+      cmd = [
+        "asciidoctor-pdf",
+        "-w",
+        "-v",
+        "-a toc",
+        "-a compress",
+        "-a pdf-theme=#{params[:theme]}",
+        "-a pdf-fontsdir=#{params[:fonts]}",
+        "-a imagesdir=#{params[:images]}",
+        "-r asciidoctor-diagram",
+        "-r idl_highlighter",
+        "-a wavedrom=/opt/node/node_modules/.bin/wavedrom-cli",
+        "-o #{pdf_filename}",
+        adoc_filename
+      ].join(" ")
+
+      Udb.logger.debug cmd
+      system cmd
+
+      puts "SUCCESS! Wrote result to #{pdf_filename}"
+    end
+
+
+    sig { override.params(argv: T::Array[String]).returns(T.noreturn) }
+    def run(argv)
+      parse(argv)
+
+      if params[:help]
+        print help
+        exit_with(:success)
+      end
+
+      if params.errors.any?
+        exit_with(:usage_error, "#{params.errors.summary}\n\n#{help}")
+      end
+
+      unless params.remaining.empty?
+        exit_with(:usage_error, "Unknown arguments: #{params.remaining}\n")
+      end
+
+      gen_pdf
+
+      exit_with(:success)
+    end
+
+  end
+end

data/lib/udb-gen/generators/ext_doc/helpers.rb

@@ -0,0 +1,63 @@
+# Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+# SPDX-License-Identifier: BSD-3-Clause-Clear
+
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module UdbGen
+  module ExtDocHelpers
+    extend T::Sig
+    include Kernel
+
+    # Returns the copyright year string for a version.
+    # Uses ratification_date year if available, otherwise current year.
+    sig { params(version: Udb::ExtensionVersion).returns(String) }
+    def copyright_year(version)
+      version.ratification_date.nil? ? Date.today.year.to_s : T.must(version.ratification_date).split("-")[0]
+    end
+
+    # Returns the revdate for a version (ratification date or today).
+    sig { params(version: Udb::ExtensionVersion).returns(T.any(String, Date)) }
+    def revdate(version)
+      version.ratification_date.nil? ? Date.today : version.ratification_date
+    end
+
+    # Returns the company name or "unknown".
+    sig { params(ext: Udb::Extension).returns(String) }
+    def company_name(ext)
+      ext.company.nil? ? "unknown" : T.must(ext.company).name
+    end
+
+    # Returns the doc license name or "unknown".
+    sig { params(ext: Udb::Extension).returns(String) }
+    def doc_license_name(ext)
+      ext.doc_license.nil? ? "unknown" : T.must(ext.doc_license).fetch("name")
+    end
+
+    # Returns the doc license URL or "unknown".
+    sig { params(ext: Udb::Extension).returns(String) }
+    def doc_license_url(ext)
+      ext.doc_license.nil? ? "unknown" : T.must(ext.doc_license).fetch("url")
+    end
+
+    # Returns true if the extension is RISC-V International branded.
+    sig { params(ext: Udb::Extension).returns(T::Boolean) }
+    def riscv_branded?(ext)
+      !ext.company.nil? && !(T.must(ext.company).name =~ /RISCV/).nil?
+    end
+
+    # Returns contributors for a version, sorted by last name.
+    sig { params(version: Udb::ExtensionVersion).returns(T::Array[Udb::Person]) }
+    def sorted_contributors(version)
+      version.contributors.sort { |a, b| T.must(a.name.split(" ").last <=> b.name.split(" ").last) }
+    end
+
+    # Returns all versions across all ext_reqs, flattened.
+    sig { params(ext_reqs: T::Array[Udb::ExtensionRequirement]).returns(T::Array[Udb::ExtensionVersion]) }
+    def all_versions(ext_reqs)
+      ext_reqs.map(&:satisfying_versions).flatten
+    end
+  end
+end