= RISC-V Zalasr Specification

This repository serves to hold the specification for the RISC-V Zalasr (Atomic, Load-Acquire Store-Release) extension. This covers the load-acquire and store-release instructions.

== License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). See the link:LICENSE[LICENSE] file for details.

== Contributors

Contributors to this specification are contained in the link:contributors.adoc[contributors] file.

For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file.

== Building the Document

=== Building on Container

To simplify the building process and avoid dealing with configurations and dependencies, you can build this documentation using a base container image, which contains everything you need. Follow these steps:

Prerequisite: https://docs.docker.com/engine/install/[ensure you have Docker installed]

1 - Clone the repository

$ git clone https://github.com/riscv/docs-dev-guide.git
$ cd ./docs-dev-guide

2 - Pull the RISC-V documentation base container image:

$ docker pull riscvintl/riscv-docs-base-container-image:latest

3 - Run the container and execute the build:

$ docker run -it -v $(pwd)/docs-spec-template:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make'

Output:

Building asciidoc
asciidoctor-pdf \
    --attribute=mathematical-format=svg \
    --attribute=pdf-fontsdir=docs-resources/fonts \
    --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \
    --failure-level=ERROR \
    --require=asciidoctor-bibtex \
    --require=asciidoctor-diagram \
    --require=asciidoctor-mathematical \
    --out-file=example-spec.pdf \
    header.adoc

4 - Clean

docker run -it -v $(pwd):/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make clean'

=== Buidling on Local Machine

==== Dependencies

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.

For more information on AsciiDoctor, specification guidelines, or building locally, see the https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide].

==== Cloning the project

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.

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:

$ 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

==== Building the document

The final specification form of PDF can be generated using the make command.