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
Version 1.1 - Now with added VGA

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 ?

For the really really brave...
  i) Extract the VGA BIOS from the original BIOS
 ii) Make a combined vga bios/etherboot payload
iii) Configure LinuxBIOS
 iv) try it out -- did it work ?

---
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_CURRTICKS -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 !


Even further optional steps - NOT for the faint of heart !

By this point, you should be resonably confidant with building and booting the
EPIA motherboard from LinuxBIOS. But what about the onboard VGA controller ?
Wouldn't it be nice to have that initalised as well ? Well, thanks to a lot of
hard work put in by Sone Takeshi, you can !

Step i) Extract the vgabios from the original BIOS.

        The VGA BIOS code is copyright and cannot be re-distributed, but it
        is supplied with the motherboard within the original BIOS code.
	You do still have the original bios in a chip to boot from don't you ?
        There are serveral possible ways to get a copy of the VGA BIOS,
        perhaps the easiest is to boot into a linux system with the original
        BIOS and as root, perform the following step :-

		dd if=/proc/kcore of=video.bios.bin \
                   bs=1 count=65536 skip=790528

	Another method, would be to use something like the DOS based
        cbrom program to extract the VGA BIOS from a copy of the bios image.
	If you choose to do it this way, you must pad the resulting file to
        64Kbytes in size, otherwise problems may occure later !

Step ii) Make combined payload

	Way back in step 3, we build an etherboot image that would load the
	Linux kernel over the network. For the perpose of this HOWTO, that's
	the payload we're going to use again. If like me, you've experimented
	you probably have you're own favorate payload to play with, feel free
	to substitute that for the via-rhine.ebi file listed.

	First some information on how and why.

		1) The bios chip on the EPIA is 256Kbytes in size.
		2) It lives in the memory at 0xFFFC0000
		3) LinuxBios normally starts looking for it's payload
		   at the start of the flash chip (ie 0xFFFC0000)
		4) By making the video bios exactly 64Kbytes in size,
		   and placing it at the start of the flash image,
                   we move the point where LinuxBIOS should start looking
		   to the nice easy location of 0xFFFD0000.

	Creating the combined payload image is simply a matter of appending
	the real payload image onto the end of the video bios. The following
	two commands assume that the video bios is less than 64Kbytes in size

		$ cp video.bios.bin vga+eb.bin
		$ dd if=via-rhine.ebi of=vga+eb.bin bs=1 seek=65536

Step iii) Configure LinuxBIOS

	Before building the new LinuxBIOS image, we need to alter our
	config file to enable the VGA chipset and tell the system how much
	of the ram to set aside for the framebuffer.

	Modify you payload line to point to the combine image

		payload /home/lb/payload/vga+eb.bin

	Add/Modify the options that tell LinuxBIOS where to find the
	vga bios image and where to start looking for the real payload

		option VGABIOS_START=0xfffc0000
		option ZKERNEL_START=0xfffd0000

	Add the following options to your config file

		option HAVE_FRAMEBUFFER=1
		option SMA_SIZE=8
		option CONFIG_VGABIOS=1
		option CONFIG_REALMODE_IDT=1
		option CONFIG_PCIBIOS=1
		dir src/bioscall

	With the exception of SMA_SIZE, these options enable the code within
	LinuxBIOS to turn on the vga chipset, and call the VGA BIOS just like
	the original BIOS would have.

	The SMA_SIZE option tells LinuxBIOS how many megabytes of memory to
	use for the framebuffer. Valid values here are :-

		0 - Disable Framebuffer
		1 - 1 Mbyte
		2 - 2 Mbytes
		8 - 8 Mbytes


Step iv) Try it out !

	Ok by now, we should have configured and re-build the LinuxBIOS image,
	it's time to burn the image to the bios chip and reset the machine.

	If all goes well, you will see to normal logging coming out of the
	serial port, and (if you have a monitor plugged in) the vga monitor
	switch on and display a cursor (until linux is loaded and prompts
	you for a username that is)


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.