<?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 <uicontrol>MMP file syntax</uicontrol> in <uicontrol>Symbian Tools Guide &gt; Building
 &gt; Symbian Build System (SBSv1) &gt; Build tools reference</uicontrol>.</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_d0e269008_href.png" placement="inline"/>
</fig> </section>
</conbody></concept>