/****************************************************************************
**
** 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 qtopiacore-porting-operatingsystem.html

    \title Porting Qtopia Core to Another Operating System
    \ingroup qtopiacore

    \l {Qtopia Core} 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 {Qtopia Core}'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 \l
    {Qtopia Core}'s event dispatcher.

    Contents:

    \tableofcontents

    \section1 Shared Memory and Semaphores

    \l {Qtopia Core} 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 {Qtopia Core} 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 Qtopia
    Core).

    \list
        \o Modify \c qwssocket_qws.cpp
    \endlist

    \section1 Screen Management

    When rendering, \l {Qtopia Core}'s 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
    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 {Qtopia Core} uses a Linux style device (\c
    /dev/dsp). If you want to use the \l {Qtopia Core} sound server on
    another platform you must reimplement it.

    \list
        \o Reimplement \c qsoundqss_qws.cpp
    \endlist

    \section1 Event Dispatching

    \l {Qtopia Core} uses an event dispatcher to pass events to and
    from the \l {Qtopia Core} server application. Reimplement the \c
    select() function to enable \l {Qtopia Core} to dispatch events on
    your platform.

    \list
        \o Modify \c qeventdispatcher_qws.cpp
    \endlist
*/

/*!
    \page qtopiacore-porting-device.html

    \title Porting Qtopia Core to a New Architecture
    \ingroup qtopiacore

    When porting \l {Qtopia Core} 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 {Qtopia Core} 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 {Qtopia Core Pointer Handling}{Pointer Handling}
        \o \l {Qtopia Core Character Input}{Character Input}
        \o \l {Qtopia Core Display Management}{Display Management}
    \endlist

    \section1 Atomic Operations

    Using Qt/Embedded, Linux was always supported as long as you had a
    compiler for the architecture. Starting with Qt 4.0 and \l {Qtopia
    Core}, 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 {Qtopia Core} requires that platform-specific
    atomic operations are implemented to support Linux.

    When porting \l {Qtopia Core} 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.
*/
