Resurrect the Embedded Linux page

Task-number: QTBUG-36412
Task-number: QTBUG-36580
Change-Id: Iab31f2f71e2b8f2e9ce8baa179544aaa2ab8f0a4
Reviewed-by: Jørgen Lind <jorgen.lind@digia.com>
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>

3 files changed, 264 insertions, 48 deletions

diff --git a/doc/src/platforms/emb-linux.qdoc b/doc/src/platforms/emb-linux.qdoc
new file mode 100644
index 000000000..32d905ebd
--- /dev/null
+++ b/doc/src/platforms/emb-linux.qdoc
@@ -0,0 +1,263 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** 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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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 embedded-linux.html
+  \title Qt for Embedded Linux
+
+  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. Multiple
+  graphical processes will be supported through Wayland.
+
+  There are multiple platform plugins that are potentially usable on Embedded
+  Linux systems: EGLFS, LinuxFB, KMS, DirectFB, Wayland. The availability of
+  these depend 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 -platform command-line
+  parameter can be used to request another plugin.
+
+  \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 LinuxFB 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 linux-rasp-pi-g++
+  contains build settings for the \l {http://www.raspberrypi.org}{Raspberry Pi}
+  and an implementation of the eglfs hooks (vendor-specific adaptation
+  code). This means that the eglfs platform plugin will be automatically built
+  with the correct, Raspberry Pi-specific adaptation code. 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 Raspberry Pi. For most Embedded
+  Linux boards the configure command will look very similar. The most important
+  parameters are \c -device and \c -sysroot.
+
+  \code
+    ./configure -release -opengl es2 -device linux-rasp-pi-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5
+  \endcode
+
+  See \l {Qt Configure Options} for more information.
+
+  \section1 Platform Plugins for Embedded Linux 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 and
+  vendor-specific adaptation code (the so-called \e {eglfs hooks}).
+
+  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 Embedded Linux 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 LinuxFB.
+
+  \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, 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.
+
+  \li \c {QT_QPA_EGLFS_DEPTH} - Overrides the color depth.
+
+  \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_FORCEVSYNC} - When set, eglfs requests \c
+  FBIO_WAITFORVSYNC on the framebuffer device.
+
+  \endlist
+
+  \section2 LinuxFB
+
+  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 linuxfb plugin allows specifying additional settings by passing them in
+  the \c -platform command-line argument. For example, \c {-platform
+  linuxfb: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)}.
+
+  \li \c {nographicsmodeswitch} - Do not switch the virtual terminal to graphics
+  mode (\c KD_GRAPHICS).
+
+  \li \c {tty=/dev/ttyN} - Overrides the virtual console. Only used when \c
+  {nographicsmodeswitch} is not set.
+
+  \endlist
+
+  \section2 KMS
+
+  An experimental platform plugin using kernel modesetting and \l
+  {http://dri.freedesktop.org/wiki/DRM}{drm} (Direct Rendering Manager).
+
+  \section1 Input
+
+  When no windowing system is present, the mouse, keyboard and touch input are
+  read directly via \c evdev or using helper libraries like \c tslib. Note that
+  this requires that devices nodes \c {/dev/input/event*} are readable by the
+  user. eglfs has all the evdev input handling code built-in, while linuxfb
+  relies on the traditional \c -plugin command-line parameters.
+
+  To enable keyboard, mouse, touch or tablet support with linuxfb, pass \c
+  {-plugin evdevkeyboard}, \c {-plugin evdevmouse}, \c{-plugin evdevtouch}, or
+  \c {-plugin evdevtablet} on the command-line. Most of these can take a device
+  node parameter, for example \c {-plugin evdevmouse:/dev/event1}, in case the
+  Qt's automatic device discovery (based either on \e libudev or a walkthrough
+  of \c {/dev/input/event*}) is not functional or misbehaving.
+
+  For eglfs, these 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 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}.
+
+  The mouse cursor will show up whenever \c QT_QPA_EGLFS_HIDECURSOR (for eglfs)
+  or \c QT_QPA_FB_HIDECURSOR (for linuxfb) is not set and Qt's libudev-based
+  device discovery reports that at least one mouse is available. When libudev
+  support is not present, the mouse cursor will always show up unless explicitly
+  disabled via the environment variable.
+
+  Hot plugging is supported, but only if Qt was configured with libudev support
+  (that is, if the \e libudev development headers are present in the sysroot at
+  configure time). This allows connecting or disconnecting an input device while
+  the application is running. On eglfs the mouse cursor will disappear and
+  reappear appropriately.
+
+  EGLFS, LinuxFB and KMS are disabling the terminal keyboard on application
+  startup. This prevents keystrokes from going to the terminal \e underneath the
+  application. If the old behavior needs to be restored for some reason, set the
+  environment variable \c QT_QPA_ENABLE_TERMINAL_KEYBOARD to \c 1.
+
+  For some resistive, single-touch touch screens it may be necessary to fall
+  back to using tslib instead of relying on the Linux multitouch protocol and
+  the event devices. For modern touch screens this should not be
+  necessary. tslib support can be enabled by passing \c{-plugin tslib} instead
+  of \c evdevtouch. To change the device, set the environment variable \c
+  TSLIB_TSDEVICE or pass the device name on the command-line.
+
+  \section1 Platform Plugins for Windowing Systems on Embedded Linux Devices
+
+  \section2 XCB
+
+  This is the X11 plugin used on regular desktop Linux platforms. In some
+  embedded environments, that provide X and the necessary development files for
+  \l {http://xcb.freedesktop.org}{xcb}, this plugin will function just like it
+  does on a regular PC desktop.
+
+  \note On some devices there is no EGL and OpenGL support available under X
+  because the EGL implementation is not compatible with Xlib. In this case the
+  XCB plugin will be built without EGL support, meaning that Qt Quick 2 or other
+  OpenGL-based applications will not work with this platform plugin. It can
+  still be used however to run software-rendered applications (based on QWidget
+  for example).
+
+  As a general rule, the usage of XCB on embedded devices is not
+  advisable. Plugins like eglfs are likely to provide better performance, and
+  hardware acceleration.
+
+  \section2 Wayland
+
+  \l{http://wayland.freedesktop.org/}{Wayland} is a light-weight windowing
+  system; or more precisely, it is a protocol for clients to talk to a display
+  server.
+
+  The Qt Wayland module is not currently part of Qt 5. Development snapshots can
+  be downloaded from the \l{http://qt.gitorious.org/qt/qtwayland}{Qt Wayland git
+  repository}. \note The sources checked out from the repository may have
+  dependencies on not-yet-released changes in Qt 5's qtbase and qtdeclarative
+  repositories.
+*/
diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc
index 3a9655759..610a72353 100644
--- a/doc/src/platforms/supported-platforms.qdoc
+++ b/doc/src/platforms/supported-platforms.qdoc
@@ -57,7 +57,7 @@
     You can develop with Qt for the following embedded platforms:
     \list
         \li \l{Qt Enterprise Embedded}{Embedded Android}
-        \li Embedded Linux (DirectFB, EGLFS, KMS, and Wayland)
+        \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
     \endlist
diff --git a/doc/src/platforms/wayland-introduction.qdoc b/doc/src/platforms/wayland-introduction.qdoc
deleted file mode 100644
index 5d3e5c01a..000000000
--- a/doc/src/platforms/wayland-introduction.qdoc
+++ /dev/null
@@ -1,47 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** 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 Digia.  For licensing terms and
-** conditions see http://qt.digia.com/licensing.  For further information
-** use the contact form at http://qt.digia.com/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 wayland-introduction.html
-\title Wayland Support in Qt
-
-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. Multiple graphical
-processes will be supported through Wayland.
-
-\l{http://wayland.freedesktop.org/}{Wayland} is a light-weight windowing
-system; or more precisely, it is a protocol for clients to talk to a display
-server.
-
-The Qt Wayland module is not part of Qt 5.0.0. It is currently fully
-functional, but the adaptations required by the recent 1.0.0 release of
-Wayland itself could not be done in time for the Qt feature freeze. The Qt
-Wayland module will have its official release soon after Qt 5.0.
-Development snapshots can be downloaded from the
-\l{http://qt.gitorious.org/qt/qtwayland}{Qt Wayland git repository}.
-*/