riscv · rpsene · Jul 25, 2023 · Jul 25, 2023
diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml
@@ -1,79 +1,73 @@
-# This workflow installs dependencies for PDF generation, generates the PDF,
-# and uploads the PDF as an artifact.
-
-name: Build Document PDF
+name: Create Specification Document
 
+# The workflow is triggered by pull request, push to main, and manual dispatch.
 on:
-  push:
-    branches:
-      - main
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version, e.g. X.Y.Z:'
+        required: true
+        type: string
+      revision_mark: 
+          description: 'Set revision mark as Draft, Release or Stable:'
+          required: true
+          type: string
+          default: 'Draft'
+      prerelease:
+        description: 'Tag as a pre-release?'
+        required: false
+        type: boolean
+        default: true
+      draft:
+        description: 'Create release as a draft?'
+        required: false
+        type: boolean
+        default: false
   pull_request:
+  push:
     branches:
       - main
-  workflow_dispatch:
-  workflow_call:
-    outputs:
-      name:
-        description: "The base name of the pdf file (without .pdf extensions)"
-        value: ${{ jobs.build.outputs.name }}
-      pdf-name:
-        description: "The name of the pdf file (with .pdf extensions)"
-        value: ${{ jobs.build.outputs.pdf-name }}
 
 jobs:
   build:
-    runs-on: ubuntu-22.04
-
-    env:
-      NAME: example-spec
-      APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt
-      BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile
-      BUNDLE_BIN: ${{ github.workspace }}/bin
-      NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies
-    outputs:
-      name: ${{ steps.step1.outputs.name }}
-      pdf-name: ${{ steps.step2.outputs.pdf-name }}
+    runs-on: ubuntu-latest
+
     steps:
-    - name: Set outputs.name
-      id: step1
-      run: echo "name=$NAME" >> $GITHUB_OUTPUT
-    - name: Set outputs.pdf-name
-      id: step2
-      run: echo "pdf-name=$NAME.pdf" >> $GITHUB_OUTPUT
+    # Step 1: Checkout the repository
     - name: Checkout repository
       uses: actions/checkout@v3
       with:
-        submodules: 'true'
-    - name: Install Ubuntu packages
-      run: |
-        sudo apt-get update
-        grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends
-    # Ruby for asciidoctor
-    - name: Setup Ruby and Gemfile content
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "2.6"
-        bundler-cache: true
-    # Node.js for wavedrom
-    - uses: actions/cache@v3
-      with:
-        path: ~/.npm
-        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-        restore-keys: |
-          ${{ runner.os }}-node-
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '16'
-    - name: Install Node.js dependencies
-      run: npm install ${NPM_PACKAGE_FOLDER}
-    - name: Generate PDF
-      run: |
-        PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \
-        make
-    - name: Archive PDF result
+        submodules: 'recursive'
+
+    # Step 2: Pull the latest RISC-V Docs container image
+    - name: Pull Container
+      run: docker pull riscvintl/riscv-docs-base-container-image:latest
+
+    # Step 3: Build Files
+    - name: Build Files
+      run: make
+      env:
+        VERSION: v${{ github.event.inputs.version }}
+        REVMARK: ${{ github.event.inputs.revision_mark }}
+
+    # Step 4: Upload the built PDF files as a single artifact
+    - name: Upload Build Artifacts
       uses: actions/upload-artifact@v3
       with:
-        name: ${{ env.NAME }}.pdf
-        path: ${{ env.NAME }}.pdf
-        retention-days: 7
+        name: Build Artifacts
+        path: ${{ github.workspace }}/*.pdf
+        retention-days: 30
+
+    # Create Release
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: ${{ github.workspace }}/*.pdf
+        tag_name: v${{ github.event.inputs.version }}
+        name: Release ${{ github.event.inputs.version }}
+        draft: ${{ github.event.inputs.draft }}
+        prerelease: ${{ github.event.inputs.prerelease }}
+      env:
+        GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
+      if: github.event_name == 'workflow_dispatch' 
+      # This condition ensures this step only runs for workflow_dispatch events.
diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml
diff --git a/Makefile b/Makefile
@@ -1,21 +1,65 @@
+# Makefile for RISC-V Doc Template
+#
+# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+# International License. To view a copy of this license, visit
+# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
+# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+#
+# SPDX-License-Identifier: CC-BY-SA-4.0
+#
+# Description:
+# 
+# This Makefile is designed to automate the process of building and packaging 
+# the Doc Template for RISC-V Extensions.
+
+DATE ?= $(shell date +%Y-%m-%d)
+VERSION ?= v0.0.0
+REVMARK ?= Draft
+DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
+riscvintl/riscv-docs-base-container-image:latest
+
 HEADER_SOURCE := header.adoc
 PDF_RESULT := smmtt-spec.pdf
 
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a revnumber=${VERSION} \
+           -a revremark=${REVMARK} \
+           -a revdate=${DATE} \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-style=docs-resources/themes/riscv-pdf.yml \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-bibtex \
+            --require=asciidoctor-diagram \
+            --require=asciidoctor-mathematical
+
+.PHONY: all build clean build-container build-no-container
+
 all: build
 
-build:
+build: 
+	@echo "Checking if Docker is available..."
+	@if command -v docker &> /dev/null ; then \
+		echo "Docker is available, building inside Docker container..."; \
+		$(MAKE) build-container; \
+	else \
+		echo "Docker is not available, building without Docker..."; \
+		$(MAKE) build-no-container; \
+	fi
+
+build-container:
+	@echo "Starting build inside Docker container..."
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	@echo "Build completed successfully inside Docker container."
 
-	@echo "Building asciidoc"
-	asciidoctor-pdf \
-    --attribute=mathematical-format=svg \
-    --attribute=pdf-fontsdir=docs-resources/fonts \
-    --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \
-    --failure-level=ERROR \
-    --require=asciidoctor-bibtex \
-    --require=asciidoctor-diagram \
-    --require=asciidoctor-mathematical \
-    --out-file=$(PDF_RESULT) \
-    $(HEADER_SOURCE)
+build-no-container:
+	@echo "Starting build..."
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	@echo "Build completed successfully."
 
 clean:
-	rm $(PDF_RESULT)
+	@echo "Cleaning up generated files..."
+	rm -f $(PDF_RESULT)
+	@echo "Cleanup completed."
diff --git a/readme.adoc b/readme.adoc
@@ -1,10 +1,6 @@
-= RISC-V docs-spec-template
+= RISC-V Specification
 
-This repository is used to prime GitHub repos for the RISC-V organization which will be used
-to create specifications.
-
-**If you are reading this in a specification repo, please update the title for this section and
-provide your introduction to your repository.**
+This document describes Supervisor Domain Access Protection - RISC-V privileged architecture extension to support physical address space (memory and devices) isolation for more than one supervisor domain use cases for RISC-V platforms. Use cases may use supervisor domains to reduce the supervisor Trusted Computing Base (TCB), with differential access to memory and other platform resources e.g. Confidential Computing (CoVE), Security Services, Secure Devices etc.
 
 = License
 
@@ -19,35 +15,24 @@ For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRI
 
 = Dependencies
 
-This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on
-checkin using GitHub actions.  Workflow dependencies are located in the `dependencies` directory.
-
-For more information on AsciiDoctor, specification guidelines, or building locally, see the
-https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide].
+To build the document, you'll need the following tools installed on your system:
 
-= Cloning the project
+```
+  Make
+  asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical
+  Docker
+```
 
-This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules]
-to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project]
-to achieve a common look and feel.
+= Cloning and Building the Document
 
-When cloning this repository for the first time, you must either use
-`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory.  Failure to clone the submodule, will result
-in the PDF build fail with an error message like the following:
+This project uses submodules to include the RISC-V documentation toolchain. 
 
-    $ make
-    asciidoctor-pdf \
-    -a toc \
-    -a compress \
-    -a pdf-style=docs-resources/themes/riscv-pdf.yml \
-    -a pdf-fontsdir=docs-resources/fonts \
-    --failure-level=ERROR \
-    -o profiles.pdf profiles.adoc
-    asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme
-    No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts
-      Use --trace for backtrace
-    make: *** [Makefile:7: profiles.pdf] Error 1
+```
+  git clone --recurse-submodules https://github.com/riscv/riscv-smmtt.git
+  cd ./riscv-smmtt.git
+  make VERSION=v1.0.0 REVMARK=Draft
+```
 
-= Building the document
+`VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification.
 
-The final specification form of PDF can be generated using the `make` command.
+`REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release', 'Stable' or 'Ratified'.
diff --git a/smmtt-spec.pdf b/smmtt-spec.pdf