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 ) 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.