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!
Article originally appeared here.
This document is intended to help people bring up new LinuxBIOS targets. Our first example will be the Technoland SBC 710, since it has a set of chips that are for the most part already supported.
The SBC710 is sold by Technoland and consists of a PGA370 socket for support of Pentium 3s and Celerons; a 440BX northbridge; a PIIX4e South Bridge; a C&T video chip; and two winbond SuperIO chips (83977EF and 83877TF). As it happens most of these chips are supported by LinuxBIOS, which is one reason we chose the board. Another reason we chose the board is because PC motherboard vendors are in the habit of hiding the things you need to know to get LinuxBIOS working. This card, we are finding, is an open book. It is as a result pretty easy to get it going. Finally, it is cheap: $380 without CPU or memory and about $600 with PIII/800 CPU and 256MB memory. Getting LinuxBIOS up involves several steps:
For the SBC 710, the chips we need to be concerned with are: Intel 82443BX North Bridge (also known as 440BX); Intel PIIX4E South Bridge; C&T video chip; and two Winbond Super IO chips, the 83977EF and the 83877TF. All of these chips except the 83877 and the C&T chip are supported. We don't care about the C&T chip because we don't do graphics in LinuxBIOS (yet). We will have to add support for the 83877 later; we'll go into that.
The SBC 710 supports BOTH a 256 KB (4 Mbit) flash part and a DoC flash part. This is an ideal situation. We can boot a fairly complex LinuxBIOS from the FLASH part, as it is at least 8 times larger than the largest LinuxBIOS rom image; and we can put a very large Linux kernel in even the smallest 8 MB DoC part, and even an initial ram disk (initrd) if we wish. The FLASH part is addressed at the normal 0xf0000 address, and the DoC is addressed (via jumper) at 0xd0000.
Some systems have just normal RAM or VGA memory in the 0xa0000-0xeffff space, so this space can actually be used as a type of memory -- namely, cacheable for reads and write-invalidate for writes. Other systems have I/O devices in this address space, so the memory must be configured as completely non-cacheable. The determination of how this area is treated is controlled by the Fixed-address Memory Type Range Registers (Fixed MTRRs). To leave this address space as RAM, we don't have to do anything. To use it as a device space, we have to set
option MTRR_ONLY_TOP_64K_FLASH
in the mainboard Config file. The SBC 710 has devices in the 0xa0000-0xeffff address space -- namely, the Disk On Chip. The mainboard Config file will need to have this option set.
SDRAM configuration is the single biggest problem for LinuxBIOS. In part it is due to the complexity of SDRAM, since we need to check over 17 different parameters to figure out how to determine the SDRAM control registers. That is only one of the problems. By definition, memory is not functioning before we program the SDRAM, so our code is very limited in what it can do, which makes for some very complex and hard-to-read assembly. Finally, poor chipset designs can make it hard to get it all right. Actual SDRAM parameters such as CAS latency, speed, etc. are maintained on a Serial EEPROM (SEEPROM) on the SDRAM module. The SEEPROM is accessed over a serial motherboard link called the SMBUS. LinuxBIOS needs to access the data in the SEEPROM and then configure SDRAM control registers. The actual SDRAM control registers are on the North Bridge, as expected; the South Bridge controls the SMBUS. To actually program the SDRAM control registers on the North Bridge, we must direct the South Bridge to send packets on the SMBUS to query the Serial EPROM on the SDRAM modules to find out their configuration. Fortunately, thanks to our many contributors, both these chips are supported. If the board vendor has not done anything to make it difficult to operate the SMBUS, everything should work fine.
This program can be used to test SPD accessibility on systems with a PIIX4E. We were not sure if it would work, given that IBM on the Thinkpad T22 obscures this information.
A note on this program. You need to understand a bit about SMBUS to understand it. If you're doing a port you should understand it anyway! Here is a quick introduction. The data rate is roughly 100 Kbits/second. SMBUS is a serial bus found on most new motherboards. SMBUS is also sometimes called I2C, although that usage is being deprecated. SMBUS is a packet-oriented bus and is used for communications with many different systems on PCs, including smart batteries, sensor chips, and SDRAM. SMBUS packets contain a 7-bit address for selecting devices. This address in the SMBUS packet is shifted left one bit and, for read operations, OR'ed with a 1 in the low-order bit. Certain devices are assigned fixed addresses; SDRAM is one of them. Currently SDRAM occupies addresses 0x50 to 0x53. One thing that complicates SMBUS usage is that a system may have more than one SMBUS. For example, ASUS motherboards sometimes have two; IBM thinkpads also seem to have more than one. The motherboard vendors often obscure the existence of the SDRAM SMBUS by hiding it in hardware. On the ASUS CUA we had to find the enable control for SDRAM SMBUS by using a PCI analyzer to capture the I/O operations.
Our simple program probes the SMBUS by enabling SMBUS access in the PIIX4E and then, first, enumerating all accessible devices on the SMBUS; and, second, seeing if any SDRAM devices can be accessed. We won't describe how the program does this, since if you're doing a port you need to have a thorough understanding of how it works. Walk through it line by line until you know what it does.
When we run the program we find that it correctly probes SDRAM in slot 0, the only SDRAM slot on the SBC 710. This result is very encouraging, since it means that the LinuxBIOS SDRAM setup code will probably work with no changes whatsoever. We have cleared the worst hurdle.
The SBC 710 supports two serial ports. What we don't know is which of the two Winbond Super IO chips supports which serial port. There is no real question about our ability to drive the serial ports, the work will be in figuring out which chip to drive, and how to drive it.
There are two Super IOs on this card. They are both capable of running floppy, keyboard, serial, etc. For configuring LinuxBIOS we need to know which Super IO does which function. Fortunately we can probe the Super IOs from user mode and figure out, for all of the devices, which device is turned. This information will in turn guide the LinuxBIOS configuration.
The only new chipset to this board is the Winbond w83877tf superio. Most winbond Super IO parts are pretty much the same. To start, we can borrow code from another winbond. Since the w83627hf has the most complete support, we borrow the code from that one. To set up the new Super IO, we generally need two files: superio.c (C setup) and setup_serial.inc (needed for very early low-level debug printing). The w83627hf provides both of these. To set up the new superio:
cd src/superio/winbond mkdir w83877tf cp w83627hf/* w83877tf
Next you need to look at the superio.c file and fix it up. You can see what needs to be done by comparing the three winbond superio directories. The differences are actually quite minor. Luckily this was the only new support needed for LinuxBIOS on the SBC 710.
The next step is to set up a mainboard directory for the mainboard. The general form of the tree for components and mainboards is src/part-type/vendor-name/mainboard-name, so for example for the ASUS CUA the tree in LinuxBIOS is: src/mainboard/asus/cua. The mainboard directory contains one mandatory file: Config. Config is used by the Python-based configuration tool to build several files for building LinuxBIOS for the mainboard. These files include a Makefile, ldscript file, crt0.S file, and several other files depending on what is in the Config file. Optional files include mainboard.c, for setting up mainboard-specific features of the mainboard; irq_tables.c, for setting up irq tables for the mainboard (irq tables are ALWAYS mainboard-specific); and config.example, so users have a sample config file for the mainboard when they build it. There are enough existing mainboard targets for LinuxBIOS that we can usually find a mainboard that is close enough to use as a starting point. Thanks to one of our contributors there is a generic 440bx mainboard directory (not really guaranteed to work for everyone) called src/mainboard/intel/l440bx. The Config file in this directory is definitely wrong, since it specifies the wrong superio. Here is the original Config file. As you can see it specifies most things correctly save for the wrong Super IO part (it uses and SMC part). Here is the corrected version of Config for the SBC 710. The differences are minor:
7c7 < mainboardinit superio/NSC/pc87309/setup_serial.inc --- > # mainboardinit superio/NSC/pc87309/setup_serial.inc 13c13,15 < superio NSC/pc87309 --- > #superio NSC/pc87309 > nsuperio winbond/w83977ef keyboard=1 > nsuperio winbond/w83877tf 24a27,29 > > option UPDATE_MICROCODE > option MTRR_ONLY_TOP_64K_FLASH
We have to comment out the setup_serial.inc (we don't know which one to use yet); and we change the Super IO parts. Finally we always enable UPDATE_MICROCODE since this board always uses PIIIs and we know that some of them will need microcode patches. If you check out the CVS tree, you can see we also add a mainboard.c:
mainboard_fixup()
{
void southbridge_fixup(void);
southbridge_fixup();
}
This code is needed to fix up the PIIX4E for Linux use. The other code files, irq_tables.c and do_ramtest.inc, are also used for the SBC 710. Finally we provide an example.config to make it easy to build LinuxBIOS for the SBC 710.
To build LinuxBIOS, you need to create a config file. Here is the starting point for this mainboard.
# Sample config file for technoland sbc710 target tlsbc710 mainboard technoland/sbc710 # Enable Serial Console for debugging option SERIAL_CONSOLE option NO_KEYBOARD option INBUF_COPY option DEFAULT_CONSOLE_LOGLEVEL=9 option DEBUG option USE_GENERIC_ROM=1 # Path to your kernel (vmlinux) linux ~/src/bios/linux-2.4.7-sis # Kernel command line parameters commandline root=/dev/hda6 console=ttyS0,115200 FS_MODE=ro hda=flash hdb=flash
We name the target directory, the mainboard, and set some options. For more information on the options in a configuration file see the CVS tree; look in Documentation at the configmanual.ps document. To build this linuxbios tree, you need to figure out where you want to build it, figure out where you linux is, and fix the file as needed. For testing we take the file as is and run the config tool:
python ~/src/freebios/util/config/NLBConfig.py config.example ~/src/freebios/
The build is fine.
You will next need to burn the 256KB flash part used in the SBC 710. For this purpose we use our AMD SMP systems and either the MTD utilities or a user-mode program. We will be experimenting with MTD on the SBC 710 as well.