--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/platforms/emb-porting.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,193 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 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.
+*/