Build -Process

Mapping POSIX -handles to the Symbian platform resource objects

Using -non-system calls

Several P.I.P.S. APIs that directly manipulate -the Symbian platform (native) resources are implemented in the System Call -Adaptation Layer (SCAL). The exceptions to this are pthread s, -and memory maps. The pthread APIs use RThread s -and RMutex es directly from within libpthread. -Similarly, RChunk s that are used to provide support for -memory maps are directly manipulated from within libc. Note -that none of these APIs allow direct access to the underlying native resources. -References to these are wrapped in POSIX-defined data structures. These data -structures are intended to be treated as opaque and no attempt must be made -to dereference or use the underlying resource reference directly.

All -IPC calls enter the SCAL, but are handled in a separate IPC library. This -is a component distinction. The IPC library is logically still part of the -SCAL.

Using the -System Call Adaptation Layer

One of the supports provided by the -System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX® -file descriptors to the corresponding Symbian platform resource objects. The -section below discusses the file descriptors case.

Creating -a new file descriptor

The porting of the 'C' POSIX fopen() function, -below, is a good example of mapping POSIX handles to native Symbian platform -resource objects. The mapping is done through a file descriptor table. As -a reminder, every application/process has its own file descriptor table.

This -example shows a call to the fopen() function:

//myapp.cpp +

Introduction

Symbian currently builds its emulator code with the Metrowerks +CodeWarrior compiler. This is known as the WINSCW build target. Binaries built with this compiler are put in the epoc32\release\winscw and epoc32\winscw directory trees.

You can build your programs for the emulator +using Metrowerks CodeWarrior. The build tools also support the Microsoft® +Visual Studio .NET 2003 and Microsoft Visual Studio v6 IDEs. Note that licensees or third-parties may supply additional +tools, or extend support to additional compilers, which are not described +here.

The following sections describe the Symbian platform +target types introduced with P.I.P.S..

When using tool chains +for pre-Symbian OS v9.3, the .mmp file has to +be manually changed to link in various libraries.

For Symbian +OS v9.3 onwards the tool chain supports the new STDEXE and STDDLL target types for P.I.P.S. EXEs and DLLs. +See the Generation of STDEXE, STDDLL and STDLIB section for further +explanation of the new target types introduced with P.I.P.S..

P.I.P.S. +target types

P.I.P.S. EXEs require adaptation logic to +set up the C program environment and the P.I.P.S. run-time C library +context - this is performed by the CRT0 library (also +known as glue code, see the Glue code (CRT0) section for further details).

P.I.P.S. +executables are implemented using native Symbian platform executables +linked statically to the glue code. The new target types for P.I.P.S. +include the glue code by default. The glue code provides the linking +code between the E32Main() entry point and the main() entry point used in 'C' P.I.P.S. EXEs.

For +further information see the Target Types section.

Symbol +information

When building a P.I.P.S. DLL (that is, when +the target type is STDDLL), function and data symbols +with extern linkage will be exported or imported +by default, without any requirement for IMPORT_C /EXPORT_C declarations in the header or source +files.

Exporting of symbols with extern linkage +is the assumed default on other platforms and enables the source code +to be easily ported. Although this may normally be undesirable in +the embedded world, it is supported for STDDLL to +avoid portable source code having to include excessive decoration +(that is, the IMPORT_C /EXPORT_C macros) for the Symbian platform.

STDEXE and STDDLL provide symbol name information. For +more information on the Symbian platform target types see the Generation of STDEXE, STDDLL and STDLIB section.

Mapping +POSIX handles to the Symbian platform resource objects

Using non-system +calls

Several P.I.P.S. APIs that directly manipulate the +Symbian platform (native) resources are implemented in the System +Call Adaptation Layer (SCAL). The exceptions to this are pthread s, and memory maps. The pthread APIs use RThread s and RMutex es directly from +within libpthread. Similarly, RChunk s that are used to provide support for memory maps are directly +manipulated from within libc. Note that none of these +APIs allow direct access to the underlying native resources. References +to these are wrapped in POSIX-defined data structures. These data +structures are intended to be treated as opaque and no attempt must +be made to dereference or use the underlying resource reference directly.

All IPC calls enter the SCAL, but are handled in a separate IPC +library. This is a component distinction. The IPC library is logically +still part of the SCAL.

Using the System +Call Adaptation Layer

One of the supports provided by +the System Call Adaptation Layer (SCAL) is the mapping of operations +on UNIX® file descriptors to the corresponding Symbian platform resource +objects. The section below discusses the file descriptors case.

Creating a +new file descriptor

The porting of the 'C' POSIX fopen() function, below, is a good example of mapping POSIX +handles to native Symbian platform resource objects. The mapping is +done through a file descriptor table. As a reminder, every application/process +has its own file descriptor table.

This example shows a call +to the fopen() function:

//myapp.cpp int foo() { //open the test.tx , fd=7 in this example @@ -95,31 +83,30 @@ //writes to file referenced by the file descriptor ret = write (fd, buf, size_t); -}

When myapp tries to open the file with fopen(), -the application makes a call to the equivalent Symbian platform function, RFile::Open(), -and returns the next free entry in the file descriptor table.

In each -table, the values 0, 1 and 2 are -reserved for stdin(), sdtout() and stderr(). -The figure below shows an example file descriptor table.

- -

According to the descriptor table the file descriptor equals 7, -as this was the next free entry in the table, and the write function will -be writing to the file referenced by 7.

Note: A -POSIX descriptor is an index in the process open file table and represents, -for example, an open file, socket or pipe. A Symbian descriptor represents -data which can reside in any memory location, either in ROM or RAM. A descriptor -object maintains pointer and length information to describe the data. All -access to the data is made through the descriptor object.

Descriptors -shared across multiple threads within the same process

Originally +}

When myapp tries to open the file with fopen(), the application makes a call to the equivalent +Symbian platform function, RFile::Open(), and returns +the next free entry in the file descriptor table.

In each +table, the values 0, 1 and 2 are reserved for stdin(), sdtout() and stderr(). The figure below +shows an example file descriptor table.

+ +

According to the descriptor table the file descriptor equals 7, as this was the next free entry in the table, and the +write function will be writing to the file referenced by 7.

Note: A POSIX descriptor is an index in the process +open file table and represents, for example, an open file, socket +or pipe. A Symbian descriptor represents data which can reside in +any memory location, either in ROM or RAM. A descriptor object maintains +pointer and length information to describe the data. All access to +the data is made through the descriptor object.

Descriptors shared +across multiple threads within the same process

Originally on the Symbian platform, resources were thread specific and multi-tasking -was achieved using servers and active objects. In other operating systems, -such as Linux, resources are process-local and multi-tasking is achieved by -multi-threading. The purpose of the POSIX server in the original STDLIB was -to allow system-wide data, resources and descriptors to be shared across multiple -threads. This means there was context switching between the calling thread -and the server thread which added latency.

With the introduction of -the EKA2 kernel, session handles can now be shared across multiple threads -and processes.

P.I.P.S. takes advantage of EKA2 and re-factors the -SCAL to allow descriptors to be shared across multiple threads within the -same process, without the use of the POSIX server.

+was achieved using servers and active objects. In other operating +systems, such as Linux, resources are process-local and multi-tasking +is achieved by multi-threading. The purpose of the POSIX server in +the original STDLIB was to allow system-wide data, +resources and descriptors to be shared across multiple threads. This +means there was context switching between the calling thread and the +server thread which added latency.

With the introduction of +the EKA2 kernel, session handles can now be shared across multiple +threads and processes.

P.I.P.S. takes advantage of EKA2 and +re-factors the SCAL to allow descriptors to be shared across multiple +threads within the same process, without the use of the POSIX server.