Long live Qt!

1 files changed, 193 insertions, 0 deletions

diff --git a/doc/src/emb-porting.qdoc b/doc/src/emb-porting.qdoc
new file mode 100644
index 0000000..9d6fad6
--- /dev/null
+++ b/doc/src/emb-porting.qdoc
@@ -0,0 +1,193 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt-embedded-porting-operatingsystem.html
+
+    \title Porting Qt for Embedded Linux to Another Operating System
+    \ingroup qt-embedded-linux
+
+    \l{Qt for Embedded Linux} is reasonably platform-independent, making use of
+    the standard C library and some POSIX functions, but only a Linux
+    implementation is publically available. If you are looking for a
+    non-Linux commercial implementation, it is worth contacting \l
+    {mailto:sales@trolltech.com}{sales@trolltech.com} to see if we can
+    help.
+
+    There are several issues to be aware of if you plan to do your own
+    port to another operating system. In particular you must resolve
+    \l{Qt for Embedded Linux}'s shared memory and semaphores (used to share
+    window regions), and you must provide something similar to
+    Unix-domain sockets for inter-application communication. You must
+    also provide a screen driver, and if you want to implement sound
+    you must provide your own sound server. Finally you must modify
+    the event dispatcher used by \l{Qt for Embedded Linux}.
+
+    Contents:
+
+    \tableofcontents
+
+    \section1 Shared Memory and Semaphores
+
+    \l{Qt for Embedded Linux} uses System V IPC (shared memory and semaphores)
+    to share window regions between client and server. When porting,
+    something similar must be provided; otherwise it will not be
+    possible to run multiple applications.
+
+    System V semaphores are also used for synchronizing access to the
+    framebuffer.
+
+    \list
+        \o Modify \c qsharedmemory_p.cpp
+        \o Modify \c qlock_qws.cpp
+        \o Modify \c qwslock.cpp
+    \endlist
+
+    \section1 Inter-Application Communication
+
+    To communicate between applications, \l{Qt for Embedded Linux} uses the
+    Unix-domain sockets. When porting, something similar must be
+    provided; otherwise it will not be possible to run multiple
+    applications.
+
+    It should be possible to use message queues or similar mechanisms
+    to achieve this. With the exception of QCOP messages, individual
+    messages should be no more than a few bytes in length (QCOP
+    messages are generated by the client applications and not Qt for
+    Embedded Linux).
+
+    \list
+        \o Modify \c qwssocket_qws.cpp
+    \endlist
+
+    \section1 Screen Management
+
+    When rendering, the default behavior in \l{Qt for Embedded Linux} is
+    for each client to render its widgets into memory while the server is
+    responsible for putting the contents of the memory onto the screen
+    using the screen driver.
+
+    When porting, a new screen driver must be implemented, providing a
+    byte pointer to a memory-mapped framebuffer and information about
+    width, height and bit depth (the latter information can most
+    likely be hard-coded).
+
+    \list
+        \o Reimplement \c qscreen_qws.cpp
+    \endlist
+
+    \section1 Sound Management
+
+    To implement sound, \l{Qt for Embedded Linux} uses a Linux style device (\c
+    /dev/dsp). If you want to use the \l{Qt for Embedded Linux} sound server on
+    another platform you must reimplement it.
+
+    \list
+        \o Reimplement \c qsoundqss_qws.cpp
+    \endlist
+
+    \section1 Event Dispatching
+
+    \l{Qt for Embedded Linux} uses an event dispatcher to pass events to and
+    from the \l{Qt for Embedded Linux} server application. Reimplement the \c
+    select() function to enable \l{Qt for Embedded Linux} to dispatch events on
+    your platform.
+
+    \list
+        \o Modify \c qeventdispatcher_qws.cpp
+    \endlist
+*/
+
+/*!
+    \page qt-embedded-porting-device.html
+
+    \title Porting Qt for Embedded Linux to a New Architecture
+    \ingroup qt-embedded-linux
+
+    When porting \l{Qt for Embedded Linux} to a new architecture there are
+    several issues to be aware of: You must provide suitable hardware
+    drivers, and you must ensure to implement platform dependent
+    atomic operations to enable multithreading on the new
+    architecture.
+
+    \section1 Hardware Drivers
+
+    When running a \l{Qt for Embedded Linux} application, it either runs as a
+    server or connects to an existing server. All system generated
+    events, including keyboard and mouse events, are passed to the
+    server application which then propagates the event to the
+    appropriate client. When rendering, the default behavior is for
+    each client to render its widgets into memory while the server is
+    responsible for putting the contents of the memory onto the
+    screen.
+
+    The various hardware drivers are loaded by the server
+    application when it starts running, using Qt's \l {How to Create
+    Qt Plugins}{plugin system}.
+
+    Derive from the QWSMouseHandler, QWSKeyboardHandler and QScreen
+    classes to create a custom mouse, keyboard and screen driver
+    respectively. To load the drivers into the server application at
+    runtime, you must also create corresponding plugins. See the
+    following documentation for more details:
+
+    \list
+        \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling}
+        \o \l{Qt for Embedded Linux Character Input}{Character Input}
+        \o \l{Qt for Embedded Linux Display Management}{Display Management}
+    \endlist
+
+    \section1 Atomic Operations
+
+    Qt uses an optimization called \l {Implicitly Shared Classes}{implicit sharing}
+    for many of its value classes; implicitly shared classes can safely be
+    copied across threads. This technology is implemented using atomic
+    operations; i.e., \l{Qt for Embedded Linux} requires that platform-specific
+    atomic operations are implemented to support Linux.
+
+    When porting \l{Qt for Embedded Linux} to a new architecture, it is
+    important to ensure that the platform-specific atomic operations
+    are implemented in a corresponding header file, and that this file
+    is located in Qt's \c src/corelib/arch directory.
+
+    See the \l {Implementing Atomic Operations}{atomic operations}
+    documentation for more details.
+*/