diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 57cc750..c2b75d2 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,18 +9,18 @@ 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: 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 @@ -33,40 +34,41 @@ jobs: runs-on: ubuntu-latest steps: - # Step 1: Checkout the repository - - name: Checkout repository - uses: actions/checkout@v3 - with: - submodules: 'recursive' + # Step 1: Checkout the repository + - name: Checkout repository + uses: actions/checkout@v4 + with: + 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 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 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: - path: ${{ github.workspace }}/*.pdf - retention-days: 30 + # Step 4: 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 new file mode 100644 index 0000000..74b9ec3 --- /dev/null +++ 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/action@v3.0.0 diff --git a/.gitignore b/.gitignore index 8b13789..d9b4f01 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1 @@ - +/build/* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..dac9199 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,27 @@ +--- +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 + exclude: \.svg$ + - 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/CONTRIBUTING.md b/CONTRIBUTING.md index 3c79557..1d98c72 100644 --- a/CONTRIBUTING.md +++ b/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. \ No newline at end of file +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. diff --git a/LICENSE b/LICENSE index 53883b1..2f244ac 100644 --- 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/Makefile b/Makefile index 68bea84..12f6b2d 100644 --- a/Makefile +++ b/Makefile @@ -8,8 +8,8 @@ # 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. DATE ?= $(shell date +%Y-%m-%d) @@ -18,13 +18,13 @@ REVMARK ?= Draft DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ riscvintl/riscv-docs-base-container-image:latest -HEADER_SOURCE := server_soc_header.adoc -PDF_RESULT := riscv-server-soc.pdf - -TS_HEADER_SOURCE := server_soc_ts_header.adoc -TS_PDF_RESULT := riscv-server-soc-ts.pdf - +SRC_DIR := src +BUILD_DIR := build +HEADER_SOURCE := $(SRC_DIR)/riscv-server-soc.adoc +TS_HEADER_SOURCE := $(SRC_DIR)/riscv-server-soc-ts.adoc +XTRA_ADOC_OPTS := ASCIIDOCTOR_PDF := asciidoctor-pdf +ASCIIDOCTOR_HTML := asciidoctor OPTIONS := --trace \ -a compress \ -a mathematical-format=svg \ @@ -32,7 +32,9 @@ OPTIONS := --trace \ -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 \ @@ -42,7 +44,7 @@ REQUIRES := --require=asciidoctor-bibtex \ all: build -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..."; \ @@ -54,18 +56,21 @@ build: build-container: @echo "Starting build inside Docker container..." - $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" - $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)" + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)" + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)" + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(TS_HEADER_SOURCE)" + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(TS_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) - $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE) + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE) + $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE) + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(TS_HEADER_SOURCE) + $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(TS_HEADER_SOURCE) @echo "Build completed successfully." clean: @echo "Cleaning up generated files..." - rm -f $(PDF_RESULT) - rm -f $(TS_PDF_RESULT) + rm -rf $(BUILD_DIR) @echo "Cleanup completed." diff --git a/docs-resources b/docs-resources index 6a2d5b1..79e585b 160000 --- a/docs-resources +++ b/docs-resources @@ -1 +1 @@ -Subproject commit 6a2d5b1f929e0e25df0c832b522ed1fc0c78e325 +Subproject commit 79e585baa1fa201d20fd330f5563d9ab2c287f3a diff --git a/images/risc-v_logo.png b/images/risc-v_logo.png deleted file mode 100755 index 4e826b2..0000000 Binary files a/images/risc-v_logo.png and /dev/null differ diff --git a/readme.adoc b/readme.adoc index b2305f6..5d4b620 100644 --- a/readme.adoc +++ b/readme.adoc @@ -3,47 +3,76 @@ This document is capturing discussions at the Server SoC HW TG. This is not an official specification and everything in this document may change. -= License +== License -This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). -See the https://github.com/riscv/docs-spec-template/blob/main/LICENSE[LICENSE] file for details. +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. -= Contributors +== Contributors -Contributors to this specification are contained in the -https://github.com/riscv-non-isa/riscv-iommu/blob/main/contributors.adoc[contributors.adoc] file. +The list of contributors to this specification is maintained in the link:src/contributors.adoc[contributors] file. -= Dependencies +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. -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. +== Building the Document -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. +=== Directory Structure -= Cloning the project +The following directories are used to organize the contents of this repo: -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. +* `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 -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: +=== Prerequisites - $ 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 +To build the document, you'll need the following tools installed on your system: -= Building the document +* Make +* asciidoctor, asciidoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical +* Docker -The final specification form of PDF can be generated using the `make` command. +=== Cloning the Repository + +```shell +git clone --recurse-submodules https://github.com/riscv-non-isa/server-soc.git +``` + +=== Building the Documentation + +To start the build process, run: + +```shell +cd ./server-soc && 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 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 +---- diff --git a/images/riscv-server-platform.png b/src/images/riscv-server-platform.png similarity index 100% rename from images/riscv-server-platform.png rename to src/images/riscv-server-platform.png diff --git a/images/riscv-server-platform.svg b/src/images/riscv-server-platform.svg similarity index 100% rename from images/riscv-server-platform.svg rename to src/images/riscv-server-platform.svg diff --git a/images/riscv-server-rc.svg b/src/images/riscv-server-rc.svg similarity index 100% rename from images/riscv-server-rc.svg rename to src/images/riscv-server-rc.svg diff --git a/server_soc_ts_header.adoc b/src/riscv-server-soc-ts.adoc similarity index 83% rename from server_soc_ts_header.adoc rename to src/riscv-server-soc-ts.adoc index 0f4264f..4d240d9 100644 --- a/server_soc_ts_header.adoc +++ b/src/riscv-server-soc-ts.adoc @@ -9,13 +9,15 @@ :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images -:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] +// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/ +:imagesdir: ../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -:imagesoutdir: images -:bibtex-file: server_soc.bib +:imagesoutdir: ../build/images +:srcdir: src +:bibtex-file: {srcdir}/server_soc.bib :bibtex-order: appearance :bibtex-style: ieee :icons: font @@ -55,8 +57,12 @@ https://creativecommons.org/licenses/by/4.0/. Copyright 2022 by RISC-V International. +:imagesdir: images [preface] include::server_soc_contributors.adoc[] + include::server_soc_ts_intro.adoc[] + include::server_soc_tests.adoc[] + include::server_soc_bibliography.adoc[] diff --git a/server_soc_header.adoc b/src/riscv-server-soc.adoc similarity index 83% rename from server_soc_header.adoc rename to src/riscv-server-soc.adoc index fff4814..17ec4c9 100644 --- a/server_soc_header.adoc +++ b/src/riscv-server-soc.adoc @@ -9,13 +9,15 @@ :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images -:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] +// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/ +:imagesdir: ../docs-resources/images +:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -:imagesoutdir: images -:bibtex-file: server_soc.bib +:imagesoutdir: ../build/images +:srcdir: src +:bibtex-file: {srcdir}/server_soc.bib :bibtex-order: appearance :bibtex-style: ieee :icons: font @@ -55,8 +57,12 @@ https://creativecommons.org/licenses/by/4.0/. Copyright 2022 by RISC-V International. +:imagesdir: images [preface] include::server_soc_contributors.adoc[] + include::server_soc_intro.adoc[] + include::server_soc_requirements.adoc[] + include::server_soc_bibliography.adoc[] diff --git a/server_soc.bib b/src/server_soc.bib similarity index 100% rename from server_soc.bib rename to src/server_soc.bib diff --git a/server_soc_bibliography.adoc b/src/server_soc_bibliography.adoc similarity index 100% rename from server_soc_bibliography.adoc rename to src/server_soc_bibliography.adoc diff --git a/server_soc_contributors.adoc b/src/server_soc_contributors.adoc similarity index 100% rename from server_soc_contributors.adoc rename to src/server_soc_contributors.adoc diff --git a/server_soc_index.adoc b/src/server_soc_index.adoc similarity index 100% rename from server_soc_index.adoc rename to src/server_soc_index.adoc diff --git a/server_soc_intro.adoc b/src/server_soc_intro.adoc similarity index 100% rename from server_soc_intro.adoc rename to src/server_soc_intro.adoc diff --git a/server_soc_requirements.adoc b/src/server_soc_requirements.adoc similarity index 99% rename from server_soc_requirements.adoc rename to src/server_soc_requirements.adoc index 9bc5246..62757bf 100644 --- a/server_soc_requirements.adoc +++ b/src/server_soc_requirements.adoc @@ -591,7 +591,7 @@ space of an endpoint or RCiEP. Translated requests to translate the GPA to an SPA._ + + _When ACS direct translated P2P controls are enabled, the Translated - requests may not be routed through the host bridge. In such cases, + requests may not be routed through the host bridge. In such cases, if direct P2P routing of these requests is not desired, due to security and/or functional reasons (e.g., when operating in T2GPA mode), software should utilize the ACS controls to direct these requests to the root @@ -613,7 +613,7 @@ space of an endpoint or RCiEP. If peer device memory access is not enabled (either by design or configuration), then such accesses MUST be responded to with a UR/CA response. The host bridge MUST NOT cause any other errors - (e.g., hang, deadlock, etc.) when rejecting access by a device to + (e.g., hang, deadlock, etc.) when rejecting access by a device to a peer device's memory. 2+| _A virtual machine may violate the peer-to-peer access policies and/or configurations enforced by the hypervisor and/or SoC firmware, which diff --git a/server_soc_tests.adoc b/src/server_soc_tests.adoc similarity index 100% rename from server_soc_tests.adoc rename to src/server_soc_tests.adoc diff --git a/server_soc_ts_intro.adoc b/src/server_soc_ts_intro.adoc similarity index 99% rename from server_soc_ts_intro.adoc rename to src/server_soc_ts_intro.adoc index 3d822a2..fe40414 100644 --- a/server_soc_ts_intro.adoc +++ b/src/server_soc_ts_intro.adoc @@ -28,13 +28,13 @@ The tests in this specification are documented use the following format: record if optional features were present in the test output log. + + - The character in position `B` indicates the nature of the - test. If this character is `F` then the test exercises some + The character in position `B` indicates the nature of the + test. If this character is `F` then the test exercises some or all of the functionality associated with the feature. If - the character is `E` then the test determines for evidence - that the feature is implemented (e.g., check ACPI tables) + the character is `E` then the test determines for evidence + that the feature is implemented (e.g., check ACPI tables) but does not functionally exercise the feature. - + |=== This specification groups the tests in the following broad categories: