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-BFE1422D-3B4A-5B25-A757-B5B68D6390F8" xml:lang="en"><title>Port

    13 Implementation Tutorial</title><shortdesc>This topic describes how to customize the Base Starter. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-9F925D19-DFAB-5C2A-8A04-E82963F2D221"><title>Creating local

    15 drive mapping files</title> <ol id="GUID-B20B8E9B-2FA5-57F2-9F06-88ED21D24E87">

    16 <li id="GUID-BD13EA0C-81E2-5174-BFB0-1857B17BE85B"><p>Create an ASCII text

    17 file containing your local drive mapping records; see <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-2B95B775-1BD1-5256-86D3-CD3FA12447B9">create local drive mapping files</xref> for information about the syntax

    18 of the file. </p> </li>

    19 <li id="GUID-03BE3694-C78E-5A46-B4FF-FCAF55CED8D4"><p>Put this text file into

    20 your variant source tree. The source tree is typically of the form <filepath>sf/os/boardsupport/.../&lt;your

    21                 variant&gt;/estart/</filepath> . Depending on your port, you

    22 might need more than one local drive mapping file. </p> </li>

    23 <li id="GUID-1850EBF2-71EB-53D6-A2AC-2FE33AEC8AE8"><p>In the <filepath>kernel.iby</filepath> file

    24 for your variant, you need to add lines to make sure that your local drive

    25 mapping files are copied into the ROM's <filepath>\sys\data\</filepath> directory

    26 when the ROM is built. For example include a lines in the form </p> <codeblock id="GUID-B7C15498-DB7E-51CF-83D9-25013ABEC3B8" xml:space="preserve">data=\epoc32\rom\youvariant\ESTARTCOMP.TXT              \Sys\Data\ESTARTCOMP.TXT</codeblock> </li>

    27 <li id="GUID-2808A5CB-D270-56D7-BE0E-BA476A31AFC6"><p>If you need more than

    28 one mapping file, or your single mapping file has a name other than <filepath>ESTART.TXT</filepath>,

    29 then you need to customise the function <xref href="GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7.dita#GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7/GUID-F46A932C-8CC0-3F39-8C68-38C2660F86E7"><apiname>TFSStartUp::LocalDriveMappingFileName()</apiname></xref> so

    30 that you can return the appropriate file name at run time. </p> </li>

    31 </ol> </section>

    32 <section id="GUID-51FBCDD1-7DB4-556D-9599-5F8B54837852"><title>Making use

    33 of auto detection</title> <p>To make use of auto-detection, you need to ensure

    34 that your variant cannot find local drive mapping files in your ROM's <filepath>\sys\data\</filepath> directory.

    35 If you are using the default version of <xref href="GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7.dita#GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7/GUID-F46A932C-8CC0-3F39-8C68-38C2660F86E7"><apiname>TFSStartUp::LocalDriveMappingFileName()</apiname></xref>,

    36 then make sure that no file exists with the full path name <filepath>Z:\sys\data\estart.txt</filepath>. </p> </section>

    37 <section id="GUID-AA916F3A-E8DF-522D-BDD6-18C2FD82AC16"><title>Customising

    38 code</title> <p>The most common customisation is to provide your own implementation

    39 of the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup</apiname></xref> virtual functions. To do this: </p> <ol id="GUID-7C709736-88C7-5770-8799-44C5DE9B78A2">

    40 <li id="GUID-A5CB09C7-C008-5ADA-BC1C-BFDC268570B9"><p>Take a copy of <filepath>ESTARTMAIN.CPP</filepath> from <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/</filepath>, and insert your code into this copy. Typically this will include, but is

    41 not limited to, your implementation of the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup</apiname></xref> virtual

    42 functions. </p> </li>

    43 <li id="GUID-A67D8EB7-A4A7-54DE-A46C-BF44FC6F173C"><p>Place the copy into

    44 your variant's source tree. This is typically of the form <filepath>sf/os/boardsupport/.../&lt;your

    45 variant&gt;/estart/</filepath>. This is the general pattern for the other ports

    46 supplied with Symbian platform. </p> </li>

    47 <li id="GUID-24536FD8-EABF-5E4D-A691-F36FEEBB604C"><p>Create a <filepath>.mmp</filepath> file

    48 to build your variant's version of the Base Starter. This is usually placed

    49 in the <filepath>\&lt;youvariant&gt;\</filepath> directory. The general pattern

    50 looks like this: <filepath>sf/os/boardsupport/.../&lt;your               

    51  variant&gt;/estart/estart.mmp</filepath>. Ports to other hardware variants and

    52 the emulator (WINS) variant follow the same general pattern. </p> </li>

    53 <li id="GUID-41111731-D21E-53E8-9728-1F2E8B2977B9"><p>Your <filepath>.mmp</filepath> file

    54 should pick up the Symbian platform generic code from <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/estart.cpp</filepath>,

    55 but should pick up your variant's customised source code from <filepath>sf/os/boardsupport/.../&lt;your

    56 variant&gt;/estart/estartmain.cpp</filepath>. The general pattern is to give

    57 the resulting executable the name <filepath>e32strt.exe</filepath>. </p> </li>

    58 <li id="GUID-FBBE887B-69D6-5904-8BD6-7E67F1B049B7"><p>In the <filepath>kernel.iby</filepath> file

    59 for your variant, you need to add a line that copies your executable into

    60 the ROM's <filepath>\sys\bin\</filepath> directory when the ROM is built.

    61 For example, include a line of the form: </p> <codeblock id="GUID-DF458ADA-69B8-5AC3-92D1-F57B9C14C326" xml:space="preserve">file=\Epoc32\Release\##MAIN##\##BUILD##\_##VARIANT##_e32strt.exe        sys\bin\estart.exe HEAPMAX(0x2000)</codeblock> </li>

    62 </ol> </section>

    63 <section id="GUID-92EE546A-2945-55EC-A0C3-4CE2ED7926CF"><title>Removing auto

    64 detect from the Base Starter</title> <p>You do this only if you need to save

    65 code space, and you do not need the autodetect functionality. </p> <p>See

    66 also <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-A195BD51-80C7-5D87-ABA2-8878CC509B84">Use

    67 automatic local drive mapping</xref>. </p> <ol id="GUID-6B18F11A-5271-5E04-A246-3143A856722B">

    68 <li id="GUID-D86AD2FB-EDF7-5A95-949E-3C7BE9B609F0"><p>Create a <filepath>.mmp</filepath> file

    69 to build your variant's version of the Base Starter. This is usually placed

    70 in the <filepath>sf/os/boardsupport/.../&lt;your variant&gt;/estart/</filepath> directory.

    71 This shows the general pattern. Ports to other hardware variants and the emulator

    72 (WINS) variant follow the same general pattern. </p> </li>

    73 <li id="GUID-CFA6F952-2637-5999-8C06-191B8C9B81EB"><p>In your <filepath>.mmp</filepath> file,

    74 define the macro: </p> <codeblock id="GUID-7DCF288E-CF86-550F-95BB-33CDAF342C66" xml:space="preserve">MACRO AUTODETECT_DISABLE</codeblock> </li>

    75 <li id="GUID-3CD0D0C9-5CA5-5CCA-A918-5076DD38C576"><p>The location of all

    76 source files in the <filepath>.mmp</filepath> file will be <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/</filepath>. </p> </li>

    77 <li id="GUID-9D679A09-134A-5E09-9A29-79D52B6BE975"><p>In the <filepath>kernel.iby</filepath> file

    78 for your variant, you need to add a line to make sure that your executable

    79 is copied into the ROM's <filepath>\sys\bin\</filepath> directory when the

    80 ROM is built. For example, include a line of the form </p> <codeblock id="GUID-F893D88D-212A-5396-AB64-918CB48A37A1" xml:space="preserve">file=\Epoc32\Release\##MAIN##\##BUILD##\_##VARIANT##_e32strt.exe        sys\bin\estart.exe HEAPMAX(0x2000)</codeblock> <p>This is the general pattern for the other ports supplied with Symbian

    81 platform. </p> </li>

    82 </ol> </section>

    83 <section id="GUID-251E3B54-AB58-4FE4-8E81-0ED48484C1FD"><title>See also</title> <p><xref href="GUID-E5459A54-14BC-55C1-B911-63415E4C61A6.dita">Concepts</xref>  </p> </section>

    84 </conbody></concept>