Doc: Add VxWorks 7 specific documentation

Change-Id: I0fd2d14d2340352fef16580e8223ea9c120befff
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>

3 files changed, 384 insertions, 14 deletions

diff --git a/doc/src/platforms/platform-notes-rtos.qdoc b/doc/src/platforms/platform-notes-rtos.qdoc
index ac0e821c..1a177c0c 100644
--- a/doc/src/platforms/platform-notes-rtos.qdoc
+++ b/doc/src/platforms/platform-notes-rtos.qdoc
@@ -26,19 +26,6 @@
 ****************************************************************************/
 
 /*!
-    \page platform-notes-vxworks.html
-    \title Platform and Compiler Notes - VxWorks
-    \contentspage Platform and Compiler Notes
-    \target VxWorks
-
-    Qt for VxWorks is available only under a commercial license.
-
-    Please contact Qt sales at Digia to find out more:
-    http://info.qt.digia.com/contact-qt
-
-*/
-
-/*!
     \page platform-notes-qnx.html
     \title Platform and Compiler Notes - QNX
     \contentspage Platform and Compiler Notes
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index 84f3379a..e0071cbf 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -76,7 +76,7 @@
         \li \l{Qt Enterprise Embedded}{Embedded Android}
         \li \l{Qt for Embedded Linux}{Embedded Linux}
         \li \l{Windows CE - Introduction to using Qt}{Windows Embedded (Compact and Standard)}
-        \li Real-Time Operating Systems, such as \l{QNX}, VxWorks and INTEGRITY
+        \li Real-Time Operating Systems, such as \l{QNX}, \l{Qt for VxWorks}{VxWorks} and INTEGRITY
     \endlist
 
     \section1 Mobile Platforms
diff --git a/doc/src/platforms/vxworks.qdoc b/doc/src/platforms/vxworks.qdoc
new file mode 100644
index 00000000..c2fa3878
--- /dev/null
+++ b/doc/src/platforms/vxworks.qdoc
@@ -0,0 +1,383 @@
+/****************************************************************************
+**
+** 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:
+  http://www.qt.io/contact-us
+
+  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 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 Requirements for VxWorks 7
+
+  \section2 QtWidget Applications
+
+  \list
+  \li Framebuffer device (FBDEV)
+  \li Evdev support (for input handling: mouse, keyboard and touch)
+  \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 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.
+
+  Below is an example configuration for the BD-SL-i.MX6. For most VxWorks boards
+  the configure command will look very similar.
+
+  \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_4_1_VSB -no-gcc-sysroot -extprefix <path_to_host_dir>/qt5rtp -hostprefix <path_to_host_dir>/qt5rtp -no-openssl -static
+  \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.
+
+  See \l {Qt Configure Options} for more information.
+
+  \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 Qt5 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 both from the evdev and libinput
+    input handlers. 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 environment varialbe QSG_RENDERTHREAD_STACK_SIZE, it is possible
+  to increase availabe stack memory 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 {/dev/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 {/dev/input/...} - Specifies the name of the input device. When not
+  given, Qt will look for a suitable device either via \e libudev or by walking
+  through the available nodes.
+  \li \c {repeat-delay} - Sets a custom key repeat delay.
+  \li \c {repeat-rate} - Sets a custom key repeat rate.
+  \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
+
+  Using touch enabled display (either single or multitouch) requires setting
+  touchscreen (or touch device) resolution set to environment variable \c
+  QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS to \c size=<width>x<height>.
+
+  Multitouch support can be enabled by setting setting argument \c multitouch
+  to the environment variable \c QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS.
+
+  \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 Limitations
+
+  \section2 OpenSSl Support
+  Qt5 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.
+
+*/