> I will also put my 'technoland port howto' on the web page. I'd like to > see your document too.
Hi Ron, I don't see the technoland howto there. I assume you haven't put it there yet. But I'd like to see it. I've attached a draft of my HOWTO and also the start of a glossary of terms commonly seen in the LinuxBIOS docs and email. These may give you an idea of what puzzles the minds of newcomers :-) If anyone wants to make comments about these files right now, that's fine, your comments are welcome. A few burning questions on my mind, as I write these docs, are: - I'm looking for some consistent terminology to describe the various sections of the LinuxBIOS code, and some precise definitions of the terms (where the boundaries between the sections are). I've seen stage 1, stage 2, stage 3, bootstrap, payload, IPL and SPL. Any suggestions about what the preferred terms are, and what the definitions should be? - What does DOM stand for? Disk on Media (i.e. hard or floppy disk), in contrast to Disk on Chip? - What is the relationship of FreeBIOS to LinuxBIOS? Has FreeBIOS (especially the SourceForge project) been assimilated by LinuxBIOS? Cheers, - Jan
*** *** NOTE to newcomers: this is a DRAFT, a work in progress, written by a relative newcomer. *** No warranties, etc. etc. *** LinuxBIOS Porting HOWTO =============== This HOWTO gives an overview of the steps for getting LinuxBIOS running on an arbitrary motherboard. The emphasis is on porting to motherboards that haven't been ported to already. The intended audience is people who are familiar with Linux and gcc at the applications level, but who may not be familiar with Linux internals, building kernels, etc. Additions, corrections, etc. for this HOWTO may be sent to Jan Kok, [EMAIL PROTECTED] The overall steps covered in this document are: * Choose a motherboard. * Choose a way to program your new BIOS parts. * Prepare hardware tools for debugging your BIOS code. * Obtain the source code that you will start with. * Decide what components will go into your BIOS. * Prepare config files, run NLBConfig. * Edit, compile, program your FLASH, test, debug, etc. Choose a motherboard -------------------- The amount of work needed to get LinuxBIOS working on a given motherboard depends on whether someone has already done the development work for that board, and how well the build and install process is documented. See http://www.acl.lanl.gov/linuxbios/status/index.html for a list of motherboards which already have LinuxBIOS ported. Two boards, the Matsonic MS7308E and the LeadTek Winfast 6300, have detailed HOWTOs for building and installing LinuxBIOS on those boards. The documentation is in the source tree (see below) at freebios/........ and freebios/......... For the other boards, the Matsonic or LeadTek HOWTO can be used as a rough guideline. You may also be able to get a suitable config file by visiting http://www.acl.lanl.gov/linuxbios/help/index.html . If your motherboard uses a processor and chipset that has been used in some other motherboard that runs LinuxBIOS, then your porting job may also be relatively easy. Otherwise, you will need to obtain the programming info for the new processor or chipset, and write the necessary code to initialize your motherboard. Choose a way to program your new BIOS parts ------------------------------------------- Make sure you have some way to program the BIOS FLASH (EPROM, EEPROM, etc.) parts. Some approaches are: - An external FLASH programmer device. - Hot-swap the BIOS FLASH part, that is, boot up your motherboard with its original BIOS, pull out the original BIOS part and replace it with another FLASH part that you will program (do this while the machine is running), load up some software for programming the FLASH part, program the new FLASH part with your new BIOS, then reboot and see if it works. If not, you can switch back to the original or previous working BIOS part. As other HOWTOs point out, this procedure is hazardous to life, limb and property, don't try this at home, etc. - Use a motherboard with dual BIOS (e.g. Gigabyte GA-6OXE or GA-7DXR) which lets you program one FLASH part and try it out, and recover (using the other FLASH part) if it doesn't work, all without swapping parts in and out. (Does anyone have more info on how the dual BIOS works? Gigabyte has some patents on it, but the patent numbers are not listed in the GA-7DXR user manual.) Prepare hardware tools for debugging your BIOS code --------------------------------------------------- If you expect to have to do some debugging of your LinuxBIOS code, (Naaahh! It will work the first time you try it :-) build or obtain a POST code (Power On Self Test code) display card. This is a card that plugs into a PCI or other expansion card slot, and has LEDs that display the data byte written to port 0x80 with the OUT instruction (on Intel type architectures). LinuxBIOS outputs POST codes to indicate progress during the booting process. POST code display cards are available at http://www.pcengines.com/testordr.htm and http://www.jdr.com/interact/item.asp?itemno=gr-pcode . See also http://people.freebsd.org/~fsmp/HomeAuto/postcode/postcode.html which adds remote control and monitoring to the JDR POST code display card. Of course, an ICE (In-Circuit Emulator, a device that plugs into the CPU socket, emulates the CPU, and allows single stepping and other debugging) would be extremely helpful, but these cost $$$$. (Any recommendations for brands/models?) A logic state analyzer may also be helpful, but they are a bit of a hassle to set up, and they can't (without special options) show you exactly what instructions the CPU is executing, because of the interference of the caches and memory controller in the CPU chip. Obtain the source code that you will start with ----------------------------------------------- LinuxBIOS is based on the "freebios" project at SourceForge. Unless the latest released code is very recent, you will probably want to get the latest development code. In order to get the development code, you need to register with SourceForge. You can then download the latest code either by http with a web browser, or directly with cvs. The sections of the code tree that you need are - freebios, latest version. - linux. The recommended version changes from time to time. Check the linuxbios mailing list archives at ... . On 2001/12/15 the recommended version is ... patches? (LinuxBIOS doesn't require bcc, which is offered under the freebios project.) So, example commands to get the code are: Decide what components will go into your BIOS --------------------------------------------- You need to decide what code will go into your BIOS, what drivers you need, what the process will be for getting the machine fully booted, and so on. For LinuxBIOS and an IA32 processor, the typical sequence of events is as follows: - When the motherboard is powered up or reset, the instruction at segment 0xffff address 0xfff0 is executed. This is generally a long jump instruction. The CPU is in .... mode. (See ........ for details on the CPU power on/reset behavior.) (What about multiprocessor boards?) - A few assembly language instructions are executed that switch the CPU to protected mode. This code is at freebios/src/cpu/<cputype>/entry16.inc - There are now a few very urgent tasks that need to be done. The order in which these tasks are done depends on the author and the motherboard. - (Optionally) initialize a serial port, so that debugging/progress messages can be sent out that port. - Get memory subsystem working: determine how many and what size modules there are, get memory refresh running, enable caches. - Get CPU registers and memory set up so that compiled code can be run, then jump to the compiled code. This code is at freebios/src/cpu/<cputype>/crt0.S Although the system is in a fragile state without the memory subsystem fully set up, it is sometimes possible to run compiled code using just cache as RAM. Then the memory subsystem setup, mentioned above, can be done in compiled code, rather than assembly language. - Now the compiled code runs. This code consists of all the .o files listed in the OBJECTS variable in the Makefile. - Memory, north and southbridges, are setup now if they haven't been setup already in assembly code. - The next level of code is brought into memory and then jumped to. This next level of code is called the "payload"; all the code that has been described up to this point is called the "bootstrap". The payload could be a more full-featured bootloader, such as LILO (NOT! LILO makes BIOS calls, not supported by LinusBIOS), or it could be a Linux kernel and file system, similar to what is found on floppy boot disks. If the payload is large, such as a kernel, it will typically be compressed, in which case the bootstrap must contain a suitable decompression routine. There are a number of choices for where to store the payload, and of course the bootstrap must contain drivers for whatever device(s) it can load the payload from. Some possible storage places for the payload are: - A Disk On Chip (DOC) (See http://www.m-sys.com/) This is a part that can be inserted in place of the BIOS FLASH part on some motherboards. The bootstrap code may be stored together with the payload on a DOC. - A Disk On Key (See http://www.m-sys.com/). This is a device about the size and shape of a house key that plugs into a USB port. I'm not aware of a driver being available yet for LinuxBIOS to use this device. - The BIOS flash part. The problem is, these parts are typically 256K or 512K byte devices on most current motherboards, which is too small to fit a Linux kernel into. - A Compact Flash (CF) part. There are adapters available at http://www.pcengines.com/testordr.htm and http://www.tapr.org/tapr/html/kitsf.html that allow CFs to be connected to IDE or floppy disk connectors, and that make a CF look like a hard or floppy disk. - A hard or floppy disk, sometimes refered to as DOM (Disk on Media?) in the linuxbios mailing list. - The network. "Etherboot" code allows the payload to be downloaded through a network card. - The payload is run. In the case of a Linux kernel, the entry point is at memory location 0x100000, and is a function called "start", found in the Linux sources in ....../start.c . The Linux code requires a few patches to work with LinuxBIOS. For example, the hard disk driver should be a bit patient if it discovers that the hard disk is not ready, because Linux may have booted from a DOC in just a few seconds, before the hard disk had a chance to spin up! Prepare config files, run NLBConfig ----------------------------------- The build process for LinuxBIOS has been designed to let you develop multiple configurations of BIOSes concurrently (e.g. for different motherboards), while sharing source code as much as possible. All the object code for a given configuration goes into a target directory that is named by you. This is in contrast to the Linux build style which puts object code in the same directories as the source files. In order to create a BIOS for a new motherboard, you need to choose appropriate code modules to match your CPU type, north and southbridge parts, and to supply drivers for whatever device(s) you want to load the payload from. This information is contained in a top-level config file created by you. The file ... gives more information about the commands you may use in a config file. It is recommended that you place your config file just under the freebios directory, e.g. at freebios/hal9k.config. This lets you safely remove the target directory and its contents, without losing the config file. The NLBConfig program processes the top-level config file, as well as additional config files contained in various subdirectories of the freebios tree, creates (if necessary) the target directory, and creates a Makefile, a Makefile.settings, a crt0.S and possibly other files, and places them in the target directory. To run the config program, make sure that freebios/util/config/NLBConfig is in your PATH and is executable. (NLBConfig is a Python script, so you must have python installed on your system and available in your path as well.) Run it as NLBConfig hal9k.config ~/linuxbios where myconfig is relative or absolute path to your top-level config file, and ... (Until recently, the way to invoke the script was "python NLBConfig.py hal9k.config ~/linuxbios" NLBConfig is newer than NLBConfig.py and produces a Makefile with better documentation than NLBConfig.py.) NLBConfig generates around 20 lines of informational messages but should not output any messages labelled as "error" or "warning"; if you get an error or warning, there is probably something wrong with your config file. If NLBConfig runs successfully, take a look at the Makefile, Makefile.settings and crt0.S in the target directory. These will give you a clearer idea of how your BIOS will be built and what will go into it. Edit, compile, program your FLASH, test, debug, etc. ----------------------------------------------------
CF - Compact Flash - flash devices tens to hundreds of megabytes in size, mounted in an industry-standard physical package, commonly used in digital cameras. crt0 DOC DOM DRB flash - non-volatile, reprogrammable memory, commonly used for storing the BIOS in motherboards. Apparently "flash" is not an acronym. (http://developer.intel.com/design/flash/articles/what.htm) IPL MSR - Manufacturer Specific Register - special-purpose registers on CPU chips (for example to set up caches, or for diagnostics), may or may not be documented. MTD - Memory Technology Device - A generic subsystem for handling memory technology devices under Linux (http://www.linux-mtd.infradead.org/) SPD SPL
