P.I.P.S. Overview

Purpose

The Symbian platform already provides a library called 'ESTLIB', 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 ESTLIB is not fully compliant with the Standard C and POSIX standards. Symbian intends to deprecate ESTLIB once P.I.P.S. is mature.

The P.I.P.S. libraries are included in ROM on certain smartphones based on Symbian OS v9.3 onwards.

For devices already in the market, a SIS file is freely downloadable from the Nokia Developer site (specifically Open_C_and_C++/) and can be installed on any v9.x phone.

Required background

The differences between the Symbian platform and other operating systems

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.

The Symbian platform has been specifically designed to provide efficient memory and power management.

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.

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, fork() and exec() are not supported. This guide details such non-compliance and recommended alternatives.

Specific differences between the Symbian platform and Unix-like systems are described in the relevant sections of this guide.

What P.I.P.S. is not

The P.I.P.S. environment is not 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 .mmp file and a bld.inf file for the application and rebuild the application's source code for the Symbian platform.

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 P.I.P.S. Porting Tutorial sections.

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 fork() and exec(), but it does provide popen(), mkfifo() and so on, which can be used to implement well known alternative patterns. For further information, see the Process Creation section.

Architecture

P.I.P.S. provides an API layer above the native Symbian platform APIs that is more closely aligned with industry standard APIs.

The core P.I.P.S. libraries are:

• libc: Standard C and POSIX APIs - includes support for files, sockets, pipes, message queues, shared memory APIs and environment variables

• libm: Standard C maths support APIs

• libpthread: Standard POSIX threading APIs

• libdl: Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is supported on pre-Symbian OS v9.3 releases).

The first three libraries listed above are seeded from FreeBSD.

The diagram below shows the high level architecture of the P.I.P.S. environment.

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.I.P.S. environment is based on industry-standard APIs. These standards include

• Standard C (stdC) and

• POSIX.

The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward.

Components

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 (stdC), POSIX, GNU C library (glibc) and Standard C++ (stdC++).

The diagram below shows how the Standard C libraries and exported applications fit into the native platform.

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.

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 @internalComponent and may only be extended by Symbian.

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.

For more information, see the Build Process section.

Glue code (CRT0)

Executables built for the Symbian platform enter via E32Main(), whereas Standard C applications expect to be started from main(). 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 main() function of the application. There are two versions of the glue code library - libcrt0.lib (for use by applications that enter via char main()) and libwcrt0.lib (for use by applications that enter via wide char main()).

To include the glue code library you should explicity link to libcrt0.lib and libwcrt0.lib statically, however, if you are using the STDEXE or STDDLL target types, glue code will be added automatically.

P.I.P.S. Core libraries

Currently, the C libraries include the libc, libm, and libpthread (seeded from FreeBSD) and libdl 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.

The P.I.P.S. libraries include the following APIs:

• stdio, including print(), scanf(), and so on

• stdlib, including environment variable support, and so on

• string manipulation and character APIs

• locale and system services

• searching, sort and pattern matching

• IPC mechanisms, including shared memory, pipes, FIFOs and message queues

• process creation, including popen(), posix_spawn() and system()

• networking and socket APIs

• mathematical and arithmetic APIs

• dynamic loading and symbol lookup

• thread creation and synchronisation mechanisms.

Due to fundamental differences between Linux and the Symbian platform kernel architecture, there is no support for fork() and exec(). For more information, see the Process Creation section.

The original seed directory structure (FreeBSD) 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.

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.

Several options are available to the user:

• Port the missing APIs using the P.I.P.S. libraries

• Implement the missing APIs on top of the Symbian platform native C++ APIs

• Use a workaround - for example, use popen() instead of fork().

Note: The following are the limitations associated with porting a UNIX® application:

• Limited stack-space: 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 pthread_attr_setstacksize() function to modify this before calling pthread_create().

• Limited threads per process: 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.