update to latest cfg from docs-spec-template

includes: - update Makefile: build html output; src/build dir - move spec src to src dir - remove image dir and pull in riscv logo from docs-resource submodule - update docs-resources submodule to latest - add pre-commit hooks and GH action to run it - add GOVERNANCE and MAINTAINERS file templates - update README pull in new sections - remove generated PDF - .gitignore the build dir - modify attribute cfg in header.adoc to match build/src dir; logo image Signed-off-by: Kevin Broch <[email protected]>
riscv · Mar 15, 2024 · 2ab8cc5 · 2ab8cc5
1 parent 850dfb2
commit 2ab8cc5
Show file tree

Hide file tree

Showing 21 changed files with 267 additions and 123 deletions.
diff --git 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,18 +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: string
-          default: 'Draft'
+      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
@@ -33,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
 
-    # Step 2: 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 3: Build Files
-    - name: Build Files
-      run: make
-      env:
-        VERSION: v${{ github.event.inputs.version }}
-        REVMARK: ${{ github.event.inputs.revision_mark }}
+      # Build Files
+      - name: Build Files
+        run: make
 
-    # Step 4: Upload the built PDF files as a single artifact
-    - name: Upload Build Artifacts
-      uses: actions/upload-artifact@v3
-      with:
-        path: ${{ github.workspace }}/*.pdf
-        retention-days: 30
+      # 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
 
-    # 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.
+      # 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/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml
@@ -0,0 +1,15 @@
+---
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: pre-commit/[email protected]
diff --git a/.gitignore b/.gitignore
@@ -1 +1 @@
-
+/build/*
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,26 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-json
+      - id: check-symlinks
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+
+  - repo: local
+    hooks:
+      - id: forbidden-file-extensions
+        name: forbidden-file-extensions
+        entry: disallow these file extensions
+        language: fail
+        # Disallow other asciidoc extensions except .adoc
+        files: .*\.(asciidoc|asc)$
+
+  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+    rev: 0.2.3
+    hooks:
+      - id: yamlfmt
+        args: [--mapping, '2', --sequence, '4', --offset, '2']
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -0,0 +1,7 @@
+# Governance
+
+This project for the template specification is governed by the TBD
+
+The group can be joined by RISC-V members at: TBD
+
+Mailing list archives are available at: TBD
diff --git a/LICENSE b/LICENSE
@@ -49,7 +49,7 @@ exhaustive, and do not form part of our licenses.
      such as asking that all changes be marked or described.
      Although not required by our licenses, you are encouraged to
      respect those requests where reasonable. More_considerations
-     for the public: 
+     for the public:
 	wiki.creativecommons.org/Considerations_for_licensees
 
 =======================================================================
@@ -393,4 +393,3 @@ the avoidance of doubt, this paragraph does not form part of the
 public licenses.
 
 Creative Commons may be contacted at creativecommons.org.
-
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -0,0 +1,5 @@
+# Maintainers
+
+This project is maintained by the following people:
+
+- Maintainer1
diff --git a/Makefile b/Makefile
@@ -8,38 +8,62 @@
 # SPDX-License-Identifier: CC-BY-SA-4.0
 #
 # Description:
-# 
-# This Makefile is designed to automate the process of building and packaging 
+#
+# This Makefile is designed to automate the process of building and packaging
 # the Doc Template for RISC-V Extensions.
 
+DOCS := \
+	cfi_header.adoc
+
 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
+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
 
-HEADER_SOURCE := cfi_header.adoc
-PDF_RESULT := riscv-cfi.pdf
+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-style=docs-resources/themes/riscv-pdf.yml \
+           -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
+.PHONY: all build clean build-container build-no-container build-docs
 
 all: build
 
-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..."; \
@@ -51,15 +75,15 @@ build:
 
 build-container:
 	@echo "Starting build inside Docker container..."
-	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	$(MAKE) build-docs
 	@echo "Build completed successfully inside Docker container."
 
 build-no-container:
 	@echo "Starting build..."
-	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	$(MAKE) SKIP_DOCKER=true build-docs
 	@echo "Build completed successfully."
 
 clean:
 	@echo "Cleaning up generated files..."
-	rm -f $(PDF_RESULT)
+	rm -rf $(BUILD_DIR)
 	@echo "Cleanup completed."
diff --git a/README.adoc b/README.adoc
@@ -0,0 +1,110 @@
+= RISC-V CFI specification
+
+This document is capturing discussions at the Shadow Stacks and Landing Pads TG and attempts
+to document the baseline. This is not official specification and everything in this document
+may change. Control-flow Integrity (CFI) provides CPU instruction set architecture (ISA)
+capabilities to defend against Return-Oriented Programming (ROP) and Call/Jump-Oriented
+Programming (COP/JOP) style control-flow subversion attacks.
+
+To enforce backward edge control-flow integrity, the extension introduces a shadow stack. To
+enforce forward edge control-flow integrity, the extension introduces labeled landing pad
+instructions.
+
+== License
+
+This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file.
+
+== Maintainers
+
+The list of maintainers of this specification is maintained in the link:MAINTAINERS.md[MAINTAINERS] file.
+
+== Contributors
+
+The list of contributors to this specification is maintained in the link:src/contributors.adoc[contributors] file.
+
+For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file.
+
+== Governance
+
+The governance for this project is defined in the link:GOVERNANCE.md[GOVERNANCE] file.
+
+Community information, including meeting (if held) and mailing lists are detailed in this file.
+
+== Building the Document
+
+=== Directory Structure
+
+The following directories are used to organize the contents of this repo:
+
+* `dependencies/`: software dependencies needed to build the specification
+* `docs-resources/`: resources for all specifications sourced from link:.gitmodules[git submodule]
+* `src/`: source files for the specification
+* `build/`: default directory where the build artifacts are generated
+
+=== Prerequisites
+
+To build the document, you'll need the following tools installed on your system:
+
+* Make
+* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
+* Docker
+
+=== Cloning the Repository
+
+```shell
+git clone --recurse-submodules https://github.com/riscv/riscv-cfi.git
+```
+
+=== Building the Documentation
+
+To start the build process, run:
+
+```shell
+cd ./riscv-cfi && make build
+```
+
+The link:Makefile[] script will check the availability of Docker on your system:
+
+* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems.
+* If Docker is not available, the documentation will be built directly on your system using the installed tools.
+
+The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile.
+
+The build process utilizes several options, including theming and font settings, and generates a PDF document as output.
+
+=== Cleaning up
+
+To clean up the generated files, run:
+
+```shell
+make clean
+```
+
+== Enabling pre-commit checks locally
+
+The repository has some basic commit checks set up with https://pre-commit.com/[pre-commit] that will be enforced by the GitHub CI.
+To ensure these checks are also run in the local repository while making changes the following can be done:
+
+.Installing pre-commit tool
+[source,shell]
+----
+# Do once on your system
+pip3 install pre-commit
+----
+
+.Installing pre-commit git hook in repo
+[source,shell]
+----
+# Do once in local repo
+pre-commit install
+----
+
+Rather than doing the above `pre-commit install` in every repo that uses it, you can do it https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories[once on your system.]
+
+When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended running the newly added check on all files in the repository. This can be done with the following command:
+
+.Running all pre-commit hooks on all files
+[source,shell]
+----
+pre-commit run --all-files
+----
diff --git 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/docs-resources b/docs-resources
diff --git a/images/risc-v_logo.svg b/images/risc-v_logo.svg