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