GCC 7 on ppc64le does not recognize vec_xl_be?

GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

Hi Everyone,

I have a Travis job failing on ppc64le:
https://travis-ci.org/noloader/cryptopp-pem/jobs/612654182 .

Compiling a source file with Power9 flags:

    g++ -DNDEBUG -g2 -O3 -mcpu=power9 -maltivec -c ppc_power9.cpp

That includes a header with this function:

    inline uint32x4_p VecLoadBE(const byte src[16])
    {
    #if defined(_ARCH_PWR9)
        return (uint32x4_p)vec_xl_be(0, CONST_V8_CAST(src));
    #elif (BIG_ENDIAN)
        return (uint32x4_p)VecLoad(src);
    #else
        return (uint32x4_p)VecReverse(VecLoad(src));
    #endif
}

Results in:

    ppc_simd.h: In function ‘uint32x4_p VecLoadBE(const byte*)’:
    ppc_simd.h:466:24: error: ‘vec_xl_be’ was not declared in this scope
         return (uint32x4_p)vec_xl_be(0, CONST_V8_CAST(src));

According to the GCC docs vec_xl_be is available with ISA 3.0:
https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html

Does someone know why the compile is failing?

Thanks in advance.

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

Hi Jeffrey,

On Fri, Nov 15, 2019 at 08:05:57PM -0500, Jeffrey Walton wrote:
>     g++ -DNDEBUG -g2 -O3 -mcpu=power9 -maltivec -c ppc_power9.cpp

You forgot -Wall -Wextra, or at the very least -Wall.  It probably will
help you find this problem., too.

-g2 is the default, and -maltivec is implied by -mcpu=power9.

Why do you disable assertions (-DNDEBUG)?

>     ppc_simd.h: In function ‘uint32x4_p VecLoadBE(const byte*)’:
>     ppc_simd.h:466:24: error: ‘vec_xl_be’ was not declared in this scope
>          return (uint32x4_p)vec_xl_be(0, CONST_V8_CAST(src));

You didn't #include <altivec.h> in this scope, or you have undefined
__VSX__, or undefined something else; it is impossible for us to tell.

Always enable warnings, it helps.


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 6:25 AM Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> Hi Jeffrey,
>
> On Fri, Nov 15, 2019 at 08:05:57PM -0500, Jeffrey Walton wrote:
> >     g++ -DNDEBUG -g2 -O3 -mcpu=power9 -maltivec -c ppc_power9.cpp
>
> You forgot -Wall -Wextra, or at the very least -Wall.  It probably will
> help you find this problem., too.

OK, thanks.

I have a comprehensive test script that does things like -Wall
-Wextra. It takes 4 to 6 hours to run. It is not suitable for Travis,
though.

GCC135 is Power9, but it only has GCC 4.8 and at12 compilers. The at12
compiler does not warn of anything of interest with elevated warnings.
Just the standard unknown pragmas due to some OMP code paths.

Do you know where to find a Power9 machine with GCC 7?

> -g2 is the default, and -maltivec is implied by -mcpu=power9.
>
> Why do you disable assertions (-DNDEBUG)?
>
> >     ppc_simd.h: In function ‘uint32x4_p VecLoadBE(const byte*)’:
> >     ppc_simd.h:466:24: error: ‘vec_xl_be’ was not declared in this scope
> >          return (uint32x4_p)vec_xl_be(0, CONST_V8_CAST(src));
>
> You didn't #include <altivec.h> in this scope, or you have undefined
> __VSX__, or undefined something else; it is impossible for us to tell.

Yeah, I can't get a terminal so I can't do things like g++ -dM -E on
Travis to see what is going on.

Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Sat, Nov 16, 2019 at 06:44:35AM -0500, Jeffrey Walton wrote:
> On Sat, Nov 16, 2019 at 6:25 AM Segher Boessenkool
> <segher@kernel.crashing.org> wrote:
> > On Fri, Nov 15, 2019 at 08:05:57PM -0500, Jeffrey Walton wrote:
> > >     g++ -DNDEBUG -g2 -O3 -mcpu=power9 -maltivec -c ppc_power9.cpp
> >
> > You forgot -Wall -Wextra, or at the very least -Wall.  It probably will
> > help you find this problem., too.
> 
> OK, thanks.
> 
> I have a comprehensive test script that does things like -Wall
> -Wextra. It takes 4 to 6 hours to run. It is not suitable for Travis,
> though.

You should have warnings enabled *always*.  It does not take extra time,
not measurable anyway.  The point is that the compiler will tell you
about likely errors you made, right after you made them, so it is easy
to correct then, and a huge time saver.  And if the compiler think that
something may be wrong, but it really all is perfectly fine, perhaps the
code should be written in such a way that this is more clear.


If you still think it is a compiler bug, please file a bug in bugzilla,
with a testcase that reproduces the problem, so that we can investigate
(instead of guess).


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 9:26 AM Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> On Sat, Nov 16, 2019 at 06:44:35AM -0500, Jeffrey Walton wrote:
> > On Sat, Nov 16, 2019 at 6:25 AM Segher Boessenkool
> > <segher@kernel.crashing.org> wrote:
> > > ...
> If you still think it is a compiler bug, please file a bug in bugzilla,
> with a testcase that reproduces the problem, so that we can investigate
> (instead of guess).

If you can find a test rig with Power9 and GCC 7, then I believe this
is your reproducer:

$ cat test.cxx
// g++ -g2 -O3 -mcpu=power9 -maltivec test.cxx
#include <altivec>
int main(int argc, char* argv[])
{
#if defined(_ARCH_PWR9)
    __vector unsigned char v = vec_xl_be(0, (unsigned char*)argv[0]);
#else
    int XXX[-1];
#endif
    return 0
}

It looks like Travis provides GCC 7.4; see
https://travis-ci.org/noloader/cryptopp/jobs/612762432 .

Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Xi Ruoyao]

On 2019-11-16 08:26 -0600, Segher Boessenkool wrote:
> On Sat, Nov 16, 2019 at 06:44:35AM -0500, Jeffrey Walton wrote:
> > On Sat, Nov 16, 2019 at 6:25 AM Segher Boessenkool
> > <segher@kernel.crashing.org> wrote:
> > > On Fri, Nov 15, 2019 at 08:05:57PM -0500, Jeffrey Walton wrote:
> > > >     g++ -DNDEBUG -g2 -O3 -mcpu=power9 -maltivec -c
> > > > ppc_power9.cpp
> > > 
> > > You forgot -Wall -Wextra, or at the very least -Wall.  It
> > > probably will
> > > help you find this problem., too.
> > 
> > OK, thanks.
> > 
> > I have a comprehensive test script that does things like -Wall
> > -Wextra. It takes 4 to 6 hours to run. It is not suitable for
> > Travis,
> > though.
> 
> You should have warnings enabled *always*.  It does not take extra
> time,
> not measurable anyway.  The point is that the compiler will tell you
> about likely errors you made, right after you made them, so it is
> easy
> to correct then, and a huge time saver.  And if the compiler think
> that
> something may be wrong, but it really all is perfectly fine, perhaps
> the
> code should be written in such a way that this is more clear.

Regarding this, is it worth considering to make -Wall the default?

Recently our team is training some freshmen to write programs in C/C++.
They often make some bugs (invoking UB in some way) and puzzle
themselves.  But we noticed that 90% of their bugs can be diagnosed by
simply adding -Wall.
-- 
Xi Ruoyao <xry111@mengyan1223.wang>
School of Aerospace Science and Technology, Xidian University

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

Hi again,

On Sat, Nov 16, 2019 at 09:47:12AM -0500, Jeffrey Walton wrote:
> On Sat, Nov 16, 2019 at 9:26 AM Segher Boessenkool
> <segher@kernel.crashing.org> wrote:
> If you can find a test rig with Power9 and GCC 7, then I believe this
> is your reproducer:
> 
> $ cat test.cxx
> // g++ -g2 -O3 -mcpu=power9 -maltivec test.cxx
> #include <altivec>

(I need <altivec.h> for this to work at all, not <altivec>.)

GCC 7 simply does not support vec_xl_be: this is implemented in GCC 8 and
later.  GCC 7.5 was released just two days ago, and it was the last release
of GCC 7, so this won't ever be backported there, even if we wanted to.
Sorry.


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Sat, Nov 16, 2019 at 11:23:33PM +0800, Xi Ruoyao wrote:
> On 2019-11-16 08:26 -0600, Segher Boessenkool wrote:
> > You should have warnings enabled *always*.  It does not take extra
> > time,
> > not measurable anyway.  The point is that the compiler will tell you
> > about likely errors you made, right after you made them, so it is
> > easy
> > to correct then, and a huge time saver.  And if the compiler think
> > that
> > something may be wrong, but it really all is perfectly fine, perhaps
> > the
> > code should be written in such a way that this is more clear.
> 
> Regarding this, is it worth considering to make -Wall the default?
> 
> Recently our team is training some freshmen to write programs in C/C++.
> They often make some bugs (invoking UB in some way) and puzzle
> themselves.  But we noticed that 90% of their bugs can be diagnosed by
> simply adding -Wall.

It will be very disruptive to all users who do *not* want -Wall (misguided
perhaps, but that's not the point), and to build systems (including those
that cannot be fixed, think compiling older software with a new compiler).
Not to mention the GCC testsuite itself...  Making that work should give
us some feel for how annoying changing the default is.

I agree it is a nicer default, but how do we get there without a lot of
pain?


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jonathan Wakely]

On Sat, 16 Nov 2019 at 17:41, Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> Hi again,
>
> On Sat, Nov 16, 2019 at 09:47:12AM -0500, Jeffrey Walton wrote:
> > On Sat, Nov 16, 2019 at 9:26 AM Segher Boessenkool
> > <segher@kernel.crashing.org> wrote:
> > If you can find a test rig with Power9 and GCC 7, then I believe this
> > is your reproducer:
> >
> > $ cat test.cxx
> > // g++ -g2 -O3 -mcpu=power9 -maltivec test.cxx
> > #include <altivec>
>
> (I need <altivec.h> for this to work at all, not <altivec>.)
>
> GCC 7 simply does not support vec_xl_be: this is implemented in GCC 8 and
> later.  GCC 7.5 was released just two days ago, and it was the last release
> of GCC 7, so this won't ever be backported there, even if we wanted to.
> Sorry.

I already sent the following to Jeffrey 8 hours ago (off-list, because
I could only send HTML mail at the time):

"Those are the docs for GCC trunk. That function is not listed in the
docs for GCC 7."

If you're using GCC 7 then you should consult the docs for GCC 7,
which makes the answer obvious. The function isn't recognized, because
it's not supported by the GCC version you're using.

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>  ...
> I already sent the following to Jeffrey 8 hours ago (off-list, because
> I could only send HTML mail at the time):
>
> "Those are the docs for GCC trunk. That function is not listed in the
> docs for GCC 7."

GCC tells me it supports the load by accepting -mcpu=power9 and
defining _ARCH_PWR9.

The problems with GCC seem to be a little larger then inaccurate docs.

Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Sat, Nov 16, 2019 at 04:25:18PM -0500, Jeffrey Walton wrote:
> On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> >  ...
> > I already sent the following to Jeffrey 8 hours ago (off-list, because
> > I could only send HTML mail at the time):
> >
> > "Those are the docs for GCC trunk. That function is not listed in the
> > docs for GCC 7."
> 
> GCC tells me it supports the load by accepting -mcpu=power9 and
> defining _ARCH_PWR9.

It does no such thing.  GCC does not claim it implements this, and the
ELF v2 spec says "The two optional built-in vector functions in Table
6.4 [...]", and defines no specific way to detect it either.

> The problems with GCC seem to be a little larger then inaccurate docs.

The GCC docs are perfectly accurate for this as well.

GCC 7 is older than this revision of the ELFv2 specification, and we never
backported this feature: only very important features are backported.  It
could have made 7.2, over two years ago, but it wasn't considered important
enough to backport.


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 5:19 PM Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> On Sat, Nov 16, 2019 at 04:25:18PM -0500, Jeffrey Walton wrote:
> > On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> > >  ...
> > The problems with GCC seem to be a little larger then inaccurate docs.
>
> The GCC docs are perfectly accurate for this as well.
>
> GCC 7 is older than this revision of the ELFv2 specification, and we never
> backported this feature: only very important features are backported.  It
> could have made 7.2, over two years ago, but it wasn't considered important
> enough to backport.

Then you don't understand how search works in 2019 and how users
search for information. We cannot search for the absence of
information.

Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jonathan Wakely]

On Sat, 16 Nov 2019 at 21:25, Jeffrey Walton <noloader@gmail.com> wrote:
>
> On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> >  ...
> > I already sent the following to Jeffrey 8 hours ago (off-list, because
> > I could only send HTML mail at the time):
> >
> > "Those are the docs for GCC trunk. That function is not listed in the
> > docs for GCC 7."
>
> GCC tells me it supports the load by accepting -mcpu=power9 and
> defining _ARCH_PWR9.
>
> The problems with GCC seem to be a little larger then inaccurate docs.

What? You're talking nonsense.

You said:
"According to the GCC docs vec_xl_be is available with ISA 3.0:
https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html
"

You are consulting the docs for GCC trunk and assuming they apply to
GCC 7. That's simply wrong.

The corresponding docs for GCC 7 are at:
https://gcc.gnu.org/onlinedocs/gcc-7.5.0/gcc/PowerPC-AltiVec_002fVSX-Built-in-Functions.html#PowerPC-AltiVec_002fVSX-Built-in-Functions

It doesn't mention vec_xl_be in the functions available with
-mcpu=power9. So why do you think GCC 7 might not recognise that
function? Hmm, maybe because it isn't supported by GCC 7.

The docs are accurate. The docs for GCC 7 say which functions
-mcpu=power9 enables FOR GCC 7, and that doesn't include the function
you're trying to use.

The docs for GCC trunk say which functions -mcpu-power9 enables FOR
GCC TRUNK. Not for all versions. The intro to the pages you're looking
at says "It corresponds to the compilers (GCC) version 10.0.0." so
you're simply wrong to assume it also corresponds to older versions.
It doesn't. For older versions, see the docs for those versions.

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jonathan Wakely]

On Sat, 16 Nov 2019 at 22:26, Jeffrey Walton <noloader@gmail.com> wrote:
>
> On Sat, Nov 16, 2019 at 5:19 PM Segher Boessenkool
> <segher@kernel.crashing.org> wrote:
> >
> > On Sat, Nov 16, 2019 at 04:25:18PM -0500, Jeffrey Walton wrote:
> > > On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> > > >  ...
> > > The problems with GCC seem to be a little larger then inaccurate docs.
> >
> > The GCC docs are perfectly accurate for this as well.
> >
> > GCC 7 is older than this revision of the ELFv2 specification, and we never
> > backported this feature: only very important features are backported.  It
> > could have made 7.2, over two years ago, but it wasn't considered important
> > enough to backport.
>
> Then you don't understand how search works in 2019 and how users
> search for information. We cannot search for the absence of
> information.

The information is there:
https://gcc.gnu.org/onlinedocs/gcc-7.5.0/gcc/PowerPC-AltiVec_002fVSX-Built-in-Functions.html#PowerPC-AltiVec_002fVSX-Built-in-Functions

That lists the functions enabled by -mcpu=power9 in GCC 7. Stop
reading  the wrong docs.

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 5:33 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>
> On Sat, 16 Nov 2019 at 21:25, Jeffrey Walton <noloader@gmail.com> wrote:
> >
> > On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> > >  ...
> > > I already sent the following to Jeffrey 8 hours ago (off-list, because
> > > I could only send HTML mail at the time):
> > >
> > > "Those are the docs for GCC trunk. That function is not listed in the
> > > docs for GCC 7."
> >
> > GCC tells me it supports the load by accepting -mcpu=power9 and
> > defining _ARCH_PWR9.
> >
> > The problems with GCC seem to be a little larger then inaccurate docs.
>
> What? You're talking nonsense.
>
> You said:
> "According to the GCC docs vec_xl_be is available with ISA 3.0:
> https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html
> "
>
> You are consulting the docs for GCC trunk and assuming they apply to
> GCC 7. That's simply wrong.

The docs don't list an "applies to" or "since". We asked for that
about 5 years ago.

Here is the link returned for a search of "GCC vec_xl_be". There is no
mention of GCC 10.0 or limitations on availability:
https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html

Like I said, you don't understand how search works and how users use it.

Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jonathan Wakely]

On Sat, 16 Nov 2019 at 22:40, Jeffrey Walton <noloader@gmail.com> wrote:
>
> On Sat, Nov 16, 2019 at 5:33 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> >
> > On Sat, 16 Nov 2019 at 21:25, Jeffrey Walton <noloader@gmail.com> wrote:
> > >
> > > On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> > > >  ...
> > > > I already sent the following to Jeffrey 8 hours ago (off-list, because
> > > > I could only send HTML mail at the time):
> > > >
> > > > "Those are the docs for GCC trunk. That function is not listed in the
> > > > docs for GCC 7."
> > >
> > > GCC tells me it supports the load by accepting -mcpu=power9 and
> > > defining _ARCH_PWR9.
> > >
> > > The problems with GCC seem to be a little larger then inaccurate docs.
> >
> > What? You're talking nonsense.
> >
> > You said:
> > "According to the GCC docs vec_xl_be is available with ISA 3.0:
> > https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html
> > "
> >
> > You are consulting the docs for GCC trunk and assuming they apply to
> > GCC 7. That's simply wrong.
>
> The docs don't list an "applies to" or "since". We asked for that
> about 5 years ago.

They do actually. Not on every page, but they do, as I quoted in
another email a few minutes ago. It says the docs apply to GCC 10.0.0,
so not the version you're using.

If you want to ask for improvements to the docs then file it in
bugzilla. Complaining on the mailing list doesn't achieve much.

>
> Here is the link returned for a search of "GCC vec_xl_be". There is no
> mention of GCC 10.0 or limitations on availability:
> https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html
>
> Like I said, you don't understand how search works and how users use it.
>
> Jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Sat, Nov 16, 2019 at 05:40:11PM -0500, Jeffrey Walton wrote:
> The docs don't list an "applies to" or "since". We asked for that
> about 5 years ago.

The docs have *started* with a statement like this, since at least 2.95,
twenty years ago.


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jeffrey Walton]

On Sat, Nov 16, 2019 at 5:52 PM Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> On Sat, Nov 16, 2019 at 05:40:11PM -0500, Jeffrey Walton wrote:
> > The docs don't list an "applies to" or "since". We asked for that
> > about 5 years ago.
>
> The docs have *started* with a statement like this, since at least 2.95,
> twenty years ago.

I'm sorry Segher, but I don't see it. Perhaps you can point it out for
me: https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html

jeff

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Jonathan Wakely]

On Sat, 16 Nov 2019 at 22:56, Jeffrey Walton <noloader@gmail.com> wrote:
>
> On Sat, Nov 16, 2019 at 5:52 PM Segher Boessenkool
> <segher@kernel.crashing.org> wrote:
> >
> > On Sat, Nov 16, 2019 at 05:40:11PM -0500, Jeffrey Walton wrote:
> > > The docs don't list an "applies to" or "since". We asked for that
> > > about 5 years ago.
> >
> > The docs have *started* with a statement like this, since at least 2.95,
> > twenty years ago.
>
> I'm sorry Segher, but I don't see it. Perhaps you can point it out for
> me: https://gcc.gnu.org/onlinedocs/gcc/PowerPC-AltiVec-Built-in-Functions-Available-on-ISA-3_002e0.html

https://gcc.gnu.org/onlinedocs/gcc/#Introduction

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Richard Sandiford]

Jeffrey Walton <noloader@gmail.com> writes:
> On Sat, Nov 16, 2019 at 5:19 PM Segher Boessenkool
> <segher@kernel.crashing.org> wrote:
>>
>> On Sat, Nov 16, 2019 at 04:25:18PM -0500, Jeffrey Walton wrote:
>> > On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>> > >  ...
>> > The problems with GCC seem to be a little larger then inaccurate docs.
>>
>> The GCC docs are perfectly accurate for this as well.
>>
>> GCC 7 is older than this revision of the ELFv2 specification, and we never
>> backported this feature: only very important features are backported.  It
>> could have made 7.2, over two years ago, but it wasn't considered important
>> enough to backport.
>
> Then you don't understand how search works in 2019 and how users
> search for information. We cannot search for the absence of
> information.

Yeah, I think that's a good point.  E.g.:

   https://gcc.gnu.org/onlinedocs/gcc/AArch64-Options.html#AArch64-Options

gives no indication which version it's about, or how to find the
corresponding page for older versions.  It might be obvious to GCC
developers that it's about trunk only, but I don't think it's
reasonable to expect someone nativigating directly to the page
from search results to know that.

The "Introduction" section with the version is at the bottom of
https://gcc.gnu.org/onlinedocs/gcc/, after a long table of contents.
It's not even the first sentence in the introduction.  It doesn't
seem realistic to expect people to have read it.

It would be great if we could have a banner at the top of the generated
docs saying which version they're for and providing corresponding links
to older versions.  But that's obviously much easier said than done. :-)

Thanks,
Richard

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Mon, Nov 18, 2019 at 06:29:28PM +0000, Richard Sandiford wrote:
> Yeah, I think that's a good point.  E.g.:
> 
>    https://gcc.gnu.org/onlinedocs/gcc/AArch64-Options.html#AArch64-Options
> 
> gives no indication which version it's about,

Yes.  Although it is one click away ("contents", needs some scrolling as
well, alas).

> or how to find the corresponding page for older versions.

This is exactly the same as with a physical book, and with any other
documentation.  I would hope people who use GCC would have learned how
to use documentation.

> It might be obvious to GCC
> developers that it's about trunk only, but I don't think it's
> reasonable to expect someone nativigating directly to the page
> from search results to know that.

Yes, it would be nice if it said the GCC version number in the
navigation bar.

> The "Introduction" section with the version is at the bottom of
> https://gcc.gnu.org/onlinedocs/gcc/, after a long table of contents.
> It's not even the first sentence in the introduction.

It is the second.  The first line says what this manual is:

  This manual documents how to use the GNU compilers, as well as their
  features and incompatibilities, and how to report bugs.  It corresponds
  to the compilers (GCC) version 10.0.0.

(That identification looks a bit funny as well btw).

> It would be great if we could have a banner at the top of the generated
> docs saying which version they're for and providing corresponding links
> to older versions.  But that's obviously much easier said than done. :-)

Links to older versions is hard to do, and will take up much too much
screen real estate anyway.  But maybe we could have a link to
  https://gcc.gnu.org/onlinedocs/
somewhere?


Segher

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Martin Sebor]

On 11/18/19 11:29 AM, Richard Sandiford wrote:
> Jeffrey Walton <noloader@gmail.com> writes:
>> On Sat, Nov 16, 2019 at 5:19 PM Segher Boessenkool
>> <segher@kernel.crashing.org> wrote:
>>>
>>> On Sat, Nov 16, 2019 at 04:25:18PM -0500, Jeffrey Walton wrote:
>>>> On Sat, Nov 16, 2019 at 1:26 PM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>>>>>   ...
>>>> The problems with GCC seem to be a little larger then inaccurate docs.
>>>
>>> The GCC docs are perfectly accurate for this as well.
>>>
>>> GCC 7 is older than this revision of the ELFv2 specification, and we never
>>> backported this feature: only very important features are backported.  It
>>> could have made 7.2, over two years ago, but it wasn't considered important
>>> enough to backport.
>>
>> Then you don't understand how search works in 2019 and how users
>> search for information. We cannot search for the absence of
>> information.
> 
> Yeah, I think that's a good point.  E.g.:
> 
>     https://gcc.gnu.org/onlinedocs/gcc/AArch64-Options.html#AArch64-Options
> 
> gives no indication which version it's about,

In my experience, it's common to refer to the latest manual instead
of the version being discussed.   It is the top hit when searching
for "gcc options:"
   https://www.google.com/search?q=gcc+options

As new GCC versions come out, references to changing content become
out of date.

Including the next major version in the GCC link would keep this
from happening:
https://gcc.gnu.org/onlinedocs/gcc-<next-major-version>.1.0/gcc

If this can't be done, mentioning the major version more prominently,
such as both in the title of every HTML page (so that it's displayed
in the browser's frame) and at the top of the index.html page (i.e.,
here https://gcc.gnu.org/onlinedocs/gcc/index.html) would help (but
not solve all the problems).

Martin

> or how to find the
> corresponding page for older versions.  It might be obvious to GCC
> developers that it's about trunk only, but I don't think it's
> reasonable to expect someone nativigating directly to the page
> from search results to know that.
> 
> The "Introduction" section with the version is at the bottom of
> https://gcc.gnu.org/onlinedocs/gcc/, after a long table of contents.
> It's not even the first sentence in the introduction.  It doesn't
> seem realistic to expect people to have read it.
> 
> It would be great if we could have a banner at the top of the generated
> docs saying which version they're for and providing corresponding links
> to older versions.  But that's obviously much easier said than done. :-)
> 
> Thanks,
> Richard
> 

Re: GCC 7 on ppc64le does not recognize vec_xl_be?

[Segher Boessenkool]

On Mon, Nov 18, 2019 at 01:05:18PM -0700, Martin Sebor wrote:
> In my experience, it's common to refer to the latest manual instead
> of the version being discussed.   It is the top hit when searching
> for "gcc options:"
>   https://www.google.com/search?q=gcc+options

yes, and "gcc manual" points at trunk, 7.2, 4.9.4, the pdf for trunk,
and 4.7.4, in that order.

"gcc incomplete enum types" points at 8.2, not trunk, as first hit; and
there are no other gcc.gnu.org hit on the first page.

> As new GCC versions come out, references to changing content become
> out of date.
> 
> Including the next major version in the GCC link would keep this
> from happening:
> https://gcc.gnu.org/onlinedocs/gcc-<next-major-version>.1.0/gcc

But this is not the documentation for the next version.  Time travel is
not possible.  The contents will be updated, but even the links
themselves are not necessarily stable before the release.

This is not documentation of GCC 10.1; it is documentation for the current
development version.  It is a work in progress.


Segher