This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
[PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions
- From: Tulio Magno Quites Machado Filho <tuliom at linux dot vnet dot ibm dot com>
- To: libc-alpha at sourceware dot org
- Cc: carlos at systemhalted dot org, munroesj at us dot ibm dot com, ryan dot arnold at gmail dot com, dje dot gcc at gmail dot com, meissner at linux dot vnet dot ibm dot com, drepper at gmail dot com, joseph at codesourcery dot com, roland at hack dot frob dot com, thomas at codesourcery dot com
- Date: Wed, 4 Apr 2012 17:41:49 -0300
- Subject: [PATCH 1/2] PowerPC - Add a new header for PowerPC specific functions
- References: <CADZpyiy8hOYgQOrN-Wu4LMpypDbbpRMtwC0BGa7X_nry0LGSdw@mail.gmail.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