LinuxBIOS FAQ/HOWTO  Ver 0.0.3
Last Modified: 5/21/2003
Richard A. Smith 

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.

Context.

	Although LinuxBIOS has been ported to other architectures such as 
	the PowerPC almost all the info in this FAQ/HOWTO is specific to 
	the x86 architecture.

1. General Questions

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.  
	
	'grep -r' is your friend. Especially when attempting to figure out 
	what all the config options do.

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 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
		http://www.cwlinux.com/eng/products/products_lbmb.php
	- Compact Flash IDE adaptor  
		http://www.cwlinux.com/eng/products/products_ide2cf.php
		<Need some more links to CF adapters>
	- Oscilliscope
	- In Circuit Emulator hardware debugger
	- LinuxBIOS SDK
	  http://www.cwlinux.com/eng/products/products_sdk.php
	
How can I tell if my motherboard/chipset is supported by LinuxBIOS?
	
	There are 2 methods:
	
	1) 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 is supported.
	
	2) "Use the source Luke"
	
	Check out the latest copy of LinuxBios from CVS (instructions 
	are on the webpage) and look in the freebios/src/mainboard 
	directory. [The LinuxBios module is called 'freebios' in CVS for legacy 
	reasons] There are directories for each manufacturer of 
	mainboards that LinuxBIOS supports.  Below the manufacturer 
	directory is a directory for each mainboard or family of 
	mainboard.  If a directory for your mainboad dosen't exist 
	then theres a good chance LinuxBIOS dosen't support your 
	mainboard out-of-the-box.  Posting to the list would probally 
	be the next option.  See 'the lspci -vvv' in the earlier 
	part of the question.
	
	If the directory does exist then it still dosen't mean 100% 
	the mainboard will work but at least it probally worked at one 
	time.  Posting to the list will probally get you the latest 
	info for that mainboard.
	
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.
	
	The following items will also be of some use:
	
	IA-32 Intel Architecture Software Developer’s Manual Volume 3, System 
	Programming Guide
	 
	<What are some other good reference docs?>
	
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.
	
What hardware vendors support LinuxBIOS?

	- SIS actively supports LinuxBIOS developement. 
	  http://www.sis.com/
	- CWLinux makes various helpful LinuxBIOS stuff and also sells SBC with linuxBIOS 
	  pre-installed.
	  http://www.cwlinux.com/eng/products/
	  
	  <Who else is linux bios friendly?>

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?

	- Linux (of course)
	- Windows 2000 (via ADLO)
	
	<Someone please fill the rest of 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.
   
   Bare Metal Toolkit????

My cvs checkout failed.  Whats up?

 Error:
 	cvs [checkout aborted]: could not chdir to
 	freebios/src/arch/alpha/config: Not a directory
 
 Issue:
  Chances are that you are attempting to use a filesystem that is not case sensitive.
  i.e. under cygwin.  This won't work as several of the directories have both 
  a directory called 'config' and a file called 'Config'.
  You must use a filesystem that is case sensitive.


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
   
   Instructions 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
		
   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
   
   A quick note about PAYLOAD_SIZE.  This parameter does not specifiy 
   the exact size of the image but rather its fed to the bs=<size> 
   option of 'dd'.  This along with the 'sync' option causes dd to 
   only output files that are a mutiple of the bs= size.  So if you 
   specify bs=32768 but your input filesize is 40000 you will end up 
   with a output file thats 65536.  So far I have just kept 
   PAYLOAD_SIZE at 32768 and then go back and adjust ROM_SIZE such 
   that the final image size is the size of my ROM part.
   
   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 in some setups dd may whine about /dev/hde 
   being an "Invalid argument" but it appears to write the data to the 
   disk anyway. Somebody mentioned that it was a "buffer size" 
   mismatch with dd and ext3 but nothing definitive was ever posted. 
   If you receive this and solve the issue please report it.


	Instructions For Ver 5.0.x:
	===========================
	
	<Someone needs to fill in the info for the earlier version>

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.

I don't understand the x86 boot mechanism.

	Steve James writes:
	
   The confusion is that there are multiple stages to LinuxBIOS. All x86 machines 
   start at 0xf000:fff0 in real mode. The flash itself lives at the top of the 4GB 
   address space and the chipset arranges for an alias at the top of the 1MB real 
   mode address space.
   
   The instruction at that start address will be a jmp to the assembly language 
   initialization code. Once the memory is set up, the next stage is copied from 
   rom (possibly with decompression) to 0x80000 which includes _start. That code 
   consists of a little assembly language (equivilant to crt0 in a normal C 
   application) followed by the bulk of LinuxBIOS which is compiled from C. That 
   code is entered at hardwaremain.

	Further clarified by Steve Gehlbach:
	
	To be strictly correct, x86 machines start at 0xfffffff0 in real mode. ( IA-
	32 Intel Architecture Software Developer’s Manual Volume 3, System 
	Programming Guide, sect. 9.1.4.).

   Quoting the manual, for those that don't have it handy:
   
   ------
   "The first instruction that is fetched and executed following a hardware reset 
   is located at physical address FFFFFFF0H. This address is 16 bytes below the 
   processor’s uppermost physical address. The EPROM containing the software-
   initialization code must be located at this address
   
   The address FFFFFFF0H is beyond the 1-MByte addressable range of the processor 
   while in real-address mode. The processor is initialized to this starting 
   address as follows. The CS register has two parts: the visible segment selector 
   part and the hidden base address part. In real-address mode, the base address is 
   normally formed by shifting the 16-bit segment selector value 4 bits to the left 
   to produce a 20-bit base address. However, during a hardware reset, the segment 
   selector in the CS register is loaded with F000H and the base address is loaded 
   with FFFF0000H. The starting address is thus formed by adding the base address 
   to the value in the EIP register (that is, FFFF0000 + FFF0H = FFFFFFF0H).
   
   The first time the CS register is loaded with a new value after a hardware 
   reset, the processor will follow the normal rule for address translation in 
   real-address mode (that is, [CS base address = CS segment selector * 16]). To 
   insure that the base address in the CS register remains unchanged until the 
   EPROM based software-initialization code is completed, the code must not contain 
   a far jump or far call or allow an interrupt to occur (which would cause the CS 
   selector value to be changed)."
   ------
   
   If the biosbase option is not set, almost immediately, linuxbios does a far jump 
   to 0xf0000:0004, and so reloads the segment register such that the aliasing of 
   this address to the top 4G becomes important, as Steven James points out. But 
   setting biosbase=0xffff0000 will use a relative jump and actually execute 
   physically in the top 4G.


Whats a GDT?

	Steve Gehlbach writes:
	
   The gdt is one of a number of registers in the IA-32 model used for protected 
   mode memory management (ie, for 32-bit mode).  Typically, it is loaded to point 
   to a data structure that defines a flat (ie, 4 GB) data segment, and an 
   identical code segment, although you can in reality have many segments defined. 
   These segments are referenced by their offset into the gdt data structure, for 
   example in linux startup, 0x18 defines the data segment, and you would put this 
   into the %ds register.  This means the segment is defined 24 bytes into the gdt 
   table.  This is very different, of course, from how you use the %ds in real or 
   16-bit mode.
   
   Originally in linuxbios, the gdt was defined in flash, and not changed until 
   jumping to linux.  However, linux will hang if the gdt is located above 1M (not 
   sure why, but I have tested this many times).  So if you setup 
   biosbase=0xffff0000, this would put the gdt high, and it has to be loaded low so 
   linux will work.  However, recently, Eric setup a gdt reload in c_start.S, which 
   is relocated into ram below 1M, and so this will work fine for linux.  This 
   makes some gdt reload code I put into the sis630 area unnecessary.
   
   But the bottom line is you have to setup the gdt to point to a compatible (read 
   that identical) gdt table to linux, before jumping to linux.  Linux expects to 
   be in 32-bit mode with the gdt data structure a certain way.  You can see it at 
   the bottom of linux/arch/i386/boot/setup.S in the kernel source tree.
   
   Anytime you go into protected mode, you have to setup the gdt, and usually also 
   the idt, which handles interrupts.
   
   You can find more that you would ever want to know about it in the Intel 
   reference manuals, but most folks just copy the table data from someone else. 
   It is very painful code to debug, many bytes of the entries in the table 
   requiring bit by bit settings.

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.
		
How do I use the "new superio"/nsuperio interface.

	In light of the fact that some mainboards can have mutiple superIO's with 
	different functions enabled on different chips a slightly more flexable
	superio interface had to be established.  This is the nsuperio or "new superio" 
	setup.
	
	Basiclly it allows you to define multiple superio's, the address they are at, and 
	what functions to enable on that superio.
	
	The basic structure of the nsuperio command is:
	
	nsuperio <mfg>/<chipname> <cmd>=<value>
	
	You would have one of these lines for each superio on your mainboard that you wanted
	linuxbios to initialize.
	
	an example would be the Bitworks ims board which has a Nationl Semiconducior
	pc87351 superio on it.
	
	nsuperio NSC/pc87351 keyboard=1 com1={1} com2={1} floppy=0 lpt=0
	
	looking at this in detail:  
	
	'nsuperio NSC/pc87351' tells the config generator to use the new superio 
	interface and to use the config file in the freebios/src/superio/NSC/pc87351 
	directory.  This will auto define the USE_NEW_SUPERIO_INTERFACE config 
	option.
	
	The <cmd>=<value> options that follow set the enables and config info for all the differnet types
	of devices found in a superio.  If the <value> section is surrounded by {} its because
	that particular command is a sub structure.  In the serial device example you can also
	set the base address, IRQ value, default baud rate, etc See the pci.h file for the gory details
	of what you can and can't set.
	
	In this example the keyboard, com1, com2  are all enabled and the floppy and lpt port are
	disabled.
	
	The com port base address, and irq values are left to the defaults that are defined in 
	freebios/src/superio/NSC/pc87351/superio.c
	

Troubleshooting 

The board resets when it trys to jump to the loaded ELF image.

	So your serial log looks something like this?
	
   calling elf load... 
   New segment addr 0x94000 size 0x8128 offset 0x60 filesize 
   0x38d4 (cleaned up) New segment addr 0x94000 size 0x8128 offset 0x60 filesize 
   0x38d4 Loading Segment: addr: 0x0000000000094000 memsz: 0x0000000000008128 
   filesz: 0x00000000000038d4 Clearing Segment: addr: 0x00000000000978d4
   memsz: 0x0000000000004854 
   
   Jumping to boot code at 0x94000
   
   LinuxBIOS-1.0.0 Thu May 1 04:29:36 IST 2003 starting...
   Ram1

	This normally indicates a RAM setup problem.  What's happening is that
	the code is jumping to instructions that aren't really there.  The CPU evently 
	triple faults and resets.  Thus taking you back to the startup of linuxBIOS.
	
	
My keyboard dosen't appear to work.  Any suggestions?

	Did you set option NO_KEYBOARD=0?
	
	Next double, triple check that its really enabled.  Some chipsets have mulitple 
	places where you have to enable port 60 and 64.
	
	Don't forget to check your SuperIO chip as well since if thats where the 
	keyboard IRQ comes from you will need to have it enabled as well.


Appendix A.

These are various options that I either ran across while I was 
working with LinuxBIOS or that I saw posted to the list.

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= <address> 

	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.


Peripheral Options

option NO_KEYBOARD

	default = 1 
	
	Controls the linking and calling of the legacy keyboard enable code and ports 
	60 & 64.  The keyboard_on() either calls the chipset specific and generic 
	keyboard code or it does nothing.
	
	If your target has a keyboard port and you want it to work then you must set this
	to NO_KEYBOARD=0

 
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 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 ROM_SIZE=<n>
	
	default = ?
	
	Controls the size of the LinuxBIOS rom file.  The actual LinuxBIOS code is seldom larger than
	64k but it ususally goes into a ROM part thats much larger.  This sets the size of the final
	LinuxBIOS rom file size with the actuall LinuxBIOS code justified to the top of the image.
	
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 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.

   A quick note about PAYLOAD_SIZE.  This parameter does not specifiy 
   the exact size of the image but rather its fed to the bs=<size> 
   option of 'dd'.  This along with the 'sync' option causes dd to 
   only output files that are a mutiple of the bs= size.  So if you 
   specify bs=32768 but your input filesize is 40000 you will end up 
   with a output file thats 65536.  So far I have just kept 
   PAYLOAD_SIZE at 32768 and then go back and adjust ROM_SIZE such 
   that the final image size is the size of my ROM part.
	

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_debug.  Increasing this to >=9 enables 
	printk_spew which is currently the most verbosity avaliable.
	
	Note you have to increase MAXIMUM_CONSOLE_LOGLEVEL as well to get to level 9
	
option MAXIMUM_CONSOLE_LOGLEVEL

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