1 May
2003
1 May
'03
5:15 p.m.
After I sent that I realized that the word wrap was greater than 80 charactes.
Told you it was raw.
Heres a version wraped to 80 columns.
--
Richard A. Smith
rsmith@bitworks.com
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.