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


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.

> +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".

> +@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.

> +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>.

> +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]