D.1.1 Platform-specific types, macros and functions
It’s sometimes necessary to provide nonstandard, platform-specific
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
library may be a disadvantage if another package provides them
as well as there will be two conflicting versions of them. Also,
the features won’t be available to projects that do not use
the GNU C Library but use other GNU tools, like GCC.
The current guidelines are:
- If the header file provides features that only make sense on a particular
machine architecture and have nothing to do with an operating system, then
the features should ultimately be provided as GCC built-in functions. Until
then, the GNU C Library may provide them in the header file. When the GCC built-in
functions become available, those provided in the header file should be made
conditionally available prior to the GCC version in which the built-in
function was made available.
- If the header file provides features that are specific to an operating system,
both GCC and the GNU C Library could provide it, but the GNU C Library is preferred
as it already has a lot of information about the operating system.
- If the header file provides features that are specific to an operating system
but used by the GNU C Library, then the GNU C Library should provide them.
The general solution for providing low-level features is to export them as
follows:
- A nonstandard, low-level header file that defines macros and inline
functions should be called sys/platform/name.h.
- Each header file’s name should include the platform name, to avoid
users thinking there is anything in common between the different
header files for different platforms. For example, a
sys/platform/arch.h name such as
sys/platform/ppc.h is better than sys/platform.h.
- A platform-specific header file provided by the GNU C Library should coordinate
with GCC such that compiler built-in versions of the functions and macros are
preferred if available. This means that user programs will only ever need to
include sys/platform/arch.h, keeping the same names of types,
macros, and functions for convenience and portability.
- Each included symbol must have the prefix
__arch_, such as
__ppc_get_timebase.
The easiest way to provide a header file is to add it to the
sysdep_headers variable. For example, the combination of
Linux-specific header files on PowerPC could be provided like this:
sysdep_headers += sys/platform/ppc.h
Then ensure that you have added a sys/platform/ppc.h
header file in the machine-specific directory, e.g.,
sysdeps/powerpc/sys/platform/ppc.h.