<?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. </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>

</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>

</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 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>