!Help 12.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
SDCreate
========


Introduction
------------

SDCreate is a utility designed to help people with the task of installing RISC OS ROM images onto SD cards, for use with the OMAP3 port of RISC OS. If you attempt to create an SD card manually then there are many places where things can go wrong, either due to user error or operating system quirks. But if you use SDCreate to create the image for you then you can (almost) guarantee that it will boot without any trouble.


Requirements
------------

Images can be created on almost any RISC OS computer with >8MB of spare disc space. You will need at least version 1.28 of the FrontEnd module and version 1.52 of DDEUtils. Up-to-date versions of these modules can be found in the !System archive available for download from the RISC OS Open website:
  http://www.riscosopen.org/content/downloads/boot-zipfiles

If you want to use SDCreate to write the image to an SD card, then you'll need to be using a RISC OS 5 machine with a USB card reader and the USB mass storage drivers (SCSISoftUSB).

Alternatively, you can copy the SD card image to a Windows/Linux/Mac/etc. PC and write the image to an SD card using any number of the free utilities that are available for those platforms (see the 'Utilities for other platforms' section, below)

Before you use SDCreate to create an SD card image, you may need to track down some extra files/software:

* BeagleBoard-xM users will need suitable copies of x-loader and U-Boot. You will find suitable versions on the Linux SD card that came with your board; the 'mlo' file is x-loader, and the 'u-boot/bin' file is u-boot. Alternatively, you can extract them from the demo images available to download from the CircuitCo website:
  http://circuitco.com/support/index.php?title=Circuitco_Support_Wiki

* TouchBook users will need suitable copies of x-loader and U-Boot as well. You can either copy these off of the Linux SD card that came with the machine, or download new versions from the Always Innovating website.

* TouchBook users will also need to install the RISC OS port of mkimage, available from riscos.info:
  http://www.riscos.info/packages/CommandDetails.html#Mkimage


Usage
-----

The SDCreate main window is split into two sections - 'Create image' and 'Write image'. Depending on which options are selected the 'Run' button at the bottom may or may not be greyed out.

******** WARNING *******

The code which writes images to SD cards hasn't received thorough testing, and doesn't ask for confirmation before beginning the write operation. So if you've selected the wrong drive you will lose all your data on that drive, and if you try interacting with the drive while the write is occuring then it will likely result in a corrupt image.

******** WARNING *******


If you want to create an image, and save it as a file:

* Select 'Create image'
* Deselect 'Write image'
* Select the right machine type
* Drag the RISC OS ROM image to the 'ROM image' box
* Drag the x-loader and U-Boot binaries into the x-loader and U-Boot boxes, if necessary
* Drag your desired CMOS file into the 'CMOS file' box, if necessary
* Click 'Run'

If you want to create an image, and write it straight out to a card:

* Select both 'Create image' and 'Write image'
* Select the right machine type
* Drag the RISC OS ROM image to the 'ROM image' box
* Drag the x-loader and U-Boot  binaries into the x-loader and U-Boot boxes, if necessary
* Select the SCSI drive number which your SD card reader has appeared under
* Drag your desired CMOS file into the 'CMOS file' box, if necessary
* Click 'Run'

If you want to write an existing SD image to an SD card:

* Select 'Write image'
* Deselect 'Create image'
* Drag the image file to the 'SD image' box
* Select the SCSI drive number which your SD card reader has appeared under
* Drag your desired CMOS file into the 'CMOS file' box, if necessary
* Click 'Run'


That's it! If it all went well, you should now have a working SD card/image for use with your OMAP3 machine.


CMOS files
----------

Since OMAP3 machines lack any real CMOS RAM, the OMAP3 port of RISC OS uses a file stored on the SD card to emulate CMOS RAM. Therefore when you use SDCreate to install a new ROM image you must be careful not to overwrite the CMOS file, otherwise the settings held in CMOS will be restored to default. The behaviour of SDCreate with regards to CMOS files is as follows:

* When creating an image (i.e. the 'Create image' box is ticked), you can place a copy of a specific CMOS file into the image by entering the filename in the 'CMOS file' box.
* If you don't specify a file, a blank CMOS file will be placed in the image. This file acts as a placeholder to ensure that CMOS settings can be saved back to the card once the SD/MMC driver gains write support.
* If you're writing an existing image to a card (i.e. 'Create image' isn't ticked), then by default the CMOS file held in the image will be used.
* However you can override this behaviour by entering a filename in the 'CMOS file' box. This CMOS file will then be used instead of the one held in the image.

The format of CMOS file used is compatible with that used by the *LoadCMOS/*SaveCMOS commands, or the load/save CMOS option available within Configure. Note that you should obviously only use CMOS files that have been saved by an OMAP3 machine; a file from a RiscPC, Iyonix, etc. isn't guaranteed to work correctly.


Additional usage notes
----------------------

Owners of old BeagleBoards, with version of U-Boot before 2009.01, may find that the 'BeagleBoard' option produces an SD card that won't boot on their machine. This can be solved in one of three ways:

* Edit the !SDCreate.Desc file so that the boot script is named 'RESET/SCR' instead of 'BOOT/SCR'. You need to change the "icn 8 maps_to ..." line (line 31)
* Reflash your NAND with the latest x-loader & U-Boot. See the beagleboard.org website for details.
* Use the BeagleBoard-xM machine type (with either the BeagleBoard or BeagleBoard-xM x-loader & U-Boot; both should be compatible with the non-xM boards).
  * Note however that this may introduce an additional problem, where the machine hangs on boot, due to an old, incompatible version of x-loader in NAND being used with the new version of U-Boot on the SD card. The only way to avoid this is to find an older version of U-Boot that works, or reflash your board, or always boot while holding down the User button.


Utilities for other platforms
-----------------------------

If you don't own a working RISC OS machine and therefore can't use SDCreate to create an SD card image, then 'The techie bit' section below has information as to what files SDCreate places into the images. This should allow you to create a working card manually.

If you've created an image file using SDCreate, but can't use SDCreate itself to write the image to a card, then you can use one of the following Windows/Linux/Mac utilities to write the image for you:

* Windows - Win32DiskImager - https://wiki.ubuntu.com/Win32DiskImager
  - Just make sure the file has a .img extension for Win32DiskImager to find it
* Linux - UNetbootin - http://unetbootin.sourceforge.net/
  - Or if you're feeling adventurous, just use 'dd'
* Mac - http://meego.com/devices/netbook/installing-meego-your-netbook
  - I'm not aware of any user-friendly utilities to do this on a Mac OS X machine, but the above instructions for writing a MeeGo Linux disc image onto a USB drive can easily be adapted for writing the SD card images created by SDCreate.


The techie bit
--------------

SDCreate creates SD card images in the following manner:

* The file !SDCreate.blank is a blank, 8MB FAT12 disc image created under Linux using the following script:

  #!/bin/bash
  dd if=/dev/zero of=BlankImg bs=8225280 count=1
  sfdisk -C 1 -H 255 -S 63 -D BlankImg <<EOF
  ,,0x01,*
  EOF
  sudo losetup -v -o 32256 /dev/loop0 BlankImg
  sudo mkfs.vfat /dev/loop0 -n "RISC OS" -F 12
  sudo losetup -d /dev/loop0

* This file was then squashed using !Squash to cut down the size of the program.
* So one of the first things SDCreate does is to unsquash the image. If the image is being written straight out to the SD card then it will be unsquashed directly to the card using the SCSIFS_DiscOp SWIs. Otherwise, it will be unsquashed to a file. This file will then have its filetype set to 'DOSDisc', allowing the FAT image to be used as an image file with DOSFS.
* SDCreate then copies a series of files into the image. The exact files copied will depend upon which machine type you are using:

  BeagleBoard (non-xM):
    BOOT/SCR         <- The BeagleBoard boot script from !SDCreate.scripts
    UENV/TXT         <- U-Boot environment file from !SDCreate.scripts
    RISCOS           <- Your RISC OS ROM image
    CMOS             <- Your CMOS settings

  BeagleBoard-xM:
    MLO              <- The x-loader binary
    U-BOOT/BIN       <- The U-Boot binary
    BOOT/SCR         <- The BeagleBoard boot script from !SDCreate.scripts
    UENV/TXT         <- U-Boot environment file from !SDCreate.scripts
    RISCOS           <- Your RISC OS ROM image
    CMOS             <- Your CMOS settings

  DevKit8000:
    BOOT/SCR         <- The DevKit8000 boot script from !SDCreate.scripts
    RISCOS           <- Your RISC OS ROM image
    CMOS             <- Your CMOS settings

  IGEPv2:
    BOOT/INI         <- The IGEPv2 boot script from !SDCreate.scripts
    RISCOS           <- Your RISC OS ROM image
    CMOS             <- Your CMOS settings

  Touch Book:
    MLO              <- The x-loader binary
    U-BOOT/BIN       <- The U-Boot binary
    UIMAGE           <- Your RISC OS ROM image, packaged as a U-Boot uImage
    CMOS             <- Your CMOS settings

  Pandora:
    BOOT/SCR         <- The Pandora boot script from !SDCreate.scripts
    RISCOS           <- Your RISC OS ROM image
    CMOS             <- Your CMOS settings

* The rules for which files get used on which machine type are in the FrontEnd description file (!SDCreate.Desc). I wouldn't advise trying to decipher it, though!
* If you want to examine the contents of an image file, just set its filetype to 'DOSDisc' and double-click. (The files get typed to Data since the FrontEnd module doesn't consider image files to be valid tool output!)
* The Touch Book uImage file is created using the following command:

  mkimage -A arm -O linux -T kernel -C none -a 0x81000000 -e 0x81000064 -n "RISC OS" -d <infile> <outfile>


The even more techie bit
------------------------

The human-readable source to the boot scripts is available in !SDCreate.scripts.source. You will also find there the 'convert' script script, which uses mkimage to convert the scripts to the binary format used by U-Boot.

Each boot script will enter the ROM image at a different address; this is how RISC OS works out what machine type it's running on. The full list of (current) ROM image entry points is given below:

BeagleBoard		ROM start + &00000000
DevKit8000		ROM start + &00000004
IGEPv2			ROM start + &00000008
Pandora			ROM start + &0000000C
Touch Book		ROM start + &00000010

There is also an extra entry point at offset &00000064, which should be used when the ROM image is packed as a uImage. This entry point allows RISC OS to detect the machine type automatically, via the machine ID number that is passed to it by U-Boot. The uImage format also has a few other advantages (checksums, argument strings), so in the future it may be adopted for all machine types instead of just the Touch Book (and the only reason it's used on the Touch Book is because the default Touch Book version of U-Boot doesn't seem to look for boot scripts).

The U-Boot environment file (uenv.txt) is a file that new versions of U-Boot use to get their environment variables. Although it's supposedly an optional thing, the BeagleBoard-xM demo images have had their default environments changed such that the regular boot.scr is no longer used, and uenv.txt is the only (easy) method to boot RISC OS.


History
-------

V1.15 - 2011/5/25
 * Added a uenv.txt file to provide compatability with the latest BeagleBoard/BeagleBoard-xM versions of U-Boot
V1.10 - 2011/1/22
 * Added support for adding CMOS files to images
V1.02b - 2010/11/14
 * Changed !Run file to RMEnsure FrontEnd 1.28 after receiving reports of 1.16 not working
V1.02 - 2010/10/17
 * Fixed a bug with the step that checks for successful uImage creation
 * Corrected all filenames to be in caps, so TouchBook/xM cards actually boot!
V1.01 - 2010/10/12
 * Tweaked a couple of bits and added Chris Wraight's icon
V1.00 - 2010/10/7
 * First release of the GUI version

Other
-----

SDCreate is public domain.

SDCreate was written by Jeffrey Lee, me@phlamethrower.co.uk. SDCreate icon created by Chris Wraight.

http://www.phlamethrower.co.uk/riscos/sdcreate.php