| /**************************************************************************** |
| ** |
| ** 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. |
| |
| */ |