2 % This document is released under the GPL
3 % Initially written by Stefan Reinauer, <stepan@openbios.org>
6 \documentclass[titlepage,12pt]{article}
10 \usepackage[pdftex]{hyperref}
11 % \usepackage{makeidx}
15 urlbordercolor={1 1 1},
16 menubordercolor={1 1 1},
17 linkbordercolor={1 1 1},
19 % pdfpagemode=None, % PDF-Viewer starts without TOC
21 pdftitle={LinuxBIOS on AMD64},
22 pdfauthor={Stefan Reinauer},
23 pdfsubject={LinuxBIOS configuration and build process},
24 pdfkeywords={LinuxBIOS, Opteron, AMD64, Athlon64, Build}
28 % \newcommand{\sh}[1]{\begin{verbatim}\texttt{#1}\end{verbatim}}
29 % \newcommand{\prog}[1]{\textit{#1}}
31 \setlength{\parindent}{0pt}
33 \title{LinuxBIOS on AMD64}
34 \author{Stefan Reinauer $<$stepan@openbios.org$>$}
35 \date{November 18, 2003}
53 This document targets porting LinuxBIOS to new Motherboards and creating
54 custom firmware images using LinuxBIOS. It describes how to build
55 LinuxBIOS images for the AMD64 platform, including hypertransport
56 configuration and pertinent utilities. If you are missing information or
57 find errors in the following descriptions, contact
58 \href{mailto:stepan@openbios.org}{\textit{Stefan Reinauer $<$stepan@openbios.org$>$}}
65 \section{What is LinuxBIOS?}
67 LinuxBIOS aims to replace the normal BIOS found on PCs, Alphas, and
68 other machines with a Linux kernel that can boot Linux from a cold
69 start. The startup code of an average LinuxBIOS port is about 500 lines
70 of assembly and 5000 lines of C. It executes 16 instructions to get into
71 32bit mode and then performs DRAM and other hardware initializations
72 required before Linux can take over.
74 The projects primary motivation initially was maintenance of large
75 clusters. Not surprisingly interest and contributions have come from
76 people with varying backgrounds. Nowadays a large and growing number of
77 Systems can be booted with LinuxBIOS, including embedded systems,
78 Desktop PCs and Servers.
81 % 3 Build Requirements
84 \section{Build Requirements}
85 To build LinuxBIOS for AMD64 from the sources you need a recent Linux
86 system for x86 or AMD64. SUSE Linux 8.2 or 9.0 are known to work fine.
87 The following toolchain is recommended:
91 \item binutils 2.14.90.0.5
96 \textbf{NOTE:} Later versions should also work. Prior versions might lead to problems.
101 % 4 Getting the Sources
104 \section{Getting the Sources}
106 The latest LinuxBIOS sources are available via CVS. The CVS repository
107 is maintained at SourceForge.net (the project name is \emph{FreeBIOS}). You
108 can get the entire source tree via CVS:
112 % cvs -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios login
116 Hit return when you are asked for a password. Then checkout (or update)
117 the freebios source tree as follows:
121 % cvs -z3 -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios co freebios2
125 Once the source tree is checked out, it can be updated with:
133 Due to recent problems with SourceForge's CVS infrastructure we set up a
134 snapshot site that keeps hourly source trees of the last four days. It
135 is available at \url{http://snapshots.linuxbios.org/}.
136 Due to major structural enhancements to \hbox{LinuxBIOS}, AMD64 support
137 is only available in the \texttt{freebios2} tree. This tree reflects (as
138 of November 2003) LinuxBIOS version 1.1.5 and will lead to LinuxBIOS 2.0
139 when finished. Most x86 hardware is currently only supported by the
143 % 5 LinuxBIOS configuration overview
146 \section{LinuxBIOS configuration overview}
147 To support a large variety of existing hardware LinuxBIOS allows for a
148 lot of configuration options that can be tweaked in several ways:
152 Firmware image specific configuration options can be set in the image
153 configuration file which is usually found in
154 \texttt{freebios2/targets/$<$vendor$>$/$<$motherboard$>$/}. Such
155 options are the default amount of output verbosity during bootup, image
156 size, use of fallback mechanisms, firmware image size and payloads
157 (Linux Kernel, Bootloader...) The default configuration file name is
158 \texttt{Config.lb}, but LinuxBIOS allows multiple configurations to
159 reside in that directory.
161 \item Motherboard specific configuration options can be set in the
162 motherboard configuration file placed in
163 \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$motherboard$>$}. The
164 motherboard configuration file is always called \texttt{Config.lb}. It
165 contains information on the onboard components of the motherboard like
166 CPU type, northbridge, southbridge, hypertransport configuration and
167 SuperIO configuration. This configuration file also allows to include
168 addon code to hook into the LinuxBIOS initialization mechanism at
173 This document describes different approaches of changing and configuring the
174 LinuxBIOS source tree when building for AMD64.
176 \section{Building LinuxBIOS}
177 One of the design goals for building LinuxBIOS was to keep object files
178 out of the source tree in a seperate place. This is mandatory for
179 building parallel LinuxBIOS images for several distinct motherboards
180 and/or platforms. Therefore building LinuxBIOS consists of two steps:
183 creating a build tree which holds all files automatically created by the
184 configuration utility and the object files
186 compiling the LinuxBIOS code and creating a flashable firmware image.
189 The first of these two steps is accomplished by the \texttt{buildtarget}
190 script found in \texttt{freebios2/targets/}. To build LinuxBIOS for
191 instance for the AMD Solo Athlon64 motherboard enter:
194 % cd freebios2/targets
195 % ./buildtarget amd/solo
198 This will create a directory containing a Makefile and other software
199 components needed for this build. The directory name is defined in the
200 firmware image specific configuration file. In the case of AMD's Solo
201 motherboard the default directory resides in
202 \texttt{freebios2/targets/amd/solo/solo}. To build the LinuxBIOS image, do
209 The LinuxBIOS image filename is specified in the firmware image specific
210 configuration file. The default filename for AMD's Solo motherboard is
213 \section{Programming LinuxBIOS to flash memory}
214 The image resulting from a LinuxBIOS build can be directly programmed to
215 a flash device, either using a hardware flash programmer or by using the
216 Linux flash driver devbios or mtd. This document assumes that you use a
217 hardware flash programmer. If you are interested in doing in-system
218 software flash programming, find detailed information:
221 \item \url{http://www.openbios.org/development/devbios.html} (/dev/bios)
222 \item \url{http://www.linuxmtd.infradead.org/} (Memory Technology Device Subsystem MTD)
227 \section{LinuxBIOS configuration}
228 The following chapters will cope with configuring LinuxBIOS. All
229 configuration files share some basic rules
232 The default configuration file name in LinuxBIOS is \texttt{Config.lb}.
234 All variables used in a configuration file have to be declared in this
235 file with \texttt{uses VARNAME} before usage.
237 Comments can be added on a new line by using the comment identifier
238 \texttt{\#} at the beginning of the line.
240 LinuxBIOS distinguishes between statements and options. Statements cause
241 the LinuxBIOS configuration mechanism to act, whereas options set
242 variables that are used by the build scripts or source code.
244 Default configuration values can be set in the motherboard configuration
245 files (keyword default)
247 Option overrides to the default configuration can only be specified in
248 the build target configuration file
249 \texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb}
253 \subsection{Common Configuration Statements}
257 \item \begin{verbatim}uses\end{verbatim}
259 All local configuration variables have to be declared before they can be
265 \textbf{NOTE:} Only configuration variables known to the configuration
266 system can be used in configuration files. LinuxBIOS checks
267 \texttt{freebios2/src/config/Options.lb} to see whether a configuration
270 \item \begin{verbatim}default\end{verbatim}
272 The \texttt{default} statement is used to set a configuration variable
273 with an overridable default value. It is commonly used in motherboard
279 default ROM_IMAGE_SIZE=0x10000
282 It is also possible to assign the value of one configuration variable to
286 default FALLBACK_SIZE=ROM_SIZE
289 Also, simple expressions are allowed:
292 default FALLBACK_SIZE=(ROM_SIZE - NORMAL_SIZE)
295 If an option contains a string, this string has to be protected with
299 default CC="gcc m32"
302 \item \begin{verbatim}option\end{verbatim}
304 The \texttt{option} statement basically behaves identically to the
305 \texttt{default} statement. But unlike default it can only be used in
306 build target configuration files
307 (\texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$}). The option
308 statement allows either to set new options or to override default values
309 set with the default statement in a motherboard configuration file.
310 Syntax and application are the same as with default.
314 \subsection{Firmware image specific configuration}
315 LinuxBIOS allows to create different firmware images for the same
316 hardware. Such images can differ in the amount of output they produce,
317 the payload, the number of subimages they consist of etc.
319 The firmware image specific configuration file can be found in
320 \texttt{freebios2/targets/$<$vendor$>$/<motherboard$>$}.
322 \subsubsection{Firmware image specific keywords}
323 In addition to the above described keywords the following statements are
324 available in firmware image specific configuration files:
327 \item \begin{verbatim}romimage\end{verbatim}
329 The \texttt{romimage} definition describes a single rom build within the
330 final LinuxBIOS image. Normally there are two romimage definitions per
331 LinuxBIOS build: \texttt{normal} and \texttt{fallback}.
333 Each \texttt{romimage} section needs to specify a mainboard directory and a
334 payload. The mainboard directory contains the mainboard specific
335 configuration file and source code. It is specified relatively to
336 \texttt{freebios2/src/mainboard}. The payload definition is an absolute
337 path to a static elf binary (i.e Linux kernel or etherboot)
341 option USE_FALLBACK_IMAGE=0
342 option ROM_IMAGE_SIZE=0x10000
343 option LINUXBIOS_EXTRA_VERSION=".0Normal"
345 payload /suse/stepan/tg3ide_
350 \item \begin{verbatim}buildrom\end{verbatim}
352 The \texttt{buildrom} statement is used to determine which of the
353 LinuxBIOS image builds (created using \texttt{romimage}) are packed
354 together to the final LinuxBIOS image. It also specifies the order of
355 the images and the final image size:
358 buildrom ./solo.rom ROM_SIZE "normal" "fallback"
364 \subsubsection{Firmware image configuration options}
365 In addition to the definitions described above there are a number of
366 commonly used options. Configuration options set in the firmware image
367 specific configuration file can override default selections from the
368 Motherboard specific configuration. See above examples about
369 option on how to set them.
373 \item \begin{verbatim}CC\end{verbatim}
375 Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to
376 \texttt{gcc m32} for compiling AMD64 LinuxBIOS images on an AMD64
379 \item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim}
381 Use new \textit{chip\_configure} method for configuring (nonpci)
382 devices. Set to \texttt{1} for all AMD64 motherboards.
384 \item \begin{verbatim}MAXIMUM_CONSOLE_LOGLEVEL\end{verbatim}
386 Errors or log messages up to this level can be printed. Default is
387 \texttt{8}, minimum is \texttt{0}, maximum is \texttt{10}.
389 \item \begin{verbatim}DEFAULT_CONSOLE_LOGLEVEL\end{verbatim}
391 Console will log at this level unless changed. Default is \texttt{7},
392 minimum is \texttt{0}, maximum is \texttt{10}.
394 \item \begin{verbatim}CONFIG_CONSOLE_SERIAL8250\end{verbatim}
396 Log messages to 8250 uart based serial console. Default is \texttt{0}
397 (don't log to serial console). This value should be set to \texttt{1}
398 for all AMD64 builds.
400 \item \begin{verbatim}ROM_SIZE\end{verbatim}
402 Size of final ROM image. This option has no default value.
404 \item \begin{verbatim}FALLBACK_SIZE\end{verbatim}
406 Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:}
407 This does not include the fallback payload.
409 \item \begin{verbatim}HAVE_OPTION_TABLE\end{verbatim}
411 Export CMOS option table. Default is \texttt{0}. Set to \texttt{1} if
412 your motherboard has CMOS memory and you want to use it to store
413 LinuxBIOS parameters (Loglevel, serial line speed, ...)
415 \item \begin{verbatim}CONFIG_ROM_STREAM\end{verbatim}
417 Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_STREAM}, which
418 will boot from an IDE disk)
420 \item \begin{verbatim}HAVE_FALLBACK_BOOT\end{verbatim}
422 Set to \texttt{1} if fallback booting is required. Defaults to
428 The following options should be used within a romimage section:
432 \item \begin{verbatim}USE_FALLBACK_IMAGE\end{verbatim}
434 Set to \texttt{1} to build a fallback image. Defaults to \texttt{0}
436 \item \begin{verbatim}ROM_IMAGE_SIZE\end{verbatim}
438 Default image size. Defaults to \texttt{65535} bytes.
440 \item \begin{verbatim}LINUXBIOS_EXTRA_VERSION\end{verbatim}
442 LinuxBIOS extra version. This option has an empty string as default. Set
443 to any string to add an extra version string to your LinuxBIOS build.
449 \subsection{Motherboard specific configuration}
451 Motherboard specific configuration files describe the onboard
452 motherboard components, i.e. bridges, number and type of CPUs. They also
453 contain rules for building the low level start code which is translated
454 using romcc and/or the GNU assembler. This code enables caches and
455 registers, early mtrr settings, fallback mechanisms, dram init and
458 \textbf{NOTE:} The option keyword can not be used in motherboard specific
459 configuration files. Options shall instead be set using the default
460 keyword so that they can be overridden by the image specific
461 configuration files if needed.
463 \subsubsection{Motherboard specific keywords}
465 The following statements are used in motherboard specific configuration
469 \item \begin{verbatim}arch\end{verbatim}
471 Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.
478 \item \begin{verbatim}cpu\end{verbatim}
480 The cpu statement is needed once per possibly available CPU. In a
481 one-node system, write:
487 \item \begin{verbatim}driver\end{verbatim}
489 The \texttt{driver} keyword adds an object file to the driver section of a
490 LinuxBIOS image. This means it can be used by the PCI device
491 initialization code. Example:
497 \item \begin{verbatim}object\end{verbatim}
499 The \texttt{object} keyword adds an object file to the LinuxBIOS image.
500 Per default the object file will be compiled from a \texttt{.c} file
501 with the same name. Symbols defined in such an object file can be used
502 in other object files and drivers. Example:
508 \item \begin{verbatim}makerule\end{verbatim}
510 This keyword can be used to extend the existing file creation rules
511 during the build process. This is useful if external utilities have to
512 be used for the build. LinuxBIOS on AMD64 uses romcc for it's early
513 startup code placed in auto.c.
515 To tell the configuration mechanism how to build \texttt{romcc} files,
520 depends "$(MAINBOARD)/auto.c"
521 action "$(CPP) I$(TOP)/src $(ROMCCPPFLAGS) $(CPPFLAGS) \
522 $(MAINBOARD)/auto.c > ./auto.E"
525 depends "./auto.E ./romcc"
526 action "./romcc mcpu=k8 O ./auto.E > auto.inc"
530 Each makerule section contains file dependencies (using the depend
531 keyword) and an action that is taken when the dependencies are satisfied
532 (using the action keyword).
534 \item \begin{verbatim}mainboardinit\end{verbatim}
536 With the mainboardinit keyword it's possible to include assembler code
537 directly into the LinuxBIOS image. This is used for early infrastructure
538 initialization, i.e. to switch to protected mode. Example:
541 mainboardinit cpu/i386/entry16.inc
544 \item \begin{verbatim}ldscript\end{verbatim}
546 The GNU linker ld is used to link object files together to a LinuxBIOS
549 Since it is a lot more comfortable and flexible to use the GNU linker
550 with linker scripts (ldscripts) than to create complex command line
551 calls, LinuxBIOS features including linker scripts to control image
555 ldscript /cpu/i386/entry16.lds
559 \item \begin{verbatim}dir\end{verbatim}
561 LinuxBIOS reuses as much code between the different ports as possible.
562 To achieve this, commonly used code can be stored in a seperate
563 directory. For a new motherboard, it is enough to know that the code in
564 that directory can be used as is.
566 LinuxBIOS will also read a \texttt{Config.lb} file stored in that
567 directory. This happens with:
574 \item \begin{verbatim}config\end{verbatim}
576 This keyword is needed by the new chip configuration scheme. Should be
583 \item \begin{verbatim}register\end{verbatim}
584 The \texttt{register} keyword can occur in any section, passing
585 additional parameters to the code handling the according device.
589 register "com1" = "{1, 0, 0x3f8, 4}"
592 \item \begin{verbatim}northbridge\end{verbatim}
594 The \texttt{northbridge} keyword describes a system northbridge. Some
595 systems, like AMD64, can have more than one northbridge, i.e. one per
596 CPU node. Each northbridge is described by the path to the northbridge
597 code in LinuxBIOS (relative to \texttt{freebios2/src/northbridge}), i.e.
598 \texttt{amd/amdk8} and a unique name (i.e ´mc0' ) Example:
601 northbridge amd/amdk8 "mc0"
606 \item \begin{verbatim}southbridge\end{verbatim}
608 To simplify the handling of bus bridges in a LinuxBIOS system, all
609 bridges available in a system that are not northbridges (i.e AGP, IO,
610 PCIX) are seen as southbridges.
612 Since from the CPUs point of view any southbridge is connected via the
613 northbridge, a southbridge section is declared within the northbridge
614 section of the north bridge it is attached to.
616 Like the northbridge, any other bridge is described by the path to it's
617 driver code, and a unique name. If the described bridge is a
618 hypertransport device, the northbridge's hypertransport link it connects
619 to can be specified using the \texttt{link} keyword. Example:
622 northbridge amd/amdk8 "mc0"
624 southbridge amd/amd8111 "amd8111" link 0
631 \item \begin{verbatim}pci\end{verbatim}
633 The \texttt{pci} keyword can only occur within a \texttt{northbridge} or
634 \texttt{southbridge} section. It is used to describe the PCI devices
635 that are provided by the bridge. Generally all bridge sections have a
636 couple of \texttt{pci} keywords.
638 The first occurrence of the \texttt{pci} keyword tells LinuxBIOS where
639 the bridge devices start, relative to the PCI configuration space used
640 by the bridge. The following occurences of the \texttt{pci} keyword
641 describe the provided devices.
643 Adding the option \texttt{on} or \texttt{off} to a PCI device will
644 enable or disable this device. This feature can be used if some bridge
645 devices are not wired to hardware outputs and thus are not used.
650 northbridge amd/amdk8 "mc1"
663 southbridge amd/amd8111 "amd8111" link 0
679 \item \begin{verbatim}superio\end{verbatim}
681 SuperIO devices are basically handled like brigdes. They are taking
682 their driver code from \texttt{freebios2/src/superio/}. They don't
683 provide a PCI compatible configuration interface, but instead are ISA
684 PnP devices. Normally they are connected to a southbridge. If this is
685 the case, the \texttt{superio} section will be a subsection of the
686 \texttt{southbridge} section of the southbridge it is connected to.
690 superio NSC/pc87360 link 1
702 register "com1" = "{1, 0, 0x3f8, 4}"
703 register "lpt" = "{1}"
711 \subsubsection{Motherboard specific configuration options}
713 The following options are commonly used in motherboard specific
716 They should be set using the \texttt{default} keyword:
720 \item \begin{verbatim}HAVE_HARD_RESET\end{verbatim}
722 If set to \texttt{1}, this option defines that there is a hard reset
723 function for this mainboard. This option is not defined per default.
725 \item \begin{verbatim}HAVE_PIRQ_TABLE\end{verbatim}
727 If set to \texttt{1}, this option defines that there is an IRQ Table for
728 this mainboard. This option is not defined per default.
730 \item \begin{verbatim}IRQ_SLOT_COUNT\end{verbatim}
732 Number of IRQ slots. This option is not defined per default.
734 \item \begin{verbatim}HAVE_MP_TABLE\end{verbatim}
736 Define this option to build an MP table (v1.4). The default is not to
739 \item \begin{verbatim}HAVE_OPTION_TABLE\end{verbatim}
741 Define this option to export a CMOS option table. The default is not to
742 export a CMOS option table.
744 \item \begin{verbatim}CONFIG_SMP\end{verbatim}
746 Set this option to \texttt{1} if the mainboard supports symmetric
747 multiprocessing (SMP). This option defaults to \texttt{0} (no SMP).
749 \item \begin{verbatim}CONFIG_MAX_CPUS\end{verbatim}
751 If \begin{verbatim}CONFIG_SMP\end{verbatim} is set, this option defines
752 the maximum number of CPUs (i.e. the number of CPU sockets) in the
753 system. Defaults to \texttt{1}.
755 \item \begin{verbatim}CONFIG_IOAPIC\end{verbatim}
757 Set this option to \texttt{1} to enable IOAPIC support. This is
758 mandatory if you want to boot a 64bit Linux kernel on an AMD64 system.
760 \item \begin{verbatim}STACK_SIZE\end{verbatim}
762 LinuxBIOS stack size. The size of the function call stack defaults to
763 \texttt{0x2000} (8k).
765 \item \begin{verbatim}HEAP_SIZE\end{verbatim}
767 LinuxBIOS heap size. The heap is used when LinuxBIOS allocates memory
768 with malloc(). The default heap size is \texttt{0x2000}, but AMD64 boards
769 generally set it to \texttt{0x4000} (16k)
771 \item \begin{verbatim}XIP_ROM_BASE\end{verbatim}
773 Start address of area to cache during LinuxBIOS execution directly from
776 \item \begin{verbatim}XIP_ROM_SIZE\end{verbatim}
778 Size of area to cache during LinuxBIOS execution directly from ROM
780 \item \begin{verbatim}CONFIG_COMPRESS\end{verbatim}
782 Set this option to \texttt{1} for a compressed image. If set to
783 \texttt{0}, the image is bigger but will start slightly faster (since no
784 decompression is needed).
791 % 9. Tweaking the source code
793 \section{Tweaking the source code}
794 Besides configuring the existing code it is sometimes necessary or
795 wished to tweak certain parts of LinuxBIOS by direct changes to the
796 code. This chapter covers some possible enhancements and changes that
797 are needed when porting LinuxBIOS to a new motherboard or just come
800 \subsection{Hypertransport configuration}
801 Before LinuxBIOS is able to activate all CPUs and detect bridges
802 attached to these CPUs (and thus, see all devices attached to the
803 system) it has to initialize the coherent hypertransport devices.
805 The current algorithms to do coherent hypertransport initialization are
806 not fully automatically evaluating the hypertransport chain graph.
807 Therefore the code needs to be adapted when porting LinuxBIOS to a new
808 AMD64 motherboard. An example arrangement of hypertransport devices
813 \includegraphics[scale=1.0]{hypertransport.pdf}
814 \caption{Example: Hypertransport Link Connections}
815 \label{fix:hypertransport}
818 Each hypertransport device has one to three hypertransport links that
819 are used for device interconnection. These links are called LDT$[$012$]$, or
820 accordingly UP, ACROSS, DOWN. Communication between the hypertransport
821 devices can be freely routed, honoring the physical wiring. Teaching the
822 coherent hypertransport initialization algorithm this wiring happens in
828 \item Setting outgoing connections
829 The algorithm needs to know which outgoing port of a CPU node is
830 connected to the directly succeeding node. This is done in
831 \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/auto.c}
832 with a number of preprocessor defines (one define for two-node systems,
833 three defines for four-node systems).
835 The ports in question are flagged with a circle in the graph for
836 illustration. For the example graph above (all outgoing connections are
837 realized using LDT1/ACROSS) the defines are:
840 #define CONNECTION_0_1 ACROSS
841 #define CONNECTION_0_2 ACROSS
842 #define CONNECTION_1_3 ACROSS
845 \item Describing routing information between CPUs.
847 There are basically three different message types for hypertransport
850 \item request packages
851 \item response packages
852 \item broadcast packages
855 These three message types are routed using different hypertransport
856 ports. The routing information is written to the AMD K8 routing table.
857 In an Nnode system this routing table consists of 3*N*N entries , one
858 for each message type and for each possible CPU --> CPU communication. For
859 simplicity LinuxBIOS keeps the 3 routing entries for each CPU --> CPU
860 communication in one machine word. The routing table of each node looks
864 /* Routing Table for Node i
866 * F0: 0x40, 0x44, 0x48, 0x4c, 0x50, 0x54, 0x58, 0x5c
867 * i: 0, 1, 2, 3, 4, 5, 6, 7
869 * [ 0: 3] Request Route
870 * [0] Route to this node
871 * [1] Route to Link 0
872 * [2] Route to Link 1
873 * [3] Route to Link 2
874 * [11: 8] Response Route
875 * [0] Route to this node
876 * [1] Route to Link 0
877 * [2] Route to Link 1
878 * [3] Route to Link 2
879 * [19:16] Broadcast route
880 * [0] Route to this node
881 * [1] Route to Link 0
882 * [2] Route to Link 1
883 * [3] Route to Link 2
887 The routing table is passed to the coherent hypertransport
888 initialization algorithm by defining a function called
889 \texttt{generate\_row()} in \texttt{auto.c}:
892 static unsigned int generate_row
893 (uint8_t node, uint8_t row, uint8_t maxnodes)
896 This function is trivial if there is only one CPU in the system, since
897 no routing has to be done:
900 static unsigned int generate_row
901 (uint8_t node, uint8_t row, uint8_t maxnodes)
903 return 0x00010101; /* default row entry */
907 On a two-node system things look slightly more complicated. Since the
908 coherent hypertransport initialization algorithm works by consecutively
909 enabling CPUs, it contains routing information for driving the system
910 with one node and two nodes:
913 static unsigned int generate_row
914 (uint8_t node, uint8_t row, uint8_t maxnodes)
916 uint32_t ret=0x00010101; /* default row entry */
917 static const unsigned int rows_2p[2][2] = {
918 { 0x00050101, 0x00010404 },
919 { 0x00010404, 0x00050101 }
921 if(maxnodes>2) maxnodes=2;
922 if (!(node>=maxnodes || row>=maxnodes)) {
923 ret=rows_2p[node][row];
929 Systems with four nodes have to contain routing information for one, two
930 and four-node setups:
933 static unsigned int generate_row
934 (uint8_t node, uint8_t row, uint8_t maxnodes)
936 uint32_t ret=0x00010101; /* default row entry */
937 static const unsigned int rows_2p[2][2] = {
938 { 0x00030101, 0x00010202 },
939 { 0x00010202, 0x00030101 }
941 static const unsigned int rows_4p[4][4] = {
942 { 0x00070101, 0x00010202, 0x00030404, 0x00010204 },
943 { 0x00010202, 0x000b0101, 0x00010208, 0x00030808 },
944 { 0x00030808, 0x00010208, 0x000b0101, 0x00010202 },
945 { 0x00010204, 0x00030404, 0x00010202, 0x00070101 }
947 if (!(node>=maxnodes || row>=maxnodes)) {
949 ret=rows_2p[node][row];
951 ret=rows_4p[node][row];
958 \subsection{DRAM configuration}
959 Setting up the RAM controller(s) is probably the most complex part of
960 LinuxBIOS. Basically LinuxBIOS serially initializes all RAM controllers
961 in the system, using SPDROM (serial presence detect) data to set
962 timings, size and other properties. The SPD data is usually read
963 utilizing the I2C SMBUS interface of the southbridge.
965 There is one central data structure that describes the RAM controllers
966 available on an AMD64 system and the concerned devices:
969 struct mem_controller {
971 device_t f0, f1, f2, f3;
977 Available motherboard implementations and CPUs create the need to add
978 special setup code to RAM initialization in a number of places.
979 LinuxBIOS provides hooks to easily add code in these places without
980 having to change the generic code. Whether these hooks have to be used
981 depends on the motherboard design. In many cases the functions executed
982 by the hooks just carry out trivial default settings or they are even
985 Some motherboard/CPU combinations need to trigger an additional memory
986 controller reset before the memory can be initialized properly. This is,
987 for example, used to get memory working on preC stepping AMD64
988 processors. LinuxBIOS provides two hooks for triggering onboard memory
992 \item \begin{verbatim}static void memreset_setup(void)\end{verbatim}
993 \item \begin{verbatim}static void memreset(int controllers, const struct
994 mem_controller *ctrl)\end{verbatim}
997 Some motherboards utilize an SMBUS hub or possibly other mechanisms to
998 allow using a large number of SPDROMs and thus ram sockets. The result
999 is that only the SPDROM information of one cpu node is visible at a
1000 time. The following function, defined in \texttt{auto.c}, is called every time
1001 before a memory controller is initialized and gets the memory controller
1002 information of the next controller as a parameter:
1005 static inline void activate_spd_rom (const struct mem_controller *ctrl)
1008 The way SMBUS hub information is coded into the \texttt{mem\_controller}
1009 structure is motherboard implementation specific and not closer
1010 described here. See \texttt{freebios2/src/mainboard/amd/quartet/auto.c}
1013 LinuxBIOS folks have agreed on SPD data being the central information
1014 source for RAM specific information. But not all motherboards/RAM
1015 modules feature a physical SPD ROM. To still allow an easytouse SPD
1016 driven setup, there is a hook that abstracts reading the SPD ROM
1017 ingredients that are used by the memory initialization mechanism:
1020 static inline int spd_read_byte(unsigned device, unsigned address)
1023 This function, defined in \texttt{auto.c}, directly maps it's calls to
1024 \texttt{smbus\_read\_byte()} calls if SPD ROM information is read via
1028 static inline int spd_read_byte(unsigned device, unsigned address)
1030 return smbus_read_byte(device & 0xff, address);
1034 If there is no SPD ROM available in the system design, this function
1035 keeps an array of SPD ROM information hard coded per logical RAM module.
1036 It returns the ´faked' SPD ROM information using device and address
1037 as indices to this array.
1040 \subsection {IRQ Tables}
1042 Motherboards that provide an IRQ table should have the following two
1043 variables set in their \texttt{Config.lb} file:
1046 default HAVE_PIRQ_TABLE=1
1047 default IRQ_SLOT_COUNT=7
1050 This will make LinuxBIOS look for the file
1051 \texttt{freebios2/src/mainboard/<vendor>/<motherboard>/irq\_tables.c} which
1052 contains the source code definition of the IRQ table. LinuxBIOS corrects
1053 small inconsistencies in the IRQ table during startup (checksum and
1054 number of entries), but it is not yet writing IRQ tables in a completely
1057 \textbf{NOTE:} To get Linux to understand and actually use the IRQ
1058 table, it is not always a good idea to specify the vendor and device id
1059 of the actually present interrupt router device. Linux 2.4 for example
1060 does not know about the interrupt router of the AMD8111 southbridge. In
1061 such cases it is advised to choose the vendor/device id of a compatible
1062 device that is supported by the Linux kernel. In case of the AMD8111
1063 interrupt router it is advised to specify the AMD768/Opus interrupt
1064 controller instead (vendor id=\texttt{0x1022}, device id=\texttt{0x7443})
1066 \subsection {MP Tables}
1068 LinuxBIOS contains code to create MP tables conforming the
1069 Multiprocessor Specification V1.4. To include an MP Table in a LinuxBIOS
1070 image, the following configuration variables have to be set (in the
1071 mainboard specific configuration file
1072 \texttt{freebios2/src/mainboard/<vendor><mainboard>/Config.lb}):
1075 default CONFIG_SMP=1
1076 default CONFIG_MAX_CPUS=1 # 2,4,..
1077 default HAVE_MP_TABLE=1
1080 LinuxBIOS will then look for a function for setting up the MP table in
1081 the file \texttt{freebios2/src/mainboard<vendor>/<mainboard>/mptable.c}:
1084 void *smp_write_config_table(void *v, unsigned long * processor_map)
1087 MP Table generation is still somewhat static, i.e. changing the bus
1088 numbering will force
1089 you to adopt the code in mptable.c. This is subject to change in future
1093 LinuxBIOS has three different methods of handling POST codes. They can
1094 be triggered using configuration file options.
1097 \emph{Ignore POST completely}. No early code debugging is possible with
1098 this setting. Set the configuration variable \texttt{NO\_POST} to
1099 \texttt{1} to switch off all POST handling in LinuxBIOS.
1101 \emph{Normal IO port 80 POST}. This is the default behavior of
1102 LinuxBIOS. No configuration variables have to be set. To be able to see
1103 port 80 POST output, you need a POST expansion card for ISA or PCI. Port
1104 80 POST allows simple debugging without any other output method
1105 available (serial interface or VGA display)
1108 This option allows to push POST messages to the serial interface instead
1109 of using IO ports. \textbf{NOTE:} The serial interface has to be
1110 initialized before serial POST can work. To use serial POST, set the
1111 configuration variable \texttt{CONFIG\_SERIAL\_POST} to the value 1.
1115 \subsection{HDT Debugging}
1116 If you are debugging your LinuxBIOS code with a Hardware Debug Tool
1117 (HDT), you can find the source code line for a given physical EIP
1118 address as follows: Look the address up in the file linuxbios.map. Then
1119 search the label Lxx in the file auto.inc created by romcc. The original
1120 source code file and line number is mentioned in auto.inc.
1123 \subsection{Device Drivers}
1124 With only a few data structures LinuxBIOS features a simple but flexible
1125 device driver interface. This interface is not intended for autonomously
1126 driving the devices but to initialize all system components so that they
1127 can be used by the booted operating system.
1129 Since nowadays most systems are PCI centric, the data structures used
1130 are tuned towards (onboard and expansion bus) PCI devices. Each driver
1131 consists of at least two structures.
1133 The \texttt{pci\_driver} structure maps PCI vendor/device id pairs to a
1134 second structure that describes a set of functions that together
1135 initialize and operate the device:
1138 static void adaptec_scsi_init(struct device *dev)
1142 static struct device_operations lsi_scsi_ops = {
1143 .read_resources = pci_dev_read_resources,
1144 .set_resources = pci_dev_set_resources,
1145 .enable_resources = pci_dev_enable_resources,
1146 .init = lsi_scsi_init,
1149 static struct pci_driver lsi_scsi_driver __pci_driver = {
1150 .ops = &lsi_scsi_ops,
1156 By separating the two structures above, M:N relations between compatible
1157 devices and drivers can be described. The driver source code containing
1158 above data structures and code have to be added to a LinuxBIOS image
1159 using the driver keyword in the motherboard specific configuration file
1160 \texttt{freebios2/src/mainboard/<vendor>/<mainboard>/Config.lb}:
1166 \subsection{Bus Bridges}
1168 Currently all bridges supported in the LinuxBIOS2 tree are transparent
1169 bridges. This means, once the bridge is initialized, it's remote devices
1170 are visible on one of the PCI buses without special probing. LinuxBIOS
1171 supports also bridges that are nontransparent. The driver support code
1172 can provide a \texttt{scan\_bus} function to scan devices behind the bridge.
1174 \subsection{CPU Reset}
1175 When changing speed and width of hypertransport chain connections
1176 LinuxBIOS has to either assert an LDTSTOP or a reset to make the changes
1177 become active. Additionally Linux can do a firmware reset, if LinuxBIOS
1178 provides the needed infrastructure. To use this capability, define the
1179 option \texttt{HAVE\_HARD\_RESET} and add an object file specifying the
1180 reset code in your mainboard specific configuration file
1181 \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/Config.lb}:
1184 default HAVE_HARD_RESET=1
1188 The C source file \texttt{reset.c} (resulting in \texttt{reset.o}
1189 during compilation) shall define the following function to take care
1190 of the system reset:
1193 void hard_reset(void);
1196 See \texttt{freebios2/src/mainboard/arima/hdama/reset.c} for an example
1202 % 10. LinuxBIOS Internals
1205 \section{LinuxBIOS Internals}
1206 This chapter covers some of the internal structures and algorithms of
1207 LinuxBIOS that have not been mentioned so far.
1209 \subsection{Code Flow}
1213 \includegraphics[scale=0.7]{codeflow.pdf}
1214 \caption{LinuxBIOS rough Code Flow}
1215 \label{fix:codeflow}
1220 \subsection{Fallback mechanism}
1221 LinuxBIOS provides a mechanism to pack two different LinuxBIOS builds
1222 within one LinuxBIOS ROM image. Using the system CMOS memory LinuxBIOS
1223 determines whether the last boot with a default image succeeded and
1224 boots a failsafe image on failure. This allows insystem testing without
1225 the risk to render the system unusable. See
1226 \texttt{freebios2/src/mainboard/arima/hdama/failover.c} for example
1227 code. The fallback mechanism can be used with the \texttt{cmos\_util}.
1229 \subsection{(Un) Supported Standards}
1230 LinuxBIOS supports the following standards
1232 \item Multiprocessing Specification (MPSPEC) 1.4
1236 However, the following standards are not supported until now, and will
1237 probably not be supported in future revisions:
1243 \subsection{LinuxBIOS table}
1244 LinuxBIOS stores information about the system in a data structure called
1245 the LinuxBIOS table. This table can be read under Linux using the tool
1246 lxbios from the Lawrence Livermore National Laboratory.
1248 Get more information about lxbios and the utility itself at
1249 \url{http://www.llnl.gov/linux/lxbios/lxbios.html}
1251 \subsection{ROMCC limitations}
1252 ROMCC, part of the LinuxBIOS project, is a C compiler that translates to
1253 completely rommable code. This means the resulting code does not need
1254 any memory to work. This is one of the major improvements in LinuxBIOS
1255 V2, since it allows almost all code to be written in C. DRAM
1256 initialization can be factored and reused more easily among mainboards
1259 Since no memory is available during this early initialization point,
1260 romcc has to map all used variables in registers for their time being.
1261 Same applies for their stack usage. Generally the less registers are
1262 used up by the algorithms, the better code can be factored, resulting in
1263 a smaller object size. Since getting the best register usage is an NP
1264 hard problem, some heuristics are used to get reasonable translation
1265 time. If you run out of registers during compilation, try to refactor
1268 \subsection{CMOS handling}
1269 LinuxBIOS can use the motherboard's CMOS memory to store information
1270 defined in a data structure called the CMOS table . This information
1271 contains serial line speed, fallback boot control, output verbosity,
1272 default boot device, ECC control, and more. It can be easily enhanced by
1273 enhancing the CMOS table. This table, if present, is found at
1274 \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/cmos.layout}.
1275 It describes the available options, their possible values and their
1276 position within the CMOS memory. The layout file looks as follows:
1278 # startbit length config configID name
1283 # configid value human readable description
1295 To change CMOS values from a running Linux system, use the
1296 \texttt{cmos\_util}, provided by Linux Networks as part of the LinuxBIOS
1297 utilities suite. Get it at
1298 \textit{ftp://ftp.lnxi.com/pub/linuxbios/utilities/}
1300 \subsection {Booting Payloads}
1301 LinuxBIOS can load a payload binary from a Flash device or IDE. This
1302 payload can be a boot loader, like FILO or Etherboot, a kernel image, or
1303 any other static ELF binary.
1305 To create a Linux kernel image, that is bootable in LinuxBIOS, you have
1306 to use mkelfImage. The command line I used, looks like follows:
1309 objdir/sbin/mkelfImage t bzImagei386 kernel /boot/vmlinuz \
1310 commandline="console=ttyS0,115200 root=/dev/hda3" \
1311 initrd=/boot/initrd output vmlinuz.elf
1315 This will create the file \texttt{vmlinuz.elf} from a distribution
1316 kernel, console redirected to the serial port and using an initial
1319 \subsection{Kernel on dhcp/tftp}
1321 One possible scenario during testing is that you keep your kernel (or
1322 any additional payload) on a different machine on the network. This can
1323 quickly be done using a DHCP and TFTP server.
1325 Use for example following \texttt{/etc/dhcpd.conf} (adapt to your
1329 subnet 192.168.1.0 netmask 255.255.255.0 {
1330 range 192.168.1.0 192.168.1.31;
1331 option broadcastaddress 192.168.1.255;
1334 ddnsupdatestyle adhoc;
1337 hardware ethernet 00:04:76:EA:64:31;
1338 fixedaddress 192.168.1.24;
1339 filename "vmlinuz.elf";
1344 Additionally you have to run a \texttt{tftp} server. You can start one
1345 using \texttt{inetd}. To do this, you have to remove the comment from
1346 the following line in \texttt{/etc/inetd.conf}:
1349 tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot
1352 Then put your kernel image \texttt{vmlinuz.elf} to \texttt{/tftpboot} on
1353 the \texttt{tftp} server.
1366 LinuxBIOS only cares about lowlevel machine initialization, but also has
1367 very simple mechanisms to boot a file either from FLASHROM or IDE. That
1368 file, possibly a Linux Kernel, a boot loader or Etherboot, are called
1369 payload, since it is the first software executed that does not cope with
1370 pure initialization.
1374 Flash devices are commonly used in all different computers since unlike
1375 ROMs they can be electronically erased and reprogrammed.
1384 \section{Bibliography}
1385 \subsection{Additional Papers on LinuxBIOS}
1389 \textit{\url{http://www.linuxnetworx.com/products/linuxbios_white_paper.pdf}}
1392 \textit{\url{http://www.linuxbios.org/papers/}}
1394 \textit{\url{http://www.lysator.liu.se/upplysning/fa/linuxbios.pdf}}
1396 \textit{\url{http://portal.acm.org/citation.cfm?id=512627}}
1402 \item Etherboot: \textit{\url{http://www.etherboot.org/}}
1403 \item Filo: \textit{\url{http://te.to/~ts1/filo/}}
1404 \item OpenBIOS: \textit{\url{http://www.openbios.org/}}