m4_comment([$Id: faq.so,v 1.30 2004/08/17 13:45:35 sue Exp $])

m4_ref_title(Building m4_db for VxWorks systems,
    VxWorks FAQ,
    [@building for VxWorks FAQ, building for @VxWorks FAQ],
    build_vxworks/notes, upgrade/version)

m4_nlistbegin
m4_nlist([dnl
m4_bold([dnl
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.])

m4_p([dnl
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 m4_db
".zip" version of the m4_db distribution, and, when extracting the m4_db
sources, that you use an unzipper program that will not do any
conversion.])])

m4_nlist([dnl
m4_bold([dnl
I sometimes see spurious output errors about temporary directories.])

m4_p([dnl
These messages are coming from the m4_manref(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 m4_ref(dbenv_set_tmp_dir) to
specify a temporary directory for the application.])])

m4_nlist([dnl
m4_bold([dnl
How can I build m4_db without using Tornado?])

m4_p([dnl
The simplest way to build m4_db without using Tornado is to configure
m4_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 m4_db to be built.])

m4_p([dnl
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 m4_db VxWorks files.  The commands assume you are in the build_vxworks
directory of the m4_db distribution:])

m4_indent([dnl
% cat __GT__ /tmp/files.sed
s/__LT__BEGIN__GT__ FILE_//
s/_objects//
^D
% grep FILE_ BerkeleyDB.wpj | grep _objects | sed -f /tmp/files.sed __GT__ /tmp/db.files])

m4_p([dnl
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.])])

m4_nlist([dnl
m4_bold([dnl
Does m4_db use floating point registers?])

m4_p([dnl
Yes, there are a few places in m4_db where floating point computations
are performed.  As a result, all applications that call
m4_italic(taskSpawn) should specify the m4_bold(VX_FP_TASK) option.])])

m4_nlist([dnl
m4_bold([dnl
Can I run the test suite under VxWorks?])

m4_p([dnl
The test suite requires the m4_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
m4_italic(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.])])

m4_nlist([dnl
m4_bold([dnl
Are all m4_db features available for VxWorks?])

m4_p([dnl
All m4_db features are available for VxWorks with the exception of the
m4_ref(DB_TRUNCATE) flag for m4_ref(dbh_open).  The underlying mechanism
needed for that flag is not available consistently across different file
systems for VxWorks.])])

m4_nlist([dnl
m4_bold([dnl
Are there any constraints using particular filesystem drivers?])

m4_p([dnl
There are constraints using the dosFs filesystems with m4_db.  Namely,
you must configure your dosFs filesystem to support long filenames if
you are using m4_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.])])

m4_nlist([dnl
m4_bold([dnl
Are there any dependencies on particular filesystem drivers?])

m4_p([dnl
There is one dependency on specifics of filesystem drivers in the port
of m4_db to VxWorks.  m4_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.])])

m4_nlist([dnl
m4_bold([dnl
Are there any known filesystem problems?])

m4_p([dnl
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, m4_bold([SPR 79795 (x86)])
and m4_bold([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.])

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

m4_p([dnl
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 m4_bold([SPR 33221]) at Wind River Systems.
There are several SPR numbers at Wind River Systems that refer to this
particular problem.])])

m4_p([dnl
The third problem is that all tasks will hang on a dosFs semaphore.  You should
look at m4_bold([SPR 72063]) in the Wind River Systems' Support pages for
a more detailed description of this problem.])
m4_nlist([dnl
m4_bold([dnl
Are there any filesystems I cannot use?])

m4_p([dnl
Currently both the Target Server File System (TSFS) and NFS are not able
to be used.])

m4_p([dnl
The Target Server File System (TSFS) uses the netDrv driver.  This driver
does not support any ioctl that allows flushing to the disk, nor does
it allow renaming of files via FIORENAME.
The NFS file system uses nfsDrv and that driver
does not support FIORENAME and cannot be used
with m4_db.  ])])

m4_nlist([dnl
m4_bold([dnl
What VxWorks primitives are used for mutual exclusion in m4_db?])

m4_p([dnl
Mutexes inside of m4_db use the basic binary semaphores in VxWorks.  The
mutexes are created using the FIFO queue type.])])

m4_nlist([dnl
m4_bold([What are the implications of VxWorks' mutex implementation
using microkernel resources?])

m4_p([dnl
On VxWorks, the semaphore primitives implementing mutexes consume system
resources.  Therefore, if an application unexpectedly fails, those
resources could leak.  m4_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 m4_refT(dbenv_remove) will allow m4_db to
release those previously held mutex resources.  If an application
specifies the m4_ref(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
m4_ref(DB_PRIVATE) flag should be used with caution on VxWorks.])])

m4_nlistend

m4_page_footer