Sync with template repository to add pre-commit checks and CI

.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.
@@ -9,22 +10,22 @@ on:
         required: true
         type: string
       revision_mark:
-          description: 'Set revision mark as Draft, Release or Stable:'
-          required: true
-          type: string
-          default: 'Draft'
+        description: 'Set revision mark as Draft, Release or Stable:'
+        required: true
+        type: string
+        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
       pages:
-        description: 'Deploy HTML to Github pages?'
+        description: Deploy HTML to Github pages?
         required: false
         type: boolean
         default: false
@@ -39,57 +40,57 @@ jobs:
 
     steps:
     # Checkout the repository
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        submodules: 'recursive'
+      - 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
+      - name: Pull Container
+        run: docker pull riscvintl/riscv-docs-base-container-image:latest
 
     # Build PDF and HTML.
-    - name: Build Files
-      run: make all
-      env:
-        VERSION: v${{ github.event.inputs.version }}
-        REVMARK: ${{ github.event.inputs.revision_mark }}
+      - name: Build Files
+        run: make all
+        env:
+          VERSION: v${{ github.event.inputs.version }}
+          REVMARK: ${{ github.event.inputs.revision_mark }}
 
     # Upload the built PDF and HTML files as a single artifact
-    - name: Upload Build Artifacts
-      uses: actions/upload-artifact@v3
-      with:
-        name: Build Artifacts
-        path: |
-          build/*.pdf
-          build/*.html
-        retention-days: 30
+      - name: Upload Build Artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: Build Artifacts
+          path: |
+            build/*.pdf
+            build/*.html
+          retention-days: 30
 
     # Upload gitlab pages artefact.
-    - name: Make gitlab pages directory
-      run: mkdir dist && cp build/*.html dist/index.html
-      if: github.event_name == 'workflow_dispatch'
+      - name: Make gitlab pages directory
+        run: mkdir dist && cp build/*.html dist/index.html
+        if: github.event_name == 'workflow_dispatch'
 
-    - name: Upload artifact
-      uses: actions/upload-pages-artifact@v3
-      with:
-        path: dist
-      if: github.event_name == 'workflow_dispatch'
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+        if: github.event_name == 'workflow_dispatch'
 
     # Create Release
-    - name: Create Release
-      uses: softprops/action-gh-release@v1
-      with:
-        files: |
-          build/*.pdf
-          build/*.html
-        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'
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            build/*.pdf
+            build/*.html
+          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.
 
   # Deploy HTML to Github pages.

.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]

.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']

CONTRIBUTING.md

@@ -55,4 +55,4 @@ You can manually add the DCO text to your commit body or include either -s or --
 
 Note:
 
-Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message.
+Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message.

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.
-

Makefile

@@ -158,8 +158,10 @@ $(GEN_SRC) &: $(CSVS) $(GEN_SCRIPT)
 $(CSVS) &:
 	@echo "  DOWN CSV (isa)"
 	@curl -Lo src/csv/CHERI_ISA.csv "$(URL_ISA)"
+	@echo >> src/csv/CHERI_ISA.csv
 	@echo "  DOWN CSV (csr)"
 	@curl -Lo src/csv/CHERI_CSR.csv "$(URL_CSR)"
+	@echo >> src/csv/CHERI_CSR.csv
 
 # Clean
 clean:

readme.adoc

@@ -8,7 +8,7 @@ This work is licensed under a Creative Commons Attribution 4.0 International Lic
 
 == Contributors
 
-The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file.
+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.
 
@@ -25,13 +25,19 @@ To build the document, you'll need the following tools installed on your system:
 
 === Cloning the Repository
 
-`git clone --recurse-submodules https://github.com/riscv/riscv-cheri.git`
+```shell
+git clone --recurse-submodules https://github.com/riscv/riscv-cheri.git
+```
 
 === Building the Documentation
 
-To start the build process, run `cd ./riscv-cheri && make all`.
+To start the build process, run:
 
-The Makefile script will check the availability of Docker on your system:
+```shell
+cd ./riscv-cheri && make all
+```
+
+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.
@@ -42,4 +48,24 @@ The build process utilizes several options, including theming and font settings,
 
 === Cleaning up
 
-To clean up the generated files, run `make clean`. This will remove the generated PDF file.
+To clean up the generated files, run:
+
+```shell
+make clean
+```
+
+This will remove the generated PDF file.
+
+== 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 command can be run:
+[source,shell]
+----
+pip3 install pre-commit && pre-commit install
+----
+
+When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended to run to newly added check on all files in the repository. This can be done with the following command:
+[source,shell]
+----
+pre-commit run --all-files
+----

src/cheri-pte-ext.adoc

@@ -97,4 +97,3 @@ bit is available for S-mode address translation. When CDE=0, the implementation
 behaves as though the CD bit were not implemented. If CD is not implemented,
 CDE is read-only zero. If CD is implemented although not configurable, CDE is
 read-only one.
-

src/csv/CHERI_CSR.csv

@@ -30,4 +30,4 @@ direct write if address didn't change","✔","","","✔","✔","Zcmt","Jump Vect
 "stdc","0x163","","","S","SRW, <<asr_perm>>","<<null-cap>>","","","","","","✔","","S-mode","Supervisor Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","",""
 "ddc","0x416","","","U","URW","<<infinite-cap>>","","","","","","✔","","none","User Default Data Capability","","","","","","","","","","","","","","","","","","","","",""
 "pcc","0xcb0","","","U","URO","<<infinite-cap>>
-(address = boot address)","","","✔","","","✔","✔","none","User Program Counter Capability (to allow reading in legacy mode)","","","","","","","","","","","","","","","","","","","","",""
+(address = boot address)","","","✔","","","✔","✔","none","User Program Counter Capability (to allow reading in legacy mode)","","","","","","","","","","","","","","","","","","","","",""

src/csv/CHERI_ISA.csv

@@ -173,4 +173,4 @@
 "SH4ADD","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","OP","","","","shift and add","","","","","","","",""
 "SH4ADD.UW","","✔","","","","✔","","Legacy","","","","","","","","","","","","","","","","OP","","","","shift and add","","","","","","","",""
 "CSH4ADD","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","OP","","SH4ADD","SH4ADD","shift and add, representability check on the result","","","","","","","",""
-"CSH4ADD.UW","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","OP","","SH4ADD.UW","SH4ADD.UW","shift and add, representability check on the result","","","","","","","",""
+"CSH4ADD.UW","","✔","","","","","✔","Capability","","","","","","","","","","","","","","","","OP","","SH4ADD.UW","SH4ADD.UW","shift and add, representability check on the result","","","","","","","",""

src/debug-integration.adoc

@@ -103,4 +103,3 @@ The <<dscratch1c>> register is a CLEN-bit plus tag bit extension to
 
 .Debug scratch 1 capability register
 include::img/dscratch1creg.edn[]
-

src/img/mtvalreg.edn

@@ -18,4 +18,3 @@
 (draw-box "12"       {:span 12 :borders {}})
 (draw-box "4"        {:span 4 :borders {}})
 ----
-

src/img/stvalreg.edn

@@ -18,4 +18,3 @@
 (draw-box "12"       {:span 12 :borders {}})
 (draw-box "4"        {:span 4 :borders {}})
 ----
-

src/insns/atomic_exceptions.adoc

@@ -30,4 +30,4 @@ reported in the CAUSE field of <<mtval>> or <<stval>>:
 | Length violation      | At least one byte accessed is outside the authority capability bounds
 |==============================================================================
 
-:!cap_atomic:
+:!cap_atomic:

src/insns/candperm_32bit.adoc

@@ -46,4 +46,3 @@ Operation::
 --
 TODO: Sail does not have the new encoding of the permissions field.
 --
-

src/insns/cbo.clean.adoc

@@ -53,4 +53,3 @@ Operation::
 --
 TBD
 --
-

src/insns/cbuildcap_32bit.adoc

@@ -45,4 +45,3 @@ Operation::
 --
 TODO: Original Sail looks at otype field, etc that don't exist
 --
-

src/insns/cgethigh_32bit.adoc

@@ -25,4 +25,3 @@ Operation:: TODO #this is correct but capToMemBits is redundant, as it's now XOR
 --
 TODO
 --
-

src/insns/cgetperm_32bit.adoc

@@ -29,4 +29,3 @@ Operation::
 --
 TODO: The encoding of permissions changed.
 --
-

src/insns/cgettag_32bit.adoc

@@ -23,4 +23,3 @@ Operation::
 --
 TODO
 --
-

src/insns/cincoffset_32bit.adoc

@@ -52,4 +52,3 @@ Operation (CINCOFFSETIMM)::
 --
 TODO
 --
-

src/insns/cj_j_16bit.adoc

@@ -45,4 +45,3 @@ Prerequisites for C.J::
 
 Operation (after expansion to 32-bit encodings)::
  See <<CJAL>>, <<JAL>>
-

src/insns/cjal_jal_16bit.adoc

@@ -42,4 +42,3 @@ Prerequisites for C.JAL::
 
 Operation (after expansion to 32-bit encodings)::
  See <<CJAL>>, <<JAL>>
-

src/insns/cjal_jal_common.adoc

@@ -5,4 +5,3 @@ Link the next linear <<pcc>> to `cd` and seal. Jump to <<pcc>>.address+offset.
 Legacy Mode Description::
 Set the next PC and link to `rd` according to the standard <<JAL>> definition.
  Check a minimum length instruction is in <<pcc>> bounds at the target PC, take a CHERI Length Violation exception on error.
-

src/insns/cjalr_jalr_16bit.adoc

@@ -42,4 +42,3 @@ Prerequisites C.JALR::
 
 Operation (after expansion to 32-bit encodings)::
  See <<CJALR>>, <<JALR>>
-

src/insns/cjalr_jalr_32bit.adoc

@@ -72,4 +72,3 @@ JALR Operation::
 --
 TBD
 --
-

src/insns/cjr_jr_16bit.adoc

@@ -48,4 +48,3 @@ Prerequisites for C.JALR::
 
 Operation (after expansion to 32-bit encodings)::
  See <<CJALR>>, <<JALR>>
-

src/insns/cmove_32bit.adoc

@@ -28,4 +28,3 @@ Operation::
 --
 TODO
 --
-

src/insns/condbr_16bit.adoc

@@ -23,4 +23,3 @@ C or Zca
 
 Operation (after expansion to 32-bit encodings)::
  See <<insns-conbr-32bit>>
-

src/insns/cram_32bit.adoc

@@ -25,4 +25,3 @@ Operation::
 --
 TODO
 --
-

src/insns/cseal_32bit.adoc

@@ -26,4 +26,3 @@ Operation::
 --
 TODO: The SAIL definition for CSEAL writes the OTYPE which does not exist anymore.
 --
-

src/insns/csetaddr_32bit.adoc

@@ -28,4 +28,3 @@ Operation::
 --
 TODO
 --
-