<?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-A188606F-4A8E-5A85-A241-E15219960EFA" xml:lang="en"><title>Loader
Overview</title><shortdesc>This topic describes the overview, purpose, key concepts and architecture
of loader.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<ul>
<li id="GUID-AE825AB3-3799-5A7A-A74D-D6E457A6997E"><p> <xref href="GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita#GUID-A188606F-4A8E-5A85-A241-E15219960EFA/GUID-E36370EC-CD5E-54AE-AD62-2BA3B70F5379">Purpose</xref>  </p> </li>
<li id="GUID-9D2C951C-6092-53BB-BFA9-4D33230721FA"><p> <xref href="GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita#GUID-A188606F-4A8E-5A85-A241-E15219960EFA/GUID-89A8CABD-6B31-5D10-87F6-922CCFB83186">Key concepts</xref>  </p> </li>
<li id="GUID-B21577D8-3B8B-596F-A3B6-6AC2538F6F28"><p> <xref href="GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita#GUID-A188606F-4A8E-5A85-A241-E15219960EFA/GUID-64154337-D706-5DE1-9319-4FEA6181EFC4">Architectural relationships</xref>  </p> </li>
</ul>
<section id="GUID-E36370EC-CD5E-54AE-AD62-2BA3B70F5379"><title>Purpose</title> <p>The
loader makes EXEs and DLLs ready to run. </p> <p>The build tools compile the
source code into an executable file. An executable file is called a binary.
The build tools arrange the compiled code into EXEs and DLLs. The source code,
header files and other information that defines an executable file is defined
in an mmp file. The loader applies relocation information to the code and
data sections of EXEs and DLLs. The loader also loads DLLs that are referred
to by other EXEs and DLLs. EXEs and DLLs can then run in the process into
which they are loaded. </p> </section>
<section id="GUID-89A8CABD-6B31-5D10-87F6-922CCFB83186"><title>Key concepts</title> <p><b>The loader server</b> </p> <p>The Symbian platform loader is a server.
The loader server has no public client interface. The client interface is
internal to Symbian platform. Requests to load an EXE or a DLL are passed
to the loader when you do the following: </p> <ul>
<li id="GUID-5DFBB7F5-2F30-50C7-9144-3D6D85C0ACA1"><p>start a new process
- a call to <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>  </p> </li>
<li id="GUID-B88FC041-7643-5CA0-9796-A51E64CAA1DF"><p>load a DLL - a call
to <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>  </p> </li>
<li id="GUID-A7578989-6BDB-5CEA-B3C3-0B5A08E57166"><p>load a logical device
driver - a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE0D51B7-7ADC-3C9F-ACAA-8F6D9EA0AEFA"><apiname>User::LoadLogicalDevice()</apiname></xref>. A logical
device driver is a type of DLL. </p> </li>
<li id="GUID-34DC54FE-FCEF-5F83-B205-9BA5B7140680"><p>load a physical device
driver - a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A0F4BF4A-9C58-3E5E-88E1-6D98597DDA18"><apiname>User::LoadPhysicalDevice()</apiname></xref>. A physical
device driver is a type of DLL. </p> </li>
<li id="GUID-51318E5E-4534-589B-B4BD-92D73F832A6F"><p>load a file system -
a call to <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita#GUID-E263C747-946F-35AA-9F1D-41833BD350FC/GUID-51353BE2-9133-39F5-83F3-A5DB88D858CA"><apiname>RFs::AddFileSystem()</apiname></xref>. A file system is a type
of DLL. A call to <codeph>RFs::AddFileSystem()</codeph> requires DiskAdmin
capability. See <xref href="GUID-99D8A4E8-BC4F-39FF-A3DF-832CF0411629.dita"><apiname>ECapabilityDiskAdmin</apiname></xref>. </p> </li>
<li id="GUID-8394C231-341B-5EA6-B9C2-01F75685813D"><p>load a file server extension
- call to <xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita#GUID-E263C747-946F-35AA-9F1D-41833BD350FC/GUID-D45FD363-EEF9-3F77-8FA1-49270D8E89A0"><apiname>RFs::AddExtension()</apiname></xref>. A file server extension
is a type of DLL. This function requires DiskAdmin capability. See <xref href="GUID-99D8A4E8-BC4F-39FF-A3DF-832CF0411629.dita"><apiname>ECapabilityDiskAdmin</apiname></xref>. </p> </li>
<li id="GUID-F1889916-80EB-55B6-BEAF-F66164F3838C"><p>load a locale - a call
to <xref href="GUID-454ACAB5-1573-323C-820E-AF542B149D2A.dita#GUID-454ACAB5-1573-323C-820E-AF542B149D2A/GUID-9F04584E-DD0B-39CE-8666-88F67F3B83BF"><apiname>TExtendedLocale::LoadLocale()</apiname></xref>. </p> </li>
</ul> <p><b>Version
numbers</b> </p> <p><b>The
reason for version numbers</b> </p> <p>More than one version of an EXE can
exist on a device at the same time. More than one version of a DLL can exist
on a device at the same time. A device can store versions of an EXE or DLL
that are not compatible with an older version of that EXE or DLL. </p> <p>A
version number is a set of two numbers. The loader uses these numbers to identify
copies of the executable file. The two numbers are called the major version
number and the minor version number. The build tools encode the two numbers
into the header of the executable file. When a DLL is built, the version numbers
are encoded into the import library. </p> <p><b>The
structure of version information</b> </p> <p>DLLs are the most common users
of versions. You assign new values to the version numbers of a DLL when you
change the published API of the DLL. Symbian recommends the following procedure: </p> <ul>
<li id="GUID-A3D6B7C6-E48E-5374-8EFE-29EB129FEE04"><p>change the minor version
number if you make a change to a DLL that is backward compatible. An example
is a new function in the DLL. </p> </li>
<li id="GUID-F6813400-1E6A-58B9-8360-7FD364F2153A"><p>change the major version
number if you make a change to a DLL that breaks an interface. An example
is the removal of a function or a change to the signature of a function. An
interface break is disruptive and must be prevented. </p> </li>
</ul> <p>The major and minor version numbers are defined in the <filepath>.mmp</filepath> file
that defines the source code, header files and other options that apply to
the executable file. </p> <p>If you do not specify version numbers, the build
tools apply the following default values: </p> <ul>
<li id="GUID-CBF4D098-3A83-53E6-9E54-0A9B487D6E22"><p>Major version number
: 10 </p> </li>
<li id="GUID-46E7516E-988B-5F92-9877-FEE17D3F26A7"><p>Minor version number
: 0 </p> </li>
</ul> <p>The major version number and the minor version number are stored
in the header of an EXE and DLL. The two numbers are stored in a single 32
bit value. The high 16 bits hold the major version number. The low 16 bits
hold the minor version number. </p> <p>When you build a DLL, the build tools
encode the version numbers into the filename of the import library (the <filepath>.lib</filepath> file).
The build tools also create an import library that does not have the version
numbers encoded as part of the filename.The following example shows how the
version numbers are encoded in the filename. The major version number is (decimal)
11 and the minor version number is (decimal) 2. The version numbers in the
filename are in hexadecimal. </p> <p> <filepath>abcdsrv{000B0002}.lib</filepath>  </p> <p>Notes: </p> <ul>
<li id="GUID-7DC90016-5A54-5939-84B1-DDB0B2D4D9F5"><p>The left bracket and
the right bracket are part of the name. </p> </li>
<li id="GUID-BC291976-EB6D-59D2-8941-64F6ED3AC191"><p>The first four digits
after the open bracket are the hexadecimal representation of the major version
number. </p> </li>
<li id="GUID-51590778-985F-5DCC-9191-E937B1058F51"><p>The second four digits
are the hexadecimal representation of the minor version number. </p> </li>
</ul> <p>The build tools do not encode the version numbers in the filename
of the executable file. </p> <p><b>Loader
search rules</b> </p> <p>EXEs and DLLs can exist on more than one drive. There
can be more than one version of an EXE and more than one version of a DLL.
The loader uses search rules to select the EXE and DLL to load. </p> <p>See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita">Loader search rules</xref>  </p> <p><b>Emulator</b> </p> <p>Version numbers are stored in import files for DLLs
that run on devices and the emulator. Version numbers change how the loader
functions on devices, but not in the emulator. You cannot encode the version
numbers in the import library file name on the emulator. </p> <p><b>Tools support</b> </p> <p>Use the build tools to apply version numbers
to EXEs and DLLs. You specify version numbers in the <filepath>.mmp</filepath> file
that describes the EXE or DLL. </p> <p>See also <xref href="GUID-BBBB5000-90A2-503A-9521-2FC6DEC69DC8.dita">mmp
file syntax</xref> and <xref href="GUID-B21141D4-3BFE-59C9-8D5F-147A93BE1C95.dita">Build
tools guide</xref>. </p> </section>
<section id="GUID-64154337-D706-5DE1-9319-4FEA6181EFC4"><title>Architectural
relationships</title> <p>The loader is a server that runs in a separate thread
in the file server process. The loader is built as part of the file server. </p> <p>The
loader server starts when the file server starts. The file server starts after
the kernel is loaded at system start. </p> <p>The loader runs on the user
side, but calls the kernel for services that are not available to general
applications. Examples of services are process creation and code segment creation.
A code segment is an object that represents a piece of code loaded into RAM.
A code segment also represents a piece of code that runs directly from ROM.
The kernel services that the loader uses are protected. The file server process
only is allowed to access these services. </p> <p>The following picture is
an example of program flow. In this example, a client calls <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>,
which exists in <filepath>euser.dll</filepath>. Internal functions make client-server
calls to the loader server. The loader server code exists in <filepath>efile.exe</filepath>.
The loader server uses kernel services. </p> <fig id="GUID-5FCAE81A-19BC-5BE7-89D2-096A87735381">
<image href="GUID-2735BDAF-295F-5F1E-8925-8F4212D95CD1_d0e264145_href.png" placement="inline"/>
</fig> </section>
</conbody></concept>