[PATCH] PowerPC - Add a faster way to read the Time Base register

["Tulio Magno Quites Machado Filho" <tuliom at linux dot vnet dot ibm dot com>]

Add function __ppc_get_timebase() to directly read the Time Base register.
This is required for applications that measure time at high frequencies
with high precision that can't afford a syscall.

2012-05-11 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.

---

In this version I applied all the comments from Roland and Ryan.
The most important, IMO, is the suggestion to remove the typedef
__ppc_timebase. It's only using uint64_t now.

Roland,

I modified the menu entry in manual/maint.texi, but it isn't equal to
what you suggested. Is that OK?

---
 manual/Makefile                    |    3 +-
 manual/contrib.texi                |    2 +-
 manual/maint.texi                  |   82 +++++++++++++++++++++++++++++++++++-
 manual/platform.texi               |   32 ++++++++++++++
 sysdeps/powerpc/Makefile           |    5 ++
 sysdeps/powerpc/sys/platform/ppc.h |   50 ++++++++++++++++++++++
 sysdeps/powerpc/test-gettimebase.c |   47 ++++++++++++++++++++
 7 files changed, 218 insertions(+), 3 deletions(-)
 create mode 100644 manual/platform.texi
 create mode 100644 sysdeps/powerpc/sys/platform/ppc.h
 create mode 100644 sysdeps/powerpc/test-gettimebase.c

diff --git a/manual/Makefile b/manual/Makefile
index 29e36c2..1803628 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -49,7 +49,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 texis
diff --git a/manual/contrib.texi b/manual/contrib.texi
index ed10656..8de97be 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 e1fdbdb..b70caf3 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,86 @@ 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 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.  When the GCC built-in
+functions become available, those provided in the header should be made
+conditionally available prior to the GCC version in which the built-in
+function was made available.
+
+@item
+If the header 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 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 headers 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 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 0000000..ae8ff0f
--- /dev/null
+++ b/manual/platform.texi
@@ -0,0 +1,32 @@
+@node Platform, Contributors, Maintenance, Top
+@c %MENU% Describe all platform-specific facilities provided
+@appendix Summary of platform-specific facilities
+
+@Theglibc{} can provide machine-specific functionality.
+@ref{Adding Platform-specific} describes the process to include
+these facilities in @theglibc{} and whether they should be included in
+GCC as well.
+
+@menu
+* PowerPC::           Summary of 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 in 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
diff --git a/sysdeps/powerpc/Makefile b/sysdeps/powerpc/Makefile
index 23a9a16..79dd6fa 100644
--- a/sysdeps/powerpc/Makefile
+++ b/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
diff --git a/sysdeps/powerpc/sys/platform/ppc.h b/sysdeps/powerpc/sys/platform/ppc.h
new file mode 100644
index 0000000..729db48
--- /dev/null
+++ b/sysdeps/powerpc/sys/platform/ppc.h
@@ -0,0 +1,50 @@
+/* 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 */
diff --git a/sysdeps/powerpc/test-gettimebase.c b/sysdeps/powerpc/test-gettimebase.c
new file mode 100644
index 0000000..9951c3c
--- /dev/null
+++ b/sysdeps/powerpc/test-gettimebase.c
@@ -0,0 +1,47 @@
+/* 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.
+   In case of a read failure it may indicate a future Power ISA or a 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"
-- 
1.7.7.6