###

Berkeley DB Reference Guide:
  Building Berkeley DB for VxWorks systems

### VxWorks FAQ

1. I get the error "Workspace open failed: This project workspace is an older format.", when trying to open the supplied workspace on Tornado 2.0 under Windows.

   This error will occur if the files were extracted in a manner that adds a CR/LF to lines in the file. Make sure that you download the Berkeley DB ".zip" version of the Berkeley DB distribution, and, when extracting the Berkeley DB sources, that you use an unzipper program that will not do any conversion.

2. I sometimes see spurious output errors about temporary directories.

   These messages are coming from the stat(2) function call in VxWorks. Unlike other systems, there may not be a well known temporary directory on the target. Therefore, we highly recommend that all applications use DB_ENV->set_tmp_dir to specify a temporary directory for the application.

3. How can I build Berkeley DB without using Tornado?

   The simplest way to build Berkeley DB without using Tornado is to configure Berkeley DB on a UNIX system, and then use the Makefile and include files generated by that configuration as the starting point for your build. The Makefile and include files are created during configuration, in the current directory, based on your configuration decisions (for example, debugging vs. non-debugging builds), so you'll need to configure the system for the way you want Berkeley DB to be built.

   Additionally, you'll need to account for the slight difference between the set of source files used in a UNIX build and the set used in a VxWorks build. You can use the following command to create a list of the Berkeley DB VxWorks files. The commands assume you are in the build_vxworks directory of the Berkeley DB distribution:

   >     % cat > /tmp/files.sed
   >     s/<BEGIN> FILE_//
   >     s/_objects//
   >     ^D
   >     % grep FILE_ BerkeleyDB.wpj | grep _objects | sed -f /tmp/files.sed > /tmp/db.files

   You will then have a template Makefile and include files, and a list of VxWorks-specific source files. You will need to convert this Makefile and list of files into a form that is acceptable to your specific build environment.

4. Does Berkeley DB use floating point registers?

   Yes, there are a few places in Berkeley DB where floating point computations are performed. As a result, all applications that call taskSpawn should specify the VX_FP_TASK option.

5. Can I run the test suite under VxWorks?

   The test suite requires the Berkeley DB Tcl library. In turn, this library requires Tcl 8.4 or greater. In order to run the test suite, you would need to port Tcl 8.4 or greater to VxWorks. The Tcl shell included in windsh is not adequate for two reasons. First, it is based on Tcl 8.0. Second, it does not include the necessary Tcl components for adding a Tcl extension.

6. Are all Berkeley DB features available for VxWorks?

   All Berkeley DB features are available for VxWorks with the exception of the DB_TRUNCATE flag for DB->open. The underlying mechanism needed for that flag is not available consistently across different file systems for VxWorks.

7. Are there any constraints using particular filesystem drivers?

   There are constraints using the dosFs filesystems with Berkeley DB. Namely, you must configure your dosFs filesystem to support long filenames if you are using Berkeley DB logging in your application. The VxWorks' dosFs 1.0 filesystem, by default, uses the old MS-DOS 8.3 file-naming constraints, restricting to 8 character filenames with a 3 character extension. If you have configured with VxWorks' dosFs 2.0 you should be compatible with Windows FAT32 filesystems which supports long filenames.

8. Are there any dependencies on particular filesystem drivers?

   There is one dependency on specifics of filesystem drivers in the port of Berkeley DB to VxWorks. Berkeley DB synchronizes data using the FIOSYNC function to ioctl() (another option would have been to use the FIOFLUSH function instead). The FIOSYNC function was chosen because the NFS client driver, nfsDrv, only supports it and doesn't support FIOFLUSH. All local file systems, as of VxWorks 5.4, support FIOSYNC -- with the exception of rt11fsLib, which only supports FIOFLUSH. To use rt11fsLib, you will need to modify the os/os_fsync.c file to use the FIOFLUSH function; note that rt11fsLib cannot work with NFS clients.

9. Are there any known filesystem problems?

   During the course of our internal testing, we came across three problems with the dosFs 2.0 filesystem that warranted patches from Wind River Systems. We strongly recommend you upgrade to dosFs 2.2, SPR 79795 (x86) and SPR 79569 (PPC) which fixes all of these problems and many more. You should ask Wind River Systems for the patches to these problems if you encounter them and are unable to upgrade to dosFs 2.2.

   The first problem is that files will seem to disappear. You should look at SPR 31480 in the Wind River Systems' Support pages for a more detailed description of this problem.

   The second problem is a semaphore deadlock within the dosFs filesystem code. Looking at a stack trace via CrossWind, you will see two or more of your application's tasks waiting in semaphore code within dosFs. The patch for this problem is under SPR 33221 at Wind River Systems. There are several SPR numbers at Wind River Systems that refer to this particular problem.

   The third problem is that all tasks will hang on a dosFs semaphore. You should look at SPR 72063 in the Wind River Systems' Support pages for a more detailed description of this problem.

10. Are there any filesystems I cannot use?

    The Target Server File System (TSFS) uses the netDrv driver. This driver does not support any ioctl that allows flushing to the disk, and therefore cannot be used with Berkeley DB.

11. What VxWorks primitives are used for mutual exclusion in Berkeley DB?

    Mutexes inside of Berkeley DB use the basic binary semaphores in VxWorks. The mutexes are created using the FIFO queue type.

12. What are the implications of VxWorks' mutex implementation using microkernel resources?

    On VxWorks, the semaphore primitives implementing mutexes consume system resources. Therefore, if an application unexpectedly fails, those resources could leak. Berkeley DB solves this problem by always allocating mutexes in the persistent shared memory regions. Then, if an application fails, running recovery or explicitly removing the database environment by calling the DB_ENV->remove method will allow Berkeley DB to release those previously held mutex resources. If an application specifies the DB_PRIVATE flag (choosing not to use persistent shared memory), and then fails, mutexes allocated in that private memory may leak their underlying system resources. Therefore, the DB_PRIVATE flag should be used with caution on VxWorks.

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.