1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/boardsupport/emulator/emulatorbsp/win_drive/readme.txt Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,139 @@
1.4 +/*
1.5 +* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +Description:
1.23 +-----------------------------------
1.24 +
1.25 +The "win_drive" file system extension for the emulator allows you to attach Windows device
1.26 +(that supports CreateFile/ReadFile/WriteFile operations) to the Symbian OS emulator as the emulated drive.
1.27 +For example, windows HDD partition, removable drive or a file can be treated by the emulator as "media" mapped
1.28 +on some emulator's drive letter.
1.29 +
1.30 +How it works:
1.31 +-----------------------------------
1.32 +
1.33 +This extension is installed as a primary one and hooks all emulators media driver's operations redirecting them to
1.34 +appropriate windows file IO API.
1.35 +
1.36 +Why:
1.37 +-----------------------------------
1.38 +
1.39 +Existing Symbian OS windows emulator has a quite limited support for its drives:
1.40 +
1.41 +- emulator's drives suport can be implemented within media driver stacks (like mmc) which is not
1.42 + very easy to configure properly. Moreover, using whole driver stacks is not always required and
1.43 + slows down emulator filesystems.
1.44 +
1.45 +- it is not always easy to attach filesystem image file to the emulator and it's impossible make it
1.46 + to use physical drive (USB drive for example)
1.47 +
1.48 +- emulated MMC drives can't be bigger than 1G or something, which doesn't make work with FAT32 easy.
1.49 +
1.50 +
1.51 +How to use:
1.52 +-----------------------------------
1.53 +1. make sure that the extension file "win_drive.fxt" is present in the emulator's "Z:\" drive directory:
1.54 +"\epoc32\release\wins\udeb\" or "\epoc32\release\winscw\udeb\" or "...\urel\", depending on what platform
1.55 +and release you are using.
1.56 +
1.57 +2. copy "win_drive.ini" configuration file to: "\epoc32\data\"
1.58 +3. edit this file to set up emulated drive size, location etc. See inside.
1.59 +
1.60 +4. Tell the emulator to install "win_drive.fxt" extension to the emulator's drive you are going to use.
1.61 + to do this edit appropritae "estart.txt" file, which can be, for example, here: \epoc32\release\wins\udeb\z\sys\DATA\estart.txt
1.62 + If there is no such a file, copy the default one from "\emulator\wins\estart\estart.txt"
1.63 +
1.64 + Example:
1.65 +
1.66 + [....]
1.67 + #X: 1 EFAT32 FAT 0 FS_FORMAT_CORRUPT #<--- previous commented out line
1.68 + X: 1 EFAT32 FAT win_drive FS_FORMAT_CORRUPT #<--- drive "X:" now has "win_drive" primary extension
1.69 + [....]
1.70 +
1.71 +5. run the emulator, its drive "X:" will be redirected to the device you have set up in the "win_drive.ini" file.
1.72 +
1.73 +
1.74 +
1.75 +Configuration examples:
1.76 +-----------------------------------
1.77 +
1.78 +1. Windows drive F: is a USB cardreader with the SD card you want to use as the emulator's "X:" FAT drive.
1.79 +Minimal settings in "win_drive.ini" for this case:
1.80 +
1.81 +=========================
1.82 +[Drive_X]
1.83 +DeviceName=\\.\F:
1.84 +BytesPerSector=0 ;or just comment it out
1.85 +MediaSizeInSectors=0 ;or just comment it out
1.86 +=========================
1.87 +
1.88 +2. You have a spare partition that has "Z:" windows drive letter and you want to use a part of it (to say 1G) as the emulator's "X:" FAT drive.
1.89 +Minimal settings in "win_drive.ini" for this case:
1.90 +
1.91 +=========================
1.92 +[Drive_X]
1.93 +DeviceName=\\.\Z:
1.94 +MediaSizeInSectors=2097152
1.95 +=========================
1.96 +
1.97 +
1.98 +3. You want to use 8G file as the emulator's "X:" FAT drive. The file doesn't exist.
1.99 +
1.100 +Minimal settings in "win_drive.ini" for this case:
1.101 +=========================
1.102 +[Drive_X]
1.103 +DeviceName=c:\MyDir\MyImageFile8G.img
1.104 +MediaSizeInSectors=16777216
1.105 +=========================
1.106 +
1.107 +
1.108 +4. You have a FAT volume image file and want to attach it as as the emulator's "X:" FAT drive. You also want to have it read-only.
1.109 +
1.110 +Minimal settings in "win_drive.ini" for this case:
1.111 +=========================
1.112 +[Drive_X]
1.113 +DeviceName=c:\MyDir\MyImageFile.img
1.114 +MediaSizeInSectors=0 ;or just comment it out
1.115 +ReadOnly = 1;
1.116 +=========================
1.117 +
1.118 +
1.119 +Troubleshooting:
1.120 +-----------------------------------
1.121 +See "epocwind.out" file if something is going wrong.
1.122 +
1.123 +
1.124 +
1.125 +Drawbacks:
1.126 +-----------------------------------
1.127 +
1.128 +- you can't use this extension if the emulator's drive alredy uses primary extension (see estart.txt).
1.129 +- some dodgy tests can fail, for example, those, that dismount the file system and forget to store and mount all its extensions
1.130 + include primary.
1.131 +- Some methods from media driver are not overriden yet and just go directly to the original media driver; it can be confusing.
1.132 +
1.133 +
1.134 +
1.135 +
1.136 +
1.137 +
1.138 +
1.139 +
1.140 +
1.141 +
1.142 +