Include SAIL snippets into the specification

[andresag01]

This includes the snippets into the instruction listings as well as the capability description chapter.

Currently waiting for a publicly available, up to date SAIL model being released.

[francislaus]

Can we (and should we) pick up a dependency to the Sail model for that? Would it be possible to automatically pull in the relevant lines from the Sail model? @Timmmm @PeterRugg

[wmat]

There is for PDFs. See https://github.com/Alasdair/asciidoctor-sail I have a branch of riscv-isa-manual called sail-inclusion here: https://github.com/riscv/riscv-isa-manual/tree/sail-inclusion with an example of using Alasdair's extension to pull SAIL into the doc. If you look at my commit here: riscv/riscv-isa-manual@abd45a5 you can see the changes I had to make for the example. But please see Alasdair's documentation in his repository for more information here: https://github.com/Alasdair/asciidoctor-sail/blob/master/doc/built/sail_to_asciidoc.pdf

…

On Thu, Dec 12, 2024 at 4:46 AM Franz Fuchs ***@***.***> wrote: Can we (and should we) pick up a dependency to the Sail model for that? Would it be possible to automatically pull in the relevant lines from the Sail model? @Timmmm <https://github.com/Timmmm> @PeterRugg <https://github.com/PeterRugg> — Reply to this email directly, view it on GitHub <#362 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAN6ZGPJEDB6BSDHL5LDLT2FFLO7AVCNFSM6AAAAABODRUXICVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKMZYGM4DQOBVGI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[Timmmm]

I did set this up when the spec was in Codasip but we removed it when it was moved to GitHub since the Sail code wasn't open at the time. I'll see if I can resurrect it.

The big question is how do you get the JSON file. It's very big so I don't think you just want to add it to Git. But adding Sail compilation to the build process is also not great (although it's a lot better since we made the Sail binary release). In Codasip we had a cache on a web server which worked pretty well. How do people feel about using GitHub releases for that?

So every push (or maybe tag) in the Sail repo would generate the JSON and add it to a GitHub release, and then this repo would just point to the URL and download it.

We'll have to answer this question for riscv-isa-manual too and I think this repo could serve as a good demonstrator.

[wmat]

For my testing purposes on riscv-isa-manual I've been generating the index at the top of tree of the sail repository and adding it directly into the repo and referencing it with an AsciiDoc attribute in the document header (riscv-unprivileged.adoc) with :sail-doc: src/sail-index/riscv_RV64.json.

[Timmmm]

Yeah the issue is it's 4.5 MB (3.1 MB minified). Feels a bit much for a file that we'd continually update? Though I guess it probably does diff pretty well at least.

[Timmmm]

Ok I have update the Sail repo to have a Github workflow to generate the JSON and I have made a release of it (making a release is a manual process currently but I can automate it in future).

Next step is to update this repo to curl https://github.com/CHERI-Alliance/sail-cheri-riscv/releases/download/2024-12-19/riscv_RV64.json and add the asciidoctor-sail stuff. I'll have a go tomorrow.

[Timmmm]

PR here: #498
(on top of #497)