path: root/doc/src/platforms/vxworks.qdoc

/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
  \page vxworks.html
  \title Qt for VxWorks
  \brief Platform support for VxWorks.
  \keyword VxWorks
  \ingroup supportedplatform

  Qt for VxWorks is available only under a commercial license.

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

  \section1 Supported Architectures and VxWorks Releases

  \list
    \li Qt 5.5 was verified on VxWorks 7 release SR0480 2016-09-16.
    Supported architecture is ARM-v7.
    \note Qt 5.5 is no longer supported.
    \li Qt 5.9 LTS was verified on VxWorks 7 SR0541.
    \note Support for Qt 5.9 ends May 2020.
    \li 5.12 LTS is verified on VxWorks 7 SR0541. Qt 5.12 is supported until
    December 2021.
  \endlist

  If you are interested in later Qt releases, please \l {https://www.qt.io/contact-us/}{contact} Qt professional services.

  \section1 Qt for VxWorks Source Package

  Qt for VxWorks is delivered via the \l {Qt Account}, under the name
  \b {Qt 5.5.1} > \b {Qt VxWorks Platform Source Package}.
  \note Qt 5.5 is no longer supported.

  Source packages for up-to-date and supported Qt releases on VxWorks are
  available through Qt Professional Services.

  \section1 Requirements for VxWorks

  \section2 QtWidget Applications

  \list
  \li Framebuffer device (FBDEV)
  \li Evdev support (compatibility mode)
  \li POSIX support
  \li C++11 support
  \endlist

  \section2 Qt Quick 2 Applications

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

  \list
  \li GPU device (GPUDEV) for OpenGL ES 2.0
  \endlist

  \section1 Supported Modules

  Almost all essential \l{All Modules}{Qt modules} and some add-on modules supported.

  \section2 Limitations for Essential modules

  \table 80%
  \header
      \li Qt Module
      \li Supported Features
      \li Notes

  \row
      \li \l {Qt Multimedia}
      \li Audio
      \li \l [QML] {QtMultimedia::SoundEffect}{SoundEffect},
          \l [QtMultimedia] {QSound},
          \l [QtMultimedia] {QSoundEffect} and
          \l [QtMultimedia] {QAudioOutput}

  \row
      \li \l {Qt Multimedia Widgets}
      \li Not supported
      \li

  \row
      \li Qt WebKit
      \li Not supported
      \li

  \row
      \li Qt WebKit Widgets
      \li Not supported
      \li

  \endtable

  \section2 Supported Add-ons

  \table 80%
  \header
      \li Qt Add-on
      \li Notes
  \row
      \li \l {Qt Charts}
      \li Version 2.0.1
  \row
      \li \l {Qt Data Visualization}
      \li Version 1.2.1
  \row
      \li \l {Qt Virtual Keyboard}
      \li Version 2.0
  \row
      \li \l {Qt Quick Compiler}
      \li Version 3.0
  \row
      \li \l {Qt Concurrent}
      \li
  \row
      \li \l {Qt Graphical Effects}
      \li
  \row
      \li \l {Qt Image Formats}
      \li
  \row
      \li \l {Qt OpenGL}
      \li Only OpenGL ES 2 \note Provided to ease porting from Qt 4.x.
      Use the QOpenGL classes in \l{Qt GUI} for new code
  \row
      \li \l {Qt Platform Headers}
      \li
  \row
      \li \l {Qt SVG}
      \li
  \row
      \li \l {Qt XML Patterns}
      \li
  \endtable

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

  \section1 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 \l{Qt Platform Abstraction} is a superior solution.

  There are two platform plugins that are usable on VxWorks: EGLFS and VxWorksFB.
  The availability of these plugins depends on the configuration of Qt. The default
  platform plugin is also device-specific. For instance, on many boards \c eglfs will be
  chosen as the default one. If the default is not suitable, the \c QT_QPA_PLATFORM
  environment variable parameter can be used to request another plugin.
  Alternatively, for quick tests, the \c -platform command-line option can be used
  with the same syntax.

  \section1 Configuring for a Specific Device

  Building Qt for a given device requires a toolchain and a
  sysroot. Additionally, some devices require vendor specific adaptation code
  for EGL and OpenGL ES 2.0 support. This is not relevant for non-accelerated
  platforms, for example the ones using the VxWorksFB plugin, however neither
  OpenGL nor Qt Quick 2 will be functional in such a setup.

  The directory \e qtbase/mkspecs/devices contains configuration and graphics
  adaptation code for a number of devices. For example, \c vxworks-imx6
  contains build settings, such as the optimal compiler and linker flags, for
  the \l {http://en.wikipedia.org/wiki/I.MX#i.MX6x_series}{Freescale iMX6 series},
  and either an implementation of the eglfs hooks (vendor-specific adaptation code),
  or a reference to a suitable eglfs device integration plugin. The device is
  selected through the \l{Qt Configure Options}{configure} tool's \c -device
  parameter. The name that follows after this argument must, at least partially,
  match one of the subdirectories under \e devices.

  Before running configure and building Qt 5 it is required to open \e {VxWorks 7
  Development Shell} in command prompt.

  \list
  \li Linux:
  \badcode
  cd <VxWorks 7 installation directory>
  ./wrenv.sh -p vxworks-7
  \endcode

  \li Windows:
  \badcode
  cd <VxWorks 7 installation directory>
  wrenv -p vxworks-7
  \endcode
  \endlist

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

  \badcode
    ./configure -commercial -confirm-license -device vxworks-imx6 -device-option CROSS_COMPILE=arm -prefix /sd1:1/qt5rtp -sysroot <path_to_vxworks_vsb_dir>/fsl_imx6_1_1_11_0_VSB -no-gcc-sysroot -extprefix <path_to_host_dir>/qt5rtp -hostprefix <path_to_host_dir>/qt5rtp -no-openssl -nomake tools -nomake examples
  \endcode

  The most important parameters are \c -device, \c -device-option CROSS_COMPILE=<arch>,
  \c -sysroot and \c -no-gcc-sysroot. By specifying \c -sysroot, the include
  files and libraries used by \c {configure}'s feature detection tests, as well
  as Qt itself, will be taken from the specified location, instead of the host
  PC's standard locations. This means that installing development packages on the
  host machine has no relevance. Instead, the headers and the libraries for the
  target architecture (e.g. ARM) have to be present in the sysroot.

  It is recommended to build Qt 5 using a \e{shadow build}. See \l {Qt Configure Options}
  for more information.

  \section1 Building and Installing Qt 5

  \badcode
  make -j<N>
  make install
  \endcode

  \section1 Platform Plugins for VxWorks Devices

  \section2 EGLFS

  \l {http://www.khronos.org/egl}{EGL} is an interface between OpenGL and the
  native windowing system. Qt can use EGL for context and surface management,
  however the API contains no platform specifics: The creation of a \e {native
  window} (which will not necessarily be an actual window on the screen) must
  still be done by platform-specific means. Hence the need for the board or GPU
  specific adaptation code. Such adaptations are provided either as \e {eglfs
  hooks}, a single source file compiled in to the platform plugin, or as
  dynamically loaded \e {EGL device integration} plugins.

  EGLFS is a platform plugin for running Qt 5 applications on top of EGL and
  OpenGL ES 2.0 without an actual windowing system (like X11 or Wayland). In
  addition to Qt Quick 2 and native OpenGL applications it supports
  software-rendered windows (for example QWidget) too. In the latter case the
  widgets' contents are rendered using the CPU into images which are then
  uploaded into textures and composited by the plugin.

  This is the recommended plugin for modern VxWorks devices that include
  a GPU.

  EGLFS forces the first top-level window (be it either a QWidget or a
  QQuickView) to become fullscreen. This window is also chosen to be the \e root
  widget window into which all other top-level widgets (for example dialogs,
  popup menus or combobox dropdowns) are composited. This is necessary because
  with EGLFS there is always exactly one native window and EGL window surface,
  and these belong to the widget or window that is created first. This approach
  works well when there is a main window that exists for the entire lifetime of
  the application and all other widgets are either non top-levels or are created
  afterwards, once the main window is shown.

  There are further restrictions for OpenGL-based windows. As of Qt 5.3, eglfs
  supports a single, fullscreen GL window (for example, an OpenGL-based QWindow,
  a QQuickView or a QGLWidget). Opening additional OpenGL windows or mixing such
  windows with QWidget-based content is not supported and will terminate the
  application with an error message.

  If necessary, eglfs can be configured via environment variables:

  \list

  \li \c {QT_QPA_EGLFS_FB} - Overrides the framebuffer device. The default is
  \c /dev/fb0. On most embedded platforms this is not very relevant because the
  framebuffer is used only for querying settings like the display dimensions.
  On certain devices however this parameter provides the ability to specify
  which display to use in multiple display setups, similarly to the \c fb
  parameter in VxWorksFB.

  \li \c {QT_QPA_EGLFS_WIDTH} and \c {QT_QPA_EGLFS_HEIGHT} - Contain the screen
  width and height in pixels. While eglfs will try to determine the dimensions
  from the framebuffer device \e{/dev/fb0}, this will not always work and
  manually specifying the sizes may become necessary.

  \li \c {QT_QPA_EGLFS_PHYSICAL_WIDTH} and \c {QT_QPA_EGLFS_PHYSICAL_HEIGHT} -
  Physical screen width and height in millimeters. On platforms where the
  framebuffer device \e{/dev/fb0} is not available or the query is not
  successful, the values are calculated based on a default DPI of 100. This
  variable can be used to override any such defaults.

  \li \c {QT_QPA_EGLFS_DEPTH} - Overrides the color depth for the screen. On
  platforms where the framebuffer device \e{/dev/fb0} is not available or the
  query is not successful, the default of 32 is used. This variable can be used
  to override any such defaults. Note that this affects only the color depth
  value reported by QScreen. It has no connection to EGL configurations and the
  color depth used for OpenGL rendering.

  \li \c {QT_QPA_EGLFS_SWAPINTERVAL} - By default a swap interval of \c 1 will
  be requested. This enables synchronizing to the displays vertical refresh. The
  value can be overridden with this environment variable. For instance, passing
  0 will disable blocking on swap, resulting in running as fast as possible
  without any synchronization.

  \li \c {QT_QPA_EGLFS_FORCE888} - When set, the red, green and blue color
  channel sizes are ignored whenever creating a new context, window or offscreen
  surface. Instead, the plugin will request a configuration with 8 bits per
  channel. This can be helpful on devices where configurations with less than 32
  or 24 bits per pixel are chosen by default but are known not to be suitable,
  for example, due to banding effects. Instead of changing all the applications,
  this variable provides an easier shortcut to force 24/32 bpp configurations
  for a given device.

  \li \c {QT_QPA_EGLFS_DEBUG} - When set, some debugging information is printed
  on the debug output. For example, the input QSurfaceFormat and the properties
  of the chosen EGL configuration are printed whenever creating a new
  context. Together with Qt Quick's \c {QSG_INFO} variable, this can provide
  useful information for troubleshooting issues related to the EGL
  configuration.

  \li \c {QT_QPA_EGLFS_INTEGRATION} - In addition to the compiled-in \e hooks,
  it is also possible to provide device or vendor-specific adaptation in the
  form of dynamically loaded plugins. This environment variable enforces a
  specific plugin. For example, setting it to \e{eglfs_kms} will use the KMS/DRM
  backend. This is only an option when no static, compiled-in hooks were
  specified in the device makespecs. In practice the traditional compiled-in
  hooks are rarely used, almost all backends are now migrated to plugins. The
  device makespecs still contain a relevant \c EGLFS_DEVICE_INTEGRATION entry:
  the name of the preferred backend for that particular device. This is
  optional, but very useful to avoid the need to set this environment variable
  in case there are more than one plugins present in the target system. In a
  desktop environment the KMS or the X11 backends are prioritized, depending on
  the presence of the \c DISPLAY environment variable.

  \endlist

  In addition to \c {QT_QPA_EGLFS_DEBUG}, eglfs also supports the more modern
  categorized logging system of Qt. The following logging categories are
  available:

  \list

    \li \c qt.qpa.egldeviceintegration – Enables logging for dynamically loaded
    backends. Very useful to check what backend is in use.

    \li \c qt.qpa.input – Enables debug output from the evdev input handler.
    Very useful to check if a given input device was correctly recognized and
    opened.

  \endlist

  \section2 Qt Quick Scene Graph Rendering Thread

  The scene graph is a graphical representation of the Item scene. It
  can be thought of as a graphical deep copy, an independent structure
  that contains enough information to render all the items.

  On many platforms, the \l{Qt Quick Scene Graph}{scene graph} will even be
  rendered on a dedicated render thread while the GUI thread is preparing the
  next frame's state.

  In some cases when application is complex e.g. it's scene graph contains
  lot's of Items, scene graph can consume more stack memory than what is
  available by default for the render thread. Default stack memory size is
  64KB. Using the environment variable QSG_RENDERTHREAD_STACK_SIZE, it is possible
  to increase the stack size available for the scene graph render thread.

  \section2 VxWorksFB

  This plugin writes directly to the framebuffer. Only software-rendered content
  is supported. Note that on some setups the display performance is expected to
  be limited.

  The \c vxworksfb plugin allows specifying additional settings by passing them
  in the \c QT_QPA_PLATFORM environment variable or \c -platform command-line
  option. For example, \c {QT_QPA_PLATFORM=vxworksfb:fb=/dev/fb1} specifies that
  the framebuffer device \c /dev/fb1 should be used instead of the default
  \c fb0. Multiple settings can be specfified by separating them with a colon.

  \list

  \li \c {fb=/dev/fbN} - Specifies the framebuffer devices. On multiple display
  setups this will typically allow running the application on different
  displays. For the time being there is no way to use multiple framebuffers from
  one Qt application.

  \li \c{size=}\e{<width>}\c{x}\e{<height>} - Specifies the screen size in
  pixels. The plugin will try to query the display dimensions, both physical and
  logical, from the framebuffer device. This may not always lead to proper
  results however, and therefore it may become necessary to explicitly specify
  the values.

  \li \c{mmSize=}\e{<width>}\c{x}\e{<height>} - Physical width and height in
  millimeters.

  \li \c{offset=}\e{<width>}\c{x}\e{<height>} - Offset in pixels specifying the
  top-left corner of the screen. The default position is at \c{(0, 0)}.

  \endlist

  \section1 Input

  When no windowing system is present, the mouse, keyboard and touch input are
  read directly via \c evdev. Note that this requires that devices nodes
  \c {/input/event*} are readable by the user. eglfs and vxworksfb has all
  the evdev input handling code built-in.

  \section2 Input on eglfs and vxworksfb

  Parameters like the device node name can be set in the environment variables
  \c QT_QPA_EVDEV_MOUSE_PARAMETERS, \c QT_QPA_EVDEV_KEYBOARD_PARAMETERS and
  \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS. Additionally, the built-in input handlers
  can be disabled by setting \c QT_QPA_EGLFS_DISABLE_INPUT or
  \c QT_QPA_FB_DISABLE_INPUT to \c 1. On some touch screens the coordinates will
  need to be rotated. This can be enabled by setting
  \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS to \c {rotate=180}.

  \section2 Mouse

  The mouse cursor will show up whenever \c QT_QPA_EGLFS_HIDECURSOR (for eglfs)
  or \c QT_QPA_FB_HIDECURSOR (for vxworksfb) is not set, the mouse cursor will
  always show up unless explicitly disabled via the environment variable.

  Hot plugging is not supported.

  \section2 Keyboard

  The evdev keyboard handler supports the following extra parameters:

  \list

  \li \c {/input/...} - Specifies the name of the input device. When not
  given, Qt will look for a suitable device by walking through the available
  nodes.
  \endlist

  If the default, built-in keymap is not sufficient, a different one can be
  specified either via the \c keymap parameter or by using the eglfs-specific
  \l{QEglFSFunctions::loadKeymap()}{loadKeymap()} function. The latter allows
  switching the keymap at runtime. Note however that this requires using eglfs'
  built-in keyboard handler; it is not supported when the keyboard handler is
  loaded via the \c -plugin command-line parameter.

  \section2 Touch

  Both single and multitouch devices are supported and require that VxWorks
  has been properly configured to support touch devices.

  \section2 Debugging Input Devices

  It is possible to print some information to the debug output by enabling
  the \c qt.qpa.input logging rule, for example by setting the \c QT_LOGGING_RULES
  environment variable to \c{qt.qpa.input=true}. This is useful for detecting
  which device is being used, or to troubleshoot device discovery issues.

  \section2 Using Custom Mouse Cursor Images

  eglfs comes with its own set of 32x32 sized mouse cursor images. If these are
  not sufficient, a custom cursor atlas can be provided by setting the \c
  QT_QPA_EGLFS_CURSOR environment variable to the name of a JSON file. The file
  can also be embedded into the application via Qt's resource system.

  For example, an embedded cursor atlas with 8 cursor images per row can be
  specified like the following:

  \badcode
    {
      "image": ":/cursor-atlas.png",
      "cursorsPerRow": 8,
      "hotSpots": [
          [7, 2],
          [12, 3],
          [12, 12],
          ...
      ]
    }
  \endcode

  Note that the images are expected to be tightly packed in the atlas: the
  width and height of the cursors are decided based on the total image size and
  the \c cursorsPerRow setting. Atlases have to provide an image for all the
  supported cursors.

  \section1 QML Component Loader Thread

  In some cases, a complex application (for example, using a lot of custom
  QML components) may cause the QML loader thread to consume stack memory
  more than the 32 KB available by default. Using the environment variable
  \c QML_LOADERTHREAD_STACK_SIZE, it is possible to increase the stack
  size available for the QML loader thread.

  \section1  Preventing Timeouts in QEventDispatcher

  Default system clock rate (SYS_CLK_RATE) for VxWorks 7 is 1/60s or ~16,67ms.
  In some cases this may cause a drop in the application frame rate;
  in QEventDispatcher, the select function is blocking for the entire system
  clock interval because a timeout is used. By defining an environment variable
  \c QT_FORCE_SELECT_NOTIMEOUT=1, the select function returns immediately
  if no new events are available and the resolution of the system clock is higher
  than 10ms, which is true with default value.

  \section1 Running Qt Applications

  Following example shows how to start an application when Qt 5 is built using
  shared libraries. With a statically build Qt 5, there is no need to use the
  LD_LIBRARY_PATH environment variable. This variable is only needed to point
  the location of VxWorks shared libraries (for example libc and OpenGL ES 2.0).
  It is not needed for Qt 5 shared libraries.

  \badcode
  putenv "LD_LIBRARY_PATH=/sd0:1/lib"
  cd "/sd0:1"
  rtpSp("<Qt5_app>", 200, 0x100000, 0, 0x01000000)
  \endcode

  \section1 Limitations

  \section2 OpenSSL Support
  Qt 5 does not support OpenSSL for VxWorks as it does not support using OpenSSL
  in RTP mode.

  \section2 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 may be insufficient for such applications,
  especially when they are displayed on a high resolution (for example, full HD)
  screen. In this case they may 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.

  \section2 vxworksfb

  Use the \c fb plugin parameter to specify the framebuffer device to use.

*/