<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D" xml:lang="en"><title>P.I.P.S.
Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian
developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs
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>
<section id="GUID-08EF9B92-E9A6-4C4F-8A08-597F2EF32135"><title>Purpose</title> <p>The
Symbian platform already provides a library called '<codeph>ESTLIB</codeph>',
which includes a subset of Standard C APIs. This was created to allow the
Java virtual machine to run on the Symbian platform rather than to allow applications
written in C to be ported to the Symbian platform. Furthermore, the functionality
provided by <codeph>ESTLIB</codeph> is not fully compliant with the Standard
C and POSIX standards. Symbian intends to deprecate <codeph>ESTLIB</codeph> once
P.I.P.S. is mature. </p> <p>The P.I.P.S. libraries are included in ROM on
certain smartphones based on Symbian OS v9.3 onwards. For smartphones based
on earlier versions of Symbian platform, a freely downloadable SIS file is
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>)
and can be installed on any Symbian OS v9.x smartphones. </p> </section>
<section id="GUID-6E46D602-BED1-4E20-AE6B-5137615E2440"><title>Required background</title> <p><b>The
differences between the Symbian platform and other operating systems</b> </p> <p>The
Symbian platform is an operating system designed for mobile devices and comes
in the form of many libraries that contain hundreds of classes and thousands
of member functions. </p> <p>The Symbian platform has been specifically designed
to provide efficient memory and power management. </p> <p>P.I.P.S. has been
introduced to the Symbian platform to make it more attractive to third party
Symbian developers with C/C++ experience and to allow them to port their applications
to the Symbian platform with greater ease. </p> <p>The P.I.P.S. initiative
aims to reduce the development cost of porting software to run on the Symbian
platform. It achieves this by providing a POSIX-like API layer above the Symbian
platform. Given the structure of the Symbian platform, however, it is not
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
not supported. This guide details such non-compliance and recommended alternatives. </p> <p>Specific
differences between the Symbian platform and Unix-like systems are described
in the relevant sections of this guide. </p> <p><b>What P.I.P.S. is not</b> </p> <p>The
P.I.P.S. environment is <b>not</b> a UNIX® application environment. You will
not be able to run a UNIX application on the Symbian platform 'as is'. At
a minimum, you will need to create a <filepath>.mmp</filepath> file and a <filepath>bld.inf</filepath> file
for the application and rebuild the application's source code for the Symbian
platform. For further information, see <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The
Symbian build process</xref> section. </p> <p>If the application does not
work at the first attempt, you may have to modify the application code to
replace missing APIs or port the required APIs to extend the P.I.P.S. environment.
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
P.I.P.S. environment is not 100% POSIX compliant and it is not officially
certified as POSIX compatible. However, the implementation is as compliant
as the underlying Symbian platform allows it to be. For example, P.I.P.S.
does not provide the APIs <codeph>fork()</codeph> and <codeph>exec()</codeph>,
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
so on, which can be used to implement well known alternative patterns. For
further information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
Creation</xref> section. </p> </section>
<section id="GUID-22E7E427-C9D1-4C26-BCA8-E4A48CE0E45F"><title>Architecture</title> <p>P.I.P.S.
provides an API layer above the native Symbian platform APIs that is more
closely aligned with industry standard APIs. </p> <p>The core P.I.P.S. libraries
are: </p> <ul>
<li id="GUID-213D2779-C303-5A11-A339-8E464D4B4A68"><p> <codeph>libc</codeph>:
Standard C and POSIX APIs - includes support for files, sockets, pipes, message
queues, shared memory APIs and environment variables </p> </li>
<li id="GUID-1209CBDA-DFEB-5ECA-AD4F-A1452762C2CC"><p> <codeph>libm</codeph>:
Standard C maths support APIs </p> </li>
<li id="GUID-138D2894-8362-5C13-B5BB-24A9A22DF415"><p> <codeph>libpthread</codeph>:
Standard POSIX threading APIs </p> </li>
<li id="GUID-E00112DA-D5BB-55C0-A6A4-A443B67858C0"><p> <codeph>libdl</codeph>:
Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is
supported on pre-Symbian OS v9.3 releases). </p> </li>
</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
level architecture of the P.I.P.S. environment. </p> <fig id="GUID-103BEA25-EE1B-50D0-8C0C-950C1A43656D">
<title>              P.I.P.S. environment architecture            </title>
<image href="GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e190112_href.png" placement="inline"/>
</fig> <p>This diagram shows how P.I.P.S. fits in with the Symbian platform,
and also how C/C++ applications, additional C shared libraries and hybrid
applications developed by third party Symbian developers using P.I.P.S. fit
in. </p> <p>P.I.P.S. environment is based on industry-standard APIs. These
standards include </p> <ul>
<li id="GUID-09A5848E-7934-5202-BB09-BE6390FC2F12"><p>Standard C (<codeph>stdC</codeph>)
and </p> </li>
<li id="GUID-0478A6C5-238C-5CFF-8625-791293800E9B"><p>POSIX. </p> </li>
</ul> <p>The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward. </p> <p>For
devices already in the market, a SIS file is freely downloadable from the
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>)
and can be installed on any v9.x phone. </p> <p><b>Components</b> </p> <p>P.I.P.S.
is based on an industry-standard API and system behaviour.  The relevant
industry standards are Open Group standards and include Standard C (<codeph>stdC</codeph>),
POSIX, GNU C library (<codeph>glibc</codeph>) and Standard C++ (<codeph>stdC++</codeph>). </p> <p>The
diagram below shows how the Standard C libraries and exported applications
fit into the native platform. </p> <fig id="GUID-02F370A6-0713-5E7F-A851-339E03603A0A">
<title>                 The subsystem components               </title>
<image href="GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e190171_href.png" placement="inline"/>
</fig> <p>The System Call Adaptation Layer (SCAL) is not directly accessed
by the developer wishing to export to the Symbian platform, but through calls
in the P.I.P.S. libraries. </p> <p>Traditionally, in Unix-like systems, system
calls are implemented in the kernel, separate from the C libraries. On the
Symbian platform, the 'System Call Adaptation Layer' runs in the context of
the user side but is considered 'kernel-like' code. APIs that belong to this
layer are tagged as <codeph>@internalComponent</codeph> and may only be extended
by Symbian. </p> <p>Note that P.I.P.S. is not a Linux application environment
- you cannot simply run an application that you've compiled for your Linux
desktop. At a minimum, you will have to rebuild your application from source. </p> <p>For
more information, see the <xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita">Build
Process</xref> section. </p> <p id="GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655"><b>Glue
code (CRT0)</b> </p> <p>Executables built for the Symbian platform enter via <codeph>E32Main()</codeph>,
whereas Standard C applications expect to be started from <codeph>main()</codeph>.
It is therefore necessary to have 'glue code' (formerly known as CRT0) between
these two functions. The glue code is also responsible for allocating any
system resources, obtaining system and environment data, and initialising
the SCAL infrastructure prior to calling the <codeph>main()</codeph> function
of the application. There are two versions of the glue code library - <filepath>libcrt0.lib</filepath> (for
use by applications that enter via char <codeph>main()</codeph>) and <filepath>libwcrt0.lib</filepath> (for
use by applications that enter via wide char <codeph>main()</codeph>). </p> <p>To
include the glue code library you should explicity link to <filepath>libcrt0.lib</filepath> and <filepath>libwcrt0.lib</filepath> statically,
however, if you are using the <codeph>STDEXE</codeph> or <codeph>STDDLL</codeph> target
types, glue code will be added automatically. </p> <p id="GUID-1DDC11E7-D9D6-5251-89CE-981C4869D109"><b>P.I.P.S.
Core libraries</b> </p> <p>Currently, the C libraries include the <codeph>libc</codeph>, <codeph>libm</codeph>,
and <codeph>libpthread</codeph> (seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) and <codeph>libdl</codeph> libraries. The
APIs provided by these libraries are defined to be compliant, via compatibility
features, with the POSIX standard. They are not officially certified as POSIX
compatible but they conform to it mostly. </p> <p>The P.I.P.S. libraries include
the following APIs: </p> <ul>
<li id="GUID-95E53F0A-B919-5EEE-9A6F-427E87547088"><p> <codeph>stdio</codeph>,
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>
<li id="GUID-5359692C-17C8-5486-9DCB-0A5B9AD1C90A"><p> <codeph>stdlib</codeph>,
including environment variable support, and so on </p> </li>
<li id="GUID-F0E19C9C-5581-5E47-A775-A6B57C22EE92"><p>string manipulation
and character APIs </p> </li>
<li id="GUID-B0F2B006-6D62-5DD6-9CDC-7ADFB693E77E"><p>locale and system services </p> </li>
<li id="GUID-C5440DE9-24A2-5A34-A2A7-47E836E1545D"><p>searching, sort and
pattern matching </p> </li>
<li id="GUID-33D03F27-4B97-56CA-B4ED-67901701A1E2"><p>IPC mechanisms, including
shared memory, pipes, FIFOs and message queues </p> </li>
<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>
<li id="GUID-2AEE41E3-A696-588C-9E5B-8E362E96D4B5"><p>networking and socket
APIs </p> </li>
<li id="GUID-ACF6B3A6-0F83-50D3-B0FB-FA765BDA408D"><p>mathematical and arithmetic
APIs </p> </li>
<li id="GUID-595D4C61-0FC9-5A05-BEDD-7412CEA585BA"><p>dynamic loading and
symbol lookup </p> </li>
<li id="GUID-DC3DB027-B384-52D1-8284-BF868A5CD543"><p>thread creation and
synchronisation mechanisms. </p> </li>
</ul> <p>Due to fundamental differences between Linux and the Symbian platform
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>.
For more information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
Creation</xref> section. </p> <p>The original seed directory structure (<xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) is preserved
as fully as possible to allow for future catch-ups to be performed more easily.
The table below shows the original seed directory structure in FreeBSD. </p> <table id="GUID-A1D61A32-6F99-5B0A-B348-135373DC3AEA">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <b>Module</b>  </p> </entry>
<entry><p> <b>Description</b>  </p> </entry>
</row>
<row>
<entry><p> <filepath>core\libc</filepath>  </p> </entry>
<entry><p>Contains Standard C and POSIX APIs as defined by the Standard C
and POSIX standards </p> </entry>
</row>
<row>
<entry><p> <filepath>core\libm</filepath>  </p> </entry>
<entry><p>Contains the Standard C <codeph>Math</codeph> API as defined by
Standard C </p> </entry>
</row>
<row>
<entry><p> <filepath>core\libpthread</filepath>  </p> </entry>
<entry><p>Contains POSIX threading APIs as defined the POSIX standards </p> </entry>
</row>
<row>
<entry><p> <filepath>core\libdl</filepath>  </p> </entry>
<entry><p>Contains APIs for dynamic loading and symbol lookup by name. </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p>Although P.I.P.S. provides a wide range of APIs, some of the functionality
required in order to complete a porting task might be missing - this could
be some APIs from an existing library or an entire library. </p> <p>Several
options are available to the user: </p> <ul>
<li id="GUID-99935DCF-2678-5D76-98E9-8E94269E7CAC"><p>Port the missing APIs
using the P.I.P.S. libraries </p> </li>
<li id="GUID-FFA95C02-268F-5281-B0D3-5A4A64BC5A27"><p>Implement the missing
APIs on top of the Symbian platform native C++ APIs </p> </li>
<li id="GUID-D70619B7-E889-5D11-81C7-FD99420F3D1D"><p>Use a workaround - for
example, use <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref> instead of <codeph>fork()</codeph>. </p> </li>
</ul> <p> <b>Note:</b> The following are the limitations associated with porting
a UNIX® application: </p> <ul>
<li id="GUID-4057ED21-65DD-5C20-A65B-B9228BE920BD"><p> <b>Limited stack-space:</b> The
default stack size per thread on Unix-like operating systems ranges from 64
kB to 1 MB. The Symbian platform, however, defines a default stack size of
8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the <codeph>pthread_attr_setstacksize()</codeph> function
to modify this before calling <codeph>pthread_create()</codeph>. </p> </li>
<li id="GUID-8329F811-34A6-5812-B033-2BE49C038D3E"><p> <b>Limited threads
per process:</b> Assuming that all threads use the default stack size (8 kB),
Symbian specifies a limit of 128 threads per process. The limit changes depending
on the stack size you use for individual threads. For example, if you create
your threads with a stack size of 16 kB, the OS only supports 64 threads per
process. </p> </li>
</ul> </section>
</conbody><related-links>
<link href="GUID-2016EF4B-F001-5EB2-8095-6048582511D6.dita"><linktext>P.I.P.S.
Concepts</linktext></link>
<link href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita"><linktext>P.I.P.S.
Porting Tutorials</linktext></link>
<link href="GUID-3EB1C34E-584E-595D-A339-DE170A96AEBC.dita"><linktext>P.I.P.S.
Examples</linktext></link>
</related-links></concept>