RISC-V Memory Tagging

This repository holds the RISC-V Memory Tagging specification: the Zimt memory tagging extension, and the Svatag and Smvatag extensions for virtually indexed tag storage.

• Read the current draft on this repository’s GitHub Pages site: https://riscv.github.io/riscv-memory-tagging/

• Released PDFs are attached to the GitHub Releases.

The repository follows docs-spec-template. One set of AsciiDoc sources builds both the PDF, which is what goes to the Architecture Review Committee (ARC), and the HTML site. See ARC_SUBMISSION.md for the ARC requirements and ANTORA.md for how the two builds share the sources.

License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the LICENSE file.

Maintainers

The list of maintainers of this specification is maintained in the MAINTAINERS file.

Contributors

The list of contributors to this specification is maintained in the contributors file.

For guidelines on how to contribute, refer to the CONTRIBUTING file.

Governance

The governance for this project is defined in the GOVERNANCE file.

Community information, including meeting (if held) and mailing lists are detailed in this file.

Repository layout

• modules/ROOT/pages/: the specification text, one page per chapter. This is where you write.

• modules/ROOT/nav.adoc: the site’s table of contents. Add new chapters here as well as in the PDF assembler.

• modules/ROOT/resources/mte.bib: the bibliography database.

• src/riscv-mte.adoc: the PDF assembler. It holds the title, the prefaces and the PDF-only settings, and includes the chapter pages.

• antora.yml: the site’s component descriptor. Its version: and page-* values are stamped at release time; do not edit them by hand.

• scripts/, tests/: versioning and publishing helpers, and their tests. scripts/release-info.sh derives the version and lifecycle phase from the git tags.

• docs-resources/: shared RISC-V fonts, themes and images, as a git submodule.

• build/: build output (not committed).

Writing the specification

• Linking to another chapter: name that chapter’s page, as in mte_tag.adoc. On the site each chapter is its own page, so a bare [TAG_CHECKS] only works within the same chapter. Leave the link text out; both builds generate it.

• Adding a chapter: create the page in modules/ROOT/pages/ starting with a level-0 title (= Title), add an include::../modules/ROOT/pages/<page>.adoc[leveloffset=+1] line to src/riscv-mte.adoc, and add an xref: entry to modules/ROOT/nav.adoc.

• PDF-only settings (theme, fonts, title-page logo, the back-of-book index, the docs-resources include) belong in src/riscv-mte.adoc, never in a page.

Building the PDF

git clone --recurse-submodules https://github.com/riscv/riscv-memory-tagging.git
cd riscv-memory-tagging
make build

The build runs in the riscvintl/riscv-docs-base-container-image container when Docker is available, and with locally installed tools (Make, asciidoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-mathematical) otherwise.

The PDF is written to build/ under its ARC name, riscv-mte-v<version>-<YYYYMMDD>.pdf. The version comes from the latest release tag: a build from an untagged commit is named riscv-mte-v<latest>-<sha>-<date>.pdf and is a development build, not an ARC submission. To build a specific version, run for example make VERSION=v0.8.

make clean removes the build output.

Previewing the HTML site

Previewing needs Node.js 20 or later and Docker.

npm ci                                     # Antora and its extensions
docker compose up -d kroki                 # local diagram server for the WaveDrom figures
npm run preview                            # site in build/site/
NO_STAMP=1 ./scripts/build-pages-site.sh   # or: exactly what GitHub Pages publishes, in build/pages-site/
docker compose down

Citations (cite:[…​]) and chapter numbers do not render on the site until the specification is ratified and published on docs.riscv.org, which supplies those extensions. The PDF has both.

Releases and lifecycle phases

Versions are two-part vMAJOR.MINOR tags compared as decimals, so v0.8 is later than v0.61. Each version maps to a lifecycle phase:

Versions	Phase
below v0.6	Draft and Development
v0.6 – v0.79	Development Complete
v0.8 – v0.89	Stabilized
v0.9 – v0.98	Frozen
v0.99	Ratification-Ready
v1.0	Ratified

The phase appears on the PDF title page and in its Document State preface, and on the site’s cover page.

To cut a release, run the Version Bot workflow (.github/workflows/version-bot.yml) against main:

• Leave the inputs at their defaults for a routine revision (+0.01, for example v0.51 → v0.52).

• To reach a milestone (v0.6, v0.8, v0.9, v0.99, v1.0), pick it in target_phase or set release_version. The bot never steps onto a milestone by itself.

The bot stamps antora.yml, tags the commit, builds the PDF, publishes a GitHub Release, and republishes the GitHub Pages site. Milestone versions are published as full releases and all others as pre-releases. When a release enters a new phase, the bot also opens a PR updating SPEC_STATE.md.

Note

Releases before the migration used three-part tags (v0.1.0 to v0.5.0), which the version tooling ignores, so it currently treats v0.3 as the latest release. The first release after the migration must therefore be set explicitly with release_version, at v0.51 or later, so it sorts above the published v0.5.0. Existing tags and releases are left as they are.

Pull requests and pushes to main build the PDF and HTML as workflow artifacts, but release nothing. Each push to main also republishes the site under /riscv-mte/dev/.

Repository settings

A repository admin needs to set these once:

1. Settings → Secrets and variables → Actions: make a GHTOKEN secret available to the repository (an organization secret counts). Without it, checks on bot-opened PRs wait for manual approval, the weekly template sync cannot open its PR at all, and the Repository Setup workflow below cannot change any setting. For template sync it needs Contents, Pull requests and Workflows read/write on this repository; for Repository Setup it also needs admin rights (Administration write).

2. Settings → Actions → General → Workflow permissions: enable Allow GitHub Actions to create and approve pull requests, so the bots can open their PRs.

3. Settings → Pages → Build and deployment → Source: set it directly to GitHub Actions. Choosing Deploy from a branch first can leave a stray build that overwrites the site.

4. Settings → Environments → github-pages → Deployment branches and tags: add a Tag rule for v*. Enabling Pages restricts the github-pages environment to main, so without this rule a release tag fails at the Pages deploy step.

5. Settings → Advanced Security → Dependabot: enable Dependabot security updates, so published advisories against the site preview tooling get a PR.

Steps 3–5 can be applied in one go by running the Repository Setup workflow (Actions → Repository Setup → Run workflow). It reads each setting first, applies what is missing, and reports anything it could not apply, so it is safe to re-run as an audit.

Template updates

.github/workflows/template-sync.yml runs weekly and opens a PR that pulls newer template-owned files (workflows, scripts, the template’s *.md guides) from docs-spec-template. .template-version records which template commit the repository is on. See UPGRADING.md.

Template sync never overwrites this repository’s own files, such as GOVERNANCE.md, CONTRIBUTING.md or the specification sources. When the template changes one of the files both share (for example the Makefile or this README), the sync PR lists it for a manual merge.

Enabling pre-commit checks locally

The repository has some basic commit checks set up with 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

# Do once on your system
pip3 install pre-commit

Installing pre-commit git hook in repo

# 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 once on your system.

When enabling additional checks 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

pre-commit run --all-files