|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D" xml:lang="en"><title>P.I.P.S. |
|
13 Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian |
|
15 developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs |
|
16 are packaged into industry standard libraries - <codeph>libc</codeph>, <codeph>libm</codeph>, <codeph>libpthread</codeph> and <codeph>libdl</codeph> - and will help reduce development costs. </p> |
|
17 <section id="GUID-08EF9B92-E9A6-4C4F-8A08-597F2EF32135"><title>Purpose</title> <p>The |
|
18 Symbian platform already provides a library called '<codeph>ESTLIB</codeph>', |
|
19 which includes a subset of Standard C APIs. This was created to allow the |
|
20 Java virtual machine to run on the Symbian platform rather than to allow applications |
|
21 written in C to be ported to the Symbian platform. Furthermore, the functionality |
|
22 provided by <codeph>ESTLIB</codeph> is not fully compliant with the Standard |
|
23 C and POSIX standards. Symbian intends to deprecate <codeph>ESTLIB</codeph> once |
|
24 P.I.P.S. is mature. </p> <p>The P.I.P.S. libraries are included in ROM on |
|
25 certain smartphones based on Symbian OS v9.3 onwards. For smartphones based |
|
26 on earlier versions of Symbian platform, a freely downloadable SIS file is |
|
27 available from the Symbian Developer Network (specifically <xref href="http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start" scope="external">http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start</xref>) |
|
28 and can be installed on any Symbian OS v9.x smartphones. </p> </section> |
|
29 <section id="GUID-6E46D602-BED1-4E20-AE6B-5137615E2440"><title>Required background</title> <p><b>The |
|
30 differences between the Symbian platform and other operating systems</b> </p> <p>The |
|
31 Symbian platform is an operating system designed for mobile devices and comes |
|
32 in the form of many libraries that contain hundreds of classes and thousands |
|
33 of member functions. </p> <p>The Symbian platform has been specifically designed |
|
34 to provide efficient memory and power management. </p> <p>P.I.P.S. has been |
|
35 introduced to the Symbian platform to make it more attractive to third party |
|
36 Symbian developers with C/C++ experience and to allow them to port their applications |
|
37 to the Symbian platform with greater ease. </p> <p>The P.I.P.S. initiative |
|
38 aims to reduce the development cost of porting software to run on the Symbian |
|
39 platform. It achieves this by providing a POSIX-like API layer above the Symbian |
|
40 platform. Given the structure of the Symbian platform, however, it is not |
|
41 possible to provide a fully compliant API and some functionality, such as, <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref> are |
|
42 not supported. This guide details such non-compliance and recommended alternatives. </p> <p>Specific |
|
43 differences between the Symbian platform and Unix-like systems are described |
|
44 in the relevant sections of this guide. </p> <p><b>What P.I.P.S. is not</b> </p> <p>The |
|
45 P.I.P.S. environment is <b>not</b> a UNIX® application environment. You will |
|
46 not be able to run a UNIX application on the Symbian platform 'as is'. At |
|
47 a minimum, you will need to create a <filepath>.mmp</filepath> file and a <filepath>bld.inf</filepath> file |
|
48 for the application and rebuild the application's source code for the Symbian |
|
49 platform. For further information, see <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The |
|
50 Symbian build process</xref> section. </p> <p>If the application does not |
|
51 work at the first attempt, you may have to modify the application code to |
|
52 replace missing APIs or port the required APIs to extend the P.I.P.S. environment. |
|
53 To find out more about porting C libraries to the Symbian platform, see the <xref href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita">P.I.P.S. Porting Tutorials</xref> sections. </p> <p>The |
|
54 P.I.P.S. environment is not 100% POSIX compliant and it is not officially |
|
55 certified as POSIX compatible. However, the implementation is as compliant |
|
56 as the underlying Symbian platform allows it to be. For example, P.I.P.S. |
|
57 does not provide the APIs <codeph>fork()</codeph> and <codeph>exec()</codeph>, |
|
58 but it does provide <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-F4749DAA-1B29-3D1D-A3AA-0D52B851E501.dita"><apiname>mkfifo()</apiname></xref> and |
|
59 so on, which can be used to implement well known alternative patterns. For |
|
60 further information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process |
|
61 Creation</xref> section. </p> </section> |
|
62 <section id="GUID-22E7E427-C9D1-4C26-BCA8-E4A48CE0E45F"><title>Architecture</title> <p>P.I.P.S. |
|
63 provides an API layer above the native Symbian platform APIs that is more |
|
64 closely aligned with industry standard APIs. </p> <p>The core P.I.P.S. libraries |
|
65 are: </p> <ul> |
|
66 <li id="GUID-213D2779-C303-5A11-A339-8E464D4B4A68"><p> <codeph>libc</codeph>: |
|
67 Standard C and POSIX APIs - includes support for files, sockets, pipes, message |
|
68 queues, shared memory APIs and environment variables </p> </li> |
|
69 <li id="GUID-1209CBDA-DFEB-5ECA-AD4F-A1452762C2CC"><p> <codeph>libm</codeph>: |
|
70 Standard C maths support APIs </p> </li> |
|
71 <li id="GUID-138D2894-8362-5C13-B5BB-24A9A22DF415"><p> <codeph>libpthread</codeph>: |
|
72 Standard POSIX threading APIs </p> </li> |
|
73 <li id="GUID-E00112DA-D5BB-55C0-A6A4-A443B67858C0"><p> <codeph>libdl</codeph>: |
|
74 Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is |
|
75 supported on pre-Symbian OS v9.3 releases). </p> </li> |
|
76 </ul> <p>The first three libraries listed above are seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>. </p> <p>The diagram below shows the high |
|
77 level architecture of the P.I.P.S. environment. </p> <fig id="GUID-103BEA25-EE1B-50D0-8C0C-950C1A43656D"> |
|
78 <title> P.I.P.S. environment architecture </title> |
|
79 <image href="GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e155039_href.png" placement="inline"/> |
|
80 </fig> <p>This diagram shows how P.I.P.S. fits in with the Symbian platform, |
|
81 and also how C/C++ applications, additional C shared libraries and hybrid |
|
82 applications developed by third party Symbian developers using P.I.P.S. fit |
|
83 in. </p> <p>P.I.P.S. environment is based on industry-standard APIs. These |
|
84 standards include </p> <ul> |
|
85 <li id="GUID-09A5848E-7934-5202-BB09-BE6390FC2F12"><p>Standard C (<codeph>stdC</codeph>) |
|
86 and </p> </li> |
|
87 <li id="GUID-0478A6C5-238C-5CFF-8625-791293800E9B"><p>POSIX. </p> </li> |
|
88 </ul> <p>The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward. </p> <p>For |
|
89 devices already in the market, a SIS file is freely downloadable from the |
|
90 Forum Nokia site (specifically <xref href="http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/" scope="external">http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/</xref>) |
|
91 and can be installed on any v9.x phone. </p> <p><b>Components</b> </p> <p>P.I.P.S. |
|
92 is based on an industry-standard API and system behaviour. The relevant |
|
93 industry standards are Open Group standards and include Standard C (<codeph>stdC</codeph>), |
|
94 POSIX, GNU C library (<codeph>glibc</codeph>) and Standard C++ (<codeph>stdC++</codeph>). </p> <p>The |
|
95 diagram below shows how the Standard C libraries and exported applications |
|
96 fit into the native platform. </p> <fig id="GUID-02F370A6-0713-5E7F-A851-339E03603A0A"> |
|
97 <title> The subsystem components </title> |
|
98 <image href="GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e155098_href.png" placement="inline"/> |
|
99 </fig> <p>The System Call Adaptation Layer (SCAL) is not directly accessed |
|
100 by the developer wishing to export to the Symbian platform, but through calls |
|
101 in the P.I.P.S. libraries. </p> <p>Traditionally, in Unix-like systems, system |
|
102 calls are implemented in the kernel, separate from the C libraries. On the |
|
103 Symbian platform, the 'System Call Adaptation Layer' runs in the context of |
|
104 the user side but is considered 'kernel-like' code. APIs that belong to this |
|
105 layer are tagged as <codeph>@internalComponent</codeph> and may only be extended |
|
106 by Symbian. </p> <p>Note that P.I.P.S. is not a Linux application environment |
|
107 - you cannot simply run an application that you've compiled for your Linux |
|
108 desktop. At a minimum, you will have to rebuild your application from source. </p> <p>For |
|
109 more information, see the <xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita">Build |
|
110 Process</xref> section. </p> <p id="GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655"><b>Glue |
|
111 code (CRT0)</b> </p> <p>Executables built for the Symbian platform enter via <codeph>E32Main()</codeph>, |
|
112 whereas Standard C applications expect to be started from <codeph>main()</codeph>. |
|
113 It is therefore necessary to have 'glue code' (formerly known as CRT0) between |
|
114 these two functions. The glue code is also responsible for allocating any |
|
115 system resources, obtaining system and environment data, and initialising |
|
116 the SCAL infrastructure prior to calling the <codeph>main()</codeph> function |
|
117 of the application. There are two versions of the glue code library - <filepath>libcrt0.lib</filepath> (for |
|
118 use by applications that enter via char <codeph>main()</codeph>) and <filepath>libwcrt0.lib</filepath> (for |
|
119 use by applications that enter via wide char <codeph>main()</codeph>). </p> <p>To |
|
120 include the glue code library you should explicity link to <filepath>libcrt0.lib</filepath> and <filepath>libwcrt0.lib</filepath> statically, |
|
121 however, if you are using the <codeph>STDEXE</codeph> or <codeph>STDDLL</codeph> target |
|
122 types, glue code will be added automatically. </p> <p id="GUID-1DDC11E7-D9D6-5251-89CE-981C4869D109"><b>P.I.P.S. |
|
123 Core libraries</b> </p> <p>Currently, the C libraries include the <codeph>libc</codeph>, <codeph>libm</codeph>, |
|
124 and <codeph>libpthread</codeph> (seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) and <codeph>libdl</codeph> libraries. The |
|
125 APIs provided by these libraries are defined to be compliant, via compatibility |
|
126 features, with the POSIX standard. They are not officially certified as POSIX |
|
127 compatible but they conform to it mostly. </p> <p>The P.I.P.S. libraries include |
|
128 the following APIs: </p> <ul> |
|
129 <li id="GUID-95E53F0A-B919-5EEE-9A6F-427E87547088"><p> <codeph>stdio</codeph>, |
|
130 including <xref href="GUID-E69DB3CD-E6DA-3B1D-A499-AE68EC432CAC.dita"><apiname>print()</apiname></xref>, <xref href="GUID-58616261-FB60-37C5-9289-239144CD8FB8.dita"><apiname>scanf()</apiname></xref>, and so on </p> </li> |
|
131 <li id="GUID-5359692C-17C8-5486-9DCB-0A5B9AD1C90A"><p> <codeph>stdlib</codeph>, |
|
132 including environment variable support, and so on </p> </li> |
|
133 <li id="GUID-F0E19C9C-5581-5E47-A775-A6B57C22EE92"><p>string manipulation |
|
134 and character APIs </p> </li> |
|
135 <li id="GUID-B0F2B006-6D62-5DD6-9CDC-7ADFB693E77E"><p>locale and system services </p> </li> |
|
136 <li id="GUID-C5440DE9-24A2-5A34-A2A7-47E836E1545D"><p>searching, sort and |
|
137 pattern matching </p> </li> |
|
138 <li id="GUID-33D03F27-4B97-56CA-B4ED-67901701A1E2"><p>IPC mechanisms, including |
|
139 shared memory, pipes, FIFOs and message queues </p> </li> |
|
140 <li id="GUID-15AE7775-5FC8-59A4-924E-3987F9314F58"><p>process creation, including <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-E7C4DE71-BC5B-34AE-ACB3-C34A0DB1FC16.dita"><apiname>posix_spawn()</apiname></xref> and <xref href="GUID-3D9040E5-F6FB-3DEA-9800-A55F0CEE7B08.dita"><apiname>system()</apiname></xref> </p> </li> |
|
141 <li id="GUID-2AEE41E3-A696-588C-9E5B-8E362E96D4B5"><p>networking and socket |
|
142 APIs </p> </li> |
|
143 <li id="GUID-ACF6B3A6-0F83-50D3-B0FB-FA765BDA408D"><p>mathematical and arithmetic |
|
144 APIs </p> </li> |
|
145 <li id="GUID-595D4C61-0FC9-5A05-BEDD-7412CEA585BA"><p>dynamic loading and |
|
146 symbol lookup </p> </li> |
|
147 <li id="GUID-DC3DB027-B384-52D1-8284-BF868A5CD543"><p>thread creation and |
|
148 synchronisation mechanisms. </p> </li> |
|
149 </ul> <p>Due to fundamental differences between Linux and the Symbian platform |
|
150 kernel architecture, there is no support for <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref>. |
|
151 For more information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process |
|
152 Creation</xref> section. </p> <p>The original seed directory structure (<xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) is preserved |
|
153 as fully as possible to allow for future catch-ups to be performed more easily. |
|
154 The table below shows the original seed directory structure in FreeBSD. </p> <table id="GUID-A1D61A32-6F99-5B0A-B348-135373DC3AEA"> |
|
155 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
156 <tbody> |
|
157 <row> |
|
158 <entry><p> <b>Module</b> </p> </entry> |
|
159 <entry><p> <b>Description</b> </p> </entry> |
|
160 </row> |
|
161 <row> |
|
162 <entry><p> <filepath>core\libc</filepath> </p> </entry> |
|
163 <entry><p>Contains Standard C and POSIX APIs as defined by the Standard C |
|
164 and POSIX standards </p> </entry> |
|
165 </row> |
|
166 <row> |
|
167 <entry><p> <filepath>core\libm</filepath> </p> </entry> |
|
168 <entry><p>Contains the Standard C <codeph>Math</codeph> API as defined by |
|
169 Standard C </p> </entry> |
|
170 </row> |
|
171 <row> |
|
172 <entry><p> <filepath>core\libpthread</filepath> </p> </entry> |
|
173 <entry><p>Contains POSIX threading APIs as defined the POSIX standards </p> </entry> |
|
174 </row> |
|
175 <row> |
|
176 <entry><p> <filepath>core\libdl</filepath> </p> </entry> |
|
177 <entry><p>Contains APIs for dynamic loading and symbol lookup by name. </p> </entry> |
|
178 </row> |
|
179 </tbody> |
|
180 </tgroup> |
|
181 </table> <p>Although P.I.P.S. provides a wide range of APIs, some of the functionality |
|
182 required in order to complete a porting task might be missing - this could |
|
183 be some APIs from an existing library or an entire library. </p> <p>Several |
|
184 options are available to the user: </p> <ul> |
|
185 <li id="GUID-99935DCF-2678-5D76-98E9-8E94269E7CAC"><p>Port the missing APIs |
|
186 using the P.I.P.S. libraries </p> </li> |
|
187 <li id="GUID-FFA95C02-268F-5281-B0D3-5A4A64BC5A27"><p>Implement the missing |
|
188 APIs on top of the Symbian platform native C++ APIs </p> </li> |
|
189 <li id="GUID-D70619B7-E889-5D11-81C7-FD99420F3D1D"><p>Use a workaround - for |
|
190 example, use <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref> instead of <codeph>fork()</codeph>. </p> </li> |
|
191 </ul> <p> <b>Note:</b> The following are the limitations associated with porting |
|
192 a UNIX® application: </p> <ul> |
|
193 <li id="GUID-4057ED21-65DD-5C20-A65B-B9228BE920BD"><p> <b>Limited stack-space:</b> The |
|
194 default stack size per thread on Unix-like operating systems ranges from 64 |
|
195 kB to 1 MB. The Symbian platform, however, defines a default stack size of |
|
196 8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the <codeph>pthread_attr_setstacksize()</codeph> function |
|
197 to modify this before calling <codeph>pthread_create()</codeph>. </p> </li> |
|
198 <li id="GUID-8329F811-34A6-5812-B033-2BE49C038D3E"><p> <b>Limited threads |
|
199 per process:</b> Assuming that all threads use the default stack size (8 kB), |
|
200 Symbian specifies a limit of 128 threads per process. The limit changes depending |
|
201 on the stack size you use for individual threads. For example, if you create |
|
202 your threads with a stack size of 16 kB, the OS only supports 64 threads per |
|
203 process. </p> </li> |
|
204 </ul> </section> |
|
205 </conbody><related-links> |
|
206 <link href="GUID-2016EF4B-F001-5EB2-8095-6048582511D6.dita"><linktext>P.I.P.S. |
|
207 Concepts</linktext></link> |
|
208 <link href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita"><linktext>P.I.P.S. |
|
209 Porting Tutorials</linktext></link> |
|
210 <link href="GUID-3EB1C34E-584E-595D-A339-DE170A96AEBC.dita"><linktext>P.I.P.S. |
|
211 Examples</linktext></link> |
|
212 </related-links></concept> |