Add initial support for Sail snippets

This updates the Makefile to download `riscv_RV64.json` and then add a couple of example Sail snippets to the document.

There are some caveats:

* No syntax highlighting or hyperlinking in the code. Alasdair demonstrated this recently but I don't know if he pushed the feature to asciidoctor-sail (or maybe the version in the Docker image is too old).
* There's an encoding issue with the JSON. I temporarily worked around it with iconv. In future I will probably just remove the non-ASCII characters from the Sail code.
* The Sail code is not really written with inclusion in documentation in mind. For example the scaddr code basically calls another function which you can't see in the docs, so it's kind of useless currently.

There are a few ways I can think of to fix the last point.

1. Alasdair has some fancy system to automatically modify the Sail code that is generated. He demonstrated it before to split up `execute` clauses that switch on a union, but I think we could also do things like inlining functions.
2. The output with hyperlinks will be way more useful because you can just click on the function to see its source.
3. We could probably rewrite the code a bit to focus more on readability in a spec and less on good software development practices. For example use raw bit values instead of enums.

Author: Timmmm

Makefile

@@ -38,6 +38,12 @@ CSVS	    = $(wildcard $(CSV_DIR)/*.csv)
 GEN_DIR     = $(SRC_DIR)/generated
 SCRIPTS_DIR = $(SRC_DIR)/scripts
 
+# Downloaded Sail Asciidoc JSON, which includes all of
+# the Sail code and can be embedded. We don't vendor it
+# into this repo since it's quite large (~4MB).
+SAIL_ASCIIDOC_JSON_URL_FILE = riscv_RV64.json.url
+SAIL_ASCIIDOC_JSON = $(GEN_DIR)/riscv_RV64.json
+
 # Output files
 PDF_RESULT    := $(BUILD_DIR)/riscv-cheri.pdf
 HTML_RESULT   := $(BUILD_DIR)/riscv-cheri.html
@@ -89,7 +95,8 @@ ASCIIDOC_OPTIONS  = --trace --verbose                                \
                     --failure-level=ERROR $(EXTRA_ASCIIDOC_OPTIONS)
 ASCIIDOC_REQUIRES = --require=asciidoctor-bibtex       \
                     --require=asciidoctor-diagram      \
-                    --require=asciidoctor-mathematical
+                    --require=asciidoctor-mathematical \
+                    --require=asciidoctor-sail
 
 # File extension to backend map.
 ASCIIDOC_BACKEND_.html = html5
@@ -130,11 +137,11 @@ $(BUILD_DIR):
 	@echo "  DIR $@"
 	@mkdir -p $@
 
-%.pdf: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR)
+%.pdf: $(SRCS) $(IMGS) $(GEN_SRC) $(SAIL_ASCIIDOC_JSON) | $(BUILD_DIR)
 	@echo "  DOC $@"
 	$(BUILD_COMMAND)
 
-%.html: $(SRCS) $(IMGS) $(GEN_SRC) | $(BUILD_DIR)
+%.html: $(SRCS) $(IMGS) $(GEN_SRC) $(SAIL_ASCIIDOC_JSON) | $(BUILD_DIR)
 	@echo "  DOC $@"
 	$(BUILD_COMMAND)
 
@@ -143,9 +150,15 @@ $(GEN_SRC) &: $(CSVS) $(GEN_SCRIPT)
 	@echo "  GEN $@"
 	@$(GEN_SCRIPT) -o $(GEN_DIR) --csr $(CSV_DIR)/CHERI_CSR.csv --isa $(CSV_DIR)/CHERI_ISA.csv
 
+# Download the Sail JSON. The URL is stored in a file so if the URL changes
+# Make will know to download it again.
+# TODO: Remove iconv once this is fixed: https://github.com/Alasdair/asciidoctor-sail/issues/6
+$(SAIL_ASCIIDOC_JSON): $(SAIL_ASCIIDOC_JSON_URL_FILE)
+	@curl --location '$(shell cat $<)' | iconv -f UTF-8 -t ASCII//TRANSLIT >$@
+
 # Clean
 clean:
 	@echo "  CLEAN"
-	@$(RM) -r $(PDF_RESULT) $(HTML_RESULT) $(GEN_SRC)
+	@$(RM) -r $(PDF_RESULT) $(HTML_RESULT) $(GEN_SRC) $(SAIL_ASCIIDOC_JSON)
 
 .PHONY: all generate clean

riscv_RV64.json.url

@@ -0,0 +1 @@
+https://github.com/CHERI-Alliance/sail-cheri-riscv/releases/download/2024-12-19/riscv_RV64.json

src/attributes.adoc

@@ -36,6 +36,9 @@ endif::[]
 :xrefstyle: short
 :attribute-missing: warn
 
+// Sail source code
+:sail-doc: src/generated/riscv_RV64.json
+
 ///////////////////////////////////////////////////////////////////////////////
 // Top-level CHERI definitions
 ///////////////////////////////////////////////////////////////////////////////

src/insns/modesw_32bit.adoc

@@ -34,7 +34,5 @@ Prerequisites::
 {cheri_default_ext_name}
 
 Operation::
-[source,SAIL,subs="verbatim,quotes"]
---
-TODO
---
++
+sail::execute[clause="MODESW()",part=body,unindent]

src/insns/scaddr_32bit.adoc

@@ -34,6 +34,4 @@ Prerequisites::
 
 Operation::
 +
---
-TODO
---
+sail::execute[clause="SCADDR(_, _, _)",part=body,unindent]