Berkeley DB Reference Guide: Porting Berkeley DB to new architectures

Berkeley DB Reference Guide:
Distribution

Porting Berkeley DB to new architectures

Berkeley DB is generally easy to port to new architectures. Berkeley DB was designed to be as portable as possible, and has been ported to a wide variety of systems, from Wind River's Tornado system, to VMS, to Windows/NT and Windows/95, and most existing UNIX platforms. It runs on 16, 32 and 64-bit machines, little or big-endian. The difficulty of a port depends on how much of the ANSI C and POSIX 1003.1 standards the new architecture offers.

An abstraction layer separates the main Berkeley DB code from the operating system and architecture specific components. This layer is comprised of approximately 2500 lines of C language code, found in the os subdirectory of the Berkeley DB distribution. The following list of files include functionality that may need to be modified or implemented in order to support a new architecture. Within each file, there is usually one, but sometimes several functions (for example, the os_alloc.c file contains the malloc, calloc, realloc, free, and strdup functions).

Source file	Description
os_abs.c	Return if a filename is an absolute pathname
os_alloc.c	ANSI C malloc, calloc, realloc, strdup, free front-ends
os_clock.c	Return the current time-of-day
os_config.c	Return run-time configuration information
os_dir.c	Read the filenames from a directory
os_errno.c	Set/get the ANSI C errno value
os_fid.c	Create a unique ID for a file
os_fsync.c	POSIX 1003.1 fsync front-end
os_handle.c	Open file handles
os_id.c	Return thread ID
os_map.c	Map a shared memory area
os_method.c	Run-time replacement of system calls
os_oflags.c	Convert POSIX 1003.1 open flags, modes to Berkeley DB flags
os_open.c	Open file handles
os_region.c	Map a shared memory area
os_rename.c	POSIX 1003.1 rename call
os_root.c	Return if application has special permissions
os_rpath.c	Return last pathname separator
os_rw.c	POSIX 1003.1 read/write calls
os_seek.c	POSIX 1003.1 seek call
os_sleep.c	Cause a thread of control to release the CPU
os_spin.c	Return the times to spin while waiting for a mutex
os_stat.c	POSIX 1003.1 stat call
os_tmpdir.c	Set the path for temporary files
os_unlink.c	POSIX 1003.1 unlink call

All but a few of these files contain relatively trivial pieces of code. Typically, there is only a single version of the code for all platforms Berkeley DB supports, and that code lives in the os directory of the distribution. Where different code is required, the code is either conditionally compiled or an entirely different version is written. For example, VxWorks versions of some of these files can be found in the distribution directory os_vxworks, and Windows versions can be found in os_windows.

Historically, there are only two difficult questions to answer for each new port. The first question is how to handle shared memory. In order to write multiprocess database applications (not multithreaded, but threads of control running in different address spaces), Berkeley DB must be able to name pieces of shared memory and access them from multiple processes. On UNIX/POSIX systems, we use mmap and shmget for that purpose, but any interface that provides access to named shared memory is sufficient. If you have a simple, flat address space, you should be able to use the code in os_vxworks/os_map.c as a starting point for the port. If you are not intending to write multiprocess database applications, then this won't be necessary, as Berkeley DB can simply allocate memory from the heap if all threads of control will live in a single address space.

The second question is mutex support. Berkeley DB requires some form of self-blocking mutual exclusion mutex. Blocking mutexes are preferred as they tend to be less CPU-expensive and less likely to cause thrashing. If blocking mutexes are not available, however, test-and-set will work as well. The code for mutexes is in two places in the system: the include file dbinc/mutex.h, and the distribution directory mutex.

Berkeley DB uses the GNU autoconf tools for configuration on almost all of the platforms it supports. Specifically, the include file db_config.h configures the Berkeley DB build. The simplest way to begin a port is to configure and build Berkeley DB on a UNIX or UNIX-like system, and then take the Makefile and db_config.h file created by that configuration, and modify it by hand to reflect the needs of the new architecture. Unless you're already familiar with the GNU autoconf toolset, we don't recommend you take the time to integrate your changes back into the Berkeley DB autoconfiguration framework. Instead, send us context diffs of your changes and any new source files you created, and we'll integrate the changes into our source tree.

Finally, we're happy to work with you on the port, or potentially, do the port ourselves, if that is of interest to you. Regardless, if you have any porting questions, just let us know, and we will be happy to answer them.