riscv-elf-psabi-doc: where the RISC-V binary interface is actually specified

Six things a processor has to pin down before code can move

The repository describes itself as a processor-specific application binary interface document for RISC-V, and the list of what it covers is short and precise.

The items are the Procedure Calling Convention, the ELF Object Files Format, the DWARF Debug Information Format, the Code Model, Relocation and Relaxation. That list is the specification's whole scope, and each entry answers a question that a compiler and a linker have to agree on before a binary means anything.

The calling convention defines which registers carry arguments, which carry results and who saves what, and every ABI is a set of answers that a language implementation has to match. The object file format section fixes what the compiler emits and the linker consumes, including the details that break silently when they differ. The DWARF section is what makes a RISC-V binary debuggable, so that the debugging information produced for other architectures does not apply. The code model section says how addresses are formed. Relocation is how the linker fixes up references. Relaxation is the optimisation where the toolchain rewrites instructions, and it is the item with the most room for a specification to be subtle, because relaxation must be semantically invisible and still produce a valid binary.

So this is a document about compatibility rather than about performance, and that is what makes it interesting to read even if you never write RISC-V assembly.

The licence is CC-BY-4.0, the branch is master, and the last push was on 2026-10-15.

Drafts, a release candidate and PDFs are three different channels

The release history shows how a specification like this is published, and the three kinds of entry in the list are worth telling apart.

There are draft releases, named with a date and a commit hash, such as the draft release from 20261014 and the one from 20261008. There is also a versioned release candidate, v2.0-rc0, described as psABI 2.0 rc0 and published on 2026-10-12, two days before the newer draft. So the project publishes dated snapshots of the work in progress alongside a numbered release candidate for the major version.

For a reader, the distinction is the difference between a document you can cite and a document you can read. A release candidate is a formal proposal of a version, and a draft is a snapshot that will change. A toolchain that implements psABI 2.0 should be tested against the release candidate, not against whatever the master branch says this week.

The distribution channels are also several. The AsciiDoc sources render directly on GitHub, so the document is readable in a browser with no tooling at all. Pre-built PDFs can be downloaded from the repository's releases, and the latest snapshot is published on GitHub Pages, which is the version to link to when you want a moving target and the PDF when you want a fixed one.

That last distinction is the practical one. A link to the pages site will change under you, so any document that cites the psABI should cite a specific PDF from a specific release, and the release list is what makes that possible.

The build is one asciidoctor call and a date attribute

The Makefile in the repository root is short, and it tells you how the PDFs and the HTML are produced.

The document is named riscv-abi, and every .adoc file in the root is picked up by a wildcard so that a new chapter is included automatically. The date and the month and year are computed with the date command and passed to the converter as attributes, which is why the PDF carries a generation date without anyone editing the source by hand.

The PDF target runs asciidoctor-pdf with compression enabled, a style file from the resources themes directory and a fonts directory, so the document's typography is a repository asset rather than a converter default:

	asciidoctor-pdf \
	    $(ASCIIDOCTOR_FLAGS) \
	    -a compress \
	    -a pdf-style=resources/themes/risc-v_spec-pdf.yml \
	    -a pdf-fontsdir=resources/fonts \
	    $< -o $@

There is a parallel HTML target using plain asciidoctor with the same attribute flags, and it is selected by setting HTML to 1 when the make target is invoked. A clean target removes both outputs, and the default target is the PDF.

The details that matter for anyone reproducing the document are the two attributes, date and monthyear, and the theme and font paths. A theme file that is not in the repository will silently change the output, and a document whose date attribute is hard coded gets stale on every re-render, which is why the date is computed rather than written.

The resources directory also holds the images directory content used by the chapters, and the theme file itself is the only reason the PDF looks like an RISC-V specification rather than a generic AsciiDoc render.

One table in the document is generated by a Python script

The repository listing is mostly AsciiDoc files, and the primary language recorded for the project is Python, which is explained by a single script.

There is gen_vector_type_infos.py at the root, and a make target that regenerates the vector type table:

regen_vector_type_infos:
	python3 gen_vector_type_infos.py > vector_type_infos.adoc

The output goes to vector_type_infos.adoc, which is one of the chapters in the root. So the vector type information is not hand-maintained prose. It is produced by a script and redirected into a chapter file, and the make target exists so that a maintainer can refresh it in one command.

That pattern, a generated file checked into the repository next to the script that produced it, is a reasonable one for a specification, because the rendered document has to be a single self-contained artefact, while the source of truth for the table is code. The cost is that the checked-in chapter can drift from the script, and there is no test in the repository that would catch it.

It also explains the language field. An AsciiDoc specification with one generator script is recorded as a Python project, which is a good reminder that a repository's primary language tells you about its tooling rather than about its subject matter.

The navigation table is a map of the whole specification set

The README's navigation section is a table of the other documents in the RISC-V specification family, and it is a better guide to the ecosystem than the document itself.

There is the RISC-V ELF psABI document itself, the RISC-V Embedded ABI proposal, which is a draft for a new embedded ABI for embedded RISC-V systems, the RISC-V C API document covering predefined macros, function attributes and language extensions, the RISC-V Assembly Programmer's Manual for pseudoinstructions and assembly directives, the RISC-V Toolchain Conventions for toolchain behaviour and command line options, the semihosting specification, and the Supervisor Binary Interface specification.

Two things stand out in that table. The documents are split across two GitHub organisations, riscv-non-isa and riscv, which tells you the psABI is treated as a non-ISA document, that is, architecture-level and not tied to one particular base or extension set, while some of the others sit in the main riscv organisation. And the ELF psABI and the semihosting specification are listed under different organisations, so the family is not centrally owned even if the naming makes it look that way.

Below the table there is a link to the policy for merging pull requests, which is the repository's contribution rules. For a specification, that policy is more than boilerplate, because the process by which text becomes normative is part of what a reader of the document is entitled to know, and the repository publishes it rather than keeping it on a wiki.

The navigation table also tells you where the boundaries are. The psABI does not define the assembly language, the C API, the toolchain flags or the supervisor interface, so a project that needs those has to read several documents and keep their versions aligned.

How the source files map onto the six subjects

The chapter files in the repository root give a decent mental model of the document's structure, since each file name is a topic.

There is riscv-cc.adoc for the calling convention, riscv-elf.adoc for the object file format, riscv-dwarf.adoc for the debug information format, riscv-abi.adoc for the general ABI topics, riscv-atomic.adoc for the atomic operations, and riscv-rtabi.adoc, which is the runtime ABI material. The framing chapters are introduction.adoc, preamble.adoc and prelude.adoc, and the generated vector type table is vector_type_infos.adoc.

The naming pattern is the interesting thing. The file names follow the terminology the specification itself uses, which means the table of contents, the anchors, the cross references and any external discussion all use the same vocabulary. For a document that other specifications and toolchain implementations refer to, consistent naming is not cosmetic.

Reading the document is a matter of picking the chapter that matches the question. Anything about arguments and registers is in the calling convention chapter, anything about the bytes in an object file is in the ELF chapter, and anything about a linker rewriting instructions is in the relocation and relaxation chapters.

The final piece is the licence. CC-BY-4.0 is a content licence rather than a software licence, which is the right choice for a specification and has a practical consequence: other documents, including implementations and teaching texts, can quote and adapt the text with attribution, while the code in the repository, the generator script, is covered by the LICENSE file at the root and has to be checked separately if you plan to reuse it. For most people the text is the part they want, and it is deliberately the easy part to reuse.

Editorial conclusion

Adopt this repository as your source of truth if you are writing RISC-V user space code, a loader, a linker or a toolchain component, because the calling convention and the object file rules it defines are the ones your code has to match, and the text is versioned in git with a visible release history. Do not treat a draft release as normative, since the release list interleaves dated draft builds with the 2.0 release candidate, and read the merge policy before sending a pull request, because the document has a formal contribution process. Before you build against a specific revision, pin the release you built against, since the psABI changes between versions and the PDF you downloaded is the artefact that is fixed.

Frequently asked questions

Official sources

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