Build -Process

Introduction
P.I.P.S. target types
Symbol information
Mapping POSIX handles to the Symbian platform resource objects
- Using non-system calls
- Using the System Call Adaptation Layer

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. For further information, see the Build tools guide section. -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.. For further information see the -native build targets section.

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 - int fd = fopen("c:/test.txt", "r+"); - ... - //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 -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.

+ + + + + +Build +Process +

Introduction
P.I.P.S. target types
Symbol information
Mapping POSIX handles to the Symbian platform resource objects
- Using non-system calls
- Using the System Call Adaptation Layer

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. For further information, see the Build tools guide section. +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.. For further information see the +native build targets section.

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 + int fd = fopen("c:/test.txt", "r+"); + ... + //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 +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.

\ No newline at end of file