View source for OFW on the Via Demo Board

This page tells how to run Open Firmware on the Via 8562 demo board.  The demo board is a testbed for the chips that are used in the OLPC XO 1.5 system.

On that board, you can run Open Firmware either directly from FLASH ROM, replacing the Phoenix BIOS that comes with the board, or you can load Open Firmware from a USB stick, leaving the Phoenix BIOS installed in the FLASH ROM.  The latter "BIOS-loaded" approach is more likely to work on a random system, since the direct-from-FLASH approach requires a specific kind of RAM DIMM.

== Booting OFW from BIOS via a USB Drive ==

You need a USB drive (hard disk, FLASH stick, pendrive) that is formatted with a FAT filesystem
(they come that way from the factory).  The USB drive needs about a megabyte of free space.

These instructions assume that you know the basics of mounting USB drives and copying files to and from them.

=== Get the OFW Image ===

There is a prebuilt OFW image for the Via demo board at ...

Copy that file onto the USB drive, in the top-level (root) folder.

Also create a file there named "syslinux.cfg", containing only the following line:

  default ofwvia.c32

=== Make the USB Key Bootable ... ===

==== ... On Linux ====

* Install the "syslinux" package (e.g. "apt-get install syslinux" or "yum install syslinux" or get the whole distribution from http://www.kernel.org/pub/linux/utils/boot/syslinux/ and use linux/syslinux therein).

* Unmount any filesystems that are currently mounted on the USB drive

* Find the USB drive's device name.  It will probably be something like /dev/sda .  You want the name of the whole drive (just sda), NOT a subordinate partition (NOT sda1).

* Run this command, replacing "/dev/sda" with the appropriate device name for your USB drive:

   $ syslinux /dev/sda


==== ... On Windows ====

* Download and extract the following onto your host machine: http://www.kernel.org/pub/linux/utils/boot/syslinux/syslinux-3.72.zip

* Open My Computer and find the drive corresponding to the USB key.  The following instructions assume that it is "F".

* Open a cmd window

* cd to the directory where you unzipped the syslinux files

* cd to the win32 subdirectory

* Run this command line, replacing "f" with the drive letter for your USB key:

      syslinux -m -a f:

* Use the "Safely Remove Hardware" icon in the system tray to stop the USB key device, then remove that device

=== Setup Your BIOS to Boot From USB ===

For the Phoenix BIOS that comes with the Via demo board, the procedure for enabling USB boot is:

* Type the F2 key during the BIOS startup screen to enter the Phoenix Setup Utility
* Use the right arrow key to select the Boot screen
* Use the down arrow key to select the "USB KEY:" choice
* Use the + key, if necessary, to move the "USB KEY:" choice upwards to a position in the "Boot priority order" section that is above any other boot devices that you have installed.
* Type the F10 key to save your settings.
* Answer Yes at the confirmation screen

=== Running Open Firmware ===

Insert the USB drive into one of the USB ports on the demo board and reset the board.  After a few seconds, Open Firmware should start, showing you a white screen with black letters, and an "ok" prompt.

To learn how to use Forth, the simple-but-powerful programming language that is the core of Open Firmware, see http://wiki.laptop.org/go/Forth_Lessons

=== Building OFW from Source ===

On a Linux system with gcc and Subversion installed:

  $ svn co svn://openbios.org/openfirmware
  $ cd openfirmware/cpu/x86/pc/biosload
  $ cp config-via.fth config.fth
  $ cd build
  $ make

The output file is ofw.c32 .  Copy it to the USB drive, renaming it to "OFWVIA.C32".

== Running OFW from FLASH ROM on the Via Demo Board ==

This technique is not recommended unless you know what you are doing, because the current "direct from ROM" build for the Via board depends on a specific DIMM configuration.  If your DIMM is different, it probably won't work.  At some point I might make the build more generic, or I might not.  This version is intended for my development use, and will soon become obsolete when we switch over to the real XO 1.5 prototypes.

If someone has given you a FLASH image file containing OFW for the Via demo board, program it into an LPC FLASH ROM, insert the ROM into the socket on the board, and power it on.  You should seen an ok prompt on the screen in a few seconds.

You can build an image file from scratch as follows:

On a Linux system with gcc and Subversion installed:

  $ svn co svn://openbios.org/openfirmware
  $ cd openfirmware/cpu/x86/pc/olpc/via/build
  $ make

The last line of the output will tell you then name of the file; it should be something like:

  --- Saving as q3a00.rom

Program that .rom file into an LPC FLASH ROM and insert it into the Via demo board.

=== Understanding the Memory Controller Init Code ===

You might be tempted to think "I can't understand the Open Firmware memory init code because it is written in Forth".  But, actually, it is really just a bunch of register accesses written with assembler macros, so if you understand how the chip works and can read a sequence of numbers, you can understand the code.  To make it work with different chips, you just change the numbers.

The memory setup code is in the file "cpu/x86/pc/olpc/via/demodram.fth" in the openfirmware tree (see the preceding section for how to check out the tree).  Here is all you need to know to understand it:

* Anything after "\ " is a comment
* "0 3 devfunc" means that the next bunch of register accesses, up to the next "end-table", go to PCI configuration registers in device 0, function 3.
* "96 f0 a0 mreg" means read configuration register 0x96 (byte), clear bits 0xf0 (NOT then AND), set bits 0xa0 (OR), and write the result back to the same register.
* "DDRinit #) call" calls a subroutine that performs the SDRAM chip setup sequence (NOP, Precharge All, MRS Enable, etc).
* "d# 20 wait-us" waits for (decimal) 20 microseconds
* "h# 14 port80" puts 0x14 on port 80, for debugging