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.

ChangeLog

@@ -1,3 +1,17 @@
+2012-06-04  Tulio Magno Quites Machado Filho  <tuliom@linux.vnet.ibm.com>
+
+	[BZ #13743]
+	* sysdeps/powerpc/sys/platform/ppc.h: New file for PowerPC features.
+	* sysdeps/powerpc/Makefile (tests): Add test-gettimebase.
+	(sysdep_headers): Include sys/platform/ppc.h.
+	* sysdeps/powerpc/test-gettimebase.c: Test for
+	__ppc_get_timebase() to catch future ISA opcode/insn changes.
+	* manual/Makefile (appendices): Include platform.texi.
+	* manual/contrib.texi (Contributors): Update @node pointers.
+	* manual/maint.texi (Maintenance): Likewise.
+	(Platform): New node.
+	* manual/platform.texi: New file.  Document the new features.
+
 2012-06-04  Siddhesh Poyarekar  <siddhesh@redhat.com>
 	    Jakub Jelinek  <jakub@redhat.com>
 

NEWS

@@ -13,14 +13,14 @@ Version 2.16
   2551, 2552, 2553, 2554, 2562, 2563, 2565, 2566, 2570, 2576, 2636, 2678,
   3335, 3440, 3748, 3768, 3866, 3868, 3906, 3976, 3992, 4026, 4108, 4596,
   4822, 5077, 5461, 5805, 5993, 6471, 6486, 6578, 6649, 6730, 6770, 6794,
-  6884, 6890, 6894, 6895, 6907, 6911, 6959, 7064, 9739, 9902, 10110,
+  6884, 6890, 6894, 6895, 6907, 6911, 6959, 7064, 9739, 9902, 10110, 10135,
-  10135, 10140, 10153, 10210, 10254, 10346, 10375, 10545, 10716, 10846,
+  10140, 10153, 10210, 10254, 10346, 10375, 10545, 10716, 10846, 11174,
-  11174, 11322, 11365, 11451, 11494, 11521, 11677, 11837, 11959, 12047,
+  11322, 11365, 11451, 11494, 11521, 11677, 11837, 11959, 12047, 12097,
-  12097, 12193, 12297, 12298, 12301, 12340, 12354, 12416, 12495, 13058,
+  12193, 12297, 12298, 12301, 12340, 12354, 12416, 12495, 13058, 13223,
-  13223, 13361, 13525, 13526, 13527, 13528, 13529, 13530, 13531, 13532,
+  13361, 13525, 13526, 13527, 13528, 13529, 13530, 13531, 13532, 13533,
-  13533, 13547, 13551, 13552, 13553, 13555, 13556, 13559, 13563, 13566,
+  13547, 13551, 13552, 13553, 13555, 13556, 13559, 13563, 13566, 13576,
-  13576, 13583, 13592, 13594, 13613, 13618, 13637, 13656, 13658, 13673,
+  13583, 13592, 13594, 13613, 13618, 13637, 13656, 13658, 13673, 13691,
-  13691, 13695, 13704, 13705, 13706, 13726, 13738, 13739, 13750, 13758,
+  13695, 13704, 13705, 13706, 13726, 13738, 13739, 13743, 13750, 13758,
   13760, 13761, 13775, 13786, 13787, 13792, 13806, 13824, 13840, 13841,
   13844, 13846, 13851, 13852, 13854, 13871, 13872, 13873, 13879, 13883,
   13884, 13885, 13886, 13892, 13895, 13908, 13910, 13911, 13912, 13913,
@@ -92,7 +92,8 @@ Version 2.16
 
 * Optimized expf for x86-32 and x86-64.  Implemented by Liubov Dmitrieva.
 
-* More optimized functions for PowerPC.  Implemented by Adhemerval Zanella.
+* More optimized functions for PowerPC.  Implemented by Adhemerval Zanella
+  and Will Schmidt.
 
 * More optimized functions for SPARC.  Implemented by David S. Miller.
 
@@ -110,6 +111,11 @@ Version 2.16
   /lib/ld-linux.so.3 dynamic linker used for the base EABI.
 
 * Support for CRIS has been removed from ports.
+
+* A new class of installed header has been documented for low-level
+  platform-specific functionality.  PowerPC added the first instance with a
+  function to provide time base register access.  Contributed by Tulio
+  Magno Quites Machado Filho.
 
 Version 2.15
 

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

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{}
 

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{}
 

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

sysdeps/powerpc/Makefile

@@ -26,3 +26,8 @@ gen-as-const-headers += rtld-global-offsets.sym
 # get offset to __locale_struct.__ctype_tolower
 gen-as-const-headers += locale-defines.sym
 endif
+
+ifeq ($(subdir),misc)
+sysdep_headers += sys/platform/ppc.h
+tests += test-gettimebase
+endif

sysdeps/powerpc/sys/platform/ppc.h

@@ -0,0 +1,47 @@
+/* Facilities specific to the PowerPC architecture
+   Copyright (C) 2012 Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+
+   The GNU C Library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+
+   The GNU C Library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with the GNU C Library; if not, see
+   <http://www.gnu.org/licenses/>.  */
+
+#ifndef _SYS_PLATFORM_PPC_H
+#define _SYS_PLATFORM_PPC_H	1
+
+#include <stdint.h>
+
+/* Read the Time Base Register.   */
+static inline uint64_t
+__ppc_get_timebase (void)
+{
+#ifdef __powerpc64__
+  uint64_t __tb;
+  /* "volatile" is necessary here, because the user expects this assembly
+     isn't moved after an optimization.  */
+  __asm__ volatile ("mfspr %0, 268" : "=r" (__tb));
+  return __tb;
+#else  /* not __powerpc64__ */
+  uint32_t __tbu, __tbl, __tmp; \
+  __asm__ volatile ("0:\n\t"
+		    "mftbu %0\n\t"
+		    "mftbl %1\n\t"
+		    "mftbu %2\n\t"
+		    "cmpw %0, %2\n\t"
+		    "bne- 0b"
+		    : "=r" (__tbu), "=r" (__tbl), "=r" (__tmp));
+  return (((uint64_t) __tbu << 32) | __tbl);
+#endif  /* not __powerpc64__ */
+}
+
+#endif  /* sys/platform/ppc.h */

sysdeps/powerpc/test-gettimebase.c

@@ -0,0 +1,46 @@
+/* Check __ppc_get_timebase() for architecture changes
+   Copyright (C) 2012 Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+
+   The GNU C Library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+
+   The GNU C Library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with the GNU C Library; if not, see
+   <http://www.gnu.org/licenses/>.  */
+
+/* Test if __ppc_get_timebase() is compatible with the current processor and if
+   it's changing between reads.  A read failure might indicate a Power ISA or
+   binutils change.  */
+
+#include <inttypes.h>
+#include <stdio.h>
+
+#include <sys/platform/ppc.h>
+
+static int
+do_test (void)
+{
+  uint64_t t1, t2, t3;
+  t1 = __ppc_get_timebase ();
+  printf ("Time Base = %"PRIu64"\n", t1);
+  t2 = __ppc_get_timebase ();
+  printf ("Time Base = %"PRIu64"\n", t2);
+  t3 = __ppc_get_timebase ();
+  printf ("Time Base = %"PRIu64"\n", t3);
+  if (t1 != t2 && t1 != t3 && t2 != t3)
+    return 0;
+
+  printf ("Fail: timebase reads should always be different.");
+  return 1;
+}
+
+#define TEST_FUNCTION do_test ()
+#include "../test-skeleton.c"