This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions


On Wed, Apr 4, 2012 at 5:02 PM, Roland McGrath <roland@hack.frob.com> wrote:
> I trimmed the excessive CC. ÂWe're talking about libc changes here, so
> people who care are on the list.
>
>> +@item sysdep_headers
>> +The names of header files in this section of the library to be searched for
>> +in platform, submachine, and OS specific override directories such as
>> +@file{bits/mman.h} or @file{sys/platform/ppc.h}. ÂThese files might be
>> +found in @file{sysdeps/unix/sysv/powerpc/bits/mman.h} and
>> +@file{sysdeps/powerpc/sys/platform/ppc.h} respectively. (@pxref{Adding
>> +Platform Specific Features}).
>
> This paragraph doesn't make much sense to me. Âsysdep_headers is for
> nonstandard headers that do not exist at all in every configuration.
> bits/mman.h is not such a case.

I'd suggested this to him.  I wanted a place to introduce platform
specific features so that there wasn't a dangling menu item with no
context.  If you're fine with it, then this can just be removed.

>> +It's often necessary to provide nonstandard, platform-specific
>
> s/often/sometimes/
>
>> +features to developers. ÂThe C library is traditionally the
>> +lowest library layer, so it makes sense for it to provide these
>> +low level features. ÂHowever, including these features in the C
>
> low-level
>
>> +library may be a disadvantage if another package provides them
>> +as well as there will be two conflicting versions of them. Also,
>
> Two spaces after every sentence.
>
>> +If the header provides features that are ISA specific and have nothing to do
>> +with an operating system, then the features should be provided as GCC
>> +builtins.
>
> ISA-specific
>
> But don't use such jargon shorthand anyway. ÂSay something like "that only
> make sense on a particular machine architecture".

I thought that the term was ubiquitous and this part of the manual is
for developers... but if you feel strongly about it I don't see why it
can't be changed.

>> +@item
>> +@file{bits/} if the headers are platform and OS specific.
>
> bits/ is only for implementation details. ÂThere is never an API who
> specification involves an application using a bits/ header.
>
> This item suggests a thorough misunderstanding, so it's not really clear to
> me what you actually intend to say.

So by this do you mean that the API is always defined in
sys/platform/<foo>.h and particular OS implementation details (like
#defines) are pulled from bits/<foo.h>, but that an API itself will
never be wholely defined in bits/<foo>.h?

>> +Each is uniquely named per platform to avoid users thinking they have
>> +anything in common e.g. Â@file{sys/platform/$arch.h} or
>> +@file{sys/platform/ppc.h}, but not @file{sys/platform.h}.
>
> If you mean to use a non-literal file name, write
> @file{sys/platform/@var{arch}.h} or suchlike.
>
>> +@item
>> +The platform may create per-macro header files and include them into the
>> +master platform header e.g.
>> +@file{sys/platform/ppc-program-priority-registers.h} is included by
>> +@file{sys/platform/ppc.h}.
>
> This is an implementation detail and there is no need for it here. ÂThe API
> will always be that you use one particular named header for a particular
> interface. ÂEither it's <sys/platform/ppc-foo.h> or it's <sys/platform/ppc.h>.

This was suggested by Carlos O'Donell.  Do you have a preference, one
way or the other for how it should be?  I know we (Power) have a
number of functions that we're interested in providing, so in the
interest of keeping the number of new headers down I'm in favor of
ppc.h.

>> +A @theglibc{} provided platform header should coordinate with GCC such
>
> You can't use this macro in a construction like this. ÂThe grammar comes
> out all wrong.
>
>> +The easiest way to ship a header is to add it to the sysdep_headers
>> +variable, for example, the combination of Linux-specific headers on
>> +PowerPC could be provided like this:
>> +
>> +@smallexample
>> +--- a/sysdeps/powerpc/Makefile
>> ++++ b/sysdeps/powerpc/Makefile
>
> Never put a diff in the manual. ÂThat's just ridiculous.
>
>> +#ifndef _SYS_PLATFORM_PPC_H
>> +
>> +#define _SYS_PLATFORM_PPC_H Â1
>> +
>> +
>> +#endif Â/* sys/platform/ppc.h */
>
> We're not going to add an empty file. ÂThat's useless.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]