os/boardsupport/emulator/emulatorbsp/win_drive/readme.txt
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
     1 /*
     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:
    15 *
    16 */
    17 
    18 
    19 Description:
    20 -----------------------------------
    21 
    22 The "win_drive" file system extension for the emulator allows you to attach Windows device
    23 (that supports CreateFile/ReadFile/WriteFile operations) to the Symbian OS emulator as the emulated drive.
    24 For example, windows HDD partition, removable drive or a file can be treated by the emulator as "media" mapped
    25 on some emulator's drive letter.
    26 
    27 How it works:
    28 -----------------------------------
    29 
    30 This extension is installed as a primary one and hooks all emulators media driver's operations redirecting them to 
    31 appropriate windows file IO API.
    32 
    33 Why:
    34 -----------------------------------
    35 
    36 Existing Symbian OS windows emulator has a quite limited support for its drives:
    37 
    38 - emulator's drives suport can be implemented within media driver stacks (like mmc) which is not
    39   very easy to configure properly. Moreover, using whole driver stacks is not always required and 
    40   slows down emulator filesystems.
    41 
    42 - it is not always easy to attach filesystem image file to the emulator and it's impossible make it 
    43   to use physical drive (USB drive for example)
    44 
    45 - emulated MMC drives can't be bigger than 1G or something, which doesn't make work with FAT32 easy.
    46 
    47 
    48 How to use:
    49 -----------------------------------
    50 1. make sure that the extension file "win_drive.fxt" is present in the emulator's "Z:\" drive directory:
    51 "\epoc32\release\wins\udeb\" or "\epoc32\release\winscw\udeb\" or "...\urel\", depending on what platform
    52 and release you are using.
    53 
    54 2. copy "win_drive.ini" configuration file to: "\epoc32\data\"
    55 3. edit this file to set up emulated drive size, location etc. See inside.
    56 
    57 4. Tell the emulator to install "win_drive.fxt" extension to the emulator's drive you are going to use.
    58    to do this edit appropritae "estart.txt" file, which can be, for example, here: \epoc32\release\wins\udeb\z\sys\DATA\estart.txt
    59    If there is no such a file, copy the default one from  "\emulator\wins\estart\estart.txt"
    60 
    61    Example:
    62 
    63     [....]
    64     #X:  1   EFAT32 FAT  0          FS_FORMAT_CORRUPT #<--- previous commented out line
    65     X:   1   EFAT32 FAT  win_drive  FS_FORMAT_CORRUPT #<--- drive "X:" now has "win_drive" primary extension
    66     [....]
    67 
    68 5. run the emulator, its drive "X:" will be redirected to the device you have set up in the "win_drive.ini" file.
    69 
    70 
    71 
    72 Configuration examples:
    73 -----------------------------------
    74 
    75 1. Windows drive F: is a USB cardreader with the SD card you want to use as the emulator's "X:" FAT drive.
    76 Minimal settings in "win_drive.ini" for this case:
    77 
    78 =========================
    79 [Drive_X]
    80 DeviceName=\\.\F:
    81 BytesPerSector=0 ;or just comment it out
    82 MediaSizeInSectors=0 ;or just comment it out
    83 =========================
    84 
    85 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.
    86 Minimal settings in "win_drive.ini" for this case:
    87 
    88 =========================
    89 [Drive_X]
    90 DeviceName=\\.\Z:
    91 MediaSizeInSectors=2097152
    92 =========================
    93 
    94 
    95 3. You want to use 8G file as the emulator's "X:" FAT drive. The file doesn't exist.
    96 
    97 Minimal settings in "win_drive.ini" for this case:
    98 =========================
    99 [Drive_X]
   100 DeviceName=c:\MyDir\MyImageFile8G.img
   101 MediaSizeInSectors=16777216
   102 =========================
   103 
   104 
   105 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.
   106 
   107 Minimal settings in "win_drive.ini" for this case: 
   108 =========================
   109 [Drive_X]
   110 DeviceName=c:\MyDir\MyImageFile.img
   111 MediaSizeInSectors=0 ;or just comment it out
   112 ReadOnly = 1;
   113 =========================
   114 
   115 
   116 Troubleshooting:
   117 -----------------------------------
   118 See "epocwind.out" file if something is going wrong. 
   119 
   120 
   121 
   122 Drawbacks:
   123 -----------------------------------
   124 
   125 - you can't use this extension if the emulator's drive alredy uses primary extension (see estart.txt).
   126 - some dodgy tests can fail, for example, those, that dismount the file system and forget to store and mount all its extensions
   127   include primary.
   128 - Some methods from media driver are not overriden yet and just go directly to the original media driver; it can be confusing.
   129 
   130 
   131 
   132 
   133 
   134 
   135 
   136 
   137 
   138 
   139