/****************************************************************************
**
** Copyright (C) 2004-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License versions 2.0 or 3.0 as published by the Free Software
** Foundation and appearing in the files LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file.  Alternatively you may (at
** your option) use any later version of the GNU General Public
** License if such license has been publicly approved by Trolltech ASA
** (or its successors, if any) and the KDE Free Qt Foundation. In
** addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.2, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/. If
** you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech, as the sole
** copyright holder for Qt Designer, grants users of the Qt/Eclipse
** Integration plug-in the right for the Qt/Eclipse Integration to
** link to functionality provided by Qt Designer and its related
** libraries.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not expressly
** granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \page qt-embedded-porting-operatingsystem.html

    \title Porting Qt for Embedded Linux to Another Operating System
    \ingroup qt-embedded

    \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

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