[PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions
Tulio Magno Quites Machado Filho
tuliom@linux.vnet.ibm.com
Wed Apr 4 20:42:00 GMT 2012
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
More information about the Libc-alpha
mailing list