LinuxBIOS FAQ  Ver 0.0.2
Richard A. Smith 
<rsmith@bitworks.com>

Credits. 

	Various portions of this document were derived from posts on the linuxBIOS 
	mailing list.  I neglected to keep who said what in a lot of cases.
	My apologies to those people.  Let me know if you want credit for 
	what you wrote and I'll add it in.

Where is the linuxBIOS webpage?
	
	http://www.linuxbios.org
	
What kind of coding skills are necessary to work with LinuxBIOS?
	
	You better be comfortable with assembly language as LinuxBIOS has a lot of 
	it. LinuxBIOS switches to protected mode and a C enviroment as soon as it can 
	but there is a lot of hardware init that has to happen first.  Most of this 
	happens in assembly _WITHOUT_ a stack!  Very tedious to debug.
	
	Grokking the SDRAM init process is a  very humbleing experience.  DDR is said 
	to be worse.  
	
	Strong C skills are also a plus as most of LinuxBIOS and friends is/are 
	written in C.
	
	You should also not be afraid of digging hip deep in chipset datasheets and 
	attempting to mind read what the chipset designers were really trying to say 
	when they wrote the documentation.  Sometimes its less than clear.
	
	LinuxBIOS is a _very_ hands-on-study-the-code type project.  

What kind of hardware do I need?
	
	A motherboard (or mainboard as LinuxBIOS calls it) that has a supported 
	chipset on it.  Ok.. Well not exactly.  As long as you have the documentation 
	for the chipset/mainboard and its free of any NDA issues you can use an 
	unsupported chipset/Mainboard but you have a _long_ twisty road ahead of you.
	
	And of course you need a Linux developemnet machine.  The LinuxBIOS build 
	enviroment is not supported on windows.  
	
	Here's a list of the currently supported chipsets/Mainboards
	
	http://www.linuxbios.org/status/index.html
	
	It's also handy to have one/some/all of the following:
	
	- EPROM/Flash programmer that can program the flash on your motherboard.
	- ROM emulator
	- Bios Savior 
		http://www.ioss.com.tw/web/English/RD1BIOSSavior.html
	- Compact Flash IDE 
		adaptor <Need some links to CF adapters>
	- Oscilliscope
	- In Circuit Emulator hardware debugger
	
How can I tell if my motherboard/chipset is supported by LinuxBIOS?
	
	Check:
	
	http://www.linuxbios.org/status/index.html
	
	If you don't see your chipset/Mainboard listed there then boot linux on your 
	target and send the output of 'lspci -vvv' to the linuxBIOS list asking if 
	this chipset might be supported.
	
What documentation do I need?

	As much as you can possibly get a hold of.  Minimum you need the docs for 
	your chipset.  Without chipset docs you are basically lost.  
	
	There have been some reports of people making things work by popping in the 
	BIOS that comes with the board.  Dumping the PCI config registers and then 
	making LinuxBIOS match those registers.  But since sometimes you have to set 
	different bits in a given register at different times it can be a vere long 
	and involved process.
	
What documentation for linuxBIOS exists?

	You got the source. What more do you need?  *grin*
	
	Unfortunaly there is very little documentation for linuxBIOS right now and 
	what docs there are tend to be stale.  Use the source Luke.
	
	One thing to note is that LinuxBIOS has reached a stage where a good bit of 
	newer users are coming on-line and thus the signal-to-noise level of the 
	mailing list is beginning to decrease.  The mailing list archives have *TONS* 
	of good information in them I would say its required reading.  Start at the 
	beginning of the year or at least 3 to 4 months ago and read the various 
	questions/responses.  Chances are you will find serveral references to a 
	setup similar to yours.
	
	Once you have gone through the mailing list navigating the LinuxBIOS code and 
	dealing with the many config options will be much eaiser.
	
I don't have an EPROM/FLASH programmer.  What are my options?

	For a mainboard with a flash thats socketed or has a flash recovery setup. 
	Its possible to work with linuxBIOS without a EPROM/Flash programmer. 
	Personally I don't recommend it.  Especially if your Flash is soldered onto 
	the mainboard.  Screw that up and the Mainboard is toast.
	
	Some motherboards have a flash recovery method that you can set for when you 
	munge the flash.  This enables a known good BIOS boot image that will allow 
	you to recover when you screw up.  
	
	The BIOS savior also works similar to this.  It allows you to have 2 
	different BIOS images and choose the one you want to boot from.
	
Which different operating systems will LinuxBIOS boot?

	<Someone please fill this in>

What payloads can/has linuxBIOS boot/booted?

   Linux Kernel regular - use as your OS kernel
   
   Linux Kernel Kexec bootloader - boots another linux kernel from a device 
   supported by linux (I don't know where this payload stands as a formal 
   package)
   
   Memtest86 - great memory tester
   
   Plan9 - Plan9 OS
   
   9load
   
   ADLO + Bochs BIOS - Interrupt support, boots BSDs and Win2k
   
   Etherboot standard - kernel over ethernet
   
   Etherboot devel branch - kernel over ethernet and raw disk i/o
   
   Etherboot 5.0.6 polled ide patch - kernel over ethernet and buggy file
   system support
   
   Etherboot SIS patch - kernel over ethernet, file system support, and
   booting WinCE I think (but I don't know if SIS has let this out formally)
   
   RedBoot - could read the file system but never had the elf support to make
   it really usefull
   
   Steven James ELF finder - I think this was written as payload? Anyway, it
   lets you choose from payloads in your rom.
   
What is ADLO?

	See the following url:
	
	http://www.missl.cs.umd.edu/Projects/sebos/phase2.shtml	
	
	But basically its the glue which bonds LinuxBIOS to the PC
	BIOS of the Bochs project.  
	
	It allows you to boot some OS's that depend on legacy BIOS services.

What bios services does ADLO provide and when would I need them.

	The full gory details are at:

	http://www.missl.cs.umd.edu/Projects/sebos/winint/index2.html

How do I get LinuxBIOS to boot ADLO?
	
	ADLO compiles as an ELF image so you have to set up LinuxBIOS to elf boot 
	just as if you were using etherboot.  Go read the etherboot IDE section of 
	this faq and get to where you can boot etherboot.
	
	ADLO is distributed with LinuxBIOS in the freebios/util/ADLO directory.
	
	Int that directory are some README's.  Make sure you have read them.
	
	Compiling ADLO is quite simple.  Mostly you just type 'make'  You need a copy 
	of your video BIOS if you want VGA to work.  Again see the README.
	
	Out-of-the box ADLO probally won't boot unless you are using the exact 
	mainboard that the ADLO project uses.  The reason is that various areas of 
	shadowing must be enabled for ADLO to boot.
	
	If you see elfboot indicate that its 'Jumping to boot code at 0x7c00' and 
	then the board resets or hangs then its very likely that your shadow settings 
	are incorrect.
	
	Applying the serial debug patch to ADLO can help you further investigate 
	this.
	
	<Where is the defacto location for the serial patch? >
	
	The shadow settings are set in loader.s in the freebios/util/ADLO.  Find 
	section B)  These are writes to PCI space that enable various areas of 
	shadowing.
	
	Technically all you need is the only 64kb at 0xF0000 and 64kb at 0xC0000. 
	Your mileage may vary.  I would start by enabling Read/Write for all shadow 
	ranges supported by your chipset and then backing off to 0xF0000 and 0xC0000 
	after you get it working.
	
	The ADLO makefile will copy your video bios from an existing setup.  See the 
	README and makefile for details. 
	
	If you have one of the BIOS kits provided by the video chipset mfg for your 
	board then you may have a stock image an then a program that allows you to 
	customize the stock image.  If so then you need to set things up so that the 
	video bios is set to be loaded at 0x0C0000 (sometimes called the C000 
	segment) 
	
	Also I found that ADLO expected the video bios to be 64k in size whereas my 
	image file was only 32k.  I solved this by just copying it twice in the same 
	file and then letting ADLO use that.  Some creative work with 'dd' would 
	probally achieve the same result.
	
	Lastly if you have applied the serial debug patch to BOCHS then _all_ the 
	output is routed out to the serial port so your video screen will be blank. 
	However VSYNC will still be generated if the video chip is initialized 
	properly.  You can watch for VSYNC with a Oscope or plug a newer type monitor 
	up to the video output.  Most modern monitors will tell you when they 
	can/can't find the VSYNC signal.  Note you may have to power cycle the 
	monitor between attempts as sometimes they can get very confused.
	
If I burn ADLO along with linuxbios on rom do we need to specify BOOT_IDE=1?

   Nope. BOOT_IDE is merely to use the ide support thats directly in LinuxBIOS, 
   in which case it would skip right over ADLO.

My kernel won't fit in ROM so how do I boot?

	If you aren't blessed with a 8Mbit or larger flash there are a few other 
	options.
	
	- Load from the net via etherboot
	- Load from IDE via etherboot
	- Load from IDE via ADLO
	- Load from Msystems Disk on Chip (DoC)
	
How do I load a kernel from IDE?

	Currently there are 3 different methods.
	
	1. Etherboot 5.0.6 with polled ide patch:
	
	Download etherboot-5.0.6 and see http://www.missl.cs.umd.edu/~agnew/ for the 
	patch.

	2. Etherboot development series:
		
	Download >= etherboot-5.1.7

	3. ADLO

   see freebios/utils/ADLO/ from the linuxbios cvs. (this one is the most work, 
   but wont require you to modify your kernel when you're done)


How do I make LB use etherboot IDE?

   First you need to go get etherboot and compile it.  You either get the 
   developement branch with IDE support or the stable branch which need a patch 
   to work.
   
   Now modify the etherboot config file so that its compatible with LB. 
   Specifically the ./src/Config file and the arch/<your arch>/Config file
   
   For Ver 5.1.8
   
   The options you need to make sure are set are:
   
   -DELF_IMAGE -DLINUXBIOS -DCONFIG_TSC_CURRTICKS -DCONFIG_PCI_DIRECT
   
   there are other options that are helpful like -DCONSOLE_SERIAL 
   -DCOMCONSOLE=xxx 
   
   The option(s) you need to make sure it NOT set are:
   
   -DPCBIOS
   
   Then compile etherboot.  You want to compile with a specific make command so 
   that it generates the elfimage for LB to load.  This is done by taggin the 
   .zelf on to your normal makefile command.
   
   For example to make the polling IDE loader elf image you need:
   
	make bin/ide_disk.zelf
	
	For Ver 5.0.x:
	
	<Someone needs to fill in the info for the earlier version>
	
   Now modify your linuxbios config file to include:
   
   option USE_ELF_BOOT=1
   option PAYLOAD_SIZE=<size of you etherboot payload>
   payload /path/to/your/etherboot/driver
   
   You also need an input stream for the elfboot code to read from so you must 
   set one (or more?) of the following options.
   
   USE_GENERIC_ROM=1
   
   <What are all the other stream options?>
   
   Now you need to create an elf kernel for the ether boot code to find. Go 
   fetch the mkelfimage command at
   
   ftp://ftp.lnxi.com/pub/src/mkelfImage/
   
   Generally the latest one is better.  Note that there are several older 
   versions of binutils that are broken and mkelfimage will expose those bugs. 
   Insure that you are running a recient copy of binutils.  The following shows 
   the version output from a known working bintuils.
   
    # as --version
	 GNU assembler 2.13.90.0.10 20021010 Debian GNU/Linux
	 
	Now compile mkelfimage.  Which should be as easy as ./configure, make, make 
	install
	
	You can now create a elf kernel.
	
	Change to the directory where the image file for you kernel is.  Normally 
	this is somewhere in the kernel tree.  In my case this is is arch/i386/boot 
	and the kernel image is bzImage.
	
	By defaut mkelfimage is installed in /usr/local/sbin so you would do
	
	/usr/local/sbin/mkelfimage bzImage elfimage
	
	Now you have your kernel elfized in the file 'elfimage'
	
	mkelfimage support several options for adding commandlines and initrd's to 
	the kernel image type 'mkelfimage' without any arguments for the details.
	
   Ok final setp. Locate the kernel on the IDE device.  Etherboot currently 
   searchs the first 8k of disk space for the elf header.  So you have to locate 
   the start of that kernel within that space.
   
   If you don't care about having a proper partition table on your disk then you 
   can just splat the kernel at the front of the disk.
   
   For the rest of the examples lets assume your disk is mounted in your 
   *developement* machine as /dev/hde
   
   The following will write the kernel at the beginning of the IDE device.
   
   # cat elfimage > /dev/hde
   
   This works well if you don't need the IDE device for anything other than 
   booting.
   
   If you want a filesystem on the device as well then you are going to have to 
   protect the partition table as well.
   
   Currently the hack for accomplishing this is 
   
   dd if=elfimage of=/dev/hde bs=4096 seek=1 
   
   This will skip over the partition table and write the data in the area where 
   the first partition would normally be.  So you have to create a disk with at 
   least 2 partitions.  /dev/hde1 should be large enough to hold your kernel 
   plus any initrd you may want.  You can then put your filesystem on /dev/hde2
   
   Note. It appears that some version of dd may whine about /dev/hde being an 
   "Invalid argument" but it appears to write the data to the disk anyway.

What do those IDE options mean?

	See IDE section in Appendix A.

How do I make the prephials work on a 	National SCx2xx under linuxBIOS?

	The SCx2xx series have this feature where binary-only code gets executed in 
	SMM (System Management Mode) when you (or kernel drivers) access certain 
	addresses.  It's called VSA, Virtual System Architecture.  There's also VSA2 
	which adds something.

	NSC supplies some binary VSMs (Virtual System Modules) with their royalty 
	free BIOS kit BLDT (BootLoader Development Toolkit), aka XpressLOADER. Among 
	others, there are VSMs for enabling audio and video.

	LinuxBIOS does not currently implement VSA or VSA2.  I see no reason why it 
	couldn't, though, I even think it could be made as a separate ELF object 
	loaded in the same way the bare bones toolkit is, I seem to remember the idea 
	of being able to plug multiple ELF objects into the bootup sequence but this 
	still requires some twiddling, right?

	NSC offers documentation on VSA/VSA2 but I'm not sure about availability..

	NSC also offer a Linux audio driver for the SCx2xx family but this driver 
	requires the XpressAUDIO VSM to work.

Help!  I'm a newbie and I'm completely lost in the code.

   There seem to be two main parts to linuxbios. The first is 
   arch/{arch}/config/ctr0.base which does the very low level initialization, 
   like turning on memory, etc. The second is arch/{arch}/lib/c_start.S which 
   does whatever else is necessary to call the C function hardwaremain(). 
   hardwaremain() then does whatever else is necessary to load linux.
     
   c_start.S is linked with linuxbios.a, a library containing generic support 
   routines (those found in the lib directory) and anything specified using the 
   'object'  directive in a Config file (and other stuff). The resultant 
   'executable' is called linuxbios_c. The loader script used to link 
   linuxbios_c is config/linuxbios_c.ld, and is configured to be loaded relative 
   to _RAMBASE.
     
   crt0.base is not linked against anything. Any additional assembly routines 
   you need must be specified using the 'mainboardinit' directive in a Config 
   file. This causes the specified assembly file to be added to 
   "crt0_includes.h" which is in turn included at the start of crt0.base (or at 
   the end in the case of the ppc version). The loader script used to link 
   crt0.base is in arch/{arch}/config/ldscript.base. The resultant 'executable' 
   is called linuxbios and will be loaded at _ROMBASE. The tricky thing is that 
   this loader script will also load the linuxbios_c 'executable' at a location 
   called _payload in this file. The main task of crt0.base is then to 
   initialize enough hardware so that this payload can be copied from rom into 
   ram (which may also involve uncompressing code). Then control is transferred 
   to _start, which is the first location in linuxbios_c.
     
   To get an idea of how crt0.base works, look at the following files. This is 
   the order of execution specified by the configuration file for sis735.
     
     cpu/i386/entry16.inc
     cpu/i386/entry32.inc
     superio/sis/950/setup_serial.inc
     pc80/serial.inc
     arch/i386/lib/console.inc
     cpu/k7/earlymtrr.inc
     northsouthbridge/sis/735/raminit.inc
     arch/i386/config/crt0.base
     
   Next look at c_start.S which will show you what happens once control is 
   transferred to _start. Finally, look at arch/{arch}/lib/hardwaremain.c to see 
   what other stuff is done to get linux loaded.
     
   Most other files are specific to particular hardware, so it can be pretty 
   confusing to just browse the tree.

What do I need to get started with linuxbios on a new motherboard ?

	First do a  'lspci' on that motherboard and determine what chipset is being 
	used.  Then search through the LinuxBIOS src/mainboard tree and see if any 
	motherboards that are already supported are close to the chipset you have.

	If there isn't a good match then you will have to go aquire all the 
	datasheets for the chipset used on that motherboard.  Depending on the NDA 
	stance of the manufacurer this may or may not be an easy task.  
	
	Once you have all the technical data for the motherboard in question
	you create a directory(s) below the src/mainboard directory with 
	the mfg and boardname of your motherboard.  ie. if you have the 
	'superfoo5' motherboard made by Fooboards, Inc. you would create the
	following directory.
	
	src/mainboard/fooboards/superfoo5 
	
	Then if you found a motherboard that was close you can copy in all the files 
	from that motherboard.  Otherwise you start from scratch in which case you 
	should use some of the other motherboards setups as templates and rework them 
	to your needs.

   [Perhaps we need to setup a blank template directory just for this purpose?]


Is there a reference for all the options in the config file?
	
	While no defacto reference exists beyond the source code I've collected as 
	much as I can from gleaning the mailing list and my own experience with the 
	code.
	
	See appendix A for that reference.
	

Appendix A.

Code location options.

Key:  
	<bool>  		1 or 0  1=active 0=inactive
	<address>	hex address.  ie 0x0ffff or 0xffff0000 include the '0x' prefix
	<n>			decimal number ie 2 or 5, etc
	<hexval>		hex number ie. 0x0000ffff
	
option BIOSBASE=<address>

	default = 0xf0000
	
   I believe this region is automatically cached by linuxbios (maybe not?). If 
   biosbase is set to 0xffff0000, then in your config you need to set:

option XIP_ROM_SIZE= 0x01000000

	default = ?
	
option XIP_ROM_BASE= 0xff000000

	default = ?

   This will cache the upper 16M of the 4G address space.  Basically, the 
   chipsets generally map both to the same physical memory, the flash, ie, they 
   aliasing 0xf0000 to 0xffff0000.  You can cover 0xf0000 with ram, by setting 
   proper bits in the bridge, but not 0xffff0000.  But on startup by default 
   most if not all chipsets alias the top 64k under 1M to the top 64k under 4G. 
   It all has to do with legacy, real-mode stuff. linuxbios is in 32-bit mode, 
   though,  after a few initial instructions.

IDE Options

option BOOT_IDE=<bool>
	
	default = 0

	This enables booting from IDE, the file to use is linux.bin.gz: More 
	specifically it controls the compile and linking in of 
	freebios/src/rom/ide_fill_inbuff.o
	
option IDE_BOOT_DRIVE=<n>
	
	default = 0

	If you do not use drive 0  (default), then you can set which drive to boot; 
	(0,1,2,3) are the four standard PC drives:

option ONE_TRACK=<n> 
	
	default = 63

	The linux.bin.gz file is put in raw form at partition 1, ie, the first 
	partition on the disk.  This is located just past the partition table. The 
	partition table size varies, it is "one track" from the beginning of the 
	disk.  "one track" in c/h/s notation is "s" or the number of sectors per 
	track.  ONE_TRACK is in sectors, the software multiplies by 512. Most disks 
	are 63 sectors per track (the default), but my CF is 32 sectors per track. 
	eg, the partion table is 63x512 or 32x512 bytes.

	You can partition your disk as you want, but linux goes raw in partition 1; 
	just make sure partition 1 is big enough, not a problem on today's disks. You 
	could put the linux root file system on partition 2, for example.  In 
	pcchips787.config, I put the linux root file system on IDE 0, partition 2 (I 
	was experimenting with linux in partition 1), but I eventually put linux on 
	drive 2 using CF.  You are right, copying of linux.bin.gz raw to the 
	partition is dangerous, and something like "cat linux.bin.gz > /dev/hda1" 
	will definitely screw the disk if you put the wrong disk or partition.  I 
	recommend a shell script, fingers cannot be trusted.  You can also use "dd" 
	but "cat" works.

option STD_FLASH=<bool>

	default = ?

	In the sis northsouthbridge ipl.S code this controls some settings. 

	<sis person please fill in more detail>
	
option USE_GENERIC_ROM=<bool>

	default = ?

	Controls the linking in of freebios/src/rom/rom_fill_inbuf.c
	
	<someone please explain this in more detail>
	
option ZKERNEL_START=<address>

	default = 0xfff00000

	The address where the kernel is located in the ROM.  Data at this address is 
	copied to the RAM destination address.
	
option ZKERNEL_MASK=<hexval>	

	default = 0x0000ffff

	<someone please explain this in more detail>


Boot options.
	
option USE_ELF_BOOT=<bool>

	default = 0	
		
	Controls the building and linking of the elf image boot code.
	
option PAYLOAD_SIZE = <n>

	default = ?
	
	Sets the size of the elf payload that is added to the LB rom image.
	

Logging options

option DEFAULT_CONSOLE_LOGLEVEL

	default = 8  

	Sets the default for the ammount of verbosity LB uses to tell you whats 
	happining. Default is for printk_spew which is the most info possible from LB		
	
option MAXIMUM_CONSOLE_LOGLEVEL

	default = 8
	
	Max value of loglevel. If DEFAULT_CONSOLE_LOGLEVEL is higher than this it 
	gets set to this value.