######################
 Cobalt ROM Utilities
######################

flashtool            : for reading and writing rom images to flash
imagetool            : for extracting and creating rom images
rom_kernel.config    : sample kernel config for a ROM kernel
spec/                : various rom image layouts
co_romfs/            : new (ROM 2.9.x) tools for cobalt romfs
co_romfs.old/        : old (ROM 2.3.x) tools for cobalt romfs


#########
 WARNING 
#########

The use of these tools is completely _unsupported_ by Sun Cobalt.
You have been warned.  If you happen to fry your ROM contact
Gerald Waugh <gwaugh@frontstreetnetworks.com> or see his website
at http://store.raqware.com and he may be able to replace it at
a reasonable price.  Many thanks to Gerald for providing this
invaluable service!


#######
 USAGE
#######

usage: ./flashtool [options] <mode>
options:
  -h                 : get this help
  -v                 : enable verbose output
  -V                 : print version info
modes:
  -r                 : read the rom (to stdout)
  -w <rom image>     : write the rom


usage: ./imagetool [options] <mode>
options:
  -h                 : get this help
  -o                 : use older (2.3.x) romfs tools
  -s <spec>          : rom layout spec file
  -i <image>         : rom image to extract/create
  -d <dir>           : work directory
modes:
  -c                 : create filesystem and create image
  -e                 : extract image bootsector and filesystem


#######
 ABOUT
#######

These tools enable you to alter the contents of the Cobalt ROM image
and filesystem, for example to change the ROM kernel.  To understand
how these tools work it helps to have an understanding of the layout
of a Cobalt ROM image.

There are two types of rom images: paged and flat.  The difference
between these two layouts is the "paged" format is for hardware that
includes a paging register and can only access 64K at a time.  The
"flat" format is for hardware without a paging register that can
access the full address space.  (in this case up to 4MB)

The paged layout is used by the RaQ 3, RaQ 4, Qube 3, and RaQ XTR.
The flat layout is only used by the RaQ 550.

Here is the layout of a 1024K paged image.  The bootsector is in the
first 64K page, and the filesystem in the remaining 15 pages or 960K.
Unused bytes at the end of each section are padded with 0xff.

    +------------------+ 0x00000
    |    BOOTSECTOR    |
    +------------------+ 0x10000
    |                  |
    |   COBALT ROMFS   |
    |    FILESYSTEM    |
    |                  |
    |   [monitor.bz2]  |
    |   [vmlinux.bz2]  |
    |                  |
    +------------------+ 0xfffff

The layout for a 1024K flat image is reversed:

    +------------------+ 0x00000 
    |    FILESYSTEM    |
    +------------------+ 0xf0000
    |    BOOTSECTOR    |
    +------------------+ 0xfffff

Once these two sections are extracted from the rom image you can begin
to work with the filesystem.  This is accomplished with the "co_romfs"
tools that are available.  There are currently two different sets of
romfs utilities, which one you use depends on the image version:

For 2.9.x and 2.10.x ROM versions:

  co_romfs/
  |-- co_cat     : copy a romfs file to stdout
  |-- co_cpfrom  : copy a romfs file to unix file
  |-- co_cpto    : copy a unix file to romfs
  |-- co_ls      : list a romfs directory
  |-- co_mkdir   : make a romfs directory
  |-- co_mkfs    : make a rom filesystem of specified size
  |-- co_rm      : remove a romfs file
  |-- co_rmdir   : remove a romfs directory
  `-- co_touch   : create an empty romfs file

For 2.3.x ROM versions:

  co_romfs.old/
  |-- co_cat     : copy a romfs file to stdout
  |-- co_cpfrom  : copy a romfs file to unix file
  |-- co_cpto    : copy a unix file to romfs
  |-- co_ls      : list a romfs directory
  |-- co_mkfs    : make a rom filesystem of specified size
  `-- co_touch   : create an empty romfs file

Most of these utilities are self-explanatory and they all give basic
usage instructions when run without arguments.  The common romfs tools
(that imagetool uses) are co_mkfs, co_ls, co_cpfrom, and co_cpto.


########
 KERNEL
########

The in-ROM kernel is a modified version of the linux kernel that has
boot-time hooks to load a kernel from the filesystem into a specified
RAM address then jump back to ROM.

The specific kernel patch that does this is available from:

    http://cobalt.iceblink.org/rom/linux-cobalt-boot.patch

And the larger patch that includes this as well as the rest of the
Cobalt hardware support is available from:

    http://cobalt.iceblink.org/kernel/linux-2.4.20-cobalt.patch

A sample kernel config for a ROM kernel is included in this archive as
rom_kernel.config.  This is a monolithic kernel config (module support
is disabled) and only the necessary config options enabled.  There are
a few important config options to watch out for:

CONFIG_M586              : so the kernel works on all hardware
CONFIG_COBALT            : for generic cobalt support
CONFIG_COBALT_BOOTLOADER : enables the cobalt bootloader code
CONFIG_SERIAL_CONSOLE    : serial console support
CONFIG_IP_PNP_*          : netboot support
CONFIG_ROOT_NFS          : root device over NFS
CONFIG_EEPRO100          : Intel NIC support
CONFIG_NATSEMI           : NatSemi NIC support
CONFIG_BLK_DEV_ALI15X3   : ALI IDE support (RaQ 3, RaQ 4, Qube 3)
CONFIG_BLK_DEV_SVWKS     : ServerWorks IDE support (RaQ 550)
CONFIG_BLK_DEV_HPT366    : HighPoint IDE support (RaQ XTR)

As well as support for RAID and the filesystems you desire.  The sample
config is a good basic kernel that will work on all Cobalt hardware.
Size is very important here, so don't enable what you don't need.

The kernel image must be compressed ELF format.  Newer ROMs understand
bzip while older ROMs must use gzip.


#########
 CAVEATS
#########

- the romfs contents differ between 2.3.x and 2.9.x versions.
- never try to create an image with mismatched romfs/bootsector
versions.  it will _not_ work.
- space is a premium, even with a 1M flash.  much of this space
is taken up by the rom kernel.
- the sample rom_kernel.config does not include support for XFS,
this means it will not be able to boot the RaQ 550 OS.


#########
 EXAMPLE
#########

raq:~/romutils# ./flashtool -r > flash.rom

raq:~/romutils# ls -l flash.rom
-rw-r--r--    1 root     root      2097152 Mar 12 13:32 flash.rom

raq:~/romutils# ./imagetool -i flash.rom -d flash.dir -e
4e4c5754345b55030e9ea4e8f471f98e  flash.rom
reading spec/cobalt-2M-flat.spec
extracting ROM flash.rom (2097152 bytes)...
bootsector saved in flash.dir/rom.bs (65536 bytes)
filesystem saved in flash.dir/rom.fs (2031616 bytes)
extracting filesystem flash.dir/rom.fs...
 flash.dir/monitor.bz2 (72952 bytes)
 flash.dir/vmlinux.bz2 (834890 bytes)

raq:~/romutils# ls -l flash.dir/
total 2952
-rwx------    1 root     root        72952 Mar 12 13:33 monitor.bz2
-rw-r--r--    1 root     root        65536 Mar 12 13:33 rom.bs
-rw-r--r--    1 root     root      2031616 Mar 12 13:33 rom.fs
-rwx------    1 root     root       834890 Mar 12 13:33 vmlinux.bz2

raq:~/romutils# ./imagetool -i flash.rom.2 -d flash.dir -s spec/cobalt-2M-flat.spec -c
creating filesystem flash.dir/rom.fs (2031616 bytes)...
 flash.dir/monitor.bz2 (72952 bytes, 1958664 free)
 flash.dir/vmlinux.bz2 (834890 bytes, 1123774 free)
creating ROM flash.rom.2 (2097152 bytes)...
bootsector flash.dir/rom.bs added to flash.rom.2 (65536 bytes)
filesystem flash.dir/rom.fs added to flash.rom.2 (937984 bytes)
4e4c5754345b55030e9ea4e8f471f98e  flash.rom.2

raq:~/romutils# ls -l flash.rom*
-rw-r--r--    1 root     root      2097152 Mar 12 13:32 flash.rom
-rw-r--r--    1 root     root      2097152 Mar 12 13:35 flash.rom.2

raq:~/romutils# md5sum flash.rom*
4e4c5754345b55030e9ea4e8f471f98e  flash.rom
4e4c5754345b55030e9ea4e8f471f98e  flash.rom.2


