+++ /dev/null
-\input texinfo
-
-@c ---------------------------------------------------------------------
-@c Prologue
-@c ---------------------------------------------------------------------
-
-@setfilename porting.info
-@settitle Porting libstdc++-v3
-@setchapternewpage odd
-
-@copying
-Copyright @copyright{} 2000, 2001, 2002 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below). A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-
-(a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
-(b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
- software. Copies published by the Free Software Foundation raise
- funds for GNU development.
-@end copying
-
-@ifinfo
-This file explains how to port libstdc++-v3 (the GNU C++ library) to
-a new target.
-
-@insertcopying
-@end ifinfo
-
-@c ---------------------------------------------------------------------
-@c Titlepage
-@c ---------------------------------------------------------------------
-
-@titlepage
-@title Porting libstdc++-v3
-@author Mark Mitchell
-@page
-@vskip 0pt plus 1filll
-@insertcopying
-@end titlepage
-
-@c ---------------------------------------------------------------------
-@c Top
-@c ---------------------------------------------------------------------
-
-@node Top
-@top Porting libstdc++-v3
-
-This document explains how to port libstdc++-v3 (the GNU C++ library) to
-a new target.
-
-In order to make the GNU C++ library (libstdc++-v3) work with a new
-target, you must edit some configuration files and provide some new
-header files. Unless this is done, libstdc++-v3 will use generic
-settings which may not be correct for your target; even if they are
-correct, they will likely be inefficient.
-
-Before you get started, make sure that you have a working C library on
-your target. The C library need not precisely comply with any
-particular standard, but should generally conform to the requirements
-imposed by the ANSI/ISO standard.
-
-In addition, you should try to verify that the C++ compiler generally
-works. It is difficult to test the C++ compiler without a working
-library, but you should at least try some minimal test cases.
-
-Here are the primary steps required to port the library:
-
-@menu
-* Operating system:: Configuring for your operating system.
-* CPU:: Configuring for your processor chip.
-* Character types:: Implementing character classification.
-* Thread safety:: Implementing atomic operations.
-* Numeric limits:: Implementing numeric limits.
-* Libtool:: Using libtool.
-* GNU Free Documentation License:: How you can copy and share this manual.
-@end menu
-
-@c ---------------------------------------------------------------------
-@c Operating system
-@c ---------------------------------------------------------------------
-
-@node Operating system
-@chapter Operating system
-
-If you are porting to a new operating system (as opposed to a new chip
-using an existing operating system), you will need to create a new
-directory in the @file{config/os} hierarchy. For example, the IRIX
-configuration files are all in @file{config/os/irix}. There is no set
-way to organize the OS configuration directory. For example,
-@file{config/os/solaris/solaris-2.6} and
-@file{config/os/solaris/solaris-2.7} are used as configuration
-directories for these two versions of Solaris. On the other hand, both
-Solaris 2.7 and Solaris 2.8 use the @file{config/os/solaris/solaris-2.7}
-directory. The important information is that there needs to be a
-directory under @file{config/os} to store the files for your operating
-system.
-
-You might have to change the @file{configure.target} file to ensure that
-your new directory is activated. Look for the switch statement that sets
-@code{os_include_dir}, and add a pattern to handle your operating system
-if the default will not suffice. The switch statement switches on only
-the OS portion of the standard target triplet; e.g., the @code{solaris2.8}
-in @code{sparc-sun-solaris2.8}. If the new directory is named after the
-OS portion of the triplet (the default), then nothing needs to be changed.
-
-The first file to create in this directory, should be called
-@file{os_defines.h}. This file contains basic macro definitions
-that are required to allow the C++ library to work with your C library.
-This file should provide macro definitions for @code{__off_t},
-@code{__off64_t}, and @code{__ssize_t}. Typically, this just looks
-like:
-
-@example
-#define __off_t off_t
-#define __off64_t off64_t
-#define __ssize_t ssize_t
-@end example
-
-@noindent
-You don't have to provide these definitions if your system library
-already defines these types -- but the only library known to provide
-these types is the GNU C Library, so you will almost certainly have to
-provide these macros. Note that this file does not have to include a
-header file that defines @code{off_t}, or the other types; you simply
-have to provide the macros.
-
-In addition, several libstdc++-v3 source files unconditionally define
-the macro @code{_POSIX_SOURCE}. On many systems, defining this macro
-causes large portions of the C library header files to be eliminated
-at preprocessing time. Therefore, you may have to @code{#undef} this
-macro, or define other macros (like @code{_LARGEFILE_SOURCE} or
-@code{__EXTENSIONS__}). You won't know what macros to define or
-undefine at this point; you'll have to try compiling the library and
-seeing what goes wrong. If you see errors about calling functions
-that have not been declared, look in your C library headers to see if
-the functions are declared there, and then figure out what macros you
-need to define. You will need to add them to the
-@code{CPLUSPLUS_CPP_SPEC} macro in the GCC configuration file for your
-target. It will not work to simply define these macros in
-@file{os_defines.h}.
-
-At this time, there is one libstdc++-v3-specific macro which may be
-defined. @code{_G_USING_THUNKS} may be defined to 0 to express that the
-port doesn't use thunks (although it is unclear that this is still
-useful since libio support isn't currently working and the g++ v3 ABI
-invalidates the assumption that some ports don't use thunks).
-
-Finally, you should bracket the entire file in an include-guard, like
-this:
-
-@example
-#ifndef _GLIBCPP_OS_DEFINES
-#define _GLIBCPP_OS_DEFINES
-...
-#endif
-@end example
-
-We recommend copying an existing @file{os_defines.h} to use as a
-starting point.
-
-@c ---------------------------------------------------------------------
-@c CPU
-@c ---------------------------------------------------------------------
-
-@node CPU
-@chapter CPU
-
-If you are porting to a new chip (as opposed to a new operating system
-running on an existing chip), you will need to create a new directory in the
-@file{config/cpu} hierarchy. Much like the @ref{Operating system} setup,
-there are no strict rules on how to organize the CPU configuration
-directory, but careful naming choices will allow the configury to find your
-setup files without explicit help.
-
-We recommend that for a target triplet @code{<CPU>-<vendor>-<OS>}, you
-name your configuration directory @file{config/cpu/<CPU>}. If you do this,
-the configury will find the directory itself. Otherwise you will need to
-edit the @file{configure.target} file and, in the switch statement that sets
-@code{cpu_include_dir}, add a pattern to handle your chip.
-
-Note that some chip families share a single configuration directory, for
-example, @code{alpha}, @code{alphaev5}, and @code{alphaev6} all use the
-@file{config/cpu/alpha} directory, and there is an entry in the
-@file{configure.target} switch statement to handle this.
-
-The @code{cpu_include_dir} sets default locations for the files controlling
-@ref{Thread safety} and @ref{Numeric limits}, if the defaults are not
-appropriate for your chip.
-
-
-@c ---------------------------------------------------------------------
-@c Character types
-@c ---------------------------------------------------------------------
-
-@node Character types
-@chapter Character types
-
-The library requires that you provide three header files to implement
-character classification, analogous to that provided by the C libraries
-@file{<ctype.h>} header. You can model these on the files provided in
-@file{config/os/generic}. However, these files will almost
-certainly need some modification.
-
-The first file to write is @file{ctype_base.h}. This file provides
-some very basic information about character classification. The libstdc++-v3
-library assumes that your C library implements @file{<ctype.h>} by using
-a table (indexed by character code) containing integers, where each of
-these integers is a bit-mask indicating whether the character is
-upper-case, lower-case, alphabetic, etc. The @file{ctype_base.h}
-file gives the type of the integer, and the values of the various bit
-masks. You will have to peer at your own @file{<ctype.h>} to figure out
-how to define the values required by this file.
-
-The @file{ctype_base.h} header file does not need include guards.
-It should contain a single @code{struct} definition called
-@code{ctype_base}. This @code{struct} should contain two type
-declarations, and one enumeration declaration, like this example, taken
-from the IRIX configuration:
-
-@example
-struct ctype_base
-@{
- typedef unsigned int mask;
- typedef int* __to_type;
-
- enum
- @{
- space = _ISspace,
- print = _ISprint,
- cntrl = _IScntrl,
- upper = _ISupper,
- lower = _ISlower,
- alpha = _ISalpha,
- digit = _ISdigit,
- punct = _ISpunct,
- xdigit = _ISxdigit,
- alnum = _ISalnum,
- graph = _ISgraph
- @};
-@};
-@end example
-
-@noindent
-The @code{mask} type is the type of the elements in the table. If your
-C library uses a table to map lower-case numbers to upper-case numbers,
-and vice versa, you should define @code{__to_type} to be the type of the
-elements in that table. If you don't mind taking a minor performance
-penalty, or if your library doesn't implement @code{toupper} and
-@code{tolower} in this way, you can pick any pointer-to-integer type,
-but you must still define the type.
-
-The enumeration should give definitions for all the values in the above
-example, using the values from your native @file{<ctype.h>}. They can
-be given symbolically (as above), or numerically, if you prefer. You do
-not have to include @file{<ctype.h>} in this header; it will always be
-included before @file{ctype_base.h} is included.
-
-The next file to write is @file{ctype_noninline.h}, which also does
-not require include guards. This file defines a few member functions
-that will be included in @file{include/bits/locale_facets.h}. The first
-function that must be written is the @code{ctype<char>::ctype}
-constructor. Here is the IRIX example:
-
-@example
-ctype<char>::ctype(const mask* __table = 0, bool __del = false,
- size_t __refs = 0)
- : _Ctype_nois<char>(__refs), _M_del(__table != 0 && __del),
- _M_toupper(NULL),
- _M_tolower(NULL),
- _M_ctable(NULL),
- _M_table(!__table
- ? (const mask*) (__libc_attr._ctype_tbl->_class + 1)
- : __table)
- @{ @}
-@end example
-
-@noindent
-There are two parts of this that you might choose to alter. The first,
-and most important, is the line involving @code{__libc_attr}. That is
-IRIX system-dependent code that gets the base of the table mapping
-character codes to attributes. You need to substitute code that obtains
-the address of this table on your system. If you want to use your
-operating system's tables to map upper-case letters to lower-case, and
-vice versa, you should initialize @code{_M_toupper} and
-@code{_M_tolower} with those tables, in similar fashion.
-
-Now, you have to write two functions to convert from upper-case to
-lower-case, and vice versa. Here are the IRIX versions:
-
-@example
-char
-ctype<char>::do_toupper(char __c) const
-@{ return _toupper(__c); @}
-
-char
-ctype<char>::do_tolower(char __c) const
-@{ return _tolower(__c); @}
-@end example
-
-@noindent
-Your C library provides equivalents to IRIX's @code{_toupper} and
-@code{_tolower}. If you initialized @code{_M_toupper} and
-@code{_M_tolower} above, then you could use those tables instead.
-
-Finally, you have to provide two utility functions that convert strings
-of characters. The versions provided here will always work -- but you
-could use specialized routines for greater performance if you have
-machinery to do that on your system:
-
-@example
-const char*
-ctype<char>::do_toupper(char* __low, const char* __high) const
-@{
- while (__low < __high)
- @{
- *__low = do_toupper(*__low);
- ++__low;
- @}
- return __high;
-@}
-
-const char*
-ctype<char>::do_tolower(char* __low, const char* __high) const
-@{
- while (__low < __high)
- @{
- *__low = do_tolower(*__low);
- ++__low;
- @}
- return __high;
-@}
-@end example
-
-You must also provide the @file{ctype_inline.h} file, which
-contains a few more functions. On most systems, you can just copy
-@file{config/os/generic/ctype_inline.h} and use it on your system.
-
-In detail, the functions provided test characters for particular
-properties; they are analogous to the functions like @code{isalpha} and
-@code{islower} provided by the C library.
-
-The first function is implemented like this on IRIX:
-
-@example
-bool
-ctype<char>::
-is(mask __m, char __c) const throw()
-@{ return (_M_table)[(unsigned char)(__c)] & __m; @}
-@end example
-
-@noindent
-The @code{_M_table} is the table passed in above, in the constructor.
-This is the table that contains the bitmasks for each character. The
-implementation here should work on all systems.
-
-The next function is:
-
-@example
-const char*
-ctype<char>::
-is(const char* __low, const char* __high, mask* __vec) const throw()
-@{
- while (__low < __high)
- *__vec++ = (_M_table)[(unsigned char)(*__low++)];
- return __high;
-@}
-@end example
-
-@noindent
-This function is similar; it copies the masks for all the characters
-from @code{__low} up until @code{__high} into the vector given by
-@code{__vec}.
-
-The last two functions again are entirely generic:
-
-@example
-const char*
-ctype<char>::
-scan_is(mask __m, const char* __low, const char* __high) const throw()
-@{
- while (__low < __high && !this->is(__m, *__low))
- ++__low;
- return __low;
-@}
-
-const char*
-ctype<char>::
-scan_not(mask __m, const char* __low, const char* __high) const throw()
-@{
- while (__low < __high && this->is(__m, *__low))
- ++__low;
- return __low;
-@}
-@end example
-
-@c ---------------------------------------------------------------------
-@c Thread safety
-@c ---------------------------------------------------------------------
-
-@node Thread safety
-@chapter Thread safety
-
-The C++ library string functionality requires a couple of atomic
-operations to provide thread-safety. If you don't take any special
-action, the library will use stub versions of these functions that are
-not thread-safe. They will work fine, unless your applications are
-multi-threaded.
-
-If you want to provide custom, safe, versions of these functions, there
-are two distinct approaches. One is to provide a version for your CPU,
-using assembly language constructs. The other is to use the
-thread-safety primitives in your operating system. In either case, you
-make a file called @file{atomicity.h}, and the variable
-@code{ATOMICITYH} must point to this file.
-
-If you are using the assembly-language approach, put this code in
-@file{config/cpu/<chip>/atomicity.h}, where chip is the name of
-your processor (@pxref{CPU}). No additional changes are necessary to
-locate the file in this case; @code{ATOMICITYH} will be set by default.
-
-If you are using the operating system thread-safety primitives approach,
-you can also put this code in the same CPU directory, in which case no more
-work is needed to locate the file. For examples of this approach,
-see the @file{atomicity.h} file for IRIX or IA64.
-
-Alternatively, if the primitives are more closely related to the OS
-than they are to the CPU, you can put the @file{atomicity.h} file in
-the @ref{Operating system} directory instead. In this case, you must
-edit @file{configure.target}, and in the switch statement that handles
-operating systems, override the @code{ATOMICITYH} variable to point to
-the appropriate @code{os_include_dir}. For examples of this approach,
-see the @file{atomicity.h} file for AIX.
-
-With those bits out of the way, you have to actually write
-@file{atomicity.h} itself. This file should be wrapped in an
-include guard named @code{_BITS_ATOMICITY_H}. It should define one
-type, and two functions.
-
-The type is @code{_Atomic_word}. Here is the version used on IRIX:
-
-@example
-typedef long _Atomic_word;
-@end example
-
-@noindent
-This type must be a signed integral type supporting atomic operations.
-If you're using the OS approach, use the same type used by your system's
-primitives. Otherwise, use the type for which your CPU provides atomic
-primitives.
-
-Then, you must provide two functions. The bodies of these functions
-must be equivalent to those provided here, but using atomic operations:
-
-@example
-static inline _Atomic_word
-__attribute__ ((__unused__))
-__exchange_and_add (_Atomic_word* __mem, int __val)
-@{
- _Atomic_word __result = *__mem;
- *__mem += __val;
- return __result;
-@}
-
-static inline void
-__attribute__ ((__unused__))
-__atomic_add (_Atomic_word* __mem, int __val)
-@{
- *__mem += __val;
-@}
-@end example
-
-@c ---------------------------------------------------------------------
-@c Numeric limits
-@c ---------------------------------------------------------------------
-
-@node Numeric limits
-@chapter Numeric limits
-
-The C++ library requires information about the fundamental data types,
-such as the minimum and maximum representable values of each type.
-You can define each of these values individually, but it is usually
-easiest just to indicate how many bits are used in each of the data
-types and let the library do the rest. For information about the
-macros to define, see the top of @file{include/bits/std_limits.h}.
-
-If you need to define any macros, you can do so in @file{os_defines.h}.
-However, if all operating systems for your CPU are likely to use the
-same values, you can provide a CPU-specific file instead so that you
-do not have to provide the same definitions for each operating system.
-To take that approach, create a new file called @file{cpu_limits.h} in
-your CPU configuration directory (@pxref{CPU}).
-
-@c ---------------------------------------------------------------------
-@c Libtool
-@c ---------------------------------------------------------------------
-
-@node Libtool
-@chapter Libtool
-
-The C++ library is compiled, archived and linked with libtool.
-Explaining the full workings of libtool is beyond the scope of this
-document, but there are a few, particular bits that are necessary for
-porting.
-
-Some parts of the libstdc++-v3 library are compiled with the libtool
-@code{--tags CXX} option (the C++ definitions for libtool). Therefore,
-@file{ltcf-cxx.sh} in the top-level directory needs to have the correct
-logic to compile and archive objects equivalent to the C version of libtool,
-@file{ltcf-c.sh}. Some libtool targets have definitions for C but not
-for C++, or C++ definitions which have not been kept up to date.
-
-The C++ run-time library contains initialization code that needs to be
-run as the library is loaded. Often, that requires linking in special
-object files when the C++ library is built as a shared library, or
-taking other system-specific actions.
-
-The libstdc++-v3 library is linked with the C version of libtool, even
-though it is a C++ library. Therefore, the C version of libtool needs to
-ensure that the run-time library initializers are run. The usual way to
-do this is to build the library using @code{gcc -shared}.
-
-If you need to change how the library is linked, look at
-@file{ltcf-c.sh} in the top-level directory. Find the switch statement
-that sets @code{archive_cmds}. Here, adjust the setting for your
-operating system.
-
-@c ---------------------------------------------------------------------
-@c GFDL
-@c ---------------------------------------------------------------------
-
-@include fdl.texi
-
-@c ---------------------------------------------------------------------
-@c Epilogue
-@c ---------------------------------------------------------------------
-
-@contents
-@bye
projects / msp430-gcc.git / blobdiff