Empress
Technical News - August 2013
Empress Embedded Database for VxWorks 6.9 Simulator
Easily Build Database Applications for VxWorks
Introduction
Empress V10.20 embedded database has become the choice for many
embedded devices. When the embedded device is powered by Wind
River VxWorks operating system, there is a choice of many BSPs
(Board Support Packages) from Wind River to support the
customer’s target hardware.
In many cases, the customer’s software development process has
to start much earlier than the availability of the target
device. The Wind River VxWorks Simulator (VxSIM) is a great
choice to develop database driven applications before the target
hardware is available.
“The VxWorks simulator allows you to develop, run, and test
VxWorks applications on your host system, reducing the need for
target hardware during development.” [Wind River VxWorks
Simulator User's Guide]
Empress Embedded Database V10.20 offers many rich and efficient
features. Building these features into a VxWorks database
application in the simulator environment is no different than
building them into any VxWorks cross-development environment
using a standard board support package (BSP).
A typical cross development environment is shown in Figure 1
Here, several people (developers, testers, documentation
writers, etc.) are involved in cross platform development
environment using their dedicated host machines and the
connected target devices/boards for developing, testing,
porting…
Figure 1:
Typical Cross Development Environment
If the software development process has to start much earlier
than the availability of the target device, and the choice of
target O/S is VxWorks then a VxWorks simulator environment can
be used (see Figure 2
Figure 2: Cross Development
Environment Using VxWorks Simulator
This technical article describes the process of using Empress
10.20 Cross Development Package to build embedded database
applications for use with the VxWorks 6.9 simulator running on
Windows XP or Windows 7.
Configuring VxWorks 6.9 Simulator Development Environment
This document assumes some familiarity with application
development using the VxWorks operating system.
Prerequisites
On the host:
• Windows XP SP3, Windows 7
• WindRiver Workbench 3.3 & VxWorks 6.9
• Empress Ultra Embedded 10.20 Cross Development Package
For VxWorks 6.9 Windows Simulator
On the target:
VxWorks 6.9 operating system for the VxWorks Simulator built
with following:
• BSP:
• Address mode: 32-bit kernel
• Tool chain: diab
• Kernel project profile: PROFILE_DEVELOPMENT
• Enable Project Specific Settings
Kernel Configuration:
• Include dosFs File System Components (dosFs2)
[FOLDER_DOSFS2] from:
operating system components
IO system components
Empress Ultra Embedded requires a file system or equivalent to
store database and temporary files. Depending on the target’s
architecture and the application’s requirement for persistent
data, the device can be a RAM disk or a virtual disk device. The
virtual disk device will be used in the examples below.
• Include
XBD Block Device [INCLUDE_XBD_BLK_DEV]
XBD Disk Partition Handler [INCLUDE_XBD_PART_LIB]
XBD Ram Drive [INCLUDE_XBD_RAMDRV]
from:
operating system components
IO system components
These are necessary to format and handle the RAM disk or virtual
disk devices.
• Include RAM disk driver [INCLUDE_RAMDRV] from:
hardware
peripherals
• Include virtualDisk [INCLUDE_VIRTUAL_DISK] from:
operating system components
IO system components
To format the virtual disk as a Highly Reliable File System
(HRFS) you will need to include the HRFS components.
• Include Highly Reliable File System Components (HRFS)
[FOLDER_HRFS] from:
operating system components
IO system components
• Exclude Read-Only Highly Reliable File System
[INCLUDE_HRFS_READONLY]
from:
operating system components
IO system components
Highly Reliable File System Components (HRFS)
• Change the Default Max Files
[HRFS_DEFAULT_MAX_FILES] to 50. It can be found
at:
operating system components
IO system components
Highly Reliable File System Components (HRFS)
Highly
Reliable File System
• Exclude either:
HRFS Default Write Mode
[INCLUDE_HRFS_DEFAULT_WRITE_MODE]
OR
HRFS High Speed Write Mode
[INCLUDE_HRFS_HISPEED_WRITE_MODE]
Depending on which one you do NOT want to use
from:
operating system components
IO system components
Highly Reliable File System Components (HRFS)
Select HRFS work mode
Either mode will work with Empress Ultra Embedded.
• Change the Default Max Open Files
[DOSFS_DEFAULT_MAX_FILES] to 128 It can be found
at
Operating System Components
IO system components
dosFs File System Components (dosFs2)
dosFs File System Main Module (dosFs2)
• Change the NUM_FILES to 128. It can be found at
Operating System Components
IO System Components
IO Subsystem Components
Basic IO System
For information about
VxWorks Kernel programming, please refer to the VxWorks
Kernel Programmers’ Guide, 6.9 from Wind River.
Installing the Empress Ultra Embedded 10.20 Cross Development
Package
The Empress Ultra Embedded 10.20 Cross Development Package is
packaged as a ZIP file. To install it, you just un-zip the file
to your preferred directory on the host.
For this document, the Empress package was installed at
C:/Empress_VxWorks6.9/
It has the following structure:
Empress_VxWorks6.9/
|--> Getting
Started
A text file showing how to
get started
|-->
version.txt
A text file
showing the package Version
|-->
docs
A directory
of Empress documentation
|-->
samples
A directory of
sample programs
|--> xtarget
|-->
vx-sim
Empress files for the
Simulator target
|-->
include/
Empress include files
|-->
load_modules/
Empress loadable libraries
|-->
version.txt
Version of this target package
The Empress include files (under xtarget/vx-sim/include) are C
header files that provide Empress Database function definitions
for application development. They are used to compile
application source code on the host.
The Empress loadable library (under xtarget/vx-sim/load_modules)
is an executable binary file that enables database functions on
a VxWorks target.
In this package, Empress MR API and database utilities are
available for the VxWorks platform in the loadable library.
The Empress loadable library is a relocatable object module that
can be executed in the VxWorks kernel space.
The Empress loadable library can be downloaded and dynamically
linked to the operating system by the VxWorks object module
loader.
For information about
Empress Database MR API programming, please refer to
Empress Manual: C/C++ Kernel Level Interface – mr Routine.
Building applications with Empress for VxWorks 6.9
To build a kernel-based application with Empress Embedded for
VxWorks 6.9, please follow the guidelines below:
- Specify the target build spec:
For Wind River Workbench, select SIMNTdiab atProject Properties -> Build Properties
-> Build Specs -> Active build spec.
- Use –I compiler flag to specify the location of Empress
header files.
For Wind River workbench, add
-IC:/Empress_VxWorks6.9/xtarget/vx-sim/include
to Include Paths in the application’s
project Build Paths properties.
- If the VxWorks kernel on Windows Simulator target is
built with LOCAL_MEM_SIZE set to greater than 32MB,
use –Xcode-absolute-far compiler option to make the
application objects relocatable on the target.
For Wind River workbench, add or edit the ADDED_FLAG
macro to include
–Xcode-absolute-far
in NAME and Value section at Project
Properties -> Build Properties -> Variables -> Build
spec specific settings.
For information
about Wind River compiler and linker, please see the Wind
River Compiler User’s Guide from Wind River.
For information about Wind
River workbench, please see the Wind River Workbench
User’s Guide 3.3 from Wind River.
Running applications with Empress for VxWorks 6.9
To execute an Empress Ultra Embedded application on a VxWorks
Windows Simulator target, following conditions must be met for
the target:
- The current working directory is a writeable directory.
- The entry-point routines of the application are invoked
interactively or the VxWorks operating system
can be configured
to start applications automatically at boot time.
Sample Programs
All programs use an Empress database named sampledb (with the
exception of hello.c which does not use a database).
The sampledb database contains two tables with following
definitions:
Table: loans
name echaracter(25,1)
date edate(1)
amount dollar(6,1)
Table: personnel
number tinyint
name echaracter(25,1)
phone echaracter(15,1)
credit_limit dollar(6,1)
Empress sample programs are located in
Empress_VxWorks6.9/samples.
The samples directory contains following files needed to build
and run Empress sample programs:
- hello.c: A ‘hello’ type program that includes
basic Empress initialization and cleanup routines. No database
is required. Its entry point is myhello()
- select.c: retrieves all current employees from
the personnel table. Its entry point routine is
retrieve_employees().
- delete.c: deletes all load records made before
May 2005 from the loans table. Its entry point routine is
delete_old_loans().
- insert.c: adds 4 records into table loans. Its
entry point routine is insert_new_loans().
- update.c: renews the loan date for each current
employee. Its entry point routine is update_loans().
- oldloans.c: retrieves all amounts from the loan
table for employee 'John' which are larger than $100 or later
than January 2nd, 2005. Its entry point routine is
retrieve_oldloans().
- sampledb.ex: It is an Empress Database export
file that contains all the data required to run sample programs.
How to Build Sample Programs
On the Windows host, please use the following steps to build any
of the Empress sample programs:
- Step 1: Click File-> New and choose Start
Menu->
All Programs and choose VxWorks Downloadable
Kernel Module Project
- Step 2: Fill in the name of the Project [e.g.
Sample]
- Step 3: Keep clicking on the Next tab
until Build Specs window is shown. At this point, click
on Deselect All tab and then manually select SIMNTdiab
- Step 4: Click Finish
- Step 5: Right click on the new finished project
and choose Properties
- Step 6: Click on the tab
- Step 7: Replace < enter your include search
path here> with the absolute path to the location where your
Empress include directory is located [e.g.
C:\Empress_VxWorks6_9\xtarget\vx-sim\include].
- Step 8: Click OK.
- Step 9: If required, use the Up tab,
to ensure that this path is specified first.
- Step 10: Click tab and then Yes
tab when prompted.
- Step 11: Click on the tab and
choose New-> File
- Step 12: Fill in the name of the file (e.g.
hello.c) and click OK
- Step 13: Copy and paste from the sample program
[e.g. hello.c]
- Step 14: Click on Project tab
- Step 15: Click on Build Project tab
Congratulations, you have created your first Empress sample
project.
How to Run Sample Programs
There are several ways of starting and running the sample
programs using the VxWorks Simulator. They all result in a
command-line window that runs the simulator. This is one of them
using the VxWorks 6.9 Development Shell.
- Step 1: From the VxWorks Workbench Explorer
pane, right click on the Image project and then left
click on Open Window River VxWorks 6.9 Development Shell.
- Step 2: Change directory in the ‘default’ [e.g.
cd default].
- Step 3: Make a directory called “Empress” [e.g.
mkdir Empress]
- Step 4: Change to the Empress directory [e.g.
cd Empress]
- Step 5: Copy sample.ex to this directory [e.g.
copy c:\Empress_VxWorks6.9\samples\sampledb.ex sampledb.ex]
- Step 6: Copy libultra-10.20-F.123.out to this
directory [e.g. copy
c:\Empress_VxWorks6.9\xtarget\vx-sim\load_modules\libultra-10.20-F.123.out
libultra-10.20-F.123.out]
- Step 7: Copy Sample.out to this directory [e.g.
copy ..\..\..\Sample\SIMNTdiab\Sample\Debug\Sample.out
Sample.out]
- Step 8: Change up one directory [e.g. cd ..]
- Step 9: Run vxsim from this location.
3 shows the screen when vxsim is invoked.
Figure 3: VxWorks
Simulator vxsim
The following steps involve running shell commands via the
VxWorks command shell. The actual syntax is prefaced with an
arrow ( 
).
• Step 10: Change to the Empress directory
cd “Empress”
• Step 11: Load ‘out’ files
ld < libultra-10.20-F.123.out
ld < Sample.out
• Step 12: Create an empty database, “sampledb”
using empmkdb utility function.
empmkdb “sampledb”
• Step 13: Import data into sampledb from the
database export file on the host.
empimpt “sampledb.ex”, “sampledb”
If the device being operated on is persistent, such as a virtual
disk, then you do not need to run steps 12 and 13 more than one
time.
• Step 14: Execute entry point (For hello.c the entry
point is known as myhello)
myhello()
Instead of Summary
The Wind River VxWorks Simulator is a great choice to develop
applications in parallel or before the target hardware is
available. Empress Ultra Embedded V10.20 offers many rich and
efficient database features that go beyond what a typical
embedded database may offer. Building these features into a
VxWorks database application in the simulator environment is no
different than building them into any VxWorks cross-development
environment using a standard board support package (BSP).
Empress Software Inc.
www.empress.com
