Documentation

[ booting | success | sysconsole | graphics ]

Booting RMoX

Depending on how you built RMoX, or downloaded a copy, you should have one (or more) of the following:

• a multiboot image named rmox; or
• a hard-disk image named hdimage.rmox; or
• a user-mode executable named rmox

The multiboot image can be booted on real hardware, through the use of an appropriate bootloader. For our own testing purposes, we boot RMoX off the network, which saves repeated updates to a boot-loader. The following describe various ways of getting RMoX booted.

Booting RMoX in QEMU:

This is probably the easiest way to play around with RMoX. You'll need to have the QEMU emulator installed, along with vgabios and Bochs (the BIOS). On a Debian Linux installation, the following command (as root), will usually do the job:

bash:~/# apt-get install qemu

With the hard-disk image hdimage.rmox to hand, execute the following:

bash:~/$ qemu -boot c -hda /path/to/hdimage.rmox -serial stdio

Booting from the network on real hardware:

If you want to try out RMoX on real hardware without having to install the image, you can boot it off the network. How this is achieved will depend on your particular setup. We typically use Etherboot, in combination with a DHCP or BOOTP server, and TFTP server on the network. However, using a system's native PXE network boot mechanisms should work just as well, provided the approriate server exists.

To use Etherboot, you'll need a suitable image for your particular network hardware. The on-line rom-o-matic can be used to generate this. Once you have the Etherboot binary image, install it into your existing bootloader (GRUB or GRUB 2 recommended, but rom-o-matic will be able to generate a format compatible with most bootloaders). See below for how to put Etherboot into your existing GRUB configuration (booting the Etherboot ROM rather than RMoX).

To actually boot the RMoX image off the network, the rmox file will need to be available over TFTP (or similar). On our development systems that provide the DHCP and TFTP services, this involves having a symbolic link "/tftpboot/rmox", which points at the build-time generated "rmox" file.

Booting locally on real hardware:

If you want to use a bootloader such as GRUB or GRUB 2 on your existing Linux system to boot RMoX, copy the rmox image to somewhere the bootloader can see it (typically "/boot/"), and add an entry along the following lines:

title RMoX
kernel /boot/rmox

Then re-run "grub-install" (or whatever command your system uses to update GRUB). When the system is rebooted, select "RMoX" from the boot menu.

Booting (running) the user-mode version:

If you compiled the user-mode version of RMoX, you can simply run it with:

bash$ ./rmox

When built for user-mode, RMoX enables a driver that uses SDL to put a window on the screen. The terminal in which RMoX is started acts as a log/debug output.

Successful boot

After a successful boot, you will be left at the default virtual terminal, which displays log messages generated by the system. This should look something like the screen on the right (click for a full-size image).

There are six virtual-terminals provided by default. The first displays log messages, and the other five provide system consoles (into which commands can be entered to interact with the system). The function-keys F1 to F6 are used to switch between virtual terminals.

ROM file-system

In a similar manner to the "initrd" (initial ram-disk) used by Linux, the RMoX kernel includes a ROM file-system image. By default this is linked into the resulting bootable image and made available to RMoX. On an embedded platform, this could conceivably be held in a separate ROM.

If loadable module support is enabled (now the default), the ROM disk holds the compiled device-drivers, services and applications for RMoX, e.g.:

rmox# ls -l /rom
dr-xr-xr-x    1        396  bin
dr-xr-xr-x    1         48  drivers
dr-xr-xr-x    1         60  services
-r--r--r--    1      21008  10x20.rff
-r--r--r--    1      13840  6x13.rff
-r--r--r--    1        175  README
-r--r--r--    1      23056  swiss911.rff
-r--r--r--    1        175  system.conf

System console

Once RMoX has booted, press F2 through F6 to switch a virtual terminal running the system console. This should look something like the screenshot shown in the right (exact version numbers will probably differ):

A few useful commands are hard-coded into the shell (e.g. 'mount', 'unmount', 'ls', 'cat', etc.). The rest are supplied as loadable applications on the rom-disk image.

A few of the useful commands are:

Graphics support

For the purposes of experimenting with process-oriented graphical environments, we've put some basic graphics support into RMoX.

Starting the windowing system:

To start the windowing system, run "gfxdpy device" from the console command-line. The particular "device" will probably be one of the following:

Once started, the windowing system launches a default console. Other graphical applications can be started with "spawn program" from here, causing them to be run in parallel with the console (although no keyboard or screen I/O is available to these currently). Graphical applications currently supported (as of 20090412/r4507) are:

to be completed