+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>
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,
- 10135, 10140, 10153, 10210, 10254, 10346, 10375, 10545, 10716, 10846,
- 11174, 11322, 11365, 11451, 11494, 11521, 11677, 11837, 11959, 12047,
- 12097, 12193, 12297, 12298, 12301, 12340, 12354, 12416, 12495, 13058,
- 13223, 13361, 13525, 13526, 13527, 13528, 13529, 13530, 13531, 13532,
- 13533, 13547, 13551, 13552, 13553, 13555, 13556, 13559, 13563, 13566,
- 13576, 13583, 13592, 13594, 13613, 13618, 13637, 13656, 13658, 13673,
- 13691, 13695, 13704, 13705, 13706, 13726, 13738, 13739, 13750, 13758,
+ 6884, 6890, 6894, 6895, 6907, 6911, 6959, 7064, 9739, 9902, 10110, 10135,
+ 10140, 10153, 10210, 10254, 10346, 10375, 10545, 10716, 10846, 11174,
+ 11322, 11365, 11451, 11494, 11521, 11677, 11837, 11959, 12047, 12097,
+ 12193, 12297, 12298, 12301, 12340, 12354, 12416, 12495, 13058, 13223,
+ 13361, 13525, 13526, 13527, 13528, 13529, 13530, 13531, 13532, 13533,
+ 13547, 13551, 13552, 13553, 13555, 13556, 13559, 13563, 13566, 13576,
+ 13583, 13592, 13594, 13613, 13618, 13637, 13656, 13658, 13673, 13691,
+ 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,
* 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.
/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.
\f
Version 2.15
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
-@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{}
-@node Maintenance, Contributors, Installation, Top
+@node Maintenance, Platform, Installation, Top
@c %MENU% How to enhance and port the GNU C Library
@appendix Library Maintenance
@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{}
--- /dev/null
+@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
# 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
--- /dev/null
+/* 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 */
--- /dev/null
+/* 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"
projects / thirdparty / glibc.git / commitdiff
