Re: Instructions argument string

[Tsukasa OI <research_trasio@irq.a4lg.com>]

On 2023/07/23 5:32, Jacob Navia via Binutils wrote:
> Hi
> 
> I am trying to document and decipher the « argument strings » that are stored as character strings in the risk_opcode opcode table. They are strings like "Ct,Cc,CK » or "Ct,Cc,CK ». They are interpreted in the function riscv_ip. Is there anywhere a documentation as to the workings of the interpreter, i.e. which do the letters actually mean?

Unfortunately, none.

Those operands are subject to change in any time and in fact, it
changed.  An example is "f" [fetch offset to the 'Zicbop' extension
HINTs] to "Wif" (to vacate one-letter operand character space and
prepare for other operands that would be too much for one-letter space
such as "Wfv" [the 'Zfa' extension; floating point operand of FLI
instructions]).

I'm afraid to say, the source code is the best documentation.  I once
made a list (to prune unused operand strings; for the following patch
set) but now the list is outdated and it doesn't have any documentation.
<https://sourceware.org/pipermail/binutils/2022-August/122269.html>

At least I can provide an advise.  When I forget some details about
operand string, I mainly see three functions and I personally prefer
print_insn_args (though I use other two functions when necessary).

gas/config/tc-riscv.c: validate_riscv_insn
    It can be a quick reference to indicate which bits are used.
gas/config/tc-riscv.c: riscv_ip
    It's the main parser.  If you wonder any instruction operand
    formats, it's the best place to look at.  But it's also the most
    complex function which uses operand string.  So, if I forget
    something about operand string, it's the last function to see.
opcodes/riscv-dis.c: print_insn_args
    It's the main printer for the disassembler (objdump and GDB).
    It's not self-explanatory as validate_riscv_insn but provides
    many information yet easier to read than riscv_ip.

I understand that this is not a satisfactory answer for you but still
the best I got now.

Thanks,
Tsukasa

> 
> Of course it is not very difficult to follow the code, but it would be better if a table would exist somewhere that describes the workings in a higher level language, i.e. a human language like English.
> 
> Thanks in advance for any information you have.
> 
> Jacob
> 
> P.S. Of course, the documentation I am writing will be open sourced with the same license as your documentation.