l4/pkg/libstdc++-v3/contrib/libstdc++-v3-4.3.3/doc/html/manual/internals.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Porting to New Hardware or Operating Systems</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      internals&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="next" href="abi.html" title="ABI Policy and Guidelines" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Porting to New Hardware or Operating Systems</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><th width="60%" align="center">Appendix B. Porting and Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.internals"></a>Porting to New Hardware or Operating Systems</h2></div></div></div><p>
   4 </p><p>This document explains how to port libstdc++ (the GNU C++ library) to
   5 a new target.
   6 </p><p>In order to make the GNU C++ library (libstdc++) work with a new
   7 target, you must edit some configuration files and provide some new
   8 header files.  Unless this is done, libstdc++ will use generic
   9 settings which may not be correct for your target; even if they are
  10 correct, they will likely be inefficient.
  11    </p><p>Before you get started, make sure that you have a working C library on
  12 your target.  The C library need not precisely comply with any
  13 particular standard, but should generally conform to the requirements
  14 imposed by the ANSI/ISO standard.
  15    </p><p>In addition, you should try to verify that the C++ compiler generally
  16 works.  It is difficult to test the C++ compiler without a working
  17 library, but you should at least try some minimal test cases.
  18    </p><p>(Note that what we think of as a "target," the library refers to as
  19 a "host."  The comment at the top of <code class="code">configure.ac</code> explains why.)
  20    </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.os"></a>Operating System</h3></div></div></div><p>If you are porting to a new operating system (as opposed to a new chip
  21 using an existing operating system), you will need to create a new
  22 directory in the <code class="code">config/os</code> hierarchy.  For example, the IRIX
  23 configuration files are all in <code class="code">config/os/irix</code>.  There is no set
  24 way to organize the OS configuration directory.  For example,
  25 <code class="code">config/os/solaris/solaris-2.6</code> and
  26 <code class="code">config/os/solaris/solaris-2.7</code> are used as configuration
  27 directories for these two versions of Solaris.  On the other hand, both
  28 Solaris 2.7 and Solaris 2.8 use the <code class="code">config/os/solaris/solaris-2.7</code>
  29 directory.  The important information is that there needs to be a
  30 directory under <code class="code">config/os</code> to store the files for your operating
  31 system.
  32 </p><p>You might have to change the <code class="code">configure.host</code> file to ensure that
  33 your new directory is activated.  Look for the switch statement that sets
  34 <code class="code">os_include_dir</code>, and add a pattern to handle your operating system
  35 if the default will not suffice.  The switch statement switches on only
  36 the OS portion of the standard target triplet; e.g., the <code class="code">solaris2.8</code>
  37 in <code class="code">sparc-sun-solaris2.8</code>.  If the new directory is named after the
  38 OS portion of the triplet (the default), then nothing needs to be changed.
  39    </p><p>The first file to create in this directory, should be called
  40 <code class="code">os_defines.h</code>.  This file contains basic macro definitions
  41 that are required to allow the C++ library to work with your C library.
  42    </p><p>Several libstdc++ source files unconditionally define the macro
  43 <code class="code">_POSIX_SOURCE</code>.  On many systems, defining this macro causes
  44 large portions of the C library header files to be eliminated
  45 at preprocessing time.  Therefore, you may have to <code class="code">#undef</code> this
  46 macro, or define other macros (like <code class="code">_LARGEFILE_SOURCE</code> or
  47 <code class="code">__EXTENSIONS__</code>).  You won't know what macros to define or
  48 undefine at this point; you'll have to try compiling the library and
  49 seeing what goes wrong.  If you see errors about calling functions
  50 that have not been declared, look in your C library headers to see if
  51 the functions are declared there, and then figure out what macros you
  52 need to define.  You will need to add them to the
  53 <code class="code">CPLUSPLUS_CPP_SPEC</code> macro in the GCC configuration file for your
  54 target.  It will not work to simply define these macros in
  55 <code class="code">os_defines.h</code>.
  56    </p><p>At this time, there are a few libstdc++-specific macros which may be
  57 defined:
  58    </p><p><code class="code">_GLIBCXX_USE_C99_CHECK</code> may be defined to 1 to check C99
  59 function declarations (which are not covered by specialization below)
  60 found in system headers against versions found in the library headers
  61 derived from the standard.
  62    </p><p><code class="code">_GLIBCXX_USE_C99_DYNAMIC</code> may be defined to an expression that
  63 yields 0 if and only if the system headers are exposing proper support
  64 for C99 functions (which are not covered by specialization below).  If
  65 defined, it must be 0 while bootstrapping the compiler/rebuilding the
  66 library.
  67    </p><p><code class="code">_GLIBCXX_USE_C99_LONG_LONG_CHECK</code> may be defined to 1 to check
  68 the set of C99 long long function declarations found in system headers
  69 against versions found in the library headers derived from the
  70 standard.
  71
  72    </p><p><code class="code">_GLIBCXX_USE_C99_LONG_LONG_DYNAMIC</code> may be defined to an
  73 expression that yields 0 if and only if the system headers are
  74 exposing proper support for the set of C99 long long functions.  If
  75 defined, it must be 0 while bootstrapping the compiler/rebuilding the
  76 library.
  77    </p><p><code class="code">_GLIBCXX_USE_C99_FP_MACROS_DYNAMIC</code> may be defined to an
  78 expression that yields 0 if and only if the system headers
  79 are exposing proper support for the related set of macros.  If defined,
  80 it must be 0 while bootstrapping the compiler/rebuilding the library.
  81    </p><p><code class="code">_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_CHECK</code> may be defined
  82 to 1 to check the related set of function declarations found in system
  83 headers against versions found in the library headers derived from
  84 the standard.
  85    </p><p><code class="code">_GLIBCXX_USE_C99_FLOAT_TRANSCENDENTALS_DYNAMIC</code> may be defined
  86 to an expression that yields 0 if and only if the system headers
  87 are exposing proper support for the related set of functions.  If defined,
  88 it must be 0 while bootstrapping the compiler/rebuilding the library.
  89    </p><p>Finally, you should bracket the entire file in an include-guard, like
  90 this:
  91    </p><pre class="programlisting">
  92
  93 #ifndef _GLIBCXX_OS_DEFINES
  94 #define _GLIBCXX_OS_DEFINES
  95 ...
  96 #endif
  97 </pre><p>We recommend copying an existing <code class="code">os_defines.h</code> to use as a
  98 starting point.
  99    </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.cpu"></a>CPU</h3></div></div></div><p>If you are porting to a new chip (as opposed to a new operating system
 100 running on an existing chip), you will need to create a new directory in the
 101 <code class="code">config/cpu</code> hierarchy.  Much like the <a class="link" href="internals.html#internals.os" title="Operating System">Operating system</a> setup,
 102 there are no strict rules on how to organize the CPU configuration
 103 directory, but careful naming choices will allow the configury to find your
 104 setup files without explicit help.
 105 </p><p>We recommend that for a target triplet <code class="code">&lt;CPU&gt;-&lt;vendor&gt;-&lt;OS&gt;</code>, you
 106 name your configuration directory <code class="code">config/cpu/&lt;CPU&gt;</code>.  If you do this,
 107 the configury will find the directory by itself.  Otherwise you will need to
 108 edit the <code class="code">configure.host</code> file and, in the switch statement that sets
 109 <code class="code">cpu_include_dir</code>, add a pattern to handle your chip.
 110    </p><p>Note that some chip families share a single configuration directory, for
 111 example, <code class="code">alpha</code>, <code class="code">alphaev5</code>, and <code class="code">alphaev6</code> all use the
 112 <code class="code">config/cpu/alpha</code> directory, and there is an entry in the
 113 <code class="code">configure.host</code> switch statement to handle this.
 114    </p><p>The <code class="code">cpu_include_dir</code> sets default locations for the files controlling
 115 <a class="link" href="internals.html#internals.thread_safety" title="Thread Safety">Thread safety</a> and <a class="link" href="internals.html#internals.numeric_limits" title="Numeric Limits">Numeric limits</a>, if the defaults are not
 116 appropriate for your chip.
 117    </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.char_types"></a>Character Types</h3></div></div></div><p>The library requires that you provide three header files to implement
 118 character classification, analogous to that provided by the C libraries
 119 <code class="code">&lt;ctype.h&gt;</code> header.  You can model these on the files provided in
 120 <code class="code">config/os/generic</code>.  However, these files will almost
 121 certainly need some modification.
 122 </p><p>The first file to write is <code class="code">ctype_base.h</code>.  This file provides
 123 some very basic information about character classification.  The libstdc++
 124 library assumes that your C library implements <code class="code">&lt;ctype.h&gt;</code> by using
 125 a table (indexed by character code) containing integers, where each of
 126 these integers is a bit-mask indicating whether the character is
 127 upper-case, lower-case, alphabetic, etc.  The <code class="code">ctype_base.h</code>
 128 file gives the type of the integer, and the values of the various bit
 129 masks.  You will have to peer at your own <code class="code">&lt;ctype.h&gt;</code> to figure out
 130 how to define the values required by this file.
 131    </p><p>The <code class="code">ctype_base.h</code> header file does not need include guards.
 132 It should contain a single <code class="code">struct</code> definition called
 133 <code class="code">ctype_base</code>.  This <code class="code">struct</code> should contain two type
 134 declarations, and one enumeration declaration, like this example, taken
 135 from the IRIX configuration:
 136    </p><pre class="programlisting">
 137   struct ctype_base
 138      {
 139        typedef unsigned int     mask;
 140        typedef int*             __to_type;
 141
 142        enum
 143        {
 144          space = _ISspace,
 145          print = _ISprint,
 146          cntrl = _IScntrl,
 147          upper = _ISupper,
 148          lower = _ISlower,
 149          alpha = _ISalpha,
 150          digit = _ISdigit,
 151          punct = _ISpunct,
 152          xdigit = _ISxdigit,
 153          alnum = _ISalnum,
 154          graph = _ISgraph
 155        };
 156      };
 157 </pre><p>The <code class="code">mask</code> type is the type of the elements in the table.  If your
 158 C library uses a table to map lower-case numbers to upper-case numbers,
 159 and vice versa, you should define <code class="code">__to_type</code> to be the type of the
 160 elements in that table.  If you don't mind taking a minor performance
 161 penalty, or if your library doesn't implement <code class="code">toupper</code> and
 162 <code class="code">tolower</code> in this way, you can pick any pointer-to-integer type,
 163 but you must still define the type.
 164 </p><p>The enumeration should give definitions for all the values in the above
 165 example, using the values from your native <code class="code">&lt;ctype.h&gt;</code>.  They can
 166 be given symbolically (as above), or numerically, if you prefer.  You do
 167 not have to include <code class="code">&lt;ctype.h&gt;</code> in this header; it will always be
 168 included before <code class="code">ctype_base.h</code> is included.
 169    </p><p>The next file to write is <code class="code">ctype_noninline.h</code>, which also does
 170 not require include guards.  This file defines a few member functions
 171 that will be included in <code class="code">include/bits/locale_facets.h</code>.  The first
 172 function that must be written is the <code class="code">ctype&lt;char&gt;::ctype</code>
 173 constructor.  Here is the IRIX example:
 174    </p><pre class="programlisting">
 175 ctype&lt;char&gt;::ctype(const mask* __table = 0, bool __del = false,
 176            size_t __refs = 0)
 177        : _Ctype_nois&lt;char&gt;(__refs), _M_del(__table != 0 &amp;&amp; __del),
 178          _M_toupper(NULL),
 179          _M_tolower(NULL),
 180          _M_ctable(NULL),
 181          _M_table(!__table
 182                   ? (const mask*) (__libc_attr._ctype_tbl-&gt;_class + 1)
 183                   : __table)
 184        { }
 185 </pre><p>There are two parts of this that you might choose to alter. The first,
 186 and most important, is the line involving <code class="code">__libc_attr</code>.  That is
 187 IRIX system-dependent code that gets the base of the table mapping
 188 character codes to attributes.  You need to substitute code that obtains
 189 the address of this table on your system.  If you want to use your
 190 operating system's tables to map upper-case letters to lower-case, and
 191 vice versa, you should initialize <code class="code">_M_toupper</code> and
 192 <code class="code">_M_tolower</code> with those tables, in similar fashion.
 193 </p><p>Now, you have to write two functions to convert from upper-case to
 194 lower-case, and vice versa.  Here are the IRIX versions:
 195    </p><pre class="programlisting">
 196      char
 197      ctype&lt;char&gt;::do_toupper(char __c) const
 198      { return _toupper(__c); }
 199
 200      char
 201      ctype&lt;char&gt;::do_tolower(char __c) const
 202      { return _tolower(__c); }
 203 </pre><p>Your C library provides equivalents to IRIX's <code class="code">_toupper</code> and
 204 <code class="code">_tolower</code>.  If you initialized <code class="code">_M_toupper</code> and
 205 <code class="code">_M_tolower</code> above, then you could use those tables instead.
 206 </p><p>Finally, you have to provide two utility functions that convert strings
 207 of characters.  The versions provided here will always work - but you
 208 could use specialized routines for greater performance if you have
 209 machinery to do that on your system:
 210    </p><pre class="programlisting">
 211      const char*
 212      ctype&lt;char&gt;::do_toupper(char* __low, const char* __high) const
 213      {
 214        while (__low &lt; __high)
 215          {
 216            *__low = do_toupper(*__low);
 217            ++__low;
 218          }
 219        return __high;
 220      }
 221
 222      const char*
 223      ctype&lt;char&gt;::do_tolower(char* __low, const char* __high) const
 224      {
 225        while (__low &lt; __high)
 226          {
 227            *__low = do_tolower(*__low);
 228            ++__low;
 229          }
 230        return __high;
 231      }
 232 </pre><p>You must also provide the <code class="code">ctype_inline.h</code> file, which
 233 contains a few more functions.  On most systems, you can just copy
 234 <code class="code">config/os/generic/ctype_inline.h</code> and use it on your system.
 235    </p><p>In detail, the functions provided test characters for particular
 236 properties; they are analogous to the functions like <code class="code">isalpha</code> and
 237 <code class="code">islower</code> provided by the C library.
 238    </p><p>The first function is implemented like this on IRIX:
 239    </p><pre class="programlisting">
 240      bool
 241      ctype&lt;char&gt;::
 242      is(mask __m, char __c) const throw()
 243      { return (_M_table)[(unsigned char)(__c)] &amp; __m; }
 244 </pre><p>The <code class="code">_M_table</code> is the table passed in above, in the constructor.
 245 This is the table that contains the bitmasks for each character.  The
 246 implementation here should work on all systems.
 247 </p><p>The next function is:
 248    </p><pre class="programlisting">
 249      const char*
 250      ctype&lt;char&gt;::
 251      is(const char* __low, const char* __high, mask* __vec) const throw()
 252      {
 253        while (__low &lt; __high)
 254          *__vec++ = (_M_table)[(unsigned char)(*__low++)];
 255        return __high;
 256      }
 257 </pre><p>This function is similar; it copies the masks for all the characters
 258 from <code class="code">__low</code> up until <code class="code">__high</code> into the vector given by
 259 <code class="code">__vec</code>.
 260 </p><p>The last two functions again are entirely generic:
 261    </p><pre class="programlisting">
 262      const char*
 263      ctype&lt;char&gt;::
 264      scan_is(mask __m, const char* __low, const char* __high) const throw()
 265      {
 266        while (__low &lt; __high &amp;&amp; !this-&gt;is(__m, *__low))
 267          ++__low;
 268        return __low;
 269      }
 270
 271      const char*
 272      ctype&lt;char&gt;::
 273      scan_not(mask __m, const char* __low, const char* __high) const throw()
 274      {
 275        while (__low &lt; __high &amp;&amp; this-&gt;is(__m, *__low))
 276          ++__low;
 277        return __low;
 278      }
 279 </pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.thread_safety"></a>Thread Safety</h3></div></div></div><p>The C++ library string functionality requires a couple of atomic
 280 operations to provide thread-safety.  If you don't take any special
 281 action, the library will use stub versions of these functions that are
 282 not thread-safe.  They will work fine, unless your applications are
 283 multi-threaded.
 284 </p><p>If you want to provide custom, safe, versions of these functions, there
 285 are two distinct approaches.  One is to provide a version for your CPU,
 286 using assembly language constructs.  The other is to use the
 287 thread-safety primitives in your operating system.  In either case, you
 288 make a file called <code class="code">atomicity.h</code>, and the variable
 289 <code class="code">ATOMICITYH</code> must point to this file.
 290    </p><p>If you are using the assembly-language approach, put this code in
 291 <code class="code">config/cpu/&lt;chip&gt;/atomicity.h</code>, where chip is the name of
 292 your processor (see <a class="link" href="internals.html#internals.cpu" title="CPU">CPU</a>).  No additional changes are necessary to
 293 locate the file in this case; <code class="code">ATOMICITYH</code> will be set by default.
 294    </p><p>If you are using the operating system thread-safety primitives approach,
 295 you can also put this code in the same CPU directory, in which case no more
 296 work is needed to locate the file.  For examples of this approach,
 297 see the <code class="code">atomicity.h</code> file for IRIX or IA64.
 298    </p><p>Alternatively, if the primitives are more closely related to the OS
 299 than they are to the CPU, you can put the <code class="code">atomicity.h</code> file in
 300 the <a class="link" href="internals.html#internals.os" title="Operating System">Operating system</a> directory instead.  In this case, you must
 301 edit <code class="code">configure.host</code>, and in the switch statement that handles
 302 operating systems, override the <code class="code">ATOMICITYH</code> variable to point to
 303 the appropriate <code class="code">os_include_dir</code>.  For examples of this approach,
 304 see the <code class="code">atomicity.h</code> file for AIX.
 305    </p><p>With those bits out of the way, you have to actually write
 306 <code class="code">atomicity.h</code> itself.  This file should be wrapped in an
 307 include guard named <code class="code">_GLIBCXX_ATOMICITY_H</code>.  It should define one
 308 type, and two functions.
 309    </p><p>The type is <code class="code">_Atomic_word</code>.  Here is the version used on IRIX:
 310    </p><pre class="programlisting">
 311 typedef long _Atomic_word;
 312 </pre><p>This type must be a signed integral type supporting atomic operations.
 313 If you're using the OS approach, use the same type used by your system's
 314 primitives.  Otherwise, use the type for which your CPU provides atomic
 315 primitives.
 316 </p><p>Then, you must provide two functions.  The bodies of these functions
 317 must be equivalent to those provided here, but using atomic operations:
 318    </p><pre class="programlisting">
 319      static inline _Atomic_word
 320      __attribute__ ((__unused__))
 321      __exchange_and_add (_Atomic_word* __mem, int __val)
 322      {
 323        _Atomic_word __result = *__mem;
 324        *__mem += __val;
 325        return __result;
 326      }
 327
 328      static inline void
 329      __attribute__ ((__unused__))
 330      __atomic_add (_Atomic_word* __mem, int __val)
 331      {
 332        *__mem += __val;
 333      }
 334 </pre></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.numeric_limits"></a>Numeric Limits</h3></div></div></div><p>The C++ library requires information about the fundamental data types,
 335 such as the minimum and maximum representable values of each type.
 336 You can define each of these values individually, but it is usually
 337 easiest just to indicate how many bits are used in each of the data
 338 types and let the library do the rest.  For information about the
 339 macros to define, see the top of <code class="code">include/bits/std_limits.h</code>.
 340 </p><p>If you need to define any macros, you can do so in <code class="code">os_defines.h</code>.
 341 However, if all operating systems for your CPU are likely to use the
 342 same values, you can provide a CPU-specific file instead so that you
 343 do not have to provide the same definitions for each operating system.
 344 To take that approach, create a new file called <code class="code">cpu_limits.h</code> in
 345 your CPU configuration directory (see <a class="link" href="internals.html#internals.cpu" title="CPU">CPU</a>).
 346    </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="internals.libtool"></a>Libtool</h3></div></div></div><p>The C++ library is compiled, archived and linked with libtool.
 347 Explaining the full workings of libtool is beyond the scope of this
 348 document, but there are a few, particular bits that are necessary for
 349 porting.
 350 </p><p>Some parts of the libstdc++ library are compiled with the libtool
 351 <code class="code">--tags CXX</code> option (the C++ definitions for libtool).  Therefore,
 352 <code class="code">ltcf-cxx.sh</code> in the top-level directory needs to have the correct
 353 logic to compile and archive objects equivalent to the C version of libtool,
 354 <code class="code">ltcf-c.sh</code>.  Some libtool targets have definitions for C but not
 355 for C++, or C++ definitions which have not been kept up to date.
 356    </p><p>The C++ run-time library contains initialization code that needs to be
 357 run as the library is loaded.  Often, that requires linking in special
 358 object files when the C++ library is built as a shared library, or
 359 taking other system-specific actions.
 360    </p><p>The libstdc++ library is linked with the C version of libtool, even
 361 though it is a C++ library.  Therefore, the C version of libtool needs to
 362 ensure that the run-time library initializers are run.  The usual way to
 363 do this is to build the library using <code class="code">gcc -shared</code>.
 364    </p><p>If you need to change how the library is linked, look at
 365 <code class="code">ltcf-c.sh</code> in the top-level directory.  Find the switch statement
 366 that sets <code class="code">archive_cmds</code>.  Here, adjust the setting for your
 367 operating system.
 368    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_porting.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix B. Porting and Maintenance </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> ABI Policy and Guidelines</td></tr></table></div></body></html>