/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@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:qt-info@nokia.com}{qt-info@nokia.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.

*/