riscv-isa-manual: the AsciiDoc source behind the RISC-V specification

Three volumes share one AsciiDoc source tree

The README is short and points at one thing: this repository contains the source files for the RISC-V Instruction Set Manual. What follows is the split that matters to anyone reading the spec, because the manual is not one document but three. Volume I covers unprivileged architecture, Volume II covers privileged architecture, and Volume III covers profiles. That division is the single most useful fact for a newcomer, since the questions people arrive with usually belong to exactly one of the three.

The preface of each volume states which version of that standard has been formally ratified by RISC-V International, which is a reminder that a specification and the document describing it are separate objects. The draft you read on the web is the state of the editing branch, and it can contain proposals that no chip implements yet.

The tree shows how the text is assembled. `src/` holds the AsciiDoc sources, `modules/` holds per-topic directories, `dependencies/` pulls in external material, `docs-resources` supplies images, and the two files `tagging_normative_rules.adoc` and `normative_rule_defs/` deal with how normative statements are marked up. There is also an `antora.yml`, which is the configuration for the documentation site, and a `.pre-commit-config.yaml` for the checks that run before a commit lands.

Draft, intermediate and official are three different builds

The Makefile in the repository root is where the release policy is actually encoded, and it is worth reading because the README does not explain it. A single variable, `RELEASE_TYPE`, decides what gets built:

RELEASE_TYPE ?= draft
DOCS := riscv-spec

The default is `draft`, and a draft build sets a watermark option so the output announces itself as unofficial. Setting it to `intermediate` drops the watermark but still labels the result an intermediate release. Setting it to `official` removes the warning and changes the citation string from a date-plus-type form to a plain date, which is the format a ratified release needs so that people can cite it permanently.

Anything outside those three values stops the build with an error naming the valid set. The Makefile also derives a month and year from a `DATE` variable, with a BSD and a GNU date invocation chained so the same command works on macOS and Linux. That detail is small but tells you the build is expected to run on developer laptops as well as in CI.

The container image is the recommended way to build

The README recommends Docker for building the PDF rather than a local toolchain, and the Makefile header names the image directly:

docker pull ghcr.io/riscv/riscv-docs-base-container-image:latest

The reason is visible in the Makefile comments: a specification build pulls in AsciiDoctor plus diagram extensions, font handling and a bibliography tool, and pinning that combination in an image is cheaper than keeping a laptop in step with it. Local builds and GitHub Actions builds are also supported, and the README points at the Documentation Developer's Guide for those paths rather than duplicating the instructions.

The Makefile is explicit that it supports PDF, HTML and EPUB targets. The EPUB path has its own footnote about embedded images: readers that cannot display them need the `:data-uri:` line in `src/riscv-spec.adoc` uncommented, and the README names one known failure case, the PocketBook InkPad 3. It is a small thing, but it is the kind of detail that only exists in a repository maintained by people who actually ship the artifact.

Where to read the manual, and which copy counts

The README distinguishes four sources, and the distinction has practical consequences. Official versions live on the RISC-V International website. Compiled builds of the most recent drafts sit on the GitHub releases page. HTML snapshots of the latest commit are published at three URLs, one per volume. Older official versions are archived under a dedicated archive tag on the releases page.

That last one is the item most readers miss. Ratified versions do not disappear when a new one is published, they are copied into the archive, so a design that cites a specific ratified version can still be checked. Being able to say which ratified version a design targeted is the sort of detail that turns up in later audits, and the archive is where you settle it.

The HTML snapshots at riscv.github.io are explicitly described as snapshots of the latest commit, so they track the editing branch rather than a release. If you need a stable citation, the official versions page and the archive are the links to use.

marchid.md tracks which implementations exist

One file in the repository serves a purpose unrelated to the specification text. `marchid.md` holds the canonical list of `marchid` CSR values for open-source RISC-V implementations. `marchid` is the register an implementation reads to identify what it is, and the manual itself does not enumerate the values, so this file is the reference that fills the gap.

That matters when you read release notes. Several of them are about clarifying what a register or an extension actually does rather than about adding features, because a specification is a document that other people implement from, and an ambiguity in it turns into divergent silicon. The September releases include a change to Zifencei that extends its ordering guarantee to prior instruction fetches, not just explicit memory accesses, and a separate correction of two unprivileged instruction descriptions that named the wrong register. Those are the kind of edits that look trivial in a changelog and matter a great deal to anyone writing a core or a formal model.

Two license statements, and picking the one that applies

Two licensing statements appear in this repository and they are not identical. The README describes the work as licensed under a Creative Commons Attribution 4.0 International License, and the repository's own license metadata records CC-BY-4.0. The Makefile header, on the other hand, describes itself under the Creative Commons Attribution-ShareAlike 4.0 International License and carries the SPDX identifier CC-BY-SA-4.0.

Both statements can be read as accurate, since they describe different files, but they lead to different obligations for anyone reusing the text. Attribution alone asks you to credit the source. Attribution-ShareAlike asks you to license your adaptations under the same terms, which is a real constraint if you planned to fold chapters into your own documentation.

The practical approach is to stop guessing and check. The README directs readers to the `LICENSE` file for details, and per-file headers are the more specific statement for any individual file. If your use is redistribution or adaptation rather than reading, open `LICENSE` first and treat the file-level SPDX identifier as authoritative for that file. Both licenses are permissive enough for internal use, so this only becomes a problem at the point where you publish something derived from the manual.

What the release train tells you about the pace of change

GitHub reports the last push on 2026-09-22, and the release history matches that. The tags follow a readable pattern of `riscv-isa-release-<commit>-<date>`, with entries on 2026-09-17, 2026-09-21 and 2026-09-22, and each release body names the commit it was built from and links the comparison against the previous tag. One commit produced two releases on consecutive days, which suggests releases are cut on demand rather than on a fixed calendar.

The volume of individual changes in each release is small. The 2026-09-17 build carries two edits, the 2026-09-21 build carries the same two as the 22nd. For a reader trying to decide whether to pin a specific version, that is good news: the document changes in small, attributable increments, and the tag names let you diff any two points in the history directly.

Contributions run through `CONTRIBUTING.md`, which the README points at for setup and build instructions, and then through the RISC-V documentation developer guide for the wider process. The repository is not archived, and the commit cadence in the tag history is the practical evidence for that.

Editorial conclusion

This repository is best understood as the editing surface for a document, not as a software library. Nothing here executes on your machine, and the value is entirely in the prose and the tables under `src/`. What it does settle is how the specification is versioned: a build is a Makefile invocation, the type of build decides whether the output is a watermarked draft or an official release, and every compiled PDF lands on the releases page with the commit hash in its tag. Where it stays silent is anything about implementation, since marchid values are listed but nothing explains how to claim one. Start by reading Volume I on riscv.org if you need the ratified text, pull the container image named in the Makefile if you intend to build, and treat every PDF built locally as a draft unless RELEASE_TYPE says otherwise.

Frequently asked questions

Official sources

1. License: CC-BY-4.0
2. Project website
3. README
4. Releases
5. riscv/riscv-isa-manual on GitHub