From ecb6d419abd702ae90e966cb965f4f9e10fb7af5 Mon Sep 17 00:00:00 2001 From: Samuel Ortiz Date: Tue, 30 Apr 2024 11:17:34 +0200 Subject: [PATCH] riscv-ap-tee-io: Use the RVI specification repo template As defined by https://github.com/riscv/docs-spec-template. Signed-off-by: Samuel Ortiz --- .github/workflows/build-pdf.yml | 87 +++++++++------- .gitmodules | 2 +- Makefile | 93 ++++++++++++++++-- dependencies/README.md | 1 - dependencies/apt_packages.txt | 12 ++- dependencies/package.json | 7 +- docs-resources | 1 + specification/Makefile | 51 ---------- specification/docs-resources | 1 - specification/images/risc-v_logo.svg | 1 - {specification => src}/00-header.adoc | 4 +- {specification => src}/01-contributors.adoc | 0 {specification => src}/02-intro.adoc | 0 {specification => src}/03-glossary.adoc | 0 {specification => src}/04-requirements.adoc | 0 {specification => src}/05-security_model.adoc | 0 {specification => src}/06-arch_overview.adoc | 0 .../07-theory_operations.adoc | 0 {specification => src}/08-attestation.adoc | 0 {specification => src}/09-coveio_abi.adoc | 0 {specification => src}/10-index.adoc | 0 {specification => src}/11-bibliography.adoc | 0 {specification => src}/cove-io.bib | 0 .../images/SPDM_session.svg | 0 .../images/bounce_buffer.svg | 0 .../images/cove-io-architecture.svg | 0 .../images/cove-io-lifecycle.svg | 0 .../images/coveio_hierarchy.svg | 0 {specification => src}/images/rats-arch.svg | 0 .../images/rp_rot_idekm.svg | 0 {specification => src}/preprocessor.rb | 0 {specification => src}/riscv-cove-io.pdf | Bin 32 files changed, 156 insertions(+), 104 deletions(-) create mode 160000 docs-resources delete mode 100644 specification/Makefile delete mode 160000 specification/docs-resources delete mode 120000 specification/images/risc-v_logo.svg rename {specification => src}/00-header.adoc (93%) rename {specification => src}/01-contributors.adoc (100%) rename {specification => src}/02-intro.adoc (100%) rename {specification => src}/03-glossary.adoc (100%) rename {specification => src}/04-requirements.adoc (100%) rename {specification => src}/05-security_model.adoc (100%) rename {specification => src}/06-arch_overview.adoc (100%) rename {specification => src}/07-theory_operations.adoc (100%) rename {specification => src}/08-attestation.adoc (100%) rename {specification => src}/09-coveio_abi.adoc (100%) rename {specification => src}/10-index.adoc (100%) rename {specification => src}/11-bibliography.adoc (100%) rename {specification => src}/cove-io.bib (100%) rename {specification => src}/images/SPDM_session.svg (100%) rename {specification => src}/images/bounce_buffer.svg (100%) rename {specification => src}/images/cove-io-architecture.svg (100%) rename {specification => src}/images/cove-io-lifecycle.svg (100%) rename {specification => src}/images/coveio_hierarchy.svg (100%) rename {specification => src}/images/rats-arch.svg (100%) rename {specification => src}/images/rp_rot_idekm.svg (100%) rename {specification => src}/preprocessor.rb (100%) rename {specification => src}/riscv-cove-io.pdf (100%) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 01158c8..a5752ac 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,3 +1,4 @@ +--- name: Create Specification Document # The workflow is triggered by pull request, push to main, and manual dispatch. @@ -8,13 +9,22 @@ on: 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: choice + options: + - Draft + - Release + - Stable + default: Draft prerelease: - description: 'Tag as a pre-release?' + description: Tag as a pre-release? required: false type: boolean default: true draft: - description: 'Create release as a draft?' + description: Create release as a draft? required: false type: boolean default: false @@ -28,40 +38,45 @@ jobs: runs-on: ubuntu-latest steps: - # Step 1: Checkout the repository - - name: Checkout repository - uses: actions/checkout@v3 - with: - submodules: 'recursive' + # Checkout the repository + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + # Pull the latest RISC-V Docs container image + - name: Pull Container + run: docker pull riscvintl/riscv-docs-base-container-image:latest + + # Override VERSION and REVMARK for manual workflow dispatch + - name: Update environment variables + run: | + echo "VERSION=v${{ github.event.inputs.version }}" >> "$GITHUB_ENV" + echo "REVMARK=${{ github.event.inputs.revision_mark }}" >> "$GITHUB_ENV" + if: github.event_name == 'workflow_dispatch' - # Step 2: Pull the latest RISC-V Docs container image - - name: Pull Container - run: docker pull riscvintl/riscv-docs-base-container-image:latest + # Build Files + - name: Build Files + run: make - # Step 3: Build Files - - name: Build Files - run: make - env: - VERSION: v${{ github.event.inputs.version }} + # Upload the built PDF files as a single artifact + - name: Upload Build Artifacts + uses: actions/upload-artifact@v4 + with: + name: Build Artifacts + path: ${{ github.workspace }}/build/*.pdf + retention-days: 30 - # Step 4: Upload the built PDF files as a single artifact - - name: Upload Build Artifacts - uses: actions/upload-artifact@v3 - with: - name: Build Artifacts - path: ${{ github.workspace }}/specification/*.pdf - retention-days: 30 - - # Create Release - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - files: ${{ github.workspace }}/specification/*.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. + # Create Release + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + files: ${{ github.workspace }}/build/*.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/.gitmodules b/.gitmodules index ee9be11..cde1eb5 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,3 @@ [submodule "docs-resources"] - path = specification/docs-resources + path = docs-resources url = https://github.com/riscv/docs-resources.git diff --git a/Makefile b/Makefile index 0a1dd74..b73b36b 100644 --- a/Makefile +++ b/Makefile @@ -1,10 +1,89 @@ -spec-folder := specification +# 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. -.PHONY: all spec clean -all: spec +DOCS := \ + 00-header.adoc -spec: $(spec-folder) - $(MAKE) --directory=$^ +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.0.0 +REVMARK ?= Draft +ifneq ($(SKIP_DOCKER),true) + DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \ + riscvintl/riscv-docs-base-container-image:latest \ + /bin/sh -c + DOCKER_QUOTE := " +endif -clean: $(spec-folder) - $(MAKE) --directory=$? clean +SRC_DIR := src +BUILD_DIR := build + +DOCS_PDF := $(DOCS:%.adoc=%.pdf) +DOCS_HTML := $(DOCS:%.adoc=%.html) + +XTRA_ADOC_OPTS := +ASCIIDOCTOR_PDF := asciidoctor-pdf +ASCIIDOCTOR_HTML := asciidoctor +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-theme=docs-resources/themes/riscv-pdf.yml \ + $(XTRA_ADOC_OPTS) \ + -D build \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical + +.PHONY: all build clean build-container build-no-container build-docs + +all: build + +build-docs: $(DOCS_PDF) $(DOCS_HTML) + +vpath %.adoc $(SRC_DIR) + +%.pdf: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +%.html: %.adoc + $(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE) + +build: + @echo "Checking if Docker is available..." + @if command -v docker >/dev/null 2>&1 ; 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..." + $(MAKE) build-docs + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." + $(MAKE) SKIP_DOCKER=true build-docs + @echo "Build completed successfully." + +clean: + @echo "Cleaning up generated files..." + rm -rf $(BUILD_DIR) + @echo "Cleanup completed." diff --git a/dependencies/README.md b/dependencies/README.md index 0841ce8..f64a366 100644 --- a/dependencies/README.md +++ b/dependencies/README.md @@ -1,3 +1,2 @@ Dependencies for the build environment for various package managers. Used in `.github/workflows/`. - diff --git a/dependencies/apt_packages.txt b/dependencies/apt_packages.txt index 0682bde..6ddd571 100644 --- a/dependencies/apt_packages.txt +++ b/dependencies/apt_packages.txt @@ -1,21 +1,31 @@ bison build-essential +python3-pip cmake curl flex fonts-lyx git graphviz -# For wavedrom default-jre libcairo2-dev libffi-dev libgdk-pixbuf2.0-dev libpango1.0-dev libxml2-dev +libglib2.0-dev make pkg-config ruby ruby-dev +libgif-dev libwebp-dev libzstd-dev +ruby-full +gem +npm +texlive-latex-base +texlive-fonts-recommended +texlive-fonts-extra +texlive-latex-extra +texlive-science diff --git a/dependencies/package.json b/dependencies/package.json index 9d80afe..7347d43 100644 --- a/dependencies/package.json +++ b/dependencies/package.json @@ -1,7 +1,8 @@ { - "name": "local", - "version": "0.0.1", "dependencies": { + "bytefield-svg": "^1.8.0", "wavedrom-cli": "^2.6.8" - } + }, + "name": "local", + "version": "0.0.1" } diff --git a/docs-resources b/docs-resources new file mode 160000 index 0000000..005cb0d --- /dev/null +++ b/docs-resources @@ -0,0 +1 @@ +Subproject commit 005cb0db1c46c31fff163914f3e480dbda0306be diff --git a/specification/Makefile b/specification/Makefile deleted file mode 100644 index 45762e7..0000000 --- a/specification/Makefile +++ /dev/null @@ -1,51 +0,0 @@ -CONTAINER_RUNTIME ?= docker -CONTAINER_RUN := ${CONTAINER_RUNTIME} run --rm \ - -v ${PWD}:/build -w /build \ - riscvintl/riscv-docs-base-container-image:latest - -HEADER_SOURCE := 00-header.adoc -PDF_RESULT := riscv-cove-io.pdf - -ASCIIDOCTOR_PDF := asciidoctor-pdf -OPTIONS := --trace \ - -a compress \ - -a mathematical-format=svg \ - -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 -REQUIRES := --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ -# --require=./preprocessor.rb \ - --require=asciidoctor-mathematical - -.PHONY: all build clean build-container build-no-container - -all: build - -build: - @echo "Checking if Docker is available..." - @if command -v docker >/dev/null 2>&1 ; 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..." - $(CONTAINER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" - @echo "Build completed successfully inside Docker container." - -build-no-container: - @echo "Starting build..." - $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) - @echo "Build completed successfully." - -clean: - @echo "Cleaning up generated files..." - rm -f $(PDF_RESULT) - @echo "Cleanup completed." diff --git a/specification/docs-resources b/specification/docs-resources deleted file mode 160000 index 6a2d5b1..0000000 --- a/specification/docs-resources +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 6a2d5b1f929e0e25df0c832b522ed1fc0c78e325 diff --git a/specification/images/risc-v_logo.svg b/specification/images/risc-v_logo.svg deleted file mode 120000 index 31e4a40..0000000 --- a/specification/images/risc-v_logo.svg +++ /dev/null @@ -1 +0,0 @@ -../docs-resources/images/risc-v_logo.svg \ No newline at end of file diff --git a/specification/00-header.adoc b/src/00-header.adoc similarity index 93% rename from specification/00-header.adoc rename to src/00-header.adoc index a3a9723..2c4307c 100644 --- a/specification/00-header.adoc +++ b/src/00-header.adoc @@ -10,14 +10,14 @@ :colophon: :appendix-caption: Appendix :imagesdir: . -:title-logo-image: image:images/risc-v_logo.svg[pdfwidth=3.25in,align=center] +:title-logo-image: image:images/risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: // needs to be changed? bug discussion started //:WaveDromEditorApp: app/wavedrom-editor.app :imagesoutdir: images -:bibtex-file: cove-io.bib +:bibtex-file: src/cove-io.bib :bibtex-order: alphabetical :bibtex-style: apa :icons: font diff --git a/specification/01-contributors.adoc b/src/01-contributors.adoc similarity index 100% rename from specification/01-contributors.adoc rename to src/01-contributors.adoc diff --git a/specification/02-intro.adoc b/src/02-intro.adoc similarity index 100% rename from specification/02-intro.adoc rename to src/02-intro.adoc diff --git a/specification/03-glossary.adoc b/src/03-glossary.adoc similarity index 100% rename from specification/03-glossary.adoc rename to src/03-glossary.adoc diff --git a/specification/04-requirements.adoc b/src/04-requirements.adoc similarity index 100% rename from specification/04-requirements.adoc rename to src/04-requirements.adoc diff --git a/specification/05-security_model.adoc b/src/05-security_model.adoc similarity index 100% rename from specification/05-security_model.adoc rename to src/05-security_model.adoc diff --git a/specification/06-arch_overview.adoc b/src/06-arch_overview.adoc similarity index 100% rename from specification/06-arch_overview.adoc rename to src/06-arch_overview.adoc diff --git a/specification/07-theory_operations.adoc b/src/07-theory_operations.adoc similarity index 100% rename from specification/07-theory_operations.adoc rename to src/07-theory_operations.adoc diff --git a/specification/08-attestation.adoc b/src/08-attestation.adoc similarity index 100% rename from specification/08-attestation.adoc rename to src/08-attestation.adoc diff --git a/specification/09-coveio_abi.adoc b/src/09-coveio_abi.adoc similarity index 100% rename from specification/09-coveio_abi.adoc rename to src/09-coveio_abi.adoc diff --git a/specification/10-index.adoc b/src/10-index.adoc similarity index 100% rename from specification/10-index.adoc rename to src/10-index.adoc diff --git a/specification/11-bibliography.adoc b/src/11-bibliography.adoc similarity index 100% rename from specification/11-bibliography.adoc rename to src/11-bibliography.adoc diff --git a/specification/cove-io.bib b/src/cove-io.bib similarity index 100% rename from specification/cove-io.bib rename to src/cove-io.bib diff --git a/specification/images/SPDM_session.svg b/src/images/SPDM_session.svg similarity index 100% rename from specification/images/SPDM_session.svg rename to src/images/SPDM_session.svg diff --git a/specification/images/bounce_buffer.svg b/src/images/bounce_buffer.svg similarity index 100% rename from specification/images/bounce_buffer.svg rename to src/images/bounce_buffer.svg diff --git a/specification/images/cove-io-architecture.svg b/src/images/cove-io-architecture.svg similarity index 100% rename from specification/images/cove-io-architecture.svg rename to src/images/cove-io-architecture.svg diff --git a/specification/images/cove-io-lifecycle.svg b/src/images/cove-io-lifecycle.svg similarity index 100% rename from specification/images/cove-io-lifecycle.svg rename to src/images/cove-io-lifecycle.svg diff --git a/specification/images/coveio_hierarchy.svg b/src/images/coveio_hierarchy.svg similarity index 100% rename from specification/images/coveio_hierarchy.svg rename to src/images/coveio_hierarchy.svg diff --git a/specification/images/rats-arch.svg b/src/images/rats-arch.svg similarity index 100% rename from specification/images/rats-arch.svg rename to src/images/rats-arch.svg diff --git a/specification/images/rp_rot_idekm.svg b/src/images/rp_rot_idekm.svg similarity index 100% rename from specification/images/rp_rot_idekm.svg rename to src/images/rp_rot_idekm.svg diff --git a/specification/preprocessor.rb b/src/preprocessor.rb similarity index 100% rename from specification/preprocessor.rb rename to src/preprocessor.rb diff --git a/specification/riscv-cove-io.pdf b/src/riscv-cove-io.pdf similarity index 100% rename from specification/riscv-cove-io.pdf rename to src/riscv-cove-io.pdf