Testing a text format for instruction database

Gemfile

@@ -2,4 +2,6 @@ source 'http://rubygems.org'
 
 gem 'asciidoctor'
 gem 'asciidoctor-pdf'
-gem 'asciidoctor-revealjs'
+gem 'json_schemer'
+gem 'clamp'
+gem 'prmd'

Gemfile.lock

@@ -17,12 +17,22 @@ GEM
       prawn-templates (~> 0.1.0)
       treetop (~> 1.6.0)
       ttfunk (~> 1.7.0)
-    asciidoctor-revealjs (5.1.0)
-      asciidoctor (>= 2.0.0, < 3.0.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.7)
+    clamp (1.3.2)
     concurrent-ruby (1.2.3)
     css_parser (1.17.1)
       addressable
+    erubis (2.7.0)
+    hana (1.3.7)
     hashery (2.1.2)
+    json_schema (0.21.0)
+    json_schemer (2.2.1)
+      base64
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
     matrix (0.4.2)
     pdf-core (0.9.0)
     pdf-reader (2.12.0)
@@ -47,20 +57,31 @@ GEM
     prawn-templates (0.1.2)
       pdf-reader (~> 2.0)
       prawn (~> 2.2)
+    prmd (0.14.0)
+      erubis (~> 2.7)
+      json_schema (~> 0.3, >= 0.3.1)
     public_suffix (5.0.5)
+    regexp_parser (2.9.0)
     rexml (3.2.6)
     ruby-rc4 (0.1.5)
+    simpleidn (0.2.1)
+      unf (~> 0.1.4)
     treetop (1.6.12)
       polyglot (~> 0.3)
     ttfunk (1.7.0)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.9.1)
 
 PLATFORMS
   x64-mingw-ucrt
 
 DEPENDENCIES
   asciidoctor
   asciidoctor-pdf
-  asciidoctor-revealjs
+  clamp
+  json_schemer
+  prmd
 
 BUNDLED WITH
    2.5.9

bin/do.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+
+require 'clamp'
+require 'json_schemer'
+require 'yaml'
+require 'json'
+require 'erb'
+
+ROOT=File.realpath(File.dirname(File.dirname(__FILE__)))
+
+class InstCmd < Clamp::Command
+  subcommand "check", "Check the validity of the instruction database" do
+
+    def execute
+      schema = File.read("#{ROOT}/insts/inst_schema.json")
+      unless JSONSchemer.schema(schema)
+        raise "Invalid JSON schema for instructions: #{JSONSchemer.schema(schema).validate_schema.to_a}"
+      end
+
+      validator = JSONSchemer.schema(schema)
+      Dir.glob("#{ROOT}/insts/*.yaml") do |f|
+        data = YAML.load(File.read(f))
+        unless validator.valid?(data)
+          raise "In file #{f}:\n  Invalid format\n  #{validator.validate(data).to_a[0]['error']}"
+        end
+      end
+    end
+  end
+
+  subcommand 'schema_doc', 'Generate documentation for the schema' do
+    def execute
+      s = JSON.load(File.read("#{ROOT}/insts/inst_schema.json"))
+
+      t = ERB.new(<<~TEMPLATE, trim_mode: '-'
+        = <%= title %>
+        
+        <%= description %>
+
+        == Properties
+
+        [cols="1,2,2"]
+        |===
+        | Name | Description | Attributes
+
+        <% items['properties'].each do |name, attr| %>
+        a| `<%= name %>`
+
+        | <%= attr['description'] %>
+
+        a|
+        [horizontal]
+        Type:: <%= attr['type'] %>
+        <%- if attr.key?('examples') -%>
+        Examples:: <%= attr['examples'].join(', ') %>
+        <%- end -%>
+        Required?:: <%= items['required_properties'].any?(key) %>
+
+        <% end %>
+      TEMPLATE
+      )
+
+      puts "Writing documentation to insts/inst_schema.adoc"
+      File.write "#{ROOT}/insts/inst_schema.adoc", t.result(OpenStruct.new(s).instance_eval { binding })
+    end
+  end
+end
+
+class Main < Clamp::Command
+  subcommand "inst", "Work with the instruction database", InstCmd
+
+  def execute
+  end
+end
+
+Main.run

do

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# path to bundle executable
+BUNDLE=${BUNDLE:-bundle}
+
+ROOT=$(realpath $(dirname ${BASH_SOURCE[0]}))
+
+which $BUNDLE 2>&1 > /dev/null
+if [ $? -eq 1 ]; then
+  >&2 echo "No bundle executable found. Either install it, or set the BUNDLE environment variable to the executable path"
+  exit 1
+fi
+
+if [ ! -d .bundle ]; then
+  $BUNDLE config set --local path .bundle/gems
+fi
+
+if [ ! -d .bundle/gems ]; then
+  echo "Installing gems"
+  $BUNDLE install
+fi
+
+bundle check 2>&1 > /dev/null
+if [ $? -eq 1 ]; then
+  echo "Installing new gems"
+  $BUNDLE install
+fi
+
+# pass everything to ruby
+bundle exec ruby "$ROOT"/bin/do.rb "$@"

insts/inst_schema.adoc

@@ -0,0 +1,135 @@
+= Schema for instruction descriptions
+
+A list of candidate instructions for RISC-V Scalar Efficiency
+
+== Properties
+
+[cols="1,2,2"]
+|===
+| Name | Description | Attributes
+
+
+a| `mnemonic`
+
+| Proposed instruction mnemonic
+
+a|
+[horizontal]
+Type:: string
+Examples:: BNEI, J.FAR
+Required?:: false
+
+
+a| `categories`
+
+| List of category tags
+
+a|
+[horizontal]
+Type:: array
+Examples:: branch, large_imm
+Required?:: false
+
+
+a| `enc_size`
+
+| 
+
+a|
+[horizontal]
+Type:: integer
+Examples:: 16, 32, 64
+Required?:: false
+
+
+a| `base`
+
+| Base ISA (All, RV32, or RV64)
+
+a|
+[horizontal]
+Type:: string
+Required?:: false
+
+
+a| `class`
+
+| Intended processor class (Micro, App, or Any)
+
+a|
+[horizontal]
+Type:: string
+Required?:: false
+
+
+a| `donator`
+
+| RVI member donating/suggesting the instruction
+
+a|
+[horizontal]
+Type:: string
+Examples:: Qualcomm, NXP
+Required?:: false
+
+
+a| `implemented`
+
+| Whether or not the instruction has already been implemented in a custom extension
+
+a|
+[horizontal]
+Type:: boolean
+Required?:: false
+
+
+a| `description`
+
+| Functional description of the instruction
+
+a|
+[horizontal]
+Type:: string
+Required?:: false
+
+
+a| `srcs`
+
+| Number of source registers (including any implicit registers) read by the instruction
+
+a|
+[horizontal]
+Type:: integer
+Required?:: false
+
+
+a| `dsts`
+
+| Number of destination registers (including any implicit registers) written by the instruction
+
+a|
+[horizontal]
+Type:: integer
+Required?:: false
+
+
+a| `free_bits`
+
+| Number of non-fixed bits in the encoding. I.e., log2(# of codepoints used by instruction). For example, an R-type instruction has 3 5-bit variables fields (rd, rs1, rs2), and so has 3*5=15 free bits
+
+a|
+[horizontal]
+Type:: integer
+Required?:: false
+
+
+a| `notes`
+
+| Any extra notes
+
+a|
+[horizontal]
+Type:: string
+Required?:: false
+
+

insts/inst_schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/TODO",
+  "title": "Schema for instruction descriptions",
+  "description": "A list of candidate instructions for RISC-V Scalar Efficiency",
+
+  "type": "array",
+  "items": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "mnemonic": {
+        "type": "string",
+        "description": "Proposed instruction mnemonic",
+        "examples": ["BNEI", "J.FAR"]
+      },
+      "categories": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "List of category tags",
+        "examples": ["branch", "large_imm"]
+      },
+      "enc_size": {
+        "type": "integer",
+        "multipleOf": 16,
+        "minimum": 16,
+        "maximum": 64,
+        "examples": [16, 32, 64]
+      },
+      "base": {
+        "type": "string",
+        "enum": ["All", "RV32", "RV64"],
+        "description": "Base ISA (All, RV32, or RV64)"
+      },
+      "class": {
+        "type": "string",
+        "enum": ["Any", "Micro", "App"],
+        "description": "Intended processor class (Micro, App, or Any)"
+      },
+      "donator": {
+        "type": "string",
+        "description": "RVI member donating/suggesting the instruction",
+        "examples": ["Qualcomm", "NXP"]
+      },
+      "implemented": {
+        "type": "boolean",
+        "description": "Whether or not the instruction has already been implemented in a custom extension",
+        "default": false
+      },
+      "description": {
+        "type": "string",
+        "description": "Functional description of the instruction"
+      },
+      "srcs": {
+          "type": "integer",
+          "description": "Number of source registers (including any implicit registers) read by the instruction"
+      },
+      "dsts": {
+        "type": "integer",
+        "description": "Number of destination registers (including any implicit registers) written by the instruction"
+      },
+      "free_bits": {
+        "type": "integer",
+        "description": "Number of non-fixed bits in the encoding. I.e., log2(# of codepoints used by instruction). For example, an R-type instruction has 3 5-bit variables fields (rd, rs1, rs2), and so has 3*5=15 free bits"
+      },
+      "notes": {
+        "type": "string",
+        "description": "Any extra notes"
+      }
+    },
+    "required_properties": [
+      "mnemonic",
+      "categories",
+      "enc_size",
+      "base",
+      "class",
+      "donator",
+      "description",
+      "srcs",
+      "dsts",
+      "free_bits"
+    ]
+  }
+}