diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/Makefile | 3 | ||||
| -rw-r--r-- | manual/contrib.texi | 2 | ||||
| -rw-r--r-- | manual/maint.texi | 81 | ||||
| -rw-r--r-- | manual/platform.texi | 28 |
4 files changed, 111 insertions, 3 deletions
diff --git a/manual/Makefile b/manual/Makefile index f02f14471c..ae0440997b 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -45,7 +45,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 $(objpfx)texis diff --git a/manual/contrib.texi b/manual/contrib.texi index 4d16f4e6ef..00e13ab315 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 e1fdbdbd2c..e6fedcfa7c 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,85 @@ 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 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{} diff --git a/manual/platform.texi b/manual/platform.texi new file mode 100644 index 0000000000..02b5c554ab --- /dev/null +++ b/manual/platform.texi @@ -0,0 +1,28 @@ +@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 |