[PATCH 01/19] RISC-V: improve .insn documentation

[Jiawei]

> First of all, the "type" form of .insn does not permit (not even
> optionally) a comma after the type, much like for ordinary insns a comma
> is not permitted between insn mnemonic and first operand. The example
> given actually properly shows that already.
>
> While there, also update the .word related text: Mapping symbols have been
> in use for quite some time.
>
> --- a/gas/doc/c-riscv.texi
> +++ b/gas/doc/c-riscv.texi
> @@ -229,23 +229,22 @@ by rv32imac.
>  @end table
>
>  @cindex INSN directives
> -@item .insn @var{type}, @var{operand} [,...,@var{operand_n}]
> +@item .insn @var{type} @var{operand} [,...,@var{operand_n}]
>  @itemx .insn @var{insn_length}, @var{value}
>  @itemx .insn @var{value}
>  This directive permits the numeric representation of an instructions
>

LGTM.

While reading the patch, I noticed one small pre-existing nit:

"an instructions" could be changed to "an instruction".

This is not introduced by this patch, though.

Best regards,

Jiawei


>  and makes the assembler insert the operands according to one of the
>  instruction formats for @samp{.insn} (@ref{RISC-V-Formats}).
>  For example, the instruction @samp{add a0, a1, a2} could be written as
> -@samp{.insn r 0x33, 0, 0, a0, a1, a2}.  But in fact, the instruction
> -formats are difficult to use for some users, so most of them are using
> -@samp{.word} to encode the instruction directly, rather than using
> -@samp{.insn}.  It is fine for now, but will be wrong when the mapping
> -symbols are supported, since @samp{.word} will not be shown as an
> -instruction, it should be shown as data.  Therefore, we also support
> -two more formats of the @samp{.insn}, the instruction @samp{add a0, 
> a1, a2}
> -could also be written as @samp{.insn 0x4, 0xc58533} or @samp{.insn 
> 0xc58533}.
> -When the @var{insn_length} is set, then assembler will check if the
> -@var{value} is a valid @var{insn_length} bytes instruction.
> +@samp{.insn r 0x33, 0, 0, a0, a1, a2}.  But in fact, the instruction 
> formats
> +are difficult to use for some users, so most of them are using 
> @samp{.word} to
> +encode the instruction directly, rather than using @samp{.insn}.  
> This goes
> +wrong with the use of mapping symbols, since @samp{.word} will not be 
> shown as
> +an instruction; it is shown as data.  Therefore, we also support two more
> +formats of @samp{.insn}.  Said instruction could also be written as
> +@samp{.insn 0x4, 0xc58533} or @samp{.insn 0xc58533}.  When the
> +@var{insn_length} form is used, the assembler will check if 
> @var{value} is a
> +valid @var{insn_length} bytes instruction.
>
>  @cindex @code{.attribute} directive, RISC-V
>  @item .attribute @var{tag}, @var{value}
>