--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,125 @@
+<?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-79100974-CAE1-5451-9ED7-E06C9B27131B" xml:lang="en"><title>Build
+Process</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<ul>
+<li id="GUID-1F561425-9B98-544A-A0CB-086E0931313E"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F">Introduction</xref>  </p> </li>
+<li id="GUID-DE26248D-27DE-5B38-9BFA-FE4CBAB676F6"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-423A00CF-D668-5114-860D-B30185DAB0B2">P.I.P.S. target types</xref>  </p> </li>
+<li id="GUID-9EC5C68C-CDFC-5608-A26C-FD6001822217"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D">Symbol information</xref>  </p> </li>
+<li id="GUID-6EDF3969-49B8-5F74-BFBF-C323D2C8480C"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E">Mapping POSIX handles to the Symbian platform resource objects</xref>  </p> <ul>
+<li id="GUID-30586541-C6EB-5794-8171-2302C53AAE45"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE">Using non-system calls</xref>  </p> </li>
+<li id="GUID-E146BFE8-FDFE-551D-B280-5AD5303996C7"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-FBF12198-B501-5525-86AF-5517A012FDF1">Using the System Call Adaptation Layer</xref>  </p> </li>
+</ul> </li>
+</ul>
+<section id="GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F"><title>Introduction</title> <p>Symbian
+currently builds its emulator code with the Metrowerks CodeWarrior compiler.
+This is known as the <codeph>WINSCW</codeph> build target. Binaries built
+with this compiler are put in the <filepath>epoc32\release\winscw</filepath> and <filepath>epoc32\winscw</filepath> directory
+trees. </p> <p>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 <xref href="GUID-B21141D4-3BFE-59C9-8D5F-147A93BE1C95.dita">Build tools guide</xref> section.
+Note that licensees or third-parties may supply additional tools, or extend
+support to additional compilers, which are not described here. </p> <p>The
+following sections describe the Symbian platform target types
+introduced with P.I.P.S.. For further information see <xref href="GUID-763DCEF4-C960-58A2-99DC-7FFD3187BFD4.dita">the
+native build targets</xref> section. </p> <p>When using tool chains for pre-Symbian
+OS v9.3, the <filepath>.mmp</filepath> file has to be manually changed to
+link in various libraries. </p> <p>For Symbian OS v9.3 onwards the tool chain
+supports the new <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> target
+types for P.I.P.S. EXEs and DLLs. See the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita#GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B/GUID-5D0338E0-E2D4-5904-9B21-244CA52DD91B">Generation
+of STDEXE, STDDLL and STDLIB</xref> section for further explanation of the
+new target types introduced with P.I.P.S.. </p> </section>
+<section id="GUID-423A00CF-D668-5114-860D-B30185DAB0B2"><title>P.I.P.S. target
+types</title> <p>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 <codeph>CRT0</codeph> library (also known as glue code, see the <xref href="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita#GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D/GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655">Glue
+code (CRT0)</xref> section for further details). </p> <p>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 <codeph>E32Main()</codeph> entry
+point and the <codeph>main()</codeph> entry point used in 'C' P.I.P.S. EXEs. </p> <p>For
+further information see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita">Target
+Types</xref> section. </p> </section>
+<section id="GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D"><title>Symbol information</title> <p>When
+building a P.I.P.S. DLL (that is, when the target type is <codeph>STDDLL</codeph>),
+function and data symbols with <codeph>extern</codeph> linkage will be exported
+or imported by default, without any requirement for <xref href="GUID-BD292953-36BF-3C7D-AA93-98E6CB38968E.dita"><apiname>IMPORT_C</apiname></xref> /<xref href="GUID-2F78C3AC-7330-34C0-8A83-75D7345F2DC8.dita"><apiname>EXPORT_C</apiname></xref> declarations
+in the header or source files. </p> <p>Exporting of symbols with <codeph>extern</codeph> 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 <codeph>STDDLL</codeph> to avoid portable source code
+having to include excessive decoration (that is, the <codeph>IMPORT_C</codeph> /<codeph>EXPORT_C</codeph> macros)
+for the Symbian platform. </p> <p> <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> provide
+symbol name information. For more information on the Symbian platform target
+types see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita#GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B/GUID-5D0338E0-E2D4-5904-9B21-244CA52DD91B">Generation
+of STDEXE, STDDLL and STDLIB</xref> section. </p> </section>
+<section id="GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E"><title>Mapping POSIX
+handles to the Symbian platform resource objects</title> <p id="GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE"><b>Using
+non-system calls</b> </p> <p>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 <codeph>pthread</codeph> s,
+and memory maps. The <codeph>pthread</codeph> APIs use <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> s
+and <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref> es directly from within <codeph>libpthread</codeph>.
+Similarly, <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> s that are used to provide support for
+memory maps are directly manipulated from within <codeph>libc</codeph>. 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. </p> <p>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. </p> <p id="GUID-FBF12198-B501-5525-86AF-5517A012FDF1"><b>Using the
+System Call Adaptation Layer</b> </p> <p>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. </p> <p id="GUID-1A1FC433-B9F6-5998-9622-14B961F477E2"><b>Creating
+a new file descriptor</b> </p> <p>The porting of the 'C' POSIX <xref href="GUID-64886CC6-072F-3542-855A-5D733FC761E8.dita"><apiname>fopen()</apiname></xref> 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. </p> <p>This
+example shows a call to the <codeph>fopen()</codeph> function: </p> <codeblock id="GUID-F9681B44-A1E6-5971-9C5E-147D4281DBF0" xml:space="preserve">//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);
+
+}</codeblock> <p>When <i>myapp</i> tries to open the file with <codeph>fopen()</codeph>,
+the application makes a call to the equivalent Symbian platform function, <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita#GUID-BE0804F6-4375-3C8A-8C83-968F510466E0/GUID-72470A68-7E07-30EF-A3C8-AA855CDAF60E"><apiname>RFile::Open()</apiname></xref>,
+and returns the next free entry in the file descriptor table. </p> <p>In each
+table, the values <codeph>0</codeph>, <codeph>1</codeph> and <codeph>2</codeph> are
+reserved for <xref href="GUID-C0C1D22B-298F-3E8D-A1E9-6F5EFA81F9E8.dita"><apiname>stdin()</apiname></xref>, <xref href="GUID-0441C351-4A8B-3A23-9255-D7C8CEA2A67F.dita"><apiname>sdtout()</apiname></xref> and <xref href="GUID-4FF97B50-2C1E-37EC-888B-FB8D3F14B5B8.dita"><apiname>stderr()</apiname></xref>.
+The figure below shows an example file descriptor table. </p> <fig id="GUID-4CEA6881-49E0-5211-8258-C44A8E8F3CDE">
+<image href="GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e156386_href.png" placement="inline"/>
+</fig> <p>According to the descriptor table the file descriptor equals <codeph>7</codeph>,
+as this was the next free entry in the table, and the write function will
+be writing to the file referenced by <codeph>7</codeph>. </p> <p> <b>Note:</b> 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. </p> <p id="GUID-79958B57-8C71-5875-9C5B-8C313A96D13A"><b>Descriptors
+shared across multiple threads within the same process</b> </p> <p>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 <codeph>STDLIB</codeph> 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. </p> <p>With the introduction of
+the EKA2 kernel, session handles can now be shared across multiple threads
+and processes. </p> <p>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. </p> </section>
+</conbody></concept>
\ No newline at end of file