This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions
- From: Roland McGrath <roland at hack dot frob dot com>
- To: Tulio Magno Quites Machado Filho <tuliom at linux dot vnet dot ibm dot com>
- Cc: libc-alpha at sourceware dot org
- Date: Wed, 4 Apr 2012 15:02:17 -0700 (PDT)
- Subject: Re: [PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions
- References: <CADZpyiy8hOYgQOrN-Wu4LMpypDbbpRMtwC0BGa7X_nry0LGSdw@mail.gmail.com><1333572110-32574-1-git-send-email-tuliom@linux.vnet.ibm.com>
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.