Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-porting.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-porting-operatingsystem.html
30
31     \title Porting Qt for Embedded Linux to Another Operating System
32     \ingroup qt-embedded-linux
33
34     \l{Qt for Embedded Linux} is reasonably platform-independent, making use of
35     the standard C library and some POSIX functions, but only a Linux
36     implementation is publically available. If you are looking for a
37     non-Linux commercial implementation, it is worth contacting \l
38     {mailto:qt-info@nokia.com}{qt-info@nokia.com} to see if we can
39     help.
40
41     There are several issues to be aware of if you plan to do your own
42     port to another operating system. In particular you must resolve
43     \l{Qt for Embedded Linux}'s shared memory and semaphores (used to share
44     window regions), and you must provide something similar to
45     Unix-domain sockets for inter-application communication. You must
46     also provide a screen driver, and if you want to implement sound
47     you must provide your own sound server. Finally you must modify
48     the event dispatcher used by \l{Qt for Embedded Linux}.
49
50     Contents:
51
52     \tableofcontents
53
54     \section1 Shared Memory and Semaphores
55
56     \l{Qt for Embedded Linux} uses System V IPC (shared memory and semaphores)
57     to share window regions between client and server. When porting,
58     something similar must be provided; otherwise it will not be
59     possible to run multiple applications.
60
61     System V semaphores are also used for synchronizing access to the
62     framebuffer.
63
64     \list
65         \o Modify \c qsharedmemory_p.cpp
66         \o Modify \c qlock_qws.cpp
67         \o Modify \c qwslock.cpp
68     \endlist
69
70     \section1 Inter-Application Communication
71
72     To communicate between applications, \l{Qt for Embedded Linux} uses the
73     Unix-domain sockets. When porting, something similar must be
74     provided; otherwise it will not be possible to run multiple
75     applications.
76
77     It should be possible to use message queues or similar mechanisms
78     to achieve this. With the exception of QCOP messages, individual
79     messages should be no more than a few bytes in length (QCOP
80     messages are generated by the client applications and not Qt for
81     Embedded Linux).
82
83     \list
84         \o Modify \c qwssocket_qws.cpp
85     \endlist
86
87     \section1 Screen Management
88
89     When rendering, the default behavior in \l{Qt for Embedded Linux} is
90     for each client to render its widgets into memory while the server is
91     responsible for putting the contents of the memory onto the screen
92     using the screen driver.
93
94     When porting, a new screen driver must be implemented, providing a
95     byte pointer to a memory-mapped framebuffer and information about
96     width, height and bit depth (the latter information can most
97     likely be hard-coded).
98
99     \list
100         \o Reimplement \c qscreen_qws.cpp
101     \endlist
102
103     \section1 Sound Management
104
105     To implement sound, \l{Qt for Embedded Linux} uses a Linux style device (\c
106     /dev/dsp). If you want to use the \l{Qt for Embedded Linux} sound server on
107     another platform you must reimplement it.
108
109     \list
110         \o Reimplement \c qsoundqss_qws.cpp
111     \endlist
112
113     \section1 Event Dispatching
114
115     \l{Qt for Embedded Linux} uses an event dispatcher to pass events to and
116     from the \l{Qt for Embedded Linux} server application. Reimplement the \c
117     select() function to enable \l{Qt for Embedded Linux} to dispatch events on
118     your platform.
119
120     \list
121         \o Modify \c qeventdispatcher_qws.cpp
122     \endlist
123 */
124
125 /*!
126     \page qt-embedded-porting-device.html
127
128     \title Porting Qt for Embedded Linux to a New Architecture
129     \ingroup qt-embedded-linux
130
131     When porting \l{Qt for Embedded Linux} to a new architecture there are
132     several issues to be aware of: You must provide suitable hardware
133     drivers, and you must ensure to implement platform dependent
134     atomic operations to enable multithreading on the new
135     architecture.
136
137     \section1 Hardware Drivers
138
139     When running a \l{Qt for Embedded Linux} application, it either runs as a
140     server or connects to an existing server. All system generated
141     events, including keyboard and mouse events, are passed to the
142     server application which then propagates the event to the
143     appropriate client. When rendering, the default behavior is for
144     each client to render its widgets into memory while the server is
145     responsible for putting the contents of the memory onto the
146     screen.
147
148     The various hardware drivers are loaded by the server
149     application when it starts running, using Qt's \l {How to Create
150     Qt Plugins}{plugin system}.
151
152     Derive from the QWSMouseHandler, QWSKeyboardHandler and QScreen
153     classes to create a custom mouse, keyboard and screen driver
154     respectively. To load the drivers into the server application at
155     runtime, you must also create corresponding plugins. See the
156     following documentation for more details:
157
158     \list
159         \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling}
160         \o \l{Qt for Embedded Linux Character Input}{Character Input}
161         \o \l{Qt for Embedded Linux Display Management}{Display Management}
162     \endlist
163
164     \section1 Atomic Operations
165
166     Qt uses an optimization called \l {Implicitly Shared Classes}{implicit sharing}
167     for many of its value classes; implicitly shared classes can safely be
168     copied across threads. This technology is implemented using atomic
169     operations; i.e., \l{Qt for Embedded Linux} requires that platform-specific
170     atomic operations are implemented to support Linux.
171
172     When porting \l{Qt for Embedded Linux} to a new architecture, it is
173     important to ensure that the platform-specific atomic operations
174     are implemented in a corresponding header file, and that this file
175     is located in Qt's \c src/corelib/arch directory.
176
177     See the \l {Implementing Atomic Operations}{atomic operations}
178     documentation for more details.
179 */