invoke: RISC-V's -march doesn't take ISA strings

  The docs say we take ISA strings, but that's never really been the case:
at a bare minimum we've required lower case strings, but there's
generally been some subtle differences as well in things like version
handling and such.  We talked about removing the lower case requirement
in the last GNU toolchain meeting and we've always called other
differences just bugs.  We don't have profile support yet, but based on
the discussions on the RISC-V lists it looks like we're going to have
some differences there as well.

So let's just stop pretending these are ISA strings.  That's been a
headache for years now, if we're meant to just be ISA-string-like here
then we don't have to worry about all these long-tail ISA string parsing
issues.

Link: https://lists.riscv.org/g/sig-toolchains/message/486

gcc/ChangeLog

	doc/invoke.texi (RISC-V): -march doesn't take ISA strings.

---

This is now woefully under-documented, as we can't even fall back on the
"it's just an ISA string" excuse any more.  I'm happy to go document
that, but figured I'd just send this along now so we can have the
discussion.
---
 gcc/doc/invoke.texi | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
  

On Mon, Nov 7, 2022 at 8:01 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:

> The docs say we take ISA strings, but that's never really been the case:
> at a bare minimum we've required lower case strings, but there's
> generally been some subtle differences as well in things like version
> handling and such.  We talked about removing the lower case requirement
> in the last GNU toolchain meeting and we've always called other
> differences just bugs.  We don't have profile support yet, but based on
> the discussions on the RISC-V lists it looks like we're going to have
> some differences there as well.


> So let's just stop pretending these are ISA strings.  That's been a
> headache for years now, if we're meant to just be ISA-string-like here
> then we don't have to worry about all these long-tail ISA string parsing
> issues.
>

You are right, we should first properly specify the -march string,
before we talk about the implementation details of the parser.

I tried to collect all the recent change requests and undocumented
properties of the -march string and worked on a first draft specification.
As the -march flag should share a common behavior across different
compilers and tools, I've made a PR to the RISC-V toolchain-conventions
repo:
  https://github.com/riscv-non-isa/riscv-toolchain-conventions/pull/26

Do you mind if we continue the discussion there?



>
> Link: https://lists.riscv.org/g/sig-toolchains/message/486
>
> gcc/ChangeLog
>
>         doc/invoke.texi (RISC-V): -march doesn't take ISA strings.
>
> ---
>
> This is now woefully under-documented, as we can't even fall back on the
> "it's just an ISA string" excuse any more.  I'm happy to go document
> that, but figured I'd just send this along now so we can have the
> discussion.
> ---
>  gcc/doc/invoke.texi | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 94a2e20cfc1..780b0364c52 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -28617,11 +28617,11 @@ Produce code conforming to version 20191213.
>  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}
> +@item -march=@var{target-string}
>  @opindex march
> -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA strings
> must be
> -lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e},
> and
> -@samp{rv32imaf}.
> +Generate code for given target (e.g.@: @samp{rv64im}).  Target strings
> are
> +similar to ISA strings, but must be lower-case.  Examples include
> @samp{rv64i},
> +@samp{rv32g}, @samp{rv32e}, and @samp{rv32imaf}.
>
>  When @option{-march=} is not specified, use the setting from
> @option{-mcpu}.
>
> --
> 2.38.1
>
>
  

On Tue, 08 Nov 2022 05:40:10 PST (-0800), christoph.muellner@vrull.eu wrote:
> On Mon, Nov 7, 2022 at 8:01 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
>> The docs say we take ISA strings, but that's never really been the case:
>> at a bare minimum we've required lower case strings, but there's
>> generally been some subtle differences as well in things like version
>> handling and such.  We talked about removing the lower case requirement
>> in the last GNU toolchain meeting and we've always called other
>> differences just bugs.  We don't have profile support yet, but based on
>> the discussions on the RISC-V lists it looks like we're going to have
>> some differences there as well.
>
>
>> So let's just stop pretending these are ISA strings.  That's been a
>> headache for years now, if we're meant to just be ISA-string-like here
>> then we don't have to worry about all these long-tail ISA string parsing
>> issues.
>>
>
> You are right, we should first properly specify the -march string,
> before we talk about the implementation details of the parser.
>
> I tried to collect all the recent change requests and undocumented
> properties of the -march string and worked on a first draft specification.
> As the -march flag should share a common behavior across different
> compilers and tools, I've made a PR to the RISC-V toolchain-conventions
> repo:
>   https://github.com/riscv-non-isa/riscv-toolchain-conventions/pull/26
>
> Do you mind if we continue the discussion there?

IMO trying to handle this with another RISC-V spec is a waste of time: 
we've spent many years trying to follow the specs here, it's pretty 
clear they're just not meant to be read in that level of detail.  This 
sort of problem is all over the place in RISC-V land, moving to a 
different spec doesn't fix the problem.

>> Link: https://lists.riscv.org/g/sig-toolchains/message/486
>>
>> gcc/ChangeLog
>>
>>         doc/invoke.texi (RISC-V): -march doesn't take ISA strings.
>>
>> ---
>>
>> This is now woefully under-documented, as we can't even fall back on the
>> "it's just an ISA string" excuse any more.  I'm happy to go document
>> that, but figured I'd just send this along now so we can have the
>> discussion.
>> ---
>>  gcc/doc/invoke.texi | 8 ++++----
>>  1 file changed, 4 insertions(+), 4 deletions(-)
>>
>> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> index 94a2e20cfc1..780b0364c52 100644
>> --- a/gcc/doc/invoke.texi
>> +++ b/gcc/doc/invoke.texi
>> @@ -28617,11 +28617,11 @@ Produce code conforming to version 20191213.
>>  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}
>> +@item -march=@var{target-string}
>>  @opindex march
>> -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA strings
>> must be
>> -lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e},
>> and
>> -@samp{rv32imaf}.
>> +Generate code for given target (e.g.@: @samp{rv64im}).  Target strings
>> are
>> +similar to ISA strings, but must be lower-case.  Examples include
>> @samp{rv64i},
>> +@samp{rv32g}, @samp{rv32e}, and @samp{rv32imaf}.
>>
>>  When @option{-march=} is not specified, use the setting from
>> @option{-mcpu}.
>>
>> --
>> 2.38.1
>>
>>
  

On Wed, Nov 9, 2022 at 4:00 AM Palmer Dabbelt <palmer@rivosinc.com> wrote:

> On Tue, 08 Nov 2022 05:40:10 PST (-0800), christoph.muellner@vrull.eu
> wrote:
> > On Mon, Nov 7, 2022 at 8:01 PM Palmer Dabbelt <palmer@rivosinc.com>
> wrote:
> >
> >> The docs say we take ISA strings, but that's never really been the case:
> >> at a bare minimum we've required lower case strings, but there's
> >> generally been some subtle differences as well in things like version
> >> handling and such.  We talked about removing the lower case requirement
> >> in the last GNU toolchain meeting and we've always called other
> >> differences just bugs.  We don't have profile support yet, but based on
> >> the discussions on the RISC-V lists it looks like we're going to have
> >> some differences there as well.
> >
> >
> >> So let's just stop pretending these are ISA strings.  That's been a
> >> headache for years now, if we're meant to just be ISA-string-like here
> >> then we don't have to worry about all these long-tail ISA string parsing
> >> issues.
> >>
> >
> > You are right, we should first properly specify the -march string,
> > before we talk about the implementation details of the parser.
> >
> > I tried to collect all the recent change requests and undocumented
> > properties of the -march string and worked on a first draft
> specification.
> > As the -march flag should share a common behavior across different
> > compilers and tools, I've made a PR to the RISC-V toolchain-conventions
> > repo:
> >   https://github.com/riscv-non-isa/riscv-toolchain-conventions/pull/26
> >
> > Do you mind if we continue the discussion there?
>
> IMO trying to handle this with another RISC-V spec is a waste of time:
> we've spent many years trying to follow the specs here, it's pretty
> clear they're just not meant to be read in that level of detail.  This
> sort of problem is all over the place in RISC-V land, moving to a
> different spec doesn't fix the problem.
>

I created the documentation as a response of your comment in your patch
about
the flag being "woefully under-documented".
You can call my attempt to address this a "waste of time", but a more
constructive
approach would be appreciated.

The reason I created a PR over there in the riscv-toolchain-conventions
repo is,
that it is the agreed place to document the common behavior of RISC-V
compilers/tools (e.g. command line flags).
I.e. to ensure that LLVM developers can also contribute to a common
solution.

If I understand correctly, you want something between the documentation that
you wrote as part of this patch and the PR that I created.
If so, then please let me know the details you don't want to have documented
in my proposal.

Anyway, thanks for your feedback.
I'll quote/reference it in the PR so it won't get lost.


>
> >> Link: https://lists.riscv.org/g/sig-toolchains/message/486
> >>
> >> gcc/ChangeLog
> >>
> >>         doc/invoke.texi (RISC-V): -march doesn't take ISA strings.
> >>
> >> ---
> >>
> >> This is now woefully under-documented, as we can't even fall back on the
> >> "it's just an ISA string" excuse any more.  I'm happy to go document
> >> that, but figured I'd just send this along now so we can have the
> >> discussion.
> >> ---
> >>  gcc/doc/invoke.texi | 8 ++++----
> >>  1 file changed, 4 insertions(+), 4 deletions(-)
> >>
> >> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> >> index 94a2e20cfc1..780b0364c52 100644
> >> --- a/gcc/doc/invoke.texi
> >> +++ b/gcc/doc/invoke.texi
> >> @@ -28617,11 +28617,11 @@ Produce code conforming to version 20191213.
> >>  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}
> >> +@item -march=@var{target-string}
> >>  @opindex march
> >> -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA
> strings
> >> must be
> >> -lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e},
> >> and
> >> -@samp{rv32imaf}.
> >> +Generate code for given target (e.g.@: @samp{rv64im}).  Target strings
> >> are
> >> +similar to ISA strings, but must be lower-case.  Examples include
> >> @samp{rv64i},
> >> +@samp{rv32g}, @samp{rv32e}, and @samp{rv32imaf}.
> >>
> >>  When @option{-march=} is not specified, use the setting from
> >> @option{-mcpu}.
> >>
> >> --
> >> 2.38.1
> >>
> >>
>
  

On Wed, 9 Nov 2022 at 04:00, Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
> On Tue, 08 Nov 2022 05:40:10 PST (-0800), christoph.muellner@vrull.eu wrote:
> > On Mon, Nov 7, 2022 at 8:01 PM Palmer Dabbelt <palmer@rivosinc.com> wrote:
> >
> >> The docs say we take ISA strings, but that's never really been the case:
> >> at a bare minimum we've required lower case strings, but there's
> >> generally been some subtle differences as well in things like version
> >> handling and such.  We talked about removing the lower case requirement
> >> in the last GNU toolchain meeting and we've always called other
> >> differences just bugs.  We don't have profile support yet, but based on
> >> the discussions on the RISC-V lists it looks like we're going to have
> >> some differences there as well.
> >
> >
> >> So let's just stop pretending these are ISA strings.  That's been a
> >> headache for years now, if we're meant to just be ISA-string-like here
> >> then we don't have to worry about all these long-tail ISA string parsing
> >> issues.
> >>
> >
> > You are right, we should first properly specify the -march string,
> > before we talk about the implementation details of the parser.
> >
> > I tried to collect all the recent change requests and undocumented
> > properties of the -march string and worked on a first draft specification.
> > As the -march flag should share a common behavior across different
> > compilers and tools, I've made a PR to the RISC-V toolchain-conventions
> > repo:
> >   https://github.com/riscv-non-isa/riscv-toolchain-conventions/pull/26
> >
> > Do you mind if we continue the discussion there?
>
> IMO trying to handle this with another RISC-V spec is a waste of time:
> we've spent many years trying to follow the specs here, it's pretty
> clear they're just not meant to be read in that level of detail.  This
> sort of problem is all over the place in RISC-V land, moving to a
> different spec doesn't fix the problem.

Consider this repo as "hosted by RISC-V" and not as a RISC-V
specification (e.g., it doesn't go through the lifecycle and never
gets ratified/approved).  Maybe that's easier to digest.

Within RISC-V, some participants try hard to enforce a requirement for
end-to-end implementations before a spec lands.  This continually
leads to some friction between the software community within RISC-V
and those that "just need the specs done".  If you see something in a
spec going for public review (or even better: before it goes to public
review and is at the committee sign-off stage) that is underspecified,
let us know and we can request remedial action: the ABI effort in Zc
is a good example of this.

Anytime someone tries to skip these requirements, I point them to the
'bset' instruction (which—even though most people assume it—does not
implement 'a | (1 << b)'; instead it implements 'a | (1 << (b &
(XLEN-1)))').  Things like that get caught only if there are
end-to-end software implementations to allow experimentation and
review with various workloads and by a wide community.

Philipp.




> >> Link: https://lists.riscv.org/g/sig-toolchains/message/486
> >>
> >> gcc/ChangeLog
> >>
> >>         doc/invoke.texi (RISC-V): -march doesn't take ISA strings.
> >>
> >> ---
> >>
> >> This is now woefully under-documented, as we can't even fall back on the
> >> "it's just an ISA string" excuse any more.  I'm happy to go document
> >> that, but figured I'd just send this along now so we can have the
> >> discussion.
> >> ---
> >>  gcc/doc/invoke.texi | 8 ++++----
> >>  1 file changed, 4 insertions(+), 4 deletions(-)
> >>
> >> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> >> index 94a2e20cfc1..780b0364c52 100644
> >> --- a/gcc/doc/invoke.texi
> >> +++ b/gcc/doc/invoke.texi
> >> @@ -28617,11 +28617,11 @@ Produce code conforming to version 20191213.
> >>  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}
> >> +@item -march=@var{target-string}
> >>  @opindex march
> >> -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA strings
> >> must be
> >> -lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e},
> >> and
> >> -@samp{rv32imaf}.
> >> +Generate code for given target (e.g.@: @samp{rv64im}).  Target strings
> >> are
> >> +similar to ISA strings, but must be lower-case.  Examples include
> >> @samp{rv64i},
> >> +@samp{rv32g}, @samp{rv32e}, and @samp{rv32imaf}.
> >>
> >>  When @option{-march=} is not specified, use the setting from
> >> @option{-mcpu}.
> >>
> >> --
> >> 2.38.1
> >>
> >>
  

On 11/7/22 11:58, Palmer Dabbelt wrote:
> The docs say we take ISA strings, but that's never really been the case:
> at a bare minimum we've required lower case strings, but there's
> generally been some subtle differences as well in things like version
> handling and such.  We talked about removing the lower case requirement
> in the last GNU toolchain meeting and we've always called other
> differences just bugs.  We don't have profile support yet, but based on
> the discussions on the RISC-V lists it looks like we're going to have
> some differences there as well.
>
> So let's just stop pretending these are ISA strings.  That's been a
> headache for years now, if we're meant to just be ISA-string-like here
> then we don't have to worry about all these long-tail ISA string parsing
> issues.
>
> Link: https://lists.riscv.org/g/sig-toolchains/message/486
>
> gcc/ChangeLog
>
> 	doc/invoke.texi (RISC-V): -march doesn't take ISA strings.

No strong opinions, mostly because I don't have any of the history.  I'm 
happy to go along with the consensus here.

jeff
  

On Wed, 09 Nov 2022 01:52:12 PST (-0800), christoph.muellner@vrull.eu wrote:
> On Wed, Nov 9, 2022 at 4:00 AM Palmer Dabbelt <palmer@rivosinc.com> wrote:
>
>> On Tue, 08 Nov 2022 05:40:10 PST (-0800), christoph.muellner@vrull.eu
>> wrote:
>> > On Mon, Nov 7, 2022 at 8:01 PM Palmer Dabbelt <palmer@rivosinc.com>
>> wrote:
>> >
>> >> The docs say we take ISA strings, but that's never really been the case:
>> >> at a bare minimum we've required lower case strings, but there's
>> >> generally been some subtle differences as well in things like version
>> >> handling and such.  We talked about removing the lower case requirement
>> >> in the last GNU toolchain meeting and we've always called other
>> >> differences just bugs.  We don't have profile support yet, but based on
>> >> the discussions on the RISC-V lists it looks like we're going to have
>> >> some differences there as well.
>> >
>> >
>> >> So let's just stop pretending these are ISA strings.  That's been a
>> >> headache for years now, if we're meant to just be ISA-string-like here
>> >> then we don't have to worry about all these long-tail ISA string parsing
>> >> issues.
>> >>
>> >
>> > You are right, we should first properly specify the -march string,
>> > before we talk about the implementation details of the parser.
>> >
>> > I tried to collect all the recent change requests and undocumented
>> > properties of the -march string and worked on a first draft
>> specification.
>> > As the -march flag should share a common behavior across different
>> > compilers and tools, I've made a PR to the RISC-V toolchain-conventions
>> > repo:
>> >   https://github.com/riscv-non-isa/riscv-toolchain-conventions/pull/26
>> >
>> > Do you mind if we continue the discussion there?
>>
>> IMO trying to handle this with another RISC-V spec is a waste of time:
>> we've spent many years trying to follow the specs here, it's pretty
>> clear they're just not meant to be read in that level of detail.  This
>> sort of problem is all over the place in RISC-V land, moving to a
>> different spec doesn't fix the problem.
>>
>
> I created the documentation as a response of your comment in your patch
> about
> the flag being "woefully under-documented".
> You can call my attempt to address this a "waste of time", but a more
> constructive
> approach would be appreciated.

We need to document it in invoke (still .texi?  Not sure if that's 
changing along with sphinx...).  That's really been the case for quite a 
while now, we've had users complain about it.  We've just sort of been 
lazy and called it an ISA string with some small exceptions, but if 
something like this goes in then we don't have that excuse any more.

> The reason I created a PR over there in the riscv-toolchain-conventions
> repo is,
> that it is the agreed place to document the common behavior of RISC-V
> compilers/tools (e.g. command line flags).
> I.e. to ensure that LLVM developers can also contribute to a common
> solution.

That's very different than what you suggested.  What GCC does needs to 
be discussed on the GCC mailing lists and documented along with GCC.  If 
you want to document want all RISC-V compilers do that's up to you, but 
that PR describes things that neither GCC nor LLVM currently do.  We've 
been through this a bunch of times, it's the same discussion again.

> If I understand correctly, you want something between the documentation that
> you wrote as part of this patch and the PR that I created.
> If so, then please let me know the details you don't want to have documented
> in my proposal.

You can do whatever you want with your time, that's your decision.  That 
said, I still consider this a waste of time, for two reasons:

* We still need to document the GCC behavior along with GCC.  Nothing 
  from the RISC-V foundation changes that.  Even if that documentation 
  perfectly described the GCC behavior at any given time, there's all 
  sorts of versioning and licensing issues that make it unusable in 
  practice.
* We tried using the RISC-V specs as a single point of agreement, that 
  was the ISA string.  There's been years worth of issues around this, 
  we just have different definitions of some basic terms like 
  "compatible".  That's fine, every community does things their own way, 
  but moving these definitions to a different RISC-V spec doesn't change 
  anything.

So if you want to go write something in that repo then you're more than 
welcome to.  I just don't think it solves any problems -- we've got two 
standards, we can't fix that by adding a third.

> Anyway, thanks for your feedback.
> I'll quote/reference it in the PR so it won't get lost.
>
>
>>
>> >> Link: https://lists.riscv.org/g/sig-toolchains/message/486
>> >>
>> >> gcc/ChangeLog
>> >>
>> >>         doc/invoke.texi (RISC-V): -march doesn't take ISA strings.
>> >>
>> >> ---
>> >>
>> >> This is now woefully under-documented, as we can't even fall back on the
>> >> "it's just an ISA string" excuse any more.  I'm happy to go document
>> >> that, but figured I'd just send this along now so we can have the
>> >> discussion.
>> >> ---
>> >>  gcc/doc/invoke.texi | 8 ++++----
>> >>  1 file changed, 4 insertions(+), 4 deletions(-)
>> >>
>> >> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> >> index 94a2e20cfc1..780b0364c52 100644
>> >> --- a/gcc/doc/invoke.texi
>> >> +++ b/gcc/doc/invoke.texi
>> >> @@ -28617,11 +28617,11 @@ Produce code conforming to version 20191213.
>> >>  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}
>> >> +@item -march=@var{target-string}
>> >>  @opindex march
>> >> -Generate code for given RISC-V ISA (e.g.@: @samp{rv64im}).  ISA
>> strings
>> >> must be
>> >> -lower-case.  Examples include @samp{rv64i}, @samp{rv32g}, @samp{rv32e},
>> >> and
>> >> -@samp{rv32imaf}.
>> >> +Generate code for given target (e.g.@: @samp{rv64im}).  Target strings
>> >> are
>> >> +similar to ISA strings, but must be lower-case.  Examples include
>> >> @samp{rv64i},
>> >> +@samp{rv32g}, @samp{rv32e}, and @samp{rv32imaf}.
>> >>
>> >>  When @option{-march=} is not specified, use the setting from
>> >> @option{-mcpu}.
>> >>
>> >> --
>> >> 2.38.1
>> >>
>> >>
>>