Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
My experience getting LinuxBios working on a PC-Chips M810LR motherboard with an M-Systems Millennium MD-2800-D08 Disk-on-Chip
-- by Antony Stone
I first came across LinuxBios at the LBW workshop at Doolin, Ireland, and it seemed like such a great project that I just wanted to get home and build one of my own.
Thanks to Lance Davis and John Hearns for supplying hardware, Bill Boughton and Richard Russon for persevering with the software, and Chuck Moss for supplying some DoCs to play with.
Even better, I recognised the PC-Chips motherboard they were using there - an M810LMR, and I knew I had two of these in systems already. So all I had to do was get myself a Disk-on-Chip device, and I'd have an instant-booting system, right ?
Well, things were not quite so simple as that, so after managing to get my system working from a combination of:
I decided to write up my experiences to let other people know what I had to do to get things working, in the hope that this may make it easier for other people later on.
It seems that PC-Chips have recently (August 2002) decided to rename their motherboard product range, so this is going to lead to even more confusion over which particular board you are working with.
However, PC-Chips does appear to be one of the more helpful motherboard vendors as far as the LinuxBios project is concerned, and they certainly do seem to make some good value-for-money highly-integrated motherboards.
The Disk-on-Chip devices are something I'd never worked with before, and I had no idea where to get them from, either. I live in the UK, so I simply went to M-Systems' website and looked for UK or European distributors. There were two distributors listed for the UK, so I phoned them up, and bought three MD-2800-D08 devices from one of them. I have my own company, so I qualified as a trade customer. I have no idea where you would buy these as a private individual, but I'll stick my neck out here and say that anyone who has trouble getting the Millennium DoC devices in the UK can email me and I'll try to help.
As well as PC-Chips renumbering their motherboards, it also turns out that M-Systems are discontinuing the MD-2800 series and replacing them with the MD-2802 range, which are apparently "hardware and software interchangeable". The MD-2800 devices are being discontinued, but the MD-2802 should work identically in all designs. I bought the last three MD-2800s the supplier had :-)
So, I had a motherboard, and a Disk-on-Chip device. How to get LinuxBios up and running ?
The first thing is to read the LinuxBios FAQ and the documentation for the SiS630 motherboards. This should give you a good idea of the overall process, and the steps involved.
The steps listed in the documentation are: (Note: the following list should be numbered from 0 to 8 (as should the next list further down) for consistency with the original documentation. If your browser shows a list numbered from 1 to 9, you may want to consider updating it.)
Step 0 should be easy enough for people who are attempting LinuxBios in the first place, however note that the kernel you are running must have support for MTD (Memory Technology Devices), which most people won't have turned on as standard.
Therefore you should recompile your kernel on your machine with modules enabled (I generally don't use a modular kernel, but for programming the DoC devices in the Bios socket of the motherboard, you have to run a command before loading the DoC modules, therefore you can't compile this support directly into the kernel), and support for the Millennium DoC devices.
I generally use 'make menuconfig' to configure my kernel; here are the options you need to select (accurate for a 2.4.19 kernel) in order to build LinuxBios into a DoC device:
Loadable module support [*] Enable loadable module support [ ] Set version information on all module symbols [*] Kernel module loader Memory Technology Devices (MTD) <M> Memory Technology Device (MTD) support [ ] Debugging < > MTD partitioning support < > MTD concatenating support --- User Modules and Transition Layers <M> Direct char device access to MTD devices < > Caching block device access to MTD devices < > Readonly block device access to MTD devices < > FTL (Flash Transition Layer) support < > NFTL (NAND Flash Transition Layer) support RAM/ROM/Flash chip drivers ---> Mapping drivers for chip access ---> Self-contained MTD device drivers ---> < > Ramix PMC551 PCI Mezzanine RAM card support < > Uncached system RAM < > Test driver using RAM < > MTD emulation using block device --- Disk-On-Chip Device Drivers < > M-Systems Disk-On-Chip 1000 < > M-Systems Disk-On-Chip 2000 and Millennium <M> M-Systems Disk-On-Chip Millennium-only alternative driver [*] Advanced detection options for DiskOnChip (0) Physical address of DiskOnChip [*] Probe high addresses [ ] Probe for 0x55 0xAA BIOS Extension Signature NAND Flash Device Drivers --->
There is also a highly impressive 'gotcha' in the MTD driver support - you must edit one of the kernel source files before compiling with MTD support, in order to be able to write (ie erase or program) the DoC devices. If you do not do this you will get errors when you try to erase or program the device, such as:
/dev/mtd0: No such device /dev/mtd0: Bad file descriptor
The change required is in /usr/src/linux/drivers/mtd/devices/docprobe.c
Change the line which reads:
#define DOC_SINGLE_DRIVER
so that it becomes:
#undef DOC_SINGLE_DRIVER
You may want to read the comment just above the line you're editing, and be grateful that someone told you where to find this file to change it....
You also need to have Python installed on your system, because the LinuxBios build process is based around a Python program.
It is also highly recommended that you install a 32-pin ZIF (Zero Insertion Force) socket on your motherboard, because later on you will need to swap chips in the Bios socket while the motherboard is powered on. This is not something you want to make any mistakes with, eg using a metal tool, getting the Bios or DoC pins misaligned or bent, shorting out some nearby components or connectors...
Note the orientation of the Bios chip in its socket (there is a notch at one end, or a dot in one corner, of the chip), remove the chip, and plug a 32-pin ZIF socket into the motherboard socket (you will probably need to bend the pins of some nearby connectors to get it to fit - I found an unused 3-pin fan connector in the way). Place the lever of the ZIF socket at the end where the notch or dot was on the Bios chip. Make sure you plug the ZIF socket cleanly into all 32 holes on the socket on the motherboard - it's easy to miss a couple of pins at one end and get the whole thing moved along one place. You will probably want to do this with the motherboard not installed in a case, so you can look underneath the ZIF socket as you are inserting it.
Once the ZIF socket is in place, lift the lever, insert the original Bios chip (notch or dot at the lever end of the socket) and lower the lever to secure the chip in place.
If you see the usual Bios startup screen when you power on your motherboard, then you know you've done this bit correctly, and you can easily swap the chips over later on in the instructions.
Get the LinuxBios source by CVS:
export CVS_RSH=ssh cvs -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios login cvs -z3 -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios co freebios
(Press return at the password prompt and ignore errors about "failed to open ./cvspass for reading" and even "login aborted: fatal error: exiting". Press on regardless.)
Before you get a fresh kernel source to patch with LinuxBios, check the LinuxBios kernel patches to see which kernel version is supported for your motherboard / chipset. You may be able to apply the patches to a different kernel, but at this stage in the game it's probably best to build an old kernel strictly by the instructions, and make sure you can get LinuxBios working at all, and then afterwards you can try to bring the kernel up to the version you'd like it to be.
I used kernel version 2.4.19 because (a) this was already installed on my machine, and (b) there was a linux-2.4.19-sis.patch file available, which matched my motherboard.
You can find the kernel patches in the FreeBios source you just downloaded from CVS by looking in freebios/src/kernel-patches This directory contains both the patches for the kernels, and also the config files for building the new kernel (note that not all these are guaranteed to work in all situations - you may need to look at other config files and make some manual adjustments to get your particular setup working).
Note that the kernel patches and config files are for the kernel you will program into the DoC device and eventually boot your machine from. They may not be the best choice for the kernel you use to build LinuxBios and burn the DoC before trying to boot it.
When you build the kernel, use 'make bzImage' and then just leave the kernel where it is. LinuxBios will later look for the file /usr/src/linux/vmlinux
LinuxBios was developed from an earlier project called FreeBios, and therefore the source code you have downloaded is in a directory called 'freebios'
You need to create your own config file, and make the build images for programming into the DoC device, in a different directory so that they are not deleted when you update your copy of the source code from the CVS repository.
Because of the way the directory names worked out, I chose to create a new directory called 'linuxbios' side by side with 'freebios', and built my DoC images in there.
Here is what I did to build LinuxBios:
mkdir linuxbios cd linuxbios cp ../freebios/util/config/NLBConfig.py . cp ../freebios/util/config/pcchips.config .
I then edited pcchips.config, making the following changes:
I also edited one of the LinuxBios source files in order to get the keyboard working on my motherboard (again, thanks to Andrew Ip for this):
In the file freebios/src/arch/i386/lib/hardwaremain.c uncomment the function call keyboard_on() around line 344. If you do not do this, then when you finally boot your LinuxBios machine, you will get several hundred error messages "pc_keyb: controller jammed (0xFF)", and your keyboard will not work. It will not stop your LinuxBios system from working, however - you will still be able to log in on the serial port, and ssh across the network.
I then ran the Python program to create the build files:
python NLBConfig.py pcchips.config ~/freebios
This creates a subdirectory within linuxbios (where you are now) called pcchips, and creates the following files in it:
Once you have these files, and you have compiled your target kernel (which is then sitting in /usr/src/linux/vmlinux), you can run the makefile and build your LinuxBios image:
cd pcchips make
Note that if this is not the first time you're building the image, you may want to do a 'make clean' before the 'make'.
I then copied the 'burn_mtd' utility into the newly-created pcchips directory, because by default it looks in the current directory for the source files to burn into the DoC device, so there's a lot less typing if the utility is in the same place.
cp ../../freebios/util/mtd/burn_mtd .
I made a couple of changes to the burn_mtd utility, in order to match the filenames generated by the Makefile a few moments ago:
Change the first two occurrences of 'vmlinux' (one in the comment on line 3, the other in 'linux=vmlinux.bin.gz' on line 16) to 'linux' (so that line 16 now reads 'linux=linux.bin.gz').
Building the MTD 'erase' utility was pretty straightforward - I assume you'll have no problems here.
Go into the freebios/util/sis directory and build the 'flash_on' utility by doing:
make flash_on
Copy the 'erase' and 'flash_on' utilities which you just built into your search path (I put them into /usr/local/sbin)
This is the point where you are grateful you got yourself a 32-pin ZIF socket and plugged it into your motherboard.
While the power is on and your system is running, release the lever on the ZIF socket, remove the original Flash Bios chip, replace it with a DoC (check the orientation ! The notch in the end of the chip goes at the lever end of the socket), and secure it in place with the lever.
Run the command
./burn_mtd
and with any luck it will program a LinuxBios chip for you!
The output of burn_mtd should look like this:
# ./burn_mtd rmmod: module docprobe is not loaded rmmod: module doc2001 is not loaded rmmod: module docecc is not loaded 11+1 records in 12+0 records out 0+1 records in 1+0 records out Erase Total 1024 Units Performing Flash Erase of length 8192 at offset 0x7fe000 done 1+0 records in 1+0 records out 1+0 records in 1+0 records out 126+0 records in 126+0 records out 1536+0 records in 1536+0 records out #
If at this stage you get the following instead:
# ./burn_mtd rmmod: module docprobe is not loaded rmmod: module doc2001 is not loaded rmmod: module docecc is not loaded 11+1 records in 12+0 records out 0+1 records in 1+0 records out File open error dd: opening '/dev/mtd0': No such device dd: opening '/dev/mtd0': No such device dd: opening '/dev/mtd0': No such device dd: opening '/dev/mtd0': No such device #
then you should check that you selected the correct MTD options when building your development kernel (you did reboot after building that so you're running it now, right ?), and also that you edited the file /usr/src/linux/drivers/mtd/devices/docprobe.c to undefine DOC_SINGLE_DRIVER before building that kernel.
Press reset.
If your system reboots and you see a penguin in the top corner of your screen instead of an AMI or Award Bios startup message, then you should jump up and down, punch the air, say things like "Wow!", and generally be pleased with yourself.
Do not worry if bits of the system do seem to get started properly (eg hard disk, ethernet, keyboard, root filing system...). They can almost certainly get sorted out later.
If you do not get a penguin on your screen (in fact, you get nothing at all), then try plugging a serial cable into your RS232 port (the M810LR boards only have one RS232 port), connect a terminal emulator set to 115200 baud, 8 bits, no parity, and press reset again. You should get some debugging information and general startup message out of the serial port which might help you or someone else to work out what's not quite right.
If absolutely nothing happens, then it's possible that you haven't got a suitable image burned into the DoC, so power off the motherboard, remove the DoC and put the original Bios back in again, power the system back up, and see if you've missed something from the above instructions.
If you think I've missed something from these instructions, then please email me so I can update them for other users.
For general help with LinuxBios, there is a current mailing list at http://www.clustermatic.org/mailman/listinfo/linuxbios and archives of earlier lists at http://www.acl.lanl.gov/linuxbios/faq/archive and http://www.missl.cs.umd.edu/archives/linuxbios.
Good luck.
--
Antony Stone.