source: trunk/doc/src/platforms/emb-porting.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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:[email protected]}{[email protected]} 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.
*/