Add initial support for Sail snippets

[Timmmm]

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.

[Timmmm]

It looks like this:

[arichardson]

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).

That would definitely be nice but I don't think it should block this PR.

• 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.

What is the encoding issue? I would hope having it all as utf-8 should be fine.

• 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.

We could just have function calls be hyperlinks and include the helpers in an appendix, similar to Arm documentation. I don't think we need to restructure the sail model.

Inlining for the documentation would be quite neat but again that can be an incremental improvement.

Thanks for working on this, looks great! I think we should just add the execute clauses for all instructions and then do the incremental improvements afterwards.

[Timmmm]

That would definitely be nice but I don't think it should block this PR.

I agree.

What is the encoding issue? I would hope having it all as utf-8 should be fine.

Ruby loads files as ASCII by default. Easy to fix but I don't think we want to wait for a new release or asciidoctor-sail and for the docker image to get updated. I will just remove all the non-ascii characters from the Sail code I think.

Thanks for working on this, looks great! I think we should just add the execute clauses for all instructions and then do the incremental improvements afterwards.

Sounds good. I am off for Christmas now but I will add all the other clauses in the new year. 🎄

[tariqkurd-repo]

Ruby loads files as ASCII by default. Easy to fix but I don't think we want to wait for a new release or asciidoctor-sail and for the docker image to get updated. I will just remove all the non-ascii characters from the Sail code I think.

are there many non-ascii characters?

and I guess you'd like to keep this one open until you've added all the other SAIL snippets before merging?

[Timmmm]

are there many non-ascii characters?

No I think it's just one or two backticks.

and I guess you'd like to keep this one open until you've added all the other SAIL snippets before merging?

Yep, will do.

[Timmmm]

Ok I've made a new release with the ASCII issue fixed, and updated the Makefile so it doesn't need iconv.

I also added a load of snippets into the document. I didn't do any of the memory ones yet - probably needs a bit more thought about what to include.

I think this is ready to go anyway. After this is landed we should try and get the newer version with syntax highlighting, hyperlinking, etc.

Here's the HTML it outputs. Search for RETIRE_SUCCESS to see the snippets.

riscv-cheri.zip

[arichardson]

Just looked over the rendered HTML and this looks good. A few ones I noticed that aren't there yet and have a real sail implementation are CMV, CRAM, JALR_capmode, JAL_capmode

[arichardson]

still LGTM, futher improvements can always be made in follow-up PRs.

[Timmmm]

CMV, CRAM, JALR_capmode, JAL_capmode

Added, thanks!