Merge branch 'tqtc/vxworks-5.5' into 5.9

Change-Id: I10c8b5da4334cb3cb44af14a8c3bb1fd06a60eda

2 files changed, 534 insertions, 1 deletions

diff --git a/doc/src/platforms/supported-platforms.qdocinc b/doc/src/platforms/supported-platforms.qdocinc
index 28253eed..26d9c64b 100644
--- a/doc/src/platforms/supported-platforms.qdocinc
+++ b/doc/src/platforms/supported-platforms.qdocinc
@@ -89,7 +89,8 @@ Mobile Platforms: \l {Qt for Android}{Android},
          \li
 
     \row \li {3,1} \header \li {3,1}
-         Embedded Platforms: \l {Qt for Embedded Linux}{Embedded Linux}, \l {QNX}, \l {INTEGRITY}
+         Embedded Platforms: \l {Qt for Embedded Linux}{Embedded Linux}, \l {QNX}, \l {INTEGRITY},
+         \l{Qt for VxWorks}{VxWorks}
     \row \li \l {Qt for Embedded Linux}{Embedded Linux}
          \li GCC \li ARM Cortex-A, Intel boards with GCC-based toolchains
     \row \li QNX 6.6.0, 7.0 (armv7le and x86)
@@ -99,6 +100,9 @@ Mobile Platforms: \l {Qt for Android}{Android},
     \row \li \l {INTEGRITY} {INTEGRITY 11.4.x}
          \li As provided by Green Hills INTEGRITY
          \li Hosts: 64-bit Linux
+    \row \li \l{Qt for VxWorks}{VxWorks 7}
+         \li As provided by Wind River
+         \li Hosts: 64-bit Linux, Windows
 
     \row \li {3,1} \header \li {3,1}
           Mobile Platforms: \l {Qt for Android}{Android}, \l {Qt for iOS}{iOS},
diff --git a/doc/src/platforms/vxworks.qdoc b/doc/src/platforms/vxworks.qdoc
new file mode 100644
index 00000000..7bc891f2
--- /dev/null
+++ b/doc/src/platforms/vxworks.qdoc
@@ -0,0 +1,529 @@
+/****************************************************************************
+**
+** 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+  \page vxworks.html
+  \title Qt for VxWorks
+
+  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
+
+  Qt 5.5 is currently tested and supported on VxWorks 7 release SR0480 2016-09-16.
+  Supported architecture is ARM-v7.
+
+  \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}.
+
+  \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 /sd0:1/qt5rtp -sysroot <path_to_vxworks_vsb_dir>/fsl_imx6_1_1_6_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.
+
+*/