elisa-riscv
commented
3 years ago In answer to your open question about whether to have a monolithic document or to break it into sections, I recommend chapter-sized chunks. The chapter-sized chunks can be grouped into sections, and all can be included in a book header file. You can find an example at https://github.com/riscv/docs-templates. Right now some specifics are subject to change and there is a bug with respect to the use of wavedrom diagramming for which we might need to provide a temporary workaround.
ben-marshall
The specification needs to be converted from LaTeX to asciidoc, specifically the asciidoctor tool. This issue tries to capture what needs to happen.
What needs converting?
All of the LaTeX files under
doc/spec/tex. Starting with thescalarand files shared between specifications, but moving onto the vector spec.How will it be converted:
We can use Pandoc to bulk convert the files automatically, but there are several important gottchas while will need manual or semi-automatic fixing:
We have an extensive bibliography, particularly for the Entropy Source which should be preserved. Asciidoc does not have such a powerful bibliography system as LaTeX, but there is a standard way to do it described here. There is also a WiP script (
bin/bibtex-to-asciidoc.py) to automatically convert the bibtex citations to the asciidoc format.Pandoc does not convert the latex
\cite{X}macro into an asciidoc reference. The entire citation simply disappears from the output. This will either need to be fixed manually, or semi-scripted to be fixed.We currently inline the Sail code describing the functionality of our instructions into the specification, by sourcing from the Sail files directly. Pandoc is smart enough to extract the right parts of the source code in its automatically converted output. However, this will need to be manually maintained whenever the Sail code is updated, unless an automated solution exists / can be found.
Pandoc mangles anything in the verbatim-esq
cryptoiseenvironment. This can be manually fixed. It's just for showing assembly syntax.Edited to add: It looks like there's a great set of templates/examples here
Open Questions:
It's not clear how to represent the encodings? We can generate these tables if need be, as is currently done for the LaTeX, though it would be good if there was a standard way to do this.
We currently have one monolithic specification document, which works really well as a "single source" for people to look at. It's likely that this will be split into separate components:
ZKbsection, which is just a list of instructions from the Bitmanip extension which are useful for Scalar Cryptography, along with some rationale.ZKtproposal, which is orthogonal to the rest of the spec, and adds constant time guarantees to listed instructions. It is already in asciidoc, and is maintained here. It will eventually be moved into this repository.It's not entirely clear whether these should be distributed as a single document, or maintained as separate files but combined into one monolithic document, as is currently done with the LaTeX sources. In any case, all of them will need to be versioned.
It's not clear how our specification will be integrated into the main specification. We want to do our conversion to asciidoc so as to minimise the effort it takes to integrate into the final specification.
Progress
Shared files:
Scalar Crypto:
ZKb instruction group:
Entropy Source:
Vector:
These are not a priority right now, we are focusing on the scalar crypto work.