switch-coreboot/HOWTO/EPIA

Based on the K7SEM HOWTO by Brenden Bixler,
which is based on the Sis 630 HOWTO by Ron Minnich.
HOWTO written by Mark Wilkinson

This file contains instructions for the VIA Epia mini-ITX based mainboards.

Unfortunately, there is a step in this HOWTO that could be hazardous. The 
hazards include (but are not limited to)
	1) destroying your motherboard
	2) hurting yourself
	3) killing yourself

Because of these hazards, you must take full responsibility if you
decide to install LinuxBIOS following these procedures. Neither Los
Alamos National Labs or any lab personnel can be held responsible for
any adverse consequences of your attempt to follow these procedures.

WARNING: We assume you've built kernels, know how to open up your PC,
and how to yank the flash part out while power is on and put in a
different part. There is NO WARRANTY, express or implied, with this
software. In fact, if you don't know what you're doing, and you get
careless, you're going to end up with a nice paperweight instead of a
motherboard, an emergency room bill, or a funeral service.

			YOU HAVE BEEN WARNED.

Additional information available at: http://www.linuxbios.org/

Linux distribution: Most modern distributions are supported. 
                    This HOWTO tested using RedHat 8.0

Other software notes: You MUST have 'as' version 2.9.5 or later.
                      You MUST have 'gcc' version other than 2.96.
                      A working network and dhcp/tftp servers.

NOTE: At present, the epia can be booted with a serial console. Power
      management to turn off the power is not available, neither is the
      video bios. Memeory is currenly hard coded to report 64M - you must
      have at least this much memory.

Recommended: you might want to get a Bios Saviour (RD1-PL) - this is
a handy little piggy-back flash chip that saves you destroying the original
flash image.

You need to have a LinuxBIOS machine (the machine that runs LinuxBIOS)
and a build machine (which will let you build LinuxBIOS and runs the
dhcp/tftp servers).

Also, freebios and LinuxBIOS still share the same source tree. We use the 
name 'LinuxBIOS' where it makes sense, and 'freebios' otherwise. But they 
are the same source base. 

----
The steps for loading LinuxBIOS are simple:
1) Get Linux installed on your LinuxBIOS machine.
2) Get Etherboot source from Sourceforge.
3) Configure and build the Etherboot elf image.
4) Get LinuxBIOS source from Sourceforge.
5) Configure and build LinuxBIOS.
6) Burn the LinuxBIOS image to the flash.
7) Reset the machine -- did it work?

Option after it worked...
a) Get a 2.4.x kernel, patch it, then compile.
b) Setup the dhcp/tftp servers.
c) Make an elf image of the kernel
d) Reset the machine -- did it boot linux ?

---
Note: This HOWTO assumes that the LinuxBIOS and etherboot work will be done
in a user account. Root access will be needed for setting up the dhcp and
tftp servers.

Step 1) 
	Get Linux installed on your LinuxBIOS machine. Tested on RedHat 8.0
        Note: It may be better to use ext2 partitions rather than ext3.
              Don't forget to note which partition is / (/dev/hda3 etc.)

Step 2)
	Download the Etherboot source from http://www.etherboot.org
	cd to the directory you want the source tree to be,
	and untar the source archive.
	
Step 3)
	Configure and build the etherboot elf image
	cd into the etherboot source tree and into the src subdirectory.
	i.e. cd ~/etherboot-5.0.8/src (assuming version 5.0.8 of etherboot
             and it was untarred in the home directory)

	Using which every text editor you like, edit the Config file

	Comment out the following line(s) :-
	CFLAGS32+= -DPCIBIOS
	Uncomment the following line(s) :-
	#CFLAGS32+= -DLINUXBIOS -DCONFIG_TSC_CURTICKS -DCONSOLE_SERIAL \
                    -DCOMCONSOLE=0x3f8 -DCOMPRESERVE -DCONFIG_PCI_DIRECT \
                    -DELF_IMAGE

	Note: Line split to aid readability.

	make bin32/via-rhine.ebi

	Note: You can just use make bin32/via-rhine.elf, but the ebi version
	is stripped of extra comments and thus slightly smaller (by about 5k
	in my case).

	This will be the payload file for LinuxBIOS.

	
Step 4)
	Grab the LinuxBIOS source.
	cd to the directory you want the source tree to be.
	Note: this will create a sub directory called freebios which contains
              the LinuxBIOS source code

	export CVS_ROOT=:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios
	cvs login 
	(at the password prompt, just hit <return>)
	cvs -z3 co freebios
	cvs logout

Step 5)
	You now need to figure out where you want to put your build images.
        We used /usr/src/build a directory we created.
 
	DO NOT PUT THESE IN THE LinuxBIOS SOURCE TREE. 
	
	You want to put them OUTSIDE THE TREE, so you can always 'cvs update'
        and not lose any of your build directory. LinuxBIOS does all the
        builds in a single directory. 
	
	To build LinuxBIOS requires a Makefile, a crt0.S file, and a ld script
	file. These are generated by a config tool located in 
	freebios/utils/config. 	The config tool is a Python program originally
        written by Dean Risinger of the ACL. 	

	To build the initial Makefile, assembly stub, and ld script, 
	you need to build a config file, run the config tool,
	cd to the build directory, and type 'make'.

	That said, first create your config file using
	the text editor of your choice. This file can be located anywhere...
	I used ~/epia/epia.config. It is generally a good idea to take a 
	copy of the example config from the mainboard directory as a starting
	point. These are usually the most upto date, and will contain new
	options as the developers add them. My example below is a copy of the 
	freebios/src/mainboard/via/epia/example.config file.

	Here is the config file for the EPIA:

	#
	# LinuxBIOS config file for: VIA epia mini-itx
	#

	target /home/lb/epia

	# via epia
	mainboard via/epia

	# Enable Serial Console for debugging
	option SERIAL_CONSOLE=1
	option TTYS0_BAUD=115200
	option DEFAULT_CONSOLE_LOGLEVEL=9
	option DEBUG=1

	# Use 256KB Standard Flash as Normal BIOS 
	option RAMTEST=1
	option USE_GENERIC_ROM=1
	option STD_FLASH=1
	#option ZKERNEL_START=0xfffc0000
	option ROM_SIZE=262144

	# payload size = 192KB
	option PAYLOAD_SIZE=196608

	# use ELF Loader to load Etherboot
	option USE_ELF_BOOT=1

	# Use Etherboot as our payload 
	payload /home/lb/etherboot-5.0.8/src/bin32/via-rhine.ebi

	
	The target command names the build directory. The mainboard command
	names the mainboard. We have set options for a serial console which
	will get you LinuxBIOS debug output via the serial port. You have to
	tell it where to find the etherboot image you built (the 'payload'
	command).

	To run the config tool, you need two arguments: the first is the
	name of a config file, and the second is the (absolute) pathname
	of the freebios source tree. The config tool is NLBConfig.py.

	Make sure you use that and not LBConfig.py, the older version. 

	Now, just run the configuration tool to generate the Makefile. 

 	python /home/lb/freebios/util/config/NLBConfig.py epia.config \
               /home/lb/freebios

	Assuming no errors, cd into /home/lb/epia and type make.
	If you receive an error message then verify your configuration file
	is correct and/or consult the LinuxBios website.

Step 6)
	NOTE: BE ADVISED THAT THIS STEP CAN KILL YOUR MOTHERBOARD !
	IF YOU DO NOT HAVE A MEANS OF RECOVERING FROM FLASHING YOU BIOS,
	YOU MAY/WILL BE LEFT WITH A DEAD MACHINE.

	After running make, we now have a LinuxBIOS rom image to be loaded
	into the Bios Flash chip. This image (in the file romimage) needs to
	be burnt onto the flash using the flash_rom utility in the
	freebios/util/flash_and_burn directory.

	This utility accepts one parameter (the rom image) but for the paranoid
	can be run without, to identify the type of flash chip.

Step 7) 
	Power cycle the machine. LinuxBIOS should come up in a few seconds.

	With a connection to the serial port, you should see the LinuxBIOS
	start to come up, then etherboot configuring the network interface
	and start to look for an IP address from a dhcp server.

	If you do, CONGRATULATIONS ! It WORKED ! Pat yourself on the back,
	why not try the optional steps now ?

	If you don't, time to start capturing the output of the serial port
	and talking to the linuxbios mailing list.

Optional steps - for use only if step 7 was successfull.

Ok, so now we have a EPIA motherboard that's looking for a dhcp server to
provide it with an ip address, and a clue as to which file to load next.

The following steps can be used as an example for netbooting the motherboard
and getting the linux system up and running. 

Step a)
	Grab the source for your favorate version of the linux kernel
	Configure as required
	make dep bzImage

	Note: at present, the epia has no support for the video bios
	so don't forget to allow for serial console !

Step b)
	Install your favorate dhcp server and tftp server.

	You will need to configure the dhcp server so that the MAC address
	of the epia motherboard is given an ip address, and told that the
	file to load is 'vmlinuz.epia'

	The file will be loaded from the tftp server, usually from the
	/tftpboot directory. The next step will create the kernel image for
	booting.

Step c)
	Compile and install the mkelfImage utility from LinuxBIOS

	Build a network elf image using the following command

	# mkelfImage --kernel=/usr/src/linux-2.4/arch/i386/boot/bzImage \
	             --output=/tftpboot/vmlinuz.epia \
	             --command-line="console=ttyS0,115200n8 root=/dev/hda3"

	This will generate the file that etherboot will load from the tftp
	server.

Step d)
	Power cycle to epia once more, this time with the network connected,
	and the dhcp & tftp servers running, you should see the kernel image
	being loaded, then starting to run !

DEBUGGING
___________

   If you can, hook up a serial line to your LinuxBIOS machine, 
   settings 115200,8n1 and see what messages come out. If you can
   capture them, send them to linuxbios mailing list with a description
   of your problem.