[PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions

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

Include sys/platform/ppc.h for PowerPC specific and non-standard functions.

2012-03-26 Tulio Magno Quites Machado Filho <tuliom@linux.vnet.ibm.com>

	[BZ #13743]
	* sysdeps/powerpc/Makefile (sysdep_headers): Include
	sys/platform/ppc.h.
	* sysdeps/powerpc/sys/platform/ppc.h: New file.
	* manual/maint.texi: Document how to include platform specific
	headers.
---
 manual/maint.texi                  |  119 ++++++++++++++++++++++++++++++++++++
 sysdeps/powerpc/Makefile           |    2 +
 sysdeps/powerpc/sys/platform/ppc.h |   23 +++++++
 3 files changed, 144 insertions(+), 0 deletions(-)
 create mode 100644 sysdeps/powerpc/sys/platform/ppc.h

diff --git a/manual/maint.texi b/manual/maint.texi
index e1fdbdb..4a8fede 100644
--- a/manual/maint.texi
+++ b/manual/maint.texi
@@ -43,6 +43,14 @@ This variable @strong{must} be defined.
 The names of the header files in this section of the library,
 such as @file{stdio.h}.
 
+@item sysdep_headers
+The names of header files in this section of the library to be searched for
+in platform, submachine, and OS specific override directories such as
+@file{bits/mman.h} or @file{sys/platform/ppc.h}.  These files might be
+found in @file{sysdeps/unix/sysv/powerpc/bits/mman.h} and
+@file{sysdeps/powerpc/sys/platform/ppc.h} respectively. (@pxref{Adding
+Platform Specific Features}).
+
 @item routines
 @itemx aux
 The names of the modules (source files) in this section of the library.
@@ -104,6 +112,117 @@ This variable is used for secondary object files needed to build
 @code{others} or @code{tests}.
 @end table
 
+@menu
+* Adding Platform Specific Features::    Adding platform specific features.
+@end menu
+
+@node Adding Platform Specific Features
+@appendixsubsec Platform specific types, macros and functions
+
+It's often 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 are ISA specific and have nothing to do
+with an operating system, then the features should be provided as GCC
+builtins.
+
+@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
+Non-standard low-level headers that define macros and static inline
+functions go in:
+
+@itemize @bullet
+@item
+@file{sys/platform/} if the headers are platform specific but not OS specific.
+
+@item
+@file{bits/} if the headers are platform and OS specific.
+@end itemize
+
+@item
+Each is uniquely named per platform to avoid users thinking they have
+anything in common e.g.  @file{sys/platform/$arch.h} or
+@file{sys/platform/ppc.h}, but not @file{sys/platform.h}.
+
+@item
+The platform may create per-macro header files and include them into the
+master platform header e.g.
+@file{sys/platform/ppc-program-priority-registers.h} is included by
+@file{sys/platform/ppc.h}.
+
+@item
+A @theglibc{} provided platform header should coordinate with GCC such
+that compiler built-in versions of the functions and macros are
+preferred if available.  This allows user programs to need only ever
+include @file{sys/platform/$arch.h}, keeping the same name of types,
+macros, and functions for convenience and portability.
+
+@item
+Each included symbol must have the prefix @file{__$arch_} e.g.
+@file{__ppc_get_timebase}.
+
+@item
+The platform specific header shall pick up the OS specific header by
+performing a @file{#include <bits/$arch.h>}, e.g.,
+@file{#include <bits/ppc.h>}.
+
+@end itemize
+
+
+The easiest way to ship a header is to add it to the sysdep_headers
+variable, for example, the combination of Linux-specific headers on
+PowerPC could be provided like this:
+
+@smallexample
+--- a/sysdeps/powerpc/Makefile
++++ b/sysdeps/powerpc/Makefile
+@@ -26,3 +32,5 @@ gen-as-const-headers += rtld-global-offsets.sym
+ # get offset to __locale_struct.__ctype_tolower
+ gen-as-const-headers += locale-defines.sym
+ endif
++
++sysdeps_header += sys/platform/ppc.h
+
+--- a/sysdeps/unix/sysv/linux/powerpc/Makefile
++++ b/sysdeps/unix/sysv/linux/powerpc/Makefile
+@@ -15,3 +15,5 @@ endif
+ ifeq ($(subdir),elf)
+ sysdep_routines += dl-vdso
+ endif
++
++sysdep_headers += bits/ppc.h
+@end smallexample
+
+Then ensure that you have checked in a @file{sys/platform/ppc.h}
+header underneath your target platform sysdeps directory e.g.,
+@file{sysdeps/powerpc/sys/platform/ppc.h} and a @file{bits/ppc.h}
+underneath your target OS specific sysdeps directory e.g.,
+@file{sysdeps/unix/sysv/linux/powerpc/bits/ppc.h}.
+
+
 @node Porting
 @appendixsec Porting @theglibc{}
 
diff --git a/sysdeps/powerpc/Makefile b/sysdeps/powerpc/Makefile
index 23a9a16..2112f10 100644
--- a/sysdeps/powerpc/Makefile
+++ b/sysdeps/powerpc/Makefile
@@ -26,3 +26,5 @@ gen-as-const-headers += rtld-global-offsets.sym
 # get offset to __locale_struct.__ctype_tolower
 gen-as-const-headers += locale-defines.sym
 endif
+
+sysdep_headers += sys/platform/ppc.h
diff --git a/sysdeps/powerpc/sys/platform/ppc.h b/sysdeps/powerpc/sys/platform/ppc.h
new file mode 100644
index 0000000..b4bf7c8
--- /dev/null
+++ b/sysdeps/powerpc/sys/platform/ppc.h
@@ -0,0 +1,23 @@
+/* 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
+
+
+#endif  /* sys/platform/ppc.h */
-- 
1.7.4.4