|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B" xml:lang="en"><title>Build |
|
13 Process</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <ul> |
|
15 <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> |
|
16 <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> |
|
17 <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> |
|
18 <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> |
|
19 <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> |
|
20 <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> |
|
21 </ul> </li> |
|
22 </ul> |
|
23 <section id="GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F"><title>Introduction</title> <p>Symbian |
|
24 currently builds its emulator code with the Metrowerks CodeWarrior compiler. |
|
25 This is known as the <codeph>WINSCW</codeph> build target. Binaries built |
|
26 with this compiler are put in the <filepath>epoc32\release\winscw</filepath> and <filepath>epoc32\winscw</filepath> directory |
|
27 trees. </p> <p>You can build your programs for the emulator using Metrowerks |
|
28 CodeWarrior. The build tools also support the Microsoft® Visual Studio .NET |
|
29 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. |
|
30 Note that licensees or third-parties may supply additional tools, or extend |
|
31 support to additional compilers, which are not described here. </p> <p>The |
|
32 following sections describe the Symbian platform target types |
|
33 introduced with P.I.P.S.. For further information see <xref href="GUID-763DCEF4-C960-58A2-99DC-7FFD3187BFD4.dita">the |
|
34 native build targets</xref> section. </p> <p>When using tool chains for pre-Symbian |
|
35 OS v9.3, the <filepath>.mmp</filepath> file has to be manually changed to |
|
36 link in various libraries. </p> <p>For Symbian OS v9.3 onwards the tool chain |
|
37 supports the new <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> target |
|
38 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 |
|
39 of STDEXE, STDDLL and STDLIB</xref> section for further explanation of the |
|
40 new target types introduced with P.I.P.S.. </p> </section> |
|
41 <section id="GUID-423A00CF-D668-5114-860D-B30185DAB0B2"><title>P.I.P.S. target |
|
42 types</title> <p>P.I.P.S. EXEs require adaptation logic to set up the C program |
|
43 environment and the P.I.P.S. run-time C library context - this is performed |
|
44 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 |
|
45 code (CRT0)</xref> section for further details). </p> <p>P.I.P.S. executables |
|
46 are implemented using native Symbian platform executables linked statically |
|
47 to the glue code. The new target types for P.I.P.S. include the glue code |
|
48 by default. The glue code provides the linking code between the <codeph>E32Main()</codeph> entry |
|
49 point and the <codeph>main()</codeph> entry point used in 'C' P.I.P.S. EXEs. </p> <p>For |
|
50 further information see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita">Target |
|
51 Types</xref> section. </p> </section> |
|
52 <section id="GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D"><title>Symbol information</title> <p>When |
|
53 building a P.I.P.S. DLL (that is, when the target type is <codeph>STDDLL</codeph>), |
|
54 function and data symbols with <codeph>extern</codeph> linkage will be exported |
|
55 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 |
|
56 in the header or source files. </p> <p>Exporting of symbols with <codeph>extern</codeph> linkage |
|
57 is the assumed default on other platforms and enables the source code to be |
|
58 easily ported. Although this may normally be undesirable in the embedded world, |
|
59 it is supported for <codeph>STDDLL</codeph> to avoid portable source code |
|
60 having to include excessive decoration (that is, the <codeph>IMPORT_C</codeph> /<codeph>EXPORT_C</codeph> macros) |
|
61 for the Symbian platform. </p> <p> <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> provide |
|
62 symbol name information. For more information on the Symbian platform target |
|
63 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 |
|
64 of STDEXE, STDDLL and STDLIB</xref> section. </p> </section> |
|
65 <section id="GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E"><title>Mapping POSIX |
|
66 handles to the Symbian platform resource objects</title> <p id="GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE"><b>Using |
|
67 non-system calls</b> </p> <p>Several P.I.P.S. APIs that directly manipulate |
|
68 the Symbian platform (native) resources are implemented in the System Call |
|
69 Adaptation Layer (SCAL). The exceptions to this are <codeph>pthread</codeph> s, |
|
70 and memory maps. The <codeph>pthread</codeph> APIs use <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> s |
|
71 and <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref> es directly from within <codeph>libpthread</codeph>. |
|
72 Similarly, <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> s that are used to provide support for |
|
73 memory maps are directly manipulated from within <codeph>libc</codeph>. Note |
|
74 that none of these APIs allow direct access to the underlying native resources. |
|
75 References to these are wrapped in POSIX-defined data structures. These data |
|
76 structures are intended to be treated as opaque and no attempt must be made |
|
77 to dereference or use the underlying resource reference directly. </p> <p>All |
|
78 IPC calls enter the SCAL, but are handled in a separate IPC library. This |
|
79 is a component distinction. The IPC library is logically still part of the |
|
80 SCAL. </p> <p id="GUID-FBF12198-B501-5525-86AF-5517A012FDF1"><b>Using the |
|
81 System Call Adaptation Layer</b> </p> <p>One of the supports provided by the |
|
82 System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX® |
|
83 file descriptors to the corresponding Symbian platform resource objects. The |
|
84 section below discusses the file descriptors case. </p> <p id="GUID-1A1FC433-B9F6-5998-9622-14B961F477E2"><b>Creating |
|
85 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, |
|
86 below, is a good example of mapping POSIX handles to native Symbian platform |
|
87 resource objects. The mapping is done through a file descriptor table. As |
|
88 a reminder, every application/process has its own file descriptor table. </p> <p>This |
|
89 example shows a call to the <codeph>fopen()</codeph> function: </p> <codeblock id="GUID-F9681B44-A1E6-5971-9C5E-147D4281DBF0" xml:space="preserve">//myapp.cpp |
|
90 int foo() |
|
91 { |
|
92 //open the test.tx , fd=7 in this example |
|
93 int fd = fopen("c:/test.txt", "r+"); |
|
94 ... |
|
95 //writes to file referenced by the file descriptor |
|
96 ret = write (fd, buf, size_t); |
|
97 |
|
98 }</codeblock> <p>When <i>myapp</i> tries to open the file with <codeph>fopen()</codeph>, |
|
99 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>, |
|
100 and returns the next free entry in the file descriptor table. </p> <p>In each |
|
101 table, the values <codeph>0</codeph>, <codeph>1</codeph> and <codeph>2</codeph> are |
|
102 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>. |
|
103 The figure below shows an example file descriptor table. </p> <fig id="GUID-4CEA6881-49E0-5211-8258-C44A8E8F3CDE"> |
|
104 <image href="GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e156386_href.png" placement="inline"/> |
|
105 </fig> <p>According to the descriptor table the file descriptor equals <codeph>7</codeph>, |
|
106 as this was the next free entry in the table, and the write function will |
|
107 be writing to the file referenced by <codeph>7</codeph>. </p> <p> <b>Note:</b> A |
|
108 POSIX descriptor is an index in the process open file table and represents, |
|
109 for example, an open file, socket or pipe. A Symbian descriptor represents |
|
110 data which can reside in any memory location, either in ROM or RAM. A descriptor |
|
111 object maintains pointer and length information to describe the data. All |
|
112 access to the data is made through the descriptor object. </p> <p id="GUID-79958B57-8C71-5875-9C5B-8C313A96D13A"><b>Descriptors |
|
113 shared across multiple threads within the same process</b> </p> <p>Originally |
|
114 on the Symbian platform, resources were thread specific and multi-tasking |
|
115 was achieved using servers and active objects. In other operating systems, |
|
116 such as Linux, resources are process-local and multi-tasking is achieved by |
|
117 multi-threading. The purpose of the POSIX server in the original <codeph>STDLIB</codeph> was |
|
118 to allow system-wide data, resources and descriptors to be shared across multiple |
|
119 threads. This means there was context switching between the calling thread |
|
120 and the server thread which added latency. </p> <p>With the introduction of |
|
121 the EKA2 kernel, session handles can now be shared across multiple threads |
|
122 and processes. </p> <p>P.I.P.S. takes advantage of EKA2 and re-factors the |
|
123 SCAL to allow descriptors to be shared across multiple threads within the |
|
124 same process, without the use of the POSIX server. </p> </section> |
|
125 </conbody></concept> |