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"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Chapter��47.�� Distribution</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 11 <link rel="prev" href="test_faq.html" title="Test suite FAQ" /> 12 <link rel="next" href="distrib_layout.html" title="Source code layout" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter��47.�� 19 Distribution 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="test_faq.html">Prev</a>��</td> 24 <th width="60%" align="center">��</th> 25 <td width="20%" align="right">��<a accesskey="n" href="distrib_layout.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="chapter" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title"><a id="distrib"></a>Chapter��47.�� 35 Distribution 36 </h2> 37 </div> 38 </div> 39 </div> 40 <div class="toc"> 41 <p> 42 <b>Table of Contents</b> 43 </p> 44 <dl> 45 <dt> 46 <span class="sect1"> 47 <a href="distrib.html#distrib_port">Porting Berkeley DB to new architectures</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect1"> 52 <a href="distrib_layout.html">Source code layout</a> 53 </span> 54 </dt> 55 </dl> 56 </div> 57 <div class="sect1" lang="en" xml:lang="en"> 58 <div class="titlepage"> 59 <div> 60 <div> 61 <h2 class="title" style="clear: both"><a id="distrib_port"></a>Porting Berkeley DB to new architectures</h2> 62 </div> 63 </div> 64 </div> 65 <p>Berkeley DB is generally easy to port to new architectures. Berkeley DB was 66designed to be as portable as possible, and has been ported to a wide 67variety of systems, from Wind River's Tornado system, to VMS, to 68Windows/NT and Windows/95, and most existing UNIX platforms. It runs 69on 16, 32 and 64-bit machines, little or big-endian. The difficulty of 70a port depends on how much of the ANSI C and POSIX 1003.1 standards the 71new architecture offers.</p> 72 <p>An abstraction layer separates the main Berkeley DB code from the operating 73system and architecture specific components. This layer is comprised 74of approximately 2500 lines of C language code, found in the <code class="filename">os</code> 75subdirectory of the Berkeley DB distribution. The following list of files 76include functionality that may need to be modified or implemented in 77order to support a new architecture. Within each file, there is usually 78one, but sometimes several functions (for example, the 79<code class="filename">os_alloc.c</code> file contains the malloc, calloc, realloc, free, 80and strdup functions).</p> 81 <div class="informaltable"> 82 <table border="1" width="80%"> 83 <colgroup> 84 <col /> 85 <col /> 86 </colgroup> 87 <thead> 88 <tr> 89 <th>Source file</th> 90 <th>Description</th> 91 </tr> 92 </thead> 93 <tbody> 94 <tr> 95 <td>os_abs.c</td> 96 <td>Return if a filename is an absolute pathname</td> 97 </tr> 98 <tr> 99 <td>os_alloc.c</td> 100 <td>ANSI C malloc, calloc, realloc, strdup, free front-ends</td> 101 </tr> 102 <tr> 103 <td>os_clock.c</td> 104 <td>Return the current time-of-day</td> 105 </tr> 106 <tr> 107 <td>os_config.c</td> 108 <td>Return run-time configuration information</td> 109 </tr> 110 <tr> 111 <td>os_dir.c</td> 112 <td>Read the filenames from a directory</td> 113 </tr> 114 <tr> 115 <td>os_errno.c</td> 116 <td>Set/get the ANSI C errno value</td> 117 </tr> 118 <tr> 119 <td>os_fid.c</td> 120 <td>Create a unique ID for a file</td> 121 </tr> 122 <tr> 123 <td>os_fsync.c</td> 124 <td>POSIX 1003.1 fsync front-end</td> 125 </tr> 126 <tr> 127 <td>os_handle.c</td> 128 <td>Open file handles</td> 129 </tr> 130 <tr> 131 <td>os_id.c</td> 132 <td>Return thread ID</td> 133 </tr> 134 <tr> 135 <td>os_map.c</td> 136 <td>Map a shared memory area</td> 137 </tr> 138 <tr> 139 <td>os_method.c</td> 140 <td>Run-time replacement of system calls</td> 141 </tr> 142 <tr> 143 <td>os_oflags.c</td> 144 <td>Convert POSIX 1003.1 open flags, modes to Berkeley DB flags</td> 145 </tr> 146 <tr> 147 <td>os_open.c</td> 148 <td>Open file handles</td> 149 </tr> 150 <tr> 151 <td>os_region.c</td> 152 <td>Map a shared memory area</td> 153 </tr> 154 <tr> 155 <td>os_rename.c</td> 156 <td>POSIX 1003.1 rename call</td> 157 </tr> 158 <tr> 159 <td>os_root.c</td> 160 <td>Return if application has special permissions</td> 161 </tr> 162 <tr> 163 <td>os_rpath.c</td> 164 <td>Return last pathname separator</td> 165 </tr> 166 <tr> 167 <td>os_rw.c</td> 168 <td>POSIX 1003.1 read/write calls</td> 169 </tr> 170 <tr> 171 <td>os_seek.c</td> 172 <td>POSIX 1003.1 seek call</td> 173 </tr> 174 <tr> 175 <td>os_sleep.c</td> 176 <td>Cause a thread of control to release the CPU</td> 177 </tr> 178 <tr> 179 <td>os_spin.c</td> 180 <td>Return the times to spin while waiting for a mutex</td> 181 </tr> 182 <tr> 183 <td>os_stat.c</td> 184 <td>POSIX 1003.1 stat call</td> 185 </tr> 186 <tr> 187 <td>os_tmpdir.c</td> 188 <td>Set the path for temporary files</td> 189 </tr> 190 <tr> 191 <td>os_unlink.c</td> 192 <td>POSIX 1003.1 unlink call</td> 193 </tr> 194 </tbody> 195 </table> 196 </div> 197 <p>All but a few of these files contain relatively trivial pieces of code. 198Typically, there is only a single version of the code for all platforms 199Berkeley DB supports, and that code lives in the <code class="filename">os</code> directory of the 200distribution. Where different code is required, the code is either 201conditionally compiled or an entirely different version is written. For 202example, VxWorks versions of some of these files can be found in the 203distribution directory os_vxworks, and Windows versions can be found in 204os_windows.</p> 205 <p>Historically, there are only two difficult questions to answer for each 206new port. The first question is how to handle shared memory. In order 207to write multiprocess database applications (not multithreaded, but 208threads of control running in different address spaces), Berkeley DB must be 209able to name pieces of shared memory and access them from multiple 210processes. On UNIX/POSIX systems, we use <span class="bold"><strong>mmap</strong></span> and 211<span class="bold"><strong>shmget</strong></span> for that purpose, but any interface that provides access 212to named shared memory is sufficient. If you have a simple, flat 213address space, you should be able to use the code in 214<code class="filename">os_vxworks/os_map.c</code> as a starting point for the port. If you 215are not intending to write multiprocess database applications, then 216this won't be necessary, as Berkeley DB can simply allocate memory from the 217heap if all threads of control will live in a single address space.</p> 218 <p>The second question is mutex support. Berkeley DB requires some form of 219<span class="bold"><strong>self-blocking</strong></span> mutual exclusion mutex. Blocking mutexes are 220preferred as they tend to be less CPU-expensive and less likely to cause 221thrashing. If blocking mutexes are not available, however, test-and-set 222will work as well. The code for mutexes is in two places in the system: 223the include file <code class="filename">dbinc/mutex.h</code>, and the distribution directory 224<code class="filename">mutex</code>.</p> 225 <p>Berkeley DB uses the GNU autoconf tools for configuration on almost all of 226the platforms it supports. Specifically, the include file 227<code class="filename">db_config.h</code> configures the Berkeley DB build. The simplest way to 228begin a port is to configure and build Berkeley DB on a UNIX or UNIX-like 229system, and then take the <code class="filename">Makefile</code> and <code class="filename">db_config.h</code> 230file created by that configuration, and modify it by hand to reflect 231the needs of the new architecture. Unless you're already familiar with 232the GNU autoconf toolset, we don't recommend you take the time to 233integrate your changes back into the Berkeley DB autoconfiguration framework. 234Instead, send us context diffs of your changes and any new source files 235you created, and we'll integrate the changes into our source tree.</p> 236 <p>Finally, we're happy to work with you on the port, or potentially, do 237the port ourselves, if that is of interest to you. Regardless, if you 238have any porting questions, just let us know, and we will be happy to 239answer them.</p> 240 </div> 241 </div> 242 <div class="navfooter"> 243 <hr /> 244 <table width="100%" summary="Navigation footer"> 245 <tr> 246 <td width="40%" align="left"><a accesskey="p" href="test_faq.html">Prev</a>��</td> 247 <td width="20%" align="center">��</td> 248 <td width="40%" align="right">��<a accesskey="n" href="distrib_layout.html">Next</a></td> 249 </tr> 250 <tr> 251 <td width="40%" align="left" valign="top">Test suite FAQ��</td> 252 <td width="20%" align="center"> 253 <a accesskey="h" href="index.html">Home</a> 254 </td> 255 <td width="40%" align="right" valign="top">��Source code layout</td> 256 </tr> 257 </table> 258 </div> 259 </body> 260</html> 261