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, OMAP4, and iMx6 ports
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 >32MB of spare disc
space. You will need at least version 1.28 of the FrontEnd module and version
1.52 of DDEUtils. RISC OS 5 users can find up-to-date versions of these modules
in the HardDisc4 image available in the downloads section of the RISC OS Open
website. Users of 26bit machines can find the modules in the "System resources"
download.
  http://www.riscosopen.org/content/downloads/common

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. In
particular, 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 chosen machine.


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

RISC OS stores a number of non volatile settings in what is often referred to
as CMOS memory. Most notably, these are all the configuration settings such as
the keyboard repeat rate and the drive to boot from.

From RISC OS 5.18 onwards the OMAP3 and OMAP4 HALs will try to find CMOS
memory mounted on a carrier board plugged into the otherwise unused 14 pin
JTAG connector.
If that is not found to be present then an attempt will be made to find a valid
CMOS image loaded into volatile memory by the boot process, though any settings
will be forgotten when powered down - it is recommended to obtain a CMOS
carrier board from your supplier for full read/write capability.
If that is also not found to be present (or is corrupt) the defaults in the
kernel will be used instead, so the machine will still boot whether the
hardware is present or not and whether a CMOS file is present or not.

The default filename is simply 'cmos' but can be changed to anything you desire
as long as the corresponding boot script is ammended (see 'The Techie Bit'
later).

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, or by dragging the file into the box.
* If you don't specify a file, a blank CMOS file will be placed in the image.
* 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 the corresponding machine; a file from a RiscPC, Iyonix, etc. isn't
likely 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. To fix this
    you can 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, 32MB FAT16 disc image created under
  Windows and then copied off of the SD card using 'dd' under Linux.
  For the Wandboard !SDCreate.blankwand is used instead, because the on-chip
  bootloader looks at a specific sector offset on the SD card rather than
  searching the root directory. This means the blank 32MB FAT16 disc image
  needs those sectors reserving, leaving around 24MB of empty space.
* 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

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

  Wandboard
    README/TXT       <- An introductory welcome note
    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

PandaBoard              ROM start + &00000000

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.26 - 2018/2/1
 * Added Wandboard (iMx6) support 
V1.25 - 2012/5/21
 * Fixed bug that prevented the SCSI drive number from being saved properly by
   the "Save options" iconbar option
 * Added confirmation popup before writing an image to a card, and an extra
   popup if the destination card/drive looks like the boot drive
 * Reformatted this help file so it displays properly when viewed via the "Help"
   iconbar option
 * Added scrollbars to main window to allow SDCreate to be used on low-res
   screens
 * If Fat32Fs is loaded, SDCreate now makes sure Fat32Fs dismounts the drive
   before writing the image
V1.23 - 2012/2/22
 * Relicenced as BSD and imported into RISC OS Open's CVS server
 * ROOL CVS is now the main source repository for SDCreate
 * No functional changes
V1.21 - 2012/2/22
 * Fixed "No such function/procedure" error when attempting to write
   pre-prepared images to a card
V1.20 - 2012/2/12
 * Added PandaBoard support [Willi Theiss]
 * Fix interactive help text
 * Relaxed ROM size constraints and changed to using a 32MB FAT16 partition, to
   allow for both bigger ROMs and compressed ROMs
 * Change 'x-loader' to 'x-loader/MLO' in the templates file to help make it
   clear what's required
V1.16 - 2012/1/7
 * Scripts adjusted to load the CMOS file with 'fatload' [Rob Sprowson]
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
-----

Copyright(c)2012, RISC OS Open Ltd
Allrightsreserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met: 
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of RISC OS Open Ltd nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

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

