Installing and Configuring Qt 4.8.3 on VxWorks 6.8: A Complete Guide

A complete guide to installing and configuring Qt 4.8.3 on VxWorks 6.8

1. Introduction

#

This article describes how to install and configure Qt on the VxWorks 6.8 real-time operating system. It walks through the full procedure and includes the detailed steps required to build and run a Qt demo both on the vxsim simulator and on a real target board.

Qt for VxWorks is a commercial, embedded port of Qt 4.8.3 that targets the Wind River Media Library (WindML) graphics stack. The same source tree is used for both the simulator and the hardware target, but the directory layout, configure options, and runtime install prefix must be kept separate so the two builds do not overwrite each other.

2. Development Environment and Tools

#

Prepare the following tools before you start:

Notes:

• Strawberry Perl download: http://strawberryperl.com
• MinGW download: http://sourceforge.net/projects/mingw/files
• The Qt for VxWorks package and VxWorks 6.8 must be purchased through the appropriate commercial channels.

MinGW supplies the host g++ toolchain that Qt’s win32-g++ platform uses while generating the cross build. Strawberry Perl is required by Qt’s configure and qmake scripts. Both must be on PATH before you configure Qt.

3. Installing and Configuring the Development Environment

#

3.1 Install Workbench 3.2

#

Follow the official VxWorks 6.8 installation manual and complete the setup step by step. That procedure is not repeated here.

After installation you should have a working Wind River installation (paths in this guide assume D:\WindRiver) and a Workbench workspace under that tree.

3.2 Install MinGW

#

Extract MinGW, double-click MinGW-5.1.6.exe, and install with the default options. Installing on the C: drive is recommended.

3.3 Install Strawberry Perl

#

Double-click strawberry-perl-5.18.1.1-32bit.exe and install with the default options. Installing on the C: drive is recommended.

After installation, add the following directories to the system Path environment variable:

C:\MinGW\bin;C:\strawberry\c\bin;C:\strawberry\perl\site\bin;C:\strawberry\perl\bin

Open a new command prompt afterward and confirm that both g++ --version and perl -v resolve to these installations. An existing Perl or MinGW earlier on PATH will cause configure to pick the wrong tools.

3.4 Install Qt 4.8.3

#

1. Extract Qt-vxworks-commercial-src-4.8.3.zip.
2. Copy the extracted tree into the Wind River Workbench workspace directory.
3. Rename the directory according to the target you are building for:
   • For testing on the vxsim simulator: rename it to qtsimdkm
   • For use on a target board: rename it to qtp4dkm

Keeping two independent source trees prevents a simulator configuration from leaking into a board cross-compile (and the other way around). The dkm suffix indicates a downloadable kernel module build, which matches how the resulting Qt application is loaded on VxWorks.

Set the environment variables

#

• vxsim development: append the following to Path:

D:\WindRiver\workspace\qtsimdkm\bin

• Target-board development: append the following to Path:

D:\WindRiver\workspace\qtp4dkm\bin

Important: do not put both of these paths on PATH at the same time. qmake and the generated Makefiles must come from the tree you are actually building, or the wrong platform mkspec will be picked up.

Adjust the drive letter if your Wind River installation is not on D:.

4. Developing a Qt Application on the vxsim Simulator

#

The simulator path uses the SIMPC CPU and a RAM disk mounted at /tmpram. Qt is configured as a static, embedded QWS build and installed under the prefix /tmp/qtsimdkm.

4.1 Build the WindML Libraries

#

Follow the official manual Wind River Media Library SDK Programmer’s Guide 5.3 and configure and build WindML using the standard procedure. For this step, select the CPU SIMPC.

WindML is the graphics and input layer that Qt for VxWorks draws through. Qt will not link or run until a SIMPC WindML library that matches this image project has been built and is visible to the kernel configuration.

4.2 Create a VxWorks Image

#

Using the vxsim simulator as the example:

1. In Workbench 3.2, choose File → New → VxWorks Image Project.
2. Create a simulator image project named zvipsim.

After the project has been created, double-click Kernel Configuration and add the following component bundles:

INCLUDE_WINDML
INCLUDE_POSIX_ADVISORY_FILE_LOCKING
INCLUDE_POSIX_FTRUNC
INCLUDE_POSIX_MQ
INCLUDE_POSIX_MEM
INCLUDE_POSIX_SCHED
INCLUDE_POSIX_SEM
INCLUDE_POSIX_PTHREADS
INCLUDE_POSIX_PTHREAD_SCHEDULER
NUM_FILES=200
RTP_FD_NUM_MAX=200
INCLUDE_MMAP # Note: this bundle does not exist in VxWorks 6.8
INCLUDE_POSIX_MAPPED_FILES
INCLUDE_HRFS
INCLUDE_HRFS_FORMAT
HRFS_DEFAULT_MAX_BUFFER=1024
HRFS_DEFAULT_MAX_FILES=200
INCLUDE_XBD_RAMDRV
INCLUDE_XBD_PART_LIB

These components matter for a few distinct reasons:

• INCLUDE_WINDML pulls in the media library the Qt QWS driver depends on.
• The INCLUDE_POSIX_* set (message queues, semaphores, pthreads, mapped files, advisory locking, and ftruncate) covers the POSIX subset Qt’s embedded port expects.
• NUM_FILES and RTP_FD_NUM_MAX are raised because a static Qt application opens more descriptors than the default image allows.
• HRFS plus the XBD RAM disk driver provide a writable filesystem. QT_QWS_TEMP_DIR is later pointed at that disk.

INCLUDE_MMAP is listed only for completeness. It is not present in VxWorks 6.8, so do not try to enable it. INCLUDE_POSIX_MAPPED_FILES is the component that actually applies on this release.

Then add the following code to usrAppInit.c. It creates and formats a RAM disk when the system boots, which Qt uses as its temporary directory:

/* for QT */
#include "stdio.h"
#include "hrFsLib.h"
#include "xbdPartition.h"
#include "xbdRamDisk.h"

#define DEVNAME "/tmpram" /* name of the RAM disk */
#define BLOCKSIZE 512
#define DISKSIZE (BLOCKSIZE * 10000)
/* end of QT */

void usrAppInit (void)
{
#ifdef USER_APPL_INIT
USER_APPL_INIT; /* for backwards compatibility */
#endif

/* add application specific code here */

/* for QT ----------------- */
STATUS error;
device_t xbd;

xbd = xbdRamDiskDevCreate(BLOCKSIZE, DISKSIZE, 0, DEVNAME);
if (xbd == NULLDEV)
{
printf("**Failed to create RAM disk\n");
return;
}
printf("RAM disk created OK\n");

error = hrfsFormat(DEVNAME, DISKSIZE, BLOCKSIZE, 1000);
if (error != OK)
{
printf("**failed to format RAM disk, errno=0x%0x\n", error);
return;
}
printf("RAM create and format OK\n");
/* end of QT --------------------- */
}

The disk is about 5 MB (512 * 10000 bytes), named /tmpram, and formatted as HRFS with room for 1000 files. On a successful boot the shell should print both RAM disk created OK and RAM create and format OK. If formatting fails, check that INCLUDE_HRFS, INCLUDE_HRFS_FORMAT, INCLUDE_XBD_RAMDRV, and INCLUDE_XBD_PART_LIB are all included in the image.

After the configuration above is complete, build the image. Once the build succeeds, open the VxWorks 6.8 Development Shell, change into the zvipsim/default directory, and run:

vxsim --size 800M

This starts the simulator with 800 MB of simulated memory, which is enough for a static Qt demo plus the RAM disk.

4.3 Configure Qt

#

In the VxWorks 6.8 Development Shell, change into the qtsimdkm directory and run configure:

configure -confirm-license -embedded -platform win32-g++ \
-xplatform qws/vxworks-simdkm-g++ \
-exceptions -qt-freetype -qt-zlib -qt-libpng -qt-libtiff \
-qt-libjpeg -qt-libmng -no-qt3support -no-openssl \
-nomake examples -nomake docs -nomake translations \
-no-script -no-webkit \
-prefix /tmp/qtsimdkm -static -release \
-D QT_QWS_TEMP_DIR=\\\"/tmpram\\\" -make make

Notes: anything you would normally tune for a specific machine should be adjusted to match the actual development environment. The command above is the vxsim configuration. For an x86 target board, change:

• -xplatform qws/vxworks-Pentium4dkm-g++
• -prefix /ata0a/tmp/qtp4dkm

What the important switches do:

When configure finishes, it writes a Makefile in the qtsimdkm directory. Change into that directory and run make to compile (this typically takes 10 to 20 minutes).

After a successful build, copy everything under workspace\qtsimdkm\lib to C:\tmp\qtsimdkm\lib. For a target-board build, copy the libraries to /ata0a/tmp/qtp4dkm/lib on the target hard disk instead.

The host copy under C:\tmp\qtsimdkm\lib is what the simulator sees through the host filesystem mapping that corresponds to the /tmp/qtsimdkm prefix. If Qt later fails to find plugins or font data, confirm that this directory layout matches the prefix passed to configure.

4.4 Build and Run a Qt Program

#

1. In the VxWorks Development Shell, change into the qtsimdkm\demos\affine directory and run make. This produces the executable affine.

2. Copy the resulting affine file into the simulator image directory workspace\zvipsim\default.
3. Start the simulator:

vxsim --size 800M

4. In the vxsim0 shell, run:

ld < affine
taskSpawn("main", 200, 0x01000000, 0x100000, main, 0, 0, 0, 0, 0)

ld < affine loads the module into the kernel. taskSpawn then starts the main entry point as a task named main, at priority 200, with the VX_FP_TASK option (0x01000000, required because Qt uses floating point) and a 1 MB stack (0x100000). The five trailing zeros are unused arguments to main.

You should then see the Qt demo running.

At this point Qt is running successfully on the VxWorks vxsim simulator.

If the window does not appear, check three things first: the boot log shows the RAM disk was created and formatted, WindML was built for SIMPC and included in this image, and only the qtsimdkm\bin directory (not the board tree) is on PATH.

5. Developing a Qt Application on a Target Board

#

The target path follows the same structure as the simulator path. The differences are the BSP and CPU, the Qt mkspec and install prefix, and how the finished module is downloaded to the board.

5.1 Build the WindML Libraries

#

Again follow Wind River Media Library SDK Programmer’s Guide 5.3 to configure and build WindML. Select the CPU that matches the target board. The board used for this article has an Intel ATOM CPU, so Pentium4 was selected.

The WindML CPU selection must match the VxWorks image project and the Qt -xplatform mkspec. A SIMPC WindML library cannot be reused on the board, and a Pentium4 library cannot be reused on vxsim.

5.2 Create a VxWorks Image

#

Create a VxWorks Image Project using the same steps as in Section 4.2. When you choose the CPU and BSP, use the BSP that actually belongs to the target board. After the project is created, add the same RAM-disk code to usrAppInit.c and include the same component bundles:

INCLUDE_WINDML
INCLUDE_POSIX_ADVISORY_FILE_LOCKING
INCLUDE_POSIX_FTRUNC
INCLUDE_POSIX_MQ
INCLUDE_POSIX_MEM
INCLUDE_POSIX_SCHED
INCLUDE_POSIX_SEM
INCLUDE_POSIX_PTHREADS
INCLUDE_POSIX_PTHREAD_SCHEDULER
NUM_FILES=200
RTP_FD_NUM_MAX=200
INCLUDE_MMAP # Note: this bundle does not exist in VxWorks 6.8
INCLUDE_POSIX_MAPPED_FILES
INCLUDE_HRFS
INCLUDE_HRFS_FORMAT
HRFS_DEFAULT_MAX_BUFFER=1024
HRFS_DEFAULT_MAX_FILES=200
INCLUDE_XBD_RAMDRV
INCLUDE_XBD_PART_LIB

After the image builds, download it to the target board over the network and confirm that it boots and runs correctly before you spend time on the Qt build. You should see the same RAM-disk success messages as on the simulator.

5.3 Configure Qt

#

In the VxWorks 6.8 Development Shell, change into the qtp4dkm directory and run:

configure -confirm-license -embedded -platform win32-g++ \
-xplatform qws/vxworks-Pentium4dkm-g++ \
-exceptions -qt-freetype -qt-zlib -qt-libpng -qt-libtiff \
-qt-libjpeg -qt-libmng -no-qt3support -no-openssl \
-nomake examples -nomake docs -nomake translations \
-no-script -no-webkit \
-prefix /ata0a/tmp/qtp4dkm -static -release \
-D QT_QWS_TEMP_DIR=\\\"/tmpram\\\" -make make

Compared with the simulator command, two values change:

• The cross mkspec is qws/vxworks-Pentium4dkm-g++, matching the Pentium4 / ATOM target.
• The install prefix is /ata0a/tmp/qtp4dkm, which is a path on the target hard disk rather than a host directory mapped into vxsim.

QT_QWS_TEMP_DIR stays /tmpram because temporary files still go to the RAM disk created at boot, not to the persistent disk that holds the libraries.

A successful configuration generates a Makefile in the qtp4dkm directory. Open a command prompt, change into that directory, and run make (about 10 to 20 minutes).

When the build finishes, copy the generated library files to /ata0a/tmp/qtp4dkm/lib on the target hard disk.

Boot the target over the network, create a remote connection in Workbench, and download the application at D:\WindRiver\workspace\qtp4dkm\demos\affine\affine to the target.

After the download completes, run the following from the host debugger shell or on the target itself:

taskSpawn("main", 200, 0x01000000, 0x100000, main, 0, 0, 0, 0, 0)

Unlike the simulator, the module has already been placed on the target by the remote download, so a separate ld < affine in this shell is not required if Workbench loaded it for you. If you copied affine onto the target filesystem yourself, load it with ld first, then spawn the task.

This starts the Qt program.

6. Quick Reference

#

Do not configure both trees in the same shell session. Remove the inactive tree from PATH, start a new Development Shell, and re-run configure if you switch from the simulator to the board.