[v2] doc: RISC-V: Document the `-misa-spec=' option

  We have recently updated the default for the `-misa-spec=' option, yet 
we still have not documented it nor its `--with-isa-spec=' counterpart 
in the GCC manuals.  Fix that.

	gcc/
	* doc/install.texi (Configuration): Document `--with-isa-spec=' 
	RISC-V option.
	* doc/invoke.texi (Option Summary): List `-misa-spec=' RISC-V
	option.
	(RISC-V Options): Document it.
---
> Thanks.  I have a version of this floating around somewhere.  I probably forgot
> to post it and it's generally inferior to yours, so this LGTM.

 Thank you for your review.

> The only thing I'd point out is that this specifically controls the version of
> the Unprivileged (formally called user) specification, as there are many RISC-V
> specifications and it can be a bit ambiguous what folks mean when they just say
> "specification".  Not sure exactly what the right wording is there, maybe
> "version of the RISC-V Unprivileged (formerly user-level) ISA specification"?

 Good point.  I have updated the text to your suggested wording, which is 
also what I would use if I were to propose it (modulo capitalisation).  I 
will commit the change as included here shortly then unless I hear an
objection.

  Maciej

Changes from v1:

- Clarify it is the Unprivileged (formerly User-Level) ISA specification 
  the options concerned refer to.

- Fix a typo `-misa-spec' vs `-misa-spec=' in ChangeLog.
---
 gcc/doc/install.texi |   14 ++++++++++++++
 gcc/doc/invoke.texi  |   17 +++++++++++++++++
 2 files changed, 31 insertions(+)

gcc-riscv-misa-doc.diff
  

Thanks, LGTM :)

On Sat, Feb 5, 2022 at 7:56 AM Maciej W. Rozycki <macro@embecosm.com> wrote:
>
> We have recently updated the default for the `-misa-spec=' option, yet
> we still have not documented it nor its `--with-isa-spec=' counterpart
> in the GCC manuals.  Fix that.
>
>         gcc/
>         * doc/install.texi (Configuration): Document `--with-isa-spec='
>         RISC-V option.
>         * doc/invoke.texi (Option Summary): List `-misa-spec=' RISC-V
>         option.
>         (RISC-V Options): Document it.
> ---
> > Thanks.  I have a version of this floating around somewhere.  I probably forgot
> > to post it and it's generally inferior to yours, so this LGTM.
>
>  Thank you for your review.
>
> > The only thing I'd point out is that this specifically controls the version of
> > the Unprivileged (formally called user) specification, as there are many RISC-V
> > specifications and it can be a bit ambiguous what folks mean when they just say
> > "specification".  Not sure exactly what the right wording is there, maybe
> > "version of the RISC-V Unprivileged (formerly user-level) ISA specification"?
>
>  Good point.  I have updated the text to your suggested wording, which is
> also what I would use if I were to propose it (modulo capitalisation).  I
> will commit the change as included here shortly then unless I hear an
> objection.
>
>   Maciej
>
> Changes from v1:
>
> - Clarify it is the Unprivileged (formerly User-Level) ISA specification
>   the options concerned refer to.
>
> - Fix a typo `-misa-spec' vs `-misa-spec=' in ChangeLog.
> ---
>  gcc/doc/install.texi |   14 ++++++++++++++
>  gcc/doc/invoke.texi  |   17 +++++++++++++++++
>  2 files changed, 31 insertions(+)
>
> gcc-riscv-misa-doc.diff
> Index: gcc/gcc/doc/install.texi
> ===================================================================
> --- gcc.orig/gcc/doc/install.texi
> +++ gcc/gcc/doc/install.texi
> @@ -1599,6 +1599,20 @@ On certain targets this option sets the
>  size as a power of two in bytes.  On AArch64 @var{size} is required to be either
>  12 (4KB) or 16 (64KB).
>
> +@item --with-isa-spec=@var{ISA-spec-string}
> +On RISC-V targets specify the default version of the RISC-V Unprivileged
> +(formerly User-Level) ISA specification to produce code conforming to.
> +The possibilities for @var{ISA-spec-string} are:
> +@table @code
> +@item 2.2
> +Produce code conforming to version 2.2.
> +@item 20190608
> +Produce code conforming to version 20190608.
> +@item 20191213
> +Produce code conforming to version 20191213.
> +@end table
> +In the absence of this configuration option the default version is 20191213.
> +
>  @item --enable-__cxa_atexit
>  Define if you want to use __cxa_atexit, rather than atexit, to
>  register C++ destructors for local statics and global objects.
> Index: gcc/gcc/doc/invoke.texi
> ===================================================================
> --- gcc.orig/gcc/doc/invoke.texi
> +++ gcc/gcc/doc/invoke.texi
> @@ -1184,6 +1184,7 @@ See RS/6000 and PowerPC Options.
>  -mabi=@var{ABI-string} @gol
>  -mfdiv  -mno-fdiv @gol
>  -mdiv  -mno-div @gol
> +-misa-spec=@var{ISA-spec-string} @gol
>  -march=@var{ISA-string} @gol
>  -mtune=@var{processor-string} @gol
>  -mpreferred-stack-boundary=@var{num} @gol
> @@ -27632,6 +27633,22 @@ Do or don't use hardware instructions fo
>  M extension.  The default is to use them if the specified architecture has
>  these instructions.
>
> +@item -misa-spec=@var{ISA-spec-string}
> +@opindex misa-spec
> +Specify the version of the RISC-V Unprivileged (formerly User-Level)
> +ISA specification to produce code conforming to.  The possibilities
> +for @var{ISA-spec-string} are:
> +@table @code
> +@item 2.2
> +Produce code conforming to version 2.2.
> +@item 20190608
> +Produce code conforming to version 20190608.
> +@item 20191213
> +Produce code conforming to version 20191213.
> +@end table
> +The default is @option{-misa-spec=20191213} unless GCC has been configured
> +with @option{--with-isa-spec=} specifying a different default version.
> +
>  @item -march=@var{ISA-string}
>  @opindex march
>  Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA strings must be
  

On Sat, 05 Feb 2022 00:14:26 PST (-0800), gcc-patches@gcc.gnu.org wrote:
> Thanks, LGTM :)
>
> On Sat, Feb 5, 2022 at 7:56 AM Maciej W. Rozycki <macro@embecosm.com> wrote:
>>
>> We have recently updated the default for the `-misa-spec=' option, yet
>> we still have not documented it nor its `--with-isa-spec=' counterpart
>> in the GCC manuals.  Fix that.
>>
>>         gcc/
>>         * doc/install.texi (Configuration): Document `--with-isa-spec='
>>         RISC-V option.
>>         * doc/invoke.texi (Option Summary): List `-misa-spec=' RISC-V
>>         option.
>>         (RISC-V Options): Document it.
>> ---
>> > Thanks.  I have a version of this floating around somewhere.  I probably forgot
>> > to post it and it's generally inferior to yours, so this LGTM.
>>
>>  Thank you for your review.
>>
>> > The only thing I'd point out is that this specifically controls the version of
>> > the Unprivileged (formally called user) specification, as there are many RISC-V
>> > specifications and it can be a bit ambiguous what folks mean when they just say
>> > "specification".  Not sure exactly what the right wording is there, maybe
>> > "version of the RISC-V Unprivileged (formerly user-level) ISA specification"?
>>
>>  Good point.  I have updated the text to your suggested wording, which is
>> also what I would use if I were to propose it (modulo capitalisation).  I
>> will commit the change as included here shortly then unless I hear an
>> objection.

I wasn't sure about the capitalization either, but that's how it is on 
the website.  It's in a regular-looking sentence, not a title where I'd 
expect the extra capital, so I guess the whole spec name is a proper 
noun?

I don't really care either way, just chiming in as I don't see this on 
trunk.  The original message sounded to me like you intended on 
committing it, but just in case I misunderstood and you're waiting for 
me

Reviewed-by: Palmer Dabbelt <palmer@rivosinc.com>
Acked-by: Palmer Dabbelt <palmer@rivosinc.com>

Thanks!

>>
>>   Maciej
>>
>> Changes from v1:
>>
>> - Clarify it is the Unprivileged (formerly User-Level) ISA specification
>>   the options concerned refer to.
>>
>> - Fix a typo `-misa-spec' vs `-misa-spec=' in ChangeLog.
>> ---
>>  gcc/doc/install.texi |   14 ++++++++++++++
>>  gcc/doc/invoke.texi  |   17 +++++++++++++++++
>>  2 files changed, 31 insertions(+)
>>
>> gcc-riscv-misa-doc.diff
>> Index: gcc/gcc/doc/install.texi
>> ===================================================================
>> --- gcc.orig/gcc/doc/install.texi
>> +++ gcc/gcc/doc/install.texi
>> @@ -1599,6 +1599,20 @@ On certain targets this option sets the
>>  size as a power of two in bytes.  On AArch64 @var{size} is required to be either
>>  12 (4KB) or 16 (64KB).
>>
>> +@item --with-isa-spec=@var{ISA-spec-string}
>> +On RISC-V targets specify the default version of the RISC-V Unprivileged
>> +(formerly User-Level) ISA specification to produce code conforming to.
>> +The possibilities for @var{ISA-spec-string} are:
>> +@table @code
>> +@item 2.2
>> +Produce code conforming to version 2.2.
>> +@item 20190608
>> +Produce code conforming to version 20190608.
>> +@item 20191213
>> +Produce code conforming to version 20191213.
>> +@end table
>> +In the absence of this configuration option the default version is 20191213.
>> +
>>  @item --enable-__cxa_atexit
>>  Define if you want to use __cxa_atexit, rather than atexit, to
>>  register C++ destructors for local statics and global objects.
>> Index: gcc/gcc/doc/invoke.texi
>> ===================================================================
>> --- gcc.orig/gcc/doc/invoke.texi
>> +++ gcc/gcc/doc/invoke.texi
>> @@ -1184,6 +1184,7 @@ See RS/6000 and PowerPC Options.
>>  -mabi=@var{ABI-string} @gol
>>  -mfdiv  -mno-fdiv @gol
>>  -mdiv  -mno-div @gol
>> +-misa-spec=@var{ISA-spec-string} @gol
>>  -march=@var{ISA-string} @gol
>>  -mtune=@var{processor-string} @gol
>>  -mpreferred-stack-boundary=@var{num} @gol
>> @@ -27632,6 +27633,22 @@ Do or don't use hardware instructions fo
>>  M extension.  The default is to use them if the specified architecture has
>>  these instructions.
>>
>> +@item -misa-spec=@var{ISA-spec-string}
>> +@opindex misa-spec
>> +Specify the version of the RISC-V Unprivileged (formerly User-Level)
>> +ISA specification to produce code conforming to.  The possibilities
>> +for @var{ISA-spec-string} are:
>> +@table @code
>> +@item 2.2
>> +Produce code conforming to version 2.2.
>> +@item 20190608
>> +Produce code conforming to version 20190608.
>> +@item 20191213
>> +Produce code conforming to version 20191213.
>> +@end table
>> +The default is @option{-misa-spec=20191213} unless GCC has been configured
>> +with @option{--with-isa-spec=} specifying a different default version.
>> +
>>  @item -march=@var{ISA-string}
>>  @opindex march
>>  Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA strings must be
  

On Mon, 7 Feb 2022, Palmer Dabbelt wrote:

> > >  Good point.  I have updated the text to your suggested wording, which is
> > > also what I would use if I were to propose it (modulo capitalisation).  I
> > > will commit the change as included here shortly then unless I hear an
> > > objection.
> 
> I wasn't sure about the capitalization either, but that's how it is on the
> website.  It's in a regular-looking sentence, not a title where I'd expect the
> extra capital, so I guess the whole spec name is a proper noun?

 That has been my understanding as well.

> I don't really care either way, just chiming in as I don't see this on trunk.
> The original message sounded to me like you intended on committing it, but
> just in case I misunderstood and you're waiting for me

 I wasn't waiting for you to ack, I just gave people at least one full 
working day to chime in, as not everyone works 24/7.

> Reviewed-by: Palmer Dabbelt <palmer@rivosinc.com>
> Acked-by: Palmer Dabbelt <palmer@rivosinc.com>

 I think we're not using such tags (maybe we should), so I haven't added 
them to the commit message at this time.

 I have committed this change now.  Thank you and Kito for your reviews.

  Maciej