P.I.P.S. -Overview

P.I.P.S. -Overview -

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 - libc, libm, libpthread and libdl - and will help reduce development costs.

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 smartphones based -on earlier versions of Symbian platform, a freely downloadable SIS file is -available from the Symbian Developer Network (specifically http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start) -and can be installed on any Symbian OS v9.x smartphones.

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. For further information, see The -Symbian build process section.

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 Tutorials 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.

- P.I.P.S. environment architecture - -

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.

For -devices already in the market, a SIS file is freely downloadable from the -Forum Nokia site (specifically http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/) -and can be installed on any v9.x phone.

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 subsystem components - -

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.

- - - -

Module

Description

- - -

core\libc

Contains Standard C and POSIX APIs as defined by the Standard C -and POSIX standards

- - -

core\libm

Contains the Standard C Math API as defined by -Standard C

- - -

core\libpthread

Contains POSIX threading APIs as defined the POSIX standards

- - -

core\libdl

Contains APIs for dynamic loading and symbol lookup by name.

- - - -

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.

-P.I.P.S. -Concepts -P.I.P.S. -Porting Tutorials -P.I.P.S. -Examples + + + + + +P.I.P.S. +Overview +

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 - libc, libm, libpthread and libdl - and will help reduce development costs.

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 smartphones based +on earlier versions of Symbian platform, a freely downloadable SIS file is +available from the Symbian Developer Network (specifically http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start) +and can be installed on any Symbian OS v9.x smartphones.

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. For further information, see The +Symbian build process section.

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 Tutorials 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.

+ P.I.P.S. environment architecture + +

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.

For +devices already in the market, a SIS file is freely downloadable from the +Forum Nokia site (specifically http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/) +and can be installed on any v9.x phone.

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 subsystem components + +

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.

+ + + +

Module

Description

+ + +

core\libc

Contains Standard C and POSIX APIs as defined by the Standard C +and POSIX standards

+ + +

core\libm

Contains the Standard C Math API as defined by +Standard C

+ + +

core\libpthread

Contains POSIX threading APIs as defined the POSIX standards

+ + +

core\libdl

Contains APIs for dynamic loading and symbol lookup by name.

+ + + +

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.

+P.I.P.S. +Concepts +P.I.P.S. +Porting Tutorials +P.I.P.S. +Examples

\ No newline at end of file