Separator for long/variable length field

[AloyseTech]

This is a feature/enhancement proposition.
Bit field could be used to document binary packet format if there would be a variable length separator capability. Something like this :

Has this feature been added, trying to document a binary communications protocol and this is basically a requirement to make bitfield useful for that purpose?

[drom]

No, this feature is not being implemented yet.

I have some questions:

Are we talking about this particular example with one variable length field in the end?
Can this field be in the middle?
How this would look like with multiple variable fields?
Can we have mix of Varible anf fixed fields?
@MattIhnen can you share your use case?

[radimkrcmar]

The RISC-V ISA spec is using an inconsistent combination of wavedrom/bitfield and bytefield-svg to define its registers, where bytefield-svg is mostly used when the register has variable length.

There will generally be only one variable length field that can be positioned anywhere among fixed fields:

This image also demonstrates that it's very easy to get a bad looking definition with bytefield-svg.
How do you think it would look in wavedrom/bitfield?

[drom]

Assuming the are only 2 XLEN cases (32 and 64)
Would it be less confusing just to write them down?

MXLEN=32

MXLEN=64

{reg: [
  {bits: 26, name: 'Extensions <b>(WARL)'},
  {bits: 4, name: '0'},
  {bits: 2, name: 'MXL'}
], config: {hspace: 540}}

[radimkrcmar]

There is also a planned 128-bit extension, which will probably just expand the reserved field.
The bits would also be really small if the 128-bit definition fit on one line, 64 is already pushing readability.

I think we'd currently have to settle for something like this with wavedrom:

Having each on one line, with the 0 field being fixed display size, but variable number of bits could already be an improvement:

Fitting MXLEN - 1 and MXLEN - 2 and MXLEN - 3 would be a challenge.

[wmat]

Note that when I converted the ISA specifications from LaTeX to AsciiDoc, I implemented the diagrams as best I could using wavedrom when possible and bytefield-svg as needed to accommodate bitfields with long names. My goal was to match the original LaTeX formatting as closely as possible. That original LaTeX is from the 20191213 version of the Unprivileged spec and the 20211203 version of the Privileged spec found here: https://lf-riscv.atlassian.net/wiki/spaces/HOME/pages/16154899/RISC-V+Technical+Specifications+Archive

Improvements are always welcome, but should be made against the riscv/riscv-isa-manual repository.

Note that the ideal situation would be to generate the diagrams from the riscv/opcodes repository and/or SAIL code when possible thereby removing the need to manually code them. The inclusion of SAIL in the ISAs is forthcoming and for reference, please see the documentation for the SAIL-to-AsciiDoctor extension here: https://github.com/Alasdair/asciidoctor-sail

Note also that the specs need to be presented as PDF, HTML (using Antora), and Epub formats.

[radimkrcmar]

Improvements are always welcome, but should be made against the riscv/riscv-isa-manual repository.

Of course, this issue is to improve wavedrom. RISC-V ISA is just used as a concrete example.

The inclusion of SAIL in the ISAs is forthcoming and for reference, please see the documentation for the SAIL-to-AsciiDoctor

I see wavedrom in requirements, does asciidoctor-sail implement variable length fields without wavedrom-bitfield?

[wmat]

I haven't tested how variable length fields generate from asciidoctor-sail yet. This is going to land shortly though as it's been enabled in the CHERI spec and will be enabled in the ISAs shortly. The big lift will getting folks to replace and/or add the SAIL includes into the current asciidoc.

[radimkrcmar]

CHERI has another great example what wavedrom-bitfield would have to support if RISC-V ISA were to use it exclusively:

[ipocentro87]

I also find having this feature very useful 👍