1 May
2003
1 May
'03
5 p.m.
Over the last 2 weeks or so I've been building a FAQ/HOWTO based on all my experience getting LB up on our system.
This is the result of those efforts. Its pre-Alpha. I've barely reviewed it. It's not spell checked and I didn't even consider grammer. Just raw stuff as I came across it.
Its heavly based on things that I have direct experince with. But when I saw questions and good answers come up on the list I snagged them.
Going back over it I realized that in the cases where I just block copied what someone else wrote I failed to include credit to the orginal author. My apologies. If you want credit for something you recognize let me know and I'll add it. If future I'll try to do a better job on getting that right in the first place.
I'm happy to take on maintainance of this doc. So please send me any answers or improvements and I'll incorporate them.
In places where I need more info I enclosed my request for info in <> please if you know answers or have info send it to me.
One area that sorely lacking is the Config options Appendix. I have as many options documented as I have come across but I know there are many more. Please pick an option or 2 that you use thats not yet documented and send me an explaniation.
One thing I would like to add as well is a 'Related Options' section to each option. And perhaps a 'Conflicts With' or 'Overides' section
Ron:
I'm thinking that this needs to be setup as some sort of LinuxDOC format or someother text processing package so we can generate html/pdf/text etc. What do you think is best? Also do you have the current FAQ in text format that I can incorpoate into this?
--
Richard A. Smith
rsmith@bitworks.com
LinuxBIOS FAQ Ver 0.0.1
Richard A. Smith
rsmith@bitworks.com
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.