Manual for platform-specific features and new __ppc_get_timebase inline.

[BZ #13743]
A new class of installed headers has been documented for low-level
platform-specific functionality.  PowerPC added the first instance with a
function to provide time base register access (__ppc_get_timebase).  This
is required for applications that measure time at high frequencies with
high precision that can't afford a syscall.

4 files changed, 111 insertions, 3 deletions

diff --git a/manual/Makefile b/manual/Makefile
index f02f14471c..ae0440997b 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -45,7 +45,8 @@ chapters = $(addsuffix .texi, \
 		       resource setjmp signal startup process job nss	\
 		       users sysinfo conf crypt debug)
 add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
-appendices = lang.texi header.texi install.texi maint.texi contrib.texi
+appendices = lang.texi header.texi install.texi maint.texi platform.texi \
+	     contrib.texi
 licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi
 
 -include $(objpfx)texis
diff --git a/manual/contrib.texi b/manual/contrib.texi
index 4d16f4e6ef..00e13ab315 100644
--- a/manual/contrib.texi
+++ b/manual/contrib.texi
@@ -1,4 +1,4 @@
-@node Contributors, Free Manuals, Maintenance, Top
+@node Contributors, Free Manuals, Platform, Top
 @c %MENU% Who wrote what parts of the GNU C Library
 @appendix Contributors to @theglibc{}
 
diff --git a/manual/maint.texi b/manual/maint.texi
index e1fdbdbd2c..e6fedcfa7c 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -1,4 +1,4 @@
-@node Maintenance, Contributors, Installation, Top
+@node Maintenance, Platform, Installation, Top
 @c %MENU% How to enhance and port the GNU C Library
 @appendix Library Maintenance
 
@@ -104,6 +104,85 @@ This variable is used for secondary object files needed to build
 @code{others} or @code{tests}.
 @end table
 
+@menu
+* Platform: Adding Platform-specific.             Adding platform-specific
+                                         features.
+@end menu
+
+@node Adding Platform-specific
+@appendixsubsec 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
+@theglibc{} but use other GNU tools, like GCC.
+
+The current guidelines are:
+@itemize @bullet
+@item
+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, @theglibc{} 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.
+
+@item
+If the header file provides features that are specific to an operating system,
+both GCC and @theglibc{} could provide it, but @theglibc{} is preferred
+as it already has a lot of information about the operating system.
+
+@item
+If the header file provides features that are specific to an operating system
+but used by @theglibc{}, then @theglibc{} should provide them.
+@end itemize
+
+The general solution for providing low-level features is to export them as
+follows:
+
+@itemize @bullet
+@item
+A nonstandard, low-level header file that defines macros and inline
+functions should be called @file{sys/platform/@var{name}.h}.
+
+@item
+Each header file's name should include the platform name, to avoid
+users thinking there is anything in common between different the
+header files for different platforms.  For example, a
+@file{sys/platform/@var{arch}.h} name such as
+@file{sys/platform/ppc.h} is better than @file{sys/platform.h}.
+
+@item
+A platform-specific header file provided by @theglibc{} 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 @file{sys/platform/@var{arch}.h}, keeping the same names of types,
+macros, and functions for convenience and portability.
+
+@item
+Each included symbol must have the prefix @code{__@var{arch}_}, such as
+@code{__ppc_get_timebase}.
+@end itemize
+
+
+The easiest way to provide a header file is to add it to the
+@code{sysdep_headers} variable.  For example, the combination of
+Linux-specific header files on PowerPC could be provided like this:
+
+@smallexample
+sysdep_headers += sys/platform/ppc.h
+@end smallexample
+
+Then ensure that you have added a @file{sys/platform/ppc.h}
+header file in the machine-specific directory, e.g.,
+@file{sysdeps/powerpc/sys/platform/ppc.h}.
+
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/manual/platform.texi b/manual/platform.texi
new file mode 100644
index 0000000000..02b5c554ab
--- /dev/null
+++ b/manual/platform.texi
@@ -0,0 +1,28 @@
+@node Platform, Contributors, Maintenance, Top
+@c %MENU% Describe all platform-specific facilities provided
+@appendix Platform-specific facilities
+
+@Theglibc{} can provide machine-specific functionality.
+
+@menu
+* PowerPC::           Facilities Specific to the PowerPC Architecture
+@end menu
+
+@node PowerPC
+@appendixsec PowerPC-specific Facilities
+
+Facilities specific to PowerPC that are not specific to a particular
+operating system are declared in @file{sys/platform/ppc.h}.
+
+@deftypefun {uint64_t} __ppc_get_timebase (void)
+Read the current value of the Time Base Register.
+
+The @dfn{Time Base Register} is a 64-bit register that stores a monotonically
+incremented value updated at a system-dependent frequency that may be
+different from the processor frequency.  More information is available in
+@cite{Power ISA 2.06b - Book II - Section 5.2}.
+
+@code{__ppc_get_timebase} uses the processor's time base facility directly
+without requiring assistance from the operating system, so it is very
+efficient.
+@end deftypefun