/*!
    \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.
*/
