Qt for VxWorks

Contact The Qt Company for more information: https://www.qt.io/contact-us/

Qt for VxWorks Licensing

Qt for VxWorks is available under the Qt for Device Creation Professional (DCP) license. For more information, see Qt Pricing.

Supported Architectures and VxWorks Releases

Qt 6.8 is verified on VxWorks 24.03.

Supported architectures:

  • ARM-v7—Tested on BD-SL-i.MX6. BSP used: fsl_imx6
  • x86_64—Tested on Intel NUC6i3SYH. BSP used: itl_generic

If you are interested in later Qt releases, please contact Qt professional services.

Requirements for VxWorks

Qt Widgets Applications

  • POSIX support
  • C++17 support

Qt Quick 2 Applications

All features which are required for Qt Widgets applications, and in addition the following:

  • GPU device (GPUDEV) for OpenGL ES 2.0

Supported Modules

Most essential Qt modules and some add-on modules are supported.

Supported Essential modules

Supported Add-Ons

Note: You can explicitly exclude unsupported or unused modules from the build via the -skip <module> option when running the configure tool.

Platform Notes

With the release of Qt 5.0, Qt no longer contains its own window system implementation: QWS is no longer a supported platform. For single-process use cases, the Qt Platform Abstraction is a superior solution.

There is one plugin that is usable on VxWorks: EGLFS. The availability of this plugins depends on the configuration of Qt.

Configuring for a Specific Device

Prepare your environment by installing VxWorks SDK and obtaining WindRiver license which is needed by installer and for building VxWorks images. Search for appropriate installer in {https://gallery.windriver.com/portal/products}.

Building Qt for a given device requires a Qt 6 installation for compilation host, a toolchain and a sysroot. Additionally, some devices require vendor specific adaptation code for EGL and OpenGL 2.0 support.

VxWorks Image Requirements

Qt for VxWorks requires certain VxWorks image bundles and components to be embedded in base software to make Qt compile and work properly. The list is by no means complete as it depends on hardware, software and system requirements of your project. However, the following table contains those that are mandatory for certain functionalities to work (including touchscreen support). Note also that these might change with VxWorks versions.

Example VSB configuration for the fsl_imx6 and itl_generic BSPs

You need to add the following features to VSB for Qt to work properly. For more details please check WindRiver VxWorks Documentation.

FeatureNotes
DSI_DSI_KERNEL
IPNET_COREIP
IPNET_DHCPC
SDMMC_DEVICE
SDMMC_HOST
SDMMC_SDHC
SDMMC_STORAGE
SERVICE_UN
SOCKET
USB_EHCI
USB_KEYBOARD
USB_MOUSE
USB_STORAGE
USB_TOUCHSCREEN
EVDEV
EVDEV_LIB
EVDEV_TI_TSC2004_TS
EVDEV_EETI_EXC7200_TS
AUDIO
GPUDEV_FSLVIVGPUfsl_imx6 specific
HASH
OPENSSL
RANDOM_ENTROPY_INJECT
IPNET_SSH
USER_MANAGEMENT
ICU
DRMitl_generic specific
ITLI915itl_generic specific
LIBDRMitl_generic specific
MESAitl_generic specific

The following config variables are added implicitly and you need to remove them:

VariableNotes
_WRS_CONFIG_EVDEV_OPTIMIZED_MODE
_WRS_CONFIG_EVDEV_DISPLAY_POINT_TRANSLATE
_WRS_CONFIG_MESA_MANGLEitl_generic specific

You need to add the following variables to the config:

VariableValueNotes
_WRS_CONFIG_RTP_SSPy
_WRS_CONFIG_RTP_STACK_PROTECTORy
_WRS_CONFIG_MESA_GPUDEV_INTEL_GEN90yitl_generic specific
_WRS_CONFIG_EVDEV_COMPATIBLE_MODEyNeeded in order for Qt to work properly with a touchscreen.

Example VIP configuration for fsl_imx6 and itl_generic BSPs

For more details please check WindRiver VxWorks Documentation.

BundleNotes
BUNDLE_POSIXThis bundle is necessary for compatibility with POSIX-related functionalities which Qt requires.
BUNDLE_RTP_DEPLOY
BUNDLE_RTP_DEVELOP
BUNDLE_STANDALONE_SHELL
ComponentNotes
INCLUDE_TMP_DIR INCLUDE_RAM_DISK_FORMAT_HRFSIncluding these two components is necessary if you want to use QTemporaryFile. Note that you should also consider setting TMP_DIR_SIZE to appropriate value
DRV_AUDIO_FSL_SSI
DRV_AUDIO_FSL_SGTL5000
DRV_FSL_SDHC_CTRL
DRV_IMX_SDHC_CTRL
INCLUDE_EHCI_INIT
INCLUDE_FSL_IMX6Q_SABRELITE
DRV_MMCSTORAGE_CARD
DRV_SDSTORAGE_CARD
INCLUDE_AUDIO_LIB_CORE
INCLUDE_AUDIO_LIB_WAV
INCLUDE_CUSTOM_ENTROPY_ADD
INCLUDE_DEBUG_AGENT_START
INCLUDE_DEFAULT_TIMEZONE
INCLUDE_DISK_UTIL
INCLUDE_DOSFS
INCLUDE_DSAPARAM_CMD
INCLUDE_END
INCLUDE_EVDEV_LIB_CORE
INCLUDE_EVDEV_LIB_KBD
INCLUDE_EVDEV_LIB_KBD_MAP_US
INCLUDE_EVDEV_LIB_PTR
INCLUDE_EVDEV_LIB_TS
INCLUDE_GENDSA_CMD
INCLUDE_GENRSA_CMD
INCLUDE_GETADDRINFO
INCLUDE_GETNAMEINFO
INCLUDE_HRFS
INCLUDE_HRFS_ACCESS_TIMESTAMP
INCLUDE_HRFS_FORMAT
INCLUDE_HRFS_HISPEED_WRITE_MODE
INCLUDE_IFCONFIG
INCLUDE_IO_REALPATHThis component is needed to enable the use of the realpath function needed for QFileInfo
INCLUDE_IPATTACH
INCLUDE_IPCOM_SYSLOGD_CMD
INCLUDE_IPCOM_SYSVAR_CMD
INCLUDE_IPCOM_USE_RAM_DISK
INCLUDE_IPCOM_USE_TIME_CMD
INCLUDE_IPDHCPC
INCLUDE_IPDNSC
INCLUDE_IPD_CMD
INCLUDE_IPFTPC
INCLUDE_IPFTP_CMD
INCLUDE_IPIFCONFIG_CMD
INCLUDE_IPNETSTAT_CMD
INCLUDE_IPNSLOOKUP_CMD
INCLUDE_IPPING_CMD
INCLUDE_IPROUTE_CMD
INCLUDE_IPTRACE_ROUTE_CMD
INCLUDE_IPWRAP_GETHOSTBYADDR
INCLUDE_IPWRAP_GETHOSTBYNAME
INCLUDE_IPWRAP_GETNAMEINFO
INCLUDE_IPWRAP_IFNAME
INCLUDE_IPWRAP_ROUTECMD
INCLUDE_MMAP
INCLUDE_PING
INCLUDE_PIPES
INCLUDE_POSIX_MAPPED_FILES
INCLUDE_POSIX_PIPES
INCLUDE_POSIX_PTHREAD_SCHEDULER
INCLUDE_POSIX_SHM
INCLUDE_RAM_DISK
INCLUDE_RAM_DISK_FORMAT_HRFS
INCLUDE_RANDOM_NUM_GEN
INCLUDE_ROMFS
INCLUDE_ROUTECMD
INCLUDE_SC_PIPE
INCLUDE_SC_POSIX_PIPE
INCLUDE_SD_BUS
INCLUDE_SECURITY
INCLUDE_SEC_KEY_STORE_CMD
INCLUDE_SHELL
INCLUDE_SSH
INCLUDE_STANDALONE_SYM_TBL
INCLUDE_STARTUP_SCRIPT
INCLUDE_TMP_DIR
INCLUDE_UN_COMP
INCLUDE_USB_GEN2_KEYBOARD
INCLUDE_USB_GEN2_MOUSE
INCLUDE_USB_GEN2_STORAGE_INIT
INCLUDE_USB_TOUCH_SCREEN
INCLUDE_USB_TOUCH_SCREEN_INIT
INCLUDE_USER_DATABASE
INCLUDE_USER_IDENTIFICATION
INCLUDE_VRFS
INCLUDE_VXBUS_SHOW
DRV_TOUCH_SCREEN_TI_TSC2004
DRV_TOUCH_SCREEN_EETI_EXC7200
INCLUDE_FBDEV_FSLIPU_0fsl_imx6 specific
INCLUDE_FBDEV_SPLASH
INCLUDE_GPUDEV_FSLVIV_APIfsl_imx6 specific
INCLUDE_GPUDEV_FSLVIV_API_INITfsl_imx6 specific
INCLUDE_GPUDEV_ITLGMC_2itl_generic specific
INCLUDE_I915itl_generic specific
INCLUDE_MESA_FBDEVitl_generic specific
INCLUDE_MESA_GPUDEV_DRIitl_generic specific
INCLUDE_MESA_GPUDEV_DRI_I965itl_generic specific

The following components are added implicitly and you need to remove them:

LayerNotes
INCLUDE_FTP
INCLUDE_SHELL_SECURITY
VIP Parameters

You need to add the following parameters for Qt to run properly on VxWorks:

ParameterExample valueNotes
SEC_VAULT_KEY_ENCRYPTING_PW'"vxTarget"'Example value
UDB_STORAGE_PATH'"/ram/vxUserDB.txt"'Example value
UDB_HASH_KEY'"123456789"'Example value
UDB_HASH_KEY_LEN9Example value, see previous
FSLVIV_RTP_COMMAND_BUFFER_QUEUE32For 'arm' architecture
SYS_CLK_RATE100
RTP_PTHREAD_STACK_SIZE_DEFAULT262144Required to make qtquick3d examples work. Can be overridden with the PTHREAD_STACK_SIZE_DEFAULT env variable.
TMP_DIR_SIZE614400Minimum value for passing Qt internal tests
NUM_FILES300
RTP_FD_NUM_MAX300
HRFS_DEFAULT_MAX_FILES300
ITLGMC_FBDEV_RESOLUTION_2'"1024x768-32"'Example value for the Xenarc 706TSA touchscreen connected over HDMI.

Building Qt 6 for VxWorks

Building Qt 6 for Host

When cross-building Qt 6 for VxWorks, it's best practice to use host tools that use the same source code as cross-build does. This requires building Qt 6 for host first, but only with limited subset of submodules:

  • qtbase
  • qtdeclarative
  • qtquick3d
  • qtshadertools

Make sure to have all necessary prerequisites for building Qt 6 for host. Check details in Building Qt Sources.

Running the Configure Script

The commands to configure, build, and install Qt 6 for host are the following:

./configure \
    -cmake-generator "Ninja" \
    -extprefix <path/to/Qt6/host/installation/dir> \
    -submodules qtbase,qtdeclarative,qtquick3d,qtshadertools \
    -nomake tests \
    -nomake examples \
    -- \
    -B <host/build/directory>
cd <host/build/directory>
ninja
ninja install

These commands install Qt 6 for the host in <path_to_Qt 6_host_installation_dir>.

Building Qt 6 for the Target

Setting Up the Build Environment

Before you run configure and build Qt 6, you must open VxWorks Development Shell in command prompt.

  • Linux:
    cd <VxWorks installation directory>
    ./wrenv.sh -p vxworks
    export WIND_CC_SYSROOT=<path to VxWorks VSB directory>
  • Windows:
    cd <VxWorks installation directory>
    wrenv -p vxworks
    export WIND_CC_SYSROOT=<path to VxWorks VSB directory>

Preparing the Custom CMake Toolchain File

To include graphics libraries from the BSP, you need to first create a CMake toolchain file. An example CMake toolchain file for BD-SL-i.MX6 device:

# Copyright (C) 2024 The Qt Company Ltd.
# SPDX-License-Identifier: BSD-3-Clause

if(QT_VXWORKS_TOOLCHAIN_FILE)
    set(_original_toolchain_file "${QT_VXWORKS_TOOLCHAIN_FILE}")
elseif(DEFINED ENV{QT_VXWORKS_TOOLCHAIN_FILE})
    set(_original_toolchain_file "$ENV{QT_VXWORKS_TOOLCHAIN_FILE}")
else()
    message(FATAL_ERROR "QT_VXWORKS_TOOLCHAIN_FILE is not set.")
endif()

if(NOT EXISTS "${_original_toolchain_file}")
    message(FATAL_ERORR "${_original_toolchain_file} doesn't exists.")
endif()

include("${_original_toolchain_file}")
unset(_original_toolchain_file)

list(APPEND CMAKE_TRY_COMPILE_PLATFORM_VARIABLES QT_VXWORKS_TOOLCHAIN_FILE)

set(_common_lib_path "${CMAKE_SYSROOT}/usr/lib/common")
set(EGL_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to EGL include directory" FORCE)
set(EGL_LIBRARY ${_common_lib_path}/libgfxFslVivEGL.so CACHE PATH "Path to EGL lib" FORCE)
set(GLESv2_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to GLES include directory" FORCE)
set(GLESv2_LIBRARY ${_common_lib_path}/libgfxFslVivGLESv2.so CACHE PATH "Path to GLES lib" FORCE)

set(VxWorksPlatformGraphics_DEFINES "-D_FSLVIV")
set(VxWorksPlatformGraphics_LIBRARIES_PACK
    "${_common_lib_path}/libgfxFslVivGAL.so"
    "${_common_lib_path}/libgfxFslVivGLSLC.so"
    "${_common_lib_path}/libgfxFslVivVDK.so"
    "${_common_lib_path}/libxml.so"
)

set(VxWorksPlatformGraphics_REQUIRED_LIBRARIES
    ${VxWorksPlatformGraphics_LIBRARIES_PACK}
    ${EGL_LIBRARY}
    ${GLESv2_LIBRARY}
)
unset(_common_lib_path)

An example for Intel NUC6i3SYH:

# Copyright (C) 2024 The Qt Company Ltd.
# SPDX-License-Identifier: BSD-3-Clause

if(QT_VXWORKS_TOOLCHAIN_FILE)
    set(_original_toolchain_file "${QT_VXWORKS_TOOLCHAIN_FILE}")
elseif(DEFINED ENV{QT_VXWORKS_TOOLCHAIN_FILE})
    set(_original_toolchain_file "$ENV{QT_VXWORKS_TOOLCHAIN_FILE}")
else()
    message(FATAL_ERROR "QT_VXWORKS_TOOLCHAIN_FILE is not set.")
endif()

if(NOT EXISTS "${_original_toolchain_file}")
    message(FATAL_ERORR "${_original_toolchain_file} doesn't exists.")
endif()

include("${_original_toolchain_file}")
unset(_original_toolchain_file)

list(APPEND CMAKE_TRY_COMPILE_PLATFORM_VARIABLES QT_VXWORKS_TOOLCHAIN_FILE)

set(_common_lib_path "${CMAKE_SYSROOT}/usr/lib/common")
set(EGL_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to EGL include directory" FORCE)
set(EGL_LIBRARY ${_common_lib_path}/libgfxMesaEGL.so CACHE PATH "Path to EGL lib" FORCE)
set(GLESv2_INCLUDE_DIR ${CMAKE_SYSROOT}/usr/h/public CACHE PATH "Path to GLES include directory" FORCE)
set(GLESv2_LIBRARY ${_common_lib_path}/libgfxMesaGL.so CACHE PATH "Path to GLES lib" FORCE)

set(VxWorksPlatformGraphics_DEFINES "-D__vxworks -D__VXWORKS")
set(VxWorksPlatformGraphics_LIBRARIES_PACK
    "${_common_lib_path}/libgfxMesaSw.so"
    "${_common_lib_path}/libgfxMesa.so"
    "${_common_lib_path}/libgfxMesaDriI965.so"
    "${_common_lib_path}/libgfxLibDRM.so"
    "${_common_lib_path}/libxml.so"
)

set(VxWorksPlatformGraphics_REQUIRED_LIBRARIES
    ${VxWorksPlatformGraphics_LIBRARIES_PACK}
    ${EGL_LIBRARY}
    ${GLESv2_LIBRARY}
)
unset(_common_lib_path)

Running Qt 6 Configure for the Target

Below is an example build configuration for the BD-SL-i.MX6. For most VxWorks boards the configure command looks very similar. By default, Qt 6 is configured to use shared libraries. To build Qt 6 statically, add -static option to configure.

Make sure that {WIND_CC_SYSROOT} environment variable is set to VxWorks VSB root directory.

./configure \
    -cmake-generator "Ninja" \
    -icu \
    -eglfs \
    -qpa eglfs \
    -submodules "qtbase,qtdeclarative,qtmultimedia,qtquick3d,qtgraphs,qtimageformats,qtsvg,qtshadertools,qtvirtualkeyboard" \
    -- \
    -B <target/build/directory> \
    -DQT_VXWORKS_TOOLCHAIN_FILE=<path/to/VSB/mk/toolchain.cmake> \
    -DFEATURE_vulkan=OFF \
    -DQT_QMAKE_TARGET_MKSPEC=vxworks-clang \
    -DQT_HOST_PATH=<path/to/Qt6/host/installation/dir> \
    -DCMAKE_STAGING_PREFIX:PATH=<path/to/Qt6/target/installation/dir> \
    -DCMAKE_TOOLCHAIN_FILE=<path/to/cmake/for/graphics/file/created/above> \

In case of building for DKM rather than RTP, use -static option and change the CMAKE_TOOLCHAIN_FILE value to "$WIND_CC_SYSROOT/mk/dkm.toolchain.cmake"

It is recommended to build Qt 6 using a shadow build. See Qt Configure Options for more information.

After configuration, build and install Qt 6 for VxWorks with these commands:

cd <host build directory>
ninja
ninja install

Platform Plugins for VxWorks Devices

Qt for VxWorks supports EGLFS platform plugin for a native window substitution. Read more about its configuration in EGLFS.

Building Qt Applications

To build a Qt application, you must set the QT_VXWORKS_TOOLCHAIN_FILE as an environment variable or as a define.

An example to build the clocks Qt demo:

export WIND_CC_SYSROOT=<path/to/VxWorks/VSB/directory>
export QT_VXWORKS_TOOLCHAIN_FILE=<path/to/the/BSP/toolchain.cmake>
<path/to/Qt6/target/installation/dir>/bin/qt-cmake -G Ninja -S ~/Qt/Examples/Qt-6.9.0/demos/clocks -B <path/to/build/directory>
cd <path/to/build/directory>
ninja

Running Qt Applications

The following example shows how to start an application when Qt 6 is built using shared libraries. With a statically built Qt 6, you don't need to use the LD_LIBRARY_PATH environment variable for the Qt libraries, but it needs to point to the location of VxWorks shared libraries (for example libc and OpenGL ES 2.0). It is not needed for Qt 6 static libraries.

putenv "LD_LIBRARY_PATH=/sd0:1/lib"
cd "/sd0:1"
rtpSp("<Qt 6 VxWorks application>", 200, 0x100000, 0, 0x01000000)

Debugging Qt Applications

To debug Qt Applications, you must add the following to your VxWorks VSB:

vxprj vsb config -s -add "_WRS_CONFIG_TCF_GDB_RSP=y"

To your VxWorks VIP configuration add:

"INCLUDE_DEBUG_AGENT"
"INCLUDE_DEBUG_AGENT_START"
"INCLUDE_STANDALONE_SYM_TBL"

From the Command Line

  1. Start the application to debug on the device through SSH or the USB serial connection:
    rtpSp("<Qt 6 VxWorks application>", 200, 0x100000, 0, 0x01000000)
  2. Start the VxWorks debugger on the PC:
    vxgdb <binary to debug>
  3. List the running processes in the debugger:
    monitor ps
  4. Attach the debugger to the already running application:
    "attach <id from monitor>"
  5. Use GDB commands for debugging.

From Workbench

  1. Create a CMake Real Time Process project.

    "Select cmake RTP project"

  2. Set the VSB which has debugging configured.
  3. Remove set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -static") from CMakeLists.txt.
  4. Add Qt CMake related code to the CMakeLists.txt following Getting started with CMake.
  5. Before project() add unset(CMAKE_TOOLCHAIN_FILE CACHE) and add CMAKE_TOOLCHAIN_FILE pointing to the Qt6 toolchain file and QT_CHAINLOAD_TOOLCHAIN_FILE to the VSB toolchain file. For example:
    unset(CMAKE_TOOLCHAIN_FILE CACHE)
    set(CMAKE_TOOLCHAIN_FILE "/home/qtuser/VxWorks/qt/target_gdb/lib/cmake/Qt6/qt.toolchain.cmake")
    set(QT_CHAINLOAD_TOOLCHAIN_FILE "/home/qtuser/VxWorks/fsl_imx6_2_0_6_2_VSB_gdb/mk/toolchain.cmake")
  6. Build the application Project.
  7. Create a New Connection.

    "Connection to the device"

  8. Start RTP process to debug.

    "Select Run/Debug Real Time Process"

  9. Click on Advanced options.

    "Run settings"

  10. Set the stack size to 0x100000.

    "Advanced settings"

Limitations

Video Memory

Systems with a fixed amount of dedicated video memory may need extra care before running Qt application based on Qt Quick or classes like QOpenGLWidget. The default setting might be insufficient for such applications, especially when they are displayed on a high resolution (for example, full HD) screen. In this case they might start failing in unexpected ways. It is therefore recommended to ensure that there is at least 128 MB of GPU memory available. For systems that do not have a fixed amount of memory reserved for the GPU this is not an issue.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.