diff options
author | Pasi Petäjäjärvi <pasi.petajajarvi@theqtcompany.com> | 2015-05-05 13:55:47 +0300 |
---|---|---|
committer | Pasi Petäjäjärvi <pasi.petajajarvi@theqtcompany.com> | 2015-05-13 11:36:22 +0300 |
commit | 22f56ec593d4953f9b08180b2aa478352850dc1f (patch) | |
tree | b7e455dc01f736277250fb7856e4969c82f9296b | |
parent | 93937640fe9ae18ca8c35cc3b0b5446e0aee437c (diff) | |
download | qtdoc-22f56ec593d4953f9b08180b2aa478352850dc1f.tar.gz |
Doc: Add VxWorks 7 specific documentation
Change-Id: I0fd2d14d2340352fef16580e8223ea9c120befff
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>
-rw-r--r-- | doc/src/platforms/platform-notes-rtos.qdoc | 13 | ||||
-rw-r--r-- | doc/src/platforms/supported-platforms.qdoc | 2 | ||||
-rw-r--r-- | doc/src/platforms/vxworks.qdoc | 383 |
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. + +*/ |