riscv/docs-dev-guide

Documentation developer guide

RISC-V Documentation Developer Guide

This repo contains useful information for using AsciiDoc to write RISC-V specifications.

A simple template for beginning a RISC-V specification can be found here: https://github.com/riscv/docs-spec-template

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 repo is maintained in the MAINTAINERS file.

Contributors

The list of contributors to this document 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.

Building the Document

Directory Structure

The following directories are used to organize the contents of this repo:

• dependencies/: software dependencies needed to build the specification

• docs-resources/: resources for all specifications sourced from git submodule

• src/: source files for the specification

• build/: default directory where the build artifacts are generated

Prerequisites

To build the document, you’ll need the following tools installed on your system:

• Make

• asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical

• Docker

Cloning the Repository

git clone --recurse-submodules https://github.com/riscv/docs-dev-guide.git

All in one single line:

git clone --recurse-submodules https://github.com/riscv/docs-dev-guide.git && cd docs-dev-guide && git submodule update --init --recursive

Building the Documentation

To start the build process, run:

cd ./docs-dev-guide && make build

The 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:

make clean

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

docs-dev-guide's Issues

Missing images/wavedrom/instruction_formats.adoc

At aa50390

%  asciidoctor-pdf -r asciidoctor-diagram -r asciidoctor-mathematical -a mathematical-format=svg -r asciidoctor-bibtex book_header.adoc -a pdf-style=resources/themes/risc-v_spec-pdf.yml -a pdf-fontsdir=resources/fonts --trace
asciidoctor: ERROR: tables_graphics.adoc: line 207: include file not found: /work/jscheid/src/gh/riscv/docs-templates/images/wavedrom/instruction_formats.adoc

wavedrom rendering for 16-bit encodings

https://github.com/riscv/riscv-code-size-reduction/blob/master/Zce-release-candidate/c_mul.adoc

for example - the wavedrom encoding diagram is 32-bit wide, but it's only a 16-bit encoding.
Is there a way of configuring it to be only 16-bits?

also, this one for example:

https://github.com/riscv/riscv-code-size-reduction/blob/master/Zce-release-candidate/c_sb.adoc

the necessary text doesn't fit in the boxes if you render the file - how can I fix that?

Thanks!

Tariq

refactor to incorporate changes in the docs-spec-template

as part of updating the docs-dev-guide we should submodule the https://github.com/riscv/docs-resources
like the template does so we don't have to maintain the local copies and so the doc's team dogfoods the same flow.

I can provide a PR.

update guide to use docs-spec-template workflow

Although this isn't a spec, I see no reason it shouldn't follow same/similar workflow (some of which has already been changed).

I'll put in a PR for this:

• update Makefile: src/build dir, HTML output
• update docs-resources to latest
• incorporate global adoc attributes from docs-resources
• update adoc attributes in spec where needed
• update GitHub action build flow where needed (src dir)
• update pre-commit hooks
• update README.adoc to incorporate all these changes

Add spec integration steps.

Add the basic steps for integrating a spec into the ISA specs. Granted these could be different given an authors' dev environment, but starting somewhere is good.

Which pdf-style is preferred?

I saw there is two pdf-style file, alt2-theme.yml and risc-v_spec-pdf.yml, which is preferred or suggested one?

Precommit keeps failing

@kbroch-rivosinc the precommit in this repo is failing. Not sure why. When you get a free minute, can you diagnose? But not top priority - I can keep ignoring...

"Icon font not found for set: pencil"

Hi there

I've been working on getting the scalar crypto spec to use the right styles as was pointed out in riscv/riscv-crypto#89. It seems to work, but I get a build error:

work@ben-TF:~/riscv/riscv-crypto/doc/adoc-scalar$ make all
asciidoctor-pdf \
        -a pdf-style=resources/themes/risc-v_spec-pdf.yml \
        -a pdf-fontsdir=resources/fonts \
        -o riscv-crypto-spec-scalar.pdf riscv-crypto-spec-scalar.adoc
Icon font not found for set: pencil
  Use --trace for backtrace

If I comment out lines 165-167 of "resources/themes/risc-v_spec-pdf.yml", then everything works fine, I just get a different icon for the NOTE admonition.

The exact file set and makefile I'm using can be found here. The branch of the riscv-crypto repo I'm using is this one. Everything is under doc/adoc-scalar.

Tool versions:

work@ben-TF:~/riscv/riscv-crypto/doc/adoc-scalar$ asciidoctor-pdf --version
Asciidoctor PDF 1.5.0.alpha.17.dev using Asciidoctor 2.0.10 [https://asciidoctor.org]
Runtime Environment (ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)

I'm using Ubuntu 20.04, with asciidoctor-pdf installed via the ruby-asciidoctor-pdf apt package.

Please let me know if you need any more information? This feels like it is a problem more with my system than the template, but I figured I'd ask to be sure.

Many thanks,
Ben

Missing LICENSE file

The project is missing a LICENSE file. Per RISC-V guidelines, documentation should be licensed CC-BY-4.0.

I propose adding a plain text LICENSE file like the one in the ISA manual project. This enables GitHub to automatically find it and recognize it.

I'm happy to add this into the project directly and will do so in the coming days. If anyone has concerns, please raise them.

Thanks,
-Jeff

pdf generation error

When I used your listed command to generate a pdf file for the book_header.adoc, I encountered the following error.

Command: asciidoctor-pdf book_header.adoc -a pdf-style#resources/themes/risc-v_spec-pdf.yml -a pdf-fontsdir=resources/fonts
Error: No such file or directory - notoserif-regular-subset.ttf not found in resources/fonts

What should I do to eliminate this error?
Thanks!

having trouble installing `gem asciidoctor mathematical` on windows

I installed cmake which wasn't in the windows instructions, as I got an error from trying to install gem asciidoctor mathematical but it hasn't solved the problem.

https://github.com/Kitware/CMake/releases/download/v3.21.0-rc3/cmake-3.21.0-rc3-windows-x86_64.msi

This is most likely the problem:

Could NOT find BISON (missing: BISON_EXECUTABLE)

PS C:\Users\t00346040\docs-templates> gem install asciidoctor-mathematical
Temporarily enhancing PATH for MSYS/MINGW...
Building native extensions. This could take a while...
ERROR: Error installing asciidoctor-mathematical:
ERROR: Failed to build gem native extension.

current directory: C:/Ruby30-x64/lib/ruby/gems/3.0.0/gems/mathematical-1.6.14/ext/mathematical

C:/Ruby30-x64/bin/ruby.exe -I C:/Ruby30-x64/lib/ruby/3.0.0 -r ./siteconf20210712-1300-s3lk9a.rb extconf.rb
checking for cmake... yes
checking for -lxml2... no
checking for -lpangocairo-1.0... no
checking for libxml/tree.h in /include/libxml2,/usr/include/libxml2,/usr/local/include/libxml2,/usr/include/libxml2... no
checking for libxml/parser.h in /include/libxml2,/usr/include/libxml2,/usr/local/include/libxml2,/usr/include/libxml2... no
checking for libxml/xpath.h in /include/libxml2,/usr/include/libxml2,/usr/local/include/libxml2,/usr/include/libxml2... no
checking for libxml/xpathInternals.h in /include/libxml2,/usr/include/libxml2,/usr/local/include/libxml2,/usr/include/libxml2... no
-- Building for: Visual Studio 16 2019
-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.17763.
-- The C compiler identification is MSVC 19.29.30038.1
-- The CXX compiler identification is MSVC 19.29.30038.1
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/BuildTools/VC/Tools/MSVC/14.29.30037/bin/Hostx64/x64/cl.exe - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/BuildTools/VC/Tools/MSVC/14.29.30037/bin/Hostx64/x64/cl.exe - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
CMake Deprecation Warning at CMakeLists.txt:19 (cmake_minimum_required):
Compatibility with CMake < 2.8.12 will be removed from a future version of
CMake.

Update the VERSION argument value or use a ... suffix to tell
CMake that the project does not need compatibility with older versions.

CMake Error at C:/Program Files/CMake/share/cmake-3.21/Modules/FindPackageHandleStandardArgs.cmake:230 (message):
Could NOT find BISON (missing: BISON_EXECUTABLE)
Call Stack (most recent call first):
C:/Program Files/CMake/share/cmake-3.21/Modules/FindPackageHandleStandardArgs.cmake:594 (_FPHSA_FAILURE_MESSAGE)
C:/Program Files/CMake/share/cmake-3.21/Modules/FindBISON.cmake:306 (FIND_PACKAGE_HANDLE_STANDARD_ARGS)
CMakeLists.txt:61 (find_package)

-- Configuring incomplete, errors occurred!
See also "C:/Ruby30-x64/lib/ruby/gems/3.0.0/gems/mathematical-1.6.14/ext/mathematical/mtex2MML/build/CMakeFiles/CMakeOutput.log".
make: *** No rule to make target 'libmtex2MML_static'. Stop.
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers. Check the mkmf.log file for more details. You may
need configuration options.

Provided configuration options:
--with-opt-dir
--without-opt-dir
--with-opt-include
--without-opt-include=${opt-dir}/include
--with-opt-lib
--without-opt-lib=${opt-dir}/lib
--with-make-prog
--without-make-prog
--srcdir=.
--curdir
--ruby=C:/Ruby30-x64/bin/$(RUBY_BASE_NAME)
--with-xml2-dir
--without-xml2-dir
--with-xml2-include
--without-xml2-include=${xml2-dir}/include
--with-xml2-lib
--without-xml2-lib=${xml2-dir}/lib
--with-xml2lib
--without-xml2lib
--with-pangocairo-1.0-dir
--without-pangocairo-1.0-dir
--with-pangocairo-1.0-include
--without-pangocairo-1.0-include=${pangocairo-1.0-dir}/include
--with-pangocairo-1.0-lib
--without-pangocairo-1.0-lib=${pangocairo-1.0-dir}/lib
--with-pangocairo-1.0lib
--without-pangocairo-1.0lib
--use-system-mtex2MML
C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:494:in realpath': No such file or directory @ realpath_rec - C:/Ruby30-x64/lib/ruby/gems/3.0.0/gems/mathematical-1.6.14/ext/mathematical/mtex2MML/build/libmtex2MML.a (Errno::ENOENT) from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:494:in copy_entry'
from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:471:in block in cp_r' from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:1597:in block in fu_each_src_dest'
from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:1611:in fu_each_src_dest0' from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:1595:in fu_each_src_dest'
from C:/Ruby30-x64/lib/ruby/3.0.0/fileutils.rb:470:in cp_r' from extconf.rb:80:in

'

To see why this extension failed to compile, please check the mkmf.log which can be found here:

C:/Ruby30-x64/lib/ruby/gems/3.0.0/extensions/x64-mingw32/3.0.0/mathematical-1.6.14/mkmf.log

extconf failed, exit code 1

Gem files will remain installed in C:/Ruby30-x64/lib/ruby/gems/3.0.0/gems/mathematical-1.6.14 for inspection.
Results logged to C:/Ruby30-x64/lib/ruby/gems/3.0.0/extensions/x64-mingw32/3.0.0/mathematical-1.6.14/gem_make.out
PS C:\Users\t00346040\docs-templates>

Ruby 2.5.9?

ALERT: Ensure that you are using Ruby 2.5.9 for all gems that you install for the Asciidoctor toolchain.

http://rubyinstaller.org/

does this mean that I should download ruby 2.5.9 from rubyinstaller.org? Because that version isn't apparently available.

References non-existent backpage.png

book_header.adoc has:

:back-cover-image: image:backpage.png[opacity=25%]

but no such file exists in the repository.

Update github actions

Right now, the stuff is in the readme file in the spec templates repo. Which is good because then you get them when you clone that repo. However, instructions should also be in the dev guide. Add them and also try to put in some help for updating an old repo.

Typoes of CCA_###

The cache coherence ID 'CCA_010' and 'CCA_020' should be 'CCS_010' and 'CCS_020', to align with other IDs.

add csr rules to guide

CSR and Register are used somewhat interchangeably. What if we adopted these rules for usage?

• CSR must always be capitalized.
• Move first use of CSR in a chapter 1 - should include full text plus acronym. Control and Status Register (CSR).
• When plural, lowercase the s. CSRs.
• Register is capitalized in title, but lowercase in text. "Supervisor Status (sstatus) Register”. But “The sstatus register…”
• When in doubt, use "CSR" to indicate the type of register. You can then intermingle CSR and register in the text. So "The misa CSR is used to...." And then later in the para, you can use "register". As in, "This register also does this other thing."
• In a title, the format is “Long name (short name) Register. All other references in that section can use the short name, but it must be in tics. So "Supervisor Status (sstatus) Register”. The rest of the references to that register can be "the sstatus CSR".
• As a general rule, whenever you use a term in tics, it should be followed by what the thing is to help with translation. So avoid statements like this: “misa also helps distinguish different variants of a design.” And instead use this: “The misa CSR also helps distinguish different variants of a design.”
• Fields for registers are formatted in this style: register.FIELD. For example, sstatus.SPP

discussion is here - riscv/riscv-isa-manual#1355

Build PDF fails

Build PDF action fails with:

Error: Error: The process '/opt/hostedtoolcache/Ruby/2.6.10/x64/bin/bundle' failed with exit code 5
at ExecState._setResult (/home/runner/work/_actions/ruby/setup-ruby/v1/dist/index.js:5340:25)
at ExecState.CheckComplete (/home/runner/work/_actions/ruby/setup-ruby/v1/dist/index.js:5323:18)
at ChildProcess. (/home/runner/work/_actions/ruby/setup-ruby/v1/dist/index.js:5217:27)
at ChildProcess.emit (node:events:390:28)
at maybeClose (node:internal/child_process:1064:16)
at Process.ChildProcess._handle.onexit (node:internal/child_process:301:5)