\title{LinuxBIOS on AMD64}
\author{Stefan Reinauer $<$stepan@openbios.org$>$}
-\date{November 18, 2003}
+\date{June 2nd, 2004}
\begin{document}
\section{Abstract}
-This document targets porting LinuxBIOS to new Motherboards and creating
+This document targets porting LinuxBIOS to new mainboards and creating
custom firmware images using LinuxBIOS. It describes how to build
LinuxBIOS images for the AMD64 platform, including hypertransport
configuration and pertinent utilities. If you are missing information or
%
-% 2 What is LinuxBIOS
+% 2 Changes
+%
+
+\section{Changes}
+ \begin{itemize}
+ \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$
+ \item 2004/02/10 acpi and option rom updates
+ \item 2003/11/18 initial release
+ \end{itemize}
+
+
+
+%
+% 3 What is LinuxBIOS
%
\section{What is LinuxBIOS?}
Desktop PCs and Servers.
%
-% 3 Build Requirements
+% 4 Build Requirements
%
\section{Build Requirements}
\newpage
%
-% 4 Getting the Sources
+% 5 Getting the Sources
%
\section{Getting the Sources}
The latest LinuxBIOS sources are available via CVS. The CVS repository
-is maintained at SourceForge.net (the project name is \emph{FreeBIOS}). You
-can get the entire source tree via CVS:
+is maintained at SourceForge.net (the project name is \emph{FreeBIOS}).
+First you should create a directory for your LinuxBIOS trees:
+
+{ \small
+\begin{verbatim}
+$ mkdir linuxbios
+$ cd linuxbios
+\end{verbatim}
+}
+
+You can get the entire source tree via CVS:
{ \small
\begin{verbatim}
-% cvs -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios login
+$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freebios login
\end{verbatim}
}
{ \small
\begin{verbatim}
-% cvs -z3 -d:pserver:anonymous@cvs.freebios.sourceforge.net:/cvsroot/freebios co freebios2
+$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freebios co freebios2
\end{verbatim}
}
{ \small
\begin{verbatim}
-% cvs update Pd
+% cvs update -Pd
\end{verbatim}
}
LinuxBIOS 1.0 tree.
%
-% 5 LinuxBIOS configuration overview
+% 6 LinuxBIOS configuration overview
%
\section{LinuxBIOS configuration overview}
\item
Firmware image specific configuration options can be set in the image
configuration file which is usually found in
-\texttt{freebios2/targets/$<$vendor$>$/$<$motherboard$>$/}. Such
+\texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$/}. Such
options are the default amount of output verbosity during bootup, image
size, use of fallback mechanisms, firmware image size and payloads
(Linux Kernel, Bootloader...) The default configuration file name is
\texttt{Config.lb}, but LinuxBIOS allows multiple configurations to
reside in that directory.
-\item Motherboard specific configuration options can be set in the
-motherboard configuration file placed in
-\texttt{freebios2/src/mainboard/$<$vendor$>$/$<$motherboard$>$}. The
-motherboard configuration file is always called \texttt{Config.lb}. It
-contains information on the onboard components of the motherboard like
+\item Mainboard specific configuration options can be set in the
+mainboard configuration file placed in
+\texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$}. The
+mainboard configuration file is always called \texttt{Config.lb}. It
+contains information on the onboard components of the mainboard like
CPU type, northbridge, southbridge, hypertransport configuration and
SuperIO configuration. This configuration file also allows to include
addon code to hook into the LinuxBIOS initialization mechanism at
This document describes different approaches of changing and configuring the
LinuxBIOS source tree when building for AMD64.
+%
+% 7 Building LinuxBIOS
+%
+
\section{Building LinuxBIOS}
One of the design goals for building LinuxBIOS was to keep object files
-out of the source tree in a seperate place. This is mandatory for
-building parallel LinuxBIOS images for several distinct motherboards
+out of the source tree in a separate place. This is mandatory for
+building parallel LinuxBIOS images for several distinct mainboards
and/or platforms. Therefore building LinuxBIOS consists of two steps:
\begin{itemize}
\item
The first of these two steps is accomplished by the \texttt{buildtarget}
script found in \texttt{freebios2/targets/}. To build LinuxBIOS for
-instance for the AMD Solo Athlon64 motherboard enter:
+instance for the AMD Solo Athlon64 mainboard enter:
\begin{verbatim}
% cd freebios2/targets
This will create a directory containing a Makefile and other software
components needed for this build. The directory name is defined in the
firmware image specific configuration file. In the case of AMD's Solo
-motherboard the default directory resides in
+mainboard the default directory resides in
\texttt{freebios2/targets/amd/solo/solo}. To build the LinuxBIOS image, do
\begin{verbatim}
\end{verbatim}
The LinuxBIOS image filename is specified in the firmware image specific
-configuration file. The default filename for AMD's Solo motherboard is
+configuration file. The default filename for AMD's Solo mainboard is
\texttt{solo.rom}.
+%
+% 8 Programming LinuxBIOS to flash memory
+%
+
\section{Programming LinuxBIOS to flash memory}
The image resulting from a LinuxBIOS build can be directly programmed to
a flash device, either using a hardware flash programmer or by using the
\begin{itemize}
\item \url{http://www.openbios.org/development/devbios.html} (/dev/bios)
-\item \url{http://www.linuxmtd.infradead.org/} (Memory Technology Device Subsystem MTD)
+\item \url{http://www.linux-mtd.infradead.org/} (Memory Technology Device Subsystem MTD)
\end{itemize}
\newpage
+%
+% 9 LinuxBIOS configuration
+%
+
\section{LinuxBIOS configuration}
The following chapters will cope with configuring LinuxBIOS. All
configuration files share some basic rules
the LinuxBIOS configuration mechanism to act, whereas options set
variables that are used by the build scripts or source code.
\item
-Default configuration values can be set in the motherboard configuration
+Default configuration values can be set in the mainboard configuration
files (keyword default)
\item
Option overrides to the default configuration can only be specified in
\item \begin{verbatim}default\end{verbatim}
The \texttt{default} statement is used to set a configuration variable
-with an overridable default value. It is commonly used in motherboard
+with an overridable default value. It is commonly used in mainboard
configuration files.
Example:
quotation marks:
\begin{verbatim}
- default CC="gcc m32"
+ default CC="gcc -m32"
\end{verbatim}
\item \begin{verbatim}option\end{verbatim}
build target configuration files
(\texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$}). The option
statement allows either to set new options or to override default values
-set with the default statement in a motherboard configuration file.
+set with the default statement in a mainboard configuration file.
Syntax and application are the same as with default.
\end{itemize}
hardware. Such images can differ in the amount of output they produce,
the payload, the number of subimages they consist of etc.
-The firmware image specific configuration file can be found in
-\texttt{freebios2/targets/$<$vendor$>$/<motherboard$>$}.
+The firmware image specific configuration file can be found in \\
+\texttt{freebios2/targets/$<$vendor$>$/<mainboard$>$}.
\subsubsection{Firmware image specific keywords}
In addition to the above described keywords the following statements are
romimage "normal"
option USE_FALLBACK_IMAGE=0
option ROM_IMAGE_SIZE=0x10000
- option LINUXBIOS_EXTRA_VERSION=".0Normal"
+ option COREBOOT_EXTRA_VERSION=".0Normal"
mainboard amd/solo
payload /suse/stepan/tg3ide_
disk.zelf
In addition to the definitions described above there are a number of
commonly used options. Configuration options set in the firmware image
specific configuration file can override default selections from the
-Motherboard specific configuration. See above examples about
+Mainboard specific configuration. See above examples about
option on how to set them.
\begin{itemize}
\item \begin{verbatim}CC\end{verbatim}
Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to
-\texttt{gcc m32} for compiling AMD64 LinuxBIOS images on an AMD64
+\texttt{gcc -m32} for compiling AMD64 LinuxBIOS images on an AMD64
machine.
\item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim}
Use new \textit{chip\_configure} method for configuring (nonpci)
-devices. Set to \texttt{1} for all AMD64 motherboards.
+devices. Set to \texttt{1} for all AMD64 mainboards.
\item \begin{verbatim}MAXIMUM_CONSOLE_LOGLEVEL\end{verbatim}
\item \begin{verbatim}HAVE_OPTION_TABLE\end{verbatim}
Export CMOS option table. Default is \texttt{0}. Set to \texttt{1} if
-your motherboard has CMOS memory and you want to use it to store
+your mainboard has CMOS memory and you want to use it to store
LinuxBIOS parameters (Loglevel, serial line speed, ...)
-\item \begin{verbatim}CONFIG_ROM_STREAM\end{verbatim}
+\item \begin{verbatim}CONFIG_ROM_PAYLOAD\end{verbatim}
-Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_STREAM}, which
+Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_PAYLOAD}, which
will boot from an IDE disk)
\item \begin{verbatim}HAVE_FALLBACK_BOOT\end{verbatim}
Default image size. Defaults to \texttt{65535} bytes.
-\item \begin{verbatim}LINUXBIOS_EXTRA_VERSION\end{verbatim}
+\item \begin{verbatim}COREBOOT_EXTRA_VERSION\end{verbatim}
LinuxBIOS extra version. This option has an empty string as default. Set
to any string to add an extra version string to your LinuxBIOS build.
\newpage
-\subsection{Motherboard specific configuration}
+\subsection{Mainboard specific configuration}
-Motherboard specific configuration files describe the onboard
-motherboard components, i.e. bridges, number and type of CPUs. They also
+Mainboard specific configuration files describe the onboard
+mainboard components, i.e. bridges, number and type of CPUs. They also
contain rules for building the low level start code which is translated
using romcc and/or the GNU assembler. This code enables caches and
registers, early mtrr settings, fallback mechanisms, dram init and
possibly more.
-\textbf{NOTE:} The option keyword can not be used in motherboard specific
-configuration files. Options shall instead be set using the default
-keyword so that they can be overridden by the image specific
-configuration files if needed.
+\textbf{NOTE:} The \texttt{option} keyword can not be used in mainboard
+specific configuration files. Options shall instead be set using the
+\texttt{default} keyword so that they can be overridden by the image
+specific configuration files if needed.
-\subsubsection{Motherboard specific keywords}
+\subsubsection{Mainboard specific keywords}
-The following statements are used in motherboard specific configuration
+The following statements are used in mainboard specific configuration
files:
\begin{itemize}
\item \begin{verbatim}arch\end{verbatim}
-Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.
+Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.\\
Example:
\begin{verbatim}
\begin{verbatim}
makerule ./auto.E
- depends "$(MAINBOARD)/auto.c"
- action "$(CPP) I$(TOP)/src $(ROMCCPPFLAGS) $(CPPFLAGS) \
- $(MAINBOARD)/auto.c > ./auto.E"
+ depends "$(MAINBOARD)/auto.c option_table.h ./romcc"
+ action "./romcc -E -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \
+ $(MAINBOARD)/auto.c -o $@"
end
makerule ./auto.inc
- depends "./auto.E ./romcc"
- action "./romcc mcpu=k8 O ./auto.E > auto.inc"
+ depends "$(MAINBOARD)/auto.c option_table.h ./romcc"
+ action "./romcc -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \
+ $(MAINBOARD)/auto.c -o $@"
end
\end{verbatim}
-Each makerule section contains file dependencies (using the depend
-keyword) and an action that is taken when the dependencies are satisfied
-(using the action keyword).
+Each \texttt{makerule} section contains file dependencies (using the
+texttt{depends} keyword) and an action that is taken when the dependencies
+are satisfied (using the \texttt{action} keyword).
\item \begin{verbatim}mainboardinit\end{verbatim}
\item \begin{verbatim}dir\end{verbatim}
LinuxBIOS reuses as much code between the different ports as possible.
-To achieve this, commonly used code can be stored in a seperate
-directory. For a new motherboard, it is enough to know that the code in
+To achieve this, commonly used code can be stored in a separate
+directory. For a new mainboard, it is enough to know that the code in
that directory can be used as is.
LinuxBIOS will also read a \texttt{Config.lb} file stored in that
\item \begin{verbatim}register\end{verbatim}
The \texttt{register} keyword can occur in any section, passing
-additional parameters to the code handling the according device.
+additional \\
+parameters to the code handling the associated device.
Example:
\begin{verbatim}
systems, like AMD64, can have more than one northbridge, i.e. one per
CPU node. Each northbridge is described by the path to the northbridge
code in LinuxBIOS (relative to \texttt{freebios2/src/northbridge}), i.e.
-\texttt{amd/amdk8} and a unique name (i.e ´mc0' ) Example:
+\texttt{amd/amdk8} and a unique name (i.e \texttt{mc0}) \\
+Example:
\begin{verbatim}
northbridge amd/amdk8 "mc0"
Example:
\begin{verbatim}
-superio NSC/pc87360 link 1
+superio nsc/pc87360 link 1
pnp 2e.0
pnp 2e.1
pnp 2e.2
\newpage
-\subsubsection{Motherboard specific configuration options}
+\subsubsection{Mainboard specific configuration options}
-The following options are commonly used in motherboard specific
+The following options are commonly used in mainboard specific
configuration files.
They should be set using the \texttt{default} keyword:
\newpage
+
%
-% 9. Tweaking the source code
+% 10. Tweaking the source code
%
+
\section{Tweaking the source code}
Besides configuring the existing code it is sometimes necessary or
-wished to tweak certain parts of LinuxBIOS by direct changes to the
+desirable to tweak certain parts of LinuxBIOS by direct changes to the
code. This chapter covers some possible enhancements and changes that
-are needed when porting LinuxBIOS to a new motherboard or just come
+are needed when porting LinuxBIOS to a new mainboard or just come
handy now and then.
\subsection{Hypertransport configuration}
system) it has to initialize the coherent hypertransport devices.
The current algorithms to do coherent hypertransport initialization are
-not fully automatically evaluating the hypertransport chain graph.
+not fully, automatically evaluating the hypertransport chain graph.
Therefore the code needs to be adapted when porting LinuxBIOS to a new
-AMD64 motherboard. An example arrangement of hypertransport devices
+AMD64 mainboard. An example arrangement of hypertransport devices
looks like this:
\begin{figure}[htb]
utilizing the I2C SMBUS interface of the southbridge.
There is one central data structure that describes the RAM controllers
-available on an AMD64 system and the concerned devices:
+available on an AMD64 system and the associated devices:
\begin{verbatim}
struct mem_controller {
};
\end{verbatim}
-Available motherboard implementations and CPUs create the need to add
+Available mainboard implementations and CPUs create the need to add
special setup code to RAM initialization in a number of places.
LinuxBIOS provides hooks to easily add code in these places without
having to change the generic code. Whether these hooks have to be used
-depends on the motherboard design. In many cases the functions executed
+depends on the mainboard design. In many cases the functions executed
by the hooks just carry out trivial default settings or they are even
empty.
-Some motherboard/CPU combinations need to trigger an additional memory
+Some mainboard/CPU combinations need to trigger an additional memory
controller reset before the memory can be initialized properly. This is,
for example, used to get memory working on preC stepping AMD64
processors. LinuxBIOS provides two hooks for triggering onboard memory
mem_controller *ctrl)\end{verbatim}
\end{itemize}
-Some motherboards utilize an SMBUS hub or possibly other mechanisms to
+Some mainboards utilize an SMBUS hub or possibly other mechanisms to
allow using a large number of SPDROMs and thus ram sockets. The result
is that only the SPDROM information of one cpu node is visible at a
time. The following function, defined in \texttt{auto.c}, is called every time
\end{verbatim}
The way SMBUS hub information is coded into the \texttt{mem\_controller}
-structure is motherboard implementation specific and not closer
+structure is mainboard implementation specific and not
described here. See \texttt{freebios2/src/mainboard/amd/quartet/auto.c}
for an example.
LinuxBIOS folks have agreed on SPD data being the central information
-source for RAM specific information. But not all motherboards/RAM
-modules feature a physical SPD ROM. To still allow an easytouse SPD
+source for RAM specific information. But not all mainboards/RAM
+modules feature a physical SPD ROM. To still allow an easy to use SPD
driven setup, there is a hook that abstracts reading the SPD ROM
ingredients that are used by the memory initialization mechanism:
\subsection {IRQ Tables}
-Motherboards that provide an IRQ table should have the following two
+Mainboards that provide an IRQ table should have the following two
variables set in their \texttt{Config.lb} file:
\begin{verbatim}
default IRQ_SLOT_COUNT=7
\end{verbatim}
-This will make LinuxBIOS look for the file
-\texttt{freebios2/src/mainboard/<vendor>/<motherboard>/irq\_tables.c} which
+This will make LinuxBIOS look for the file \\
+\texttt{freebios2/src/mainboard/<vendor>/<mainboard>/irq\_tables.c} which
contains the source code definition of the IRQ table. LinuxBIOS corrects
small inconsistencies in the IRQ table during startup (checksum and
number of entries), but it is not yet writing IRQ tables in a completely
you to adopt the code in mptable.c. This is subject to change in future
revisions.
+\subsection {ACPI Tables}
+
+There is initial ACPI support in LinuxBIOS now. Currently the only gain with
+this is the ability to use HPET timers in Linux. To achieve this, there is a
+framework that can generate the following tables:
+\begin{itemize}
+\item RSDP
+\item RSDT
+\item MADT
+\item HPET
+\end{itemize}
+
+To enable ACPI in your LinuxBIOS build, add the following lines to your
+configuration files:
+\begin{verbatim}
+uses HAVE_ACPI_TABLES
+[..]
+option HAVE_ACPI_TABLES=1
+\end{verbatim}
+
+To keep Linux doing it's pci ressource allocation based on IRQ tables and MP
+tables, you have to specify the kernel parameter \texttt{pci=noacpi} otherwise
+your PCI devices won't get interrupts.
+It's likely that more ACPI support will follow, when there is need for certain
+features.
+
\subsection{POST}
LinuxBIOS has three different methods of handling POST codes. They can
be triggered using configuration file options.
By separating the two structures above, M:N relations between compatible
devices and drivers can be described. The driver source code containing
above data structures and code have to be added to a LinuxBIOS image
-using the driver keyword in the motherboard specific configuration file
+using the driver keyword in the mainboard specific configuration file \\
\texttt{freebios2/src/mainboard/<vendor>/<mainboard>/Config.lb}:
\begin{verbatim}
\newpage
%
-% 10. LinuxBIOS Internals
+% 11. LinuxBIOS Internals
%
\section{LinuxBIOS Internals}
LinuxBIOS supports the following standards
\begin{itemize}
\item Multiprocessing Specification (MPSPEC) 1.4
-\item IRQ Tables
+\item IRQ Tables (PIRQ)
+\item ACPI (initial support on AMD64)
\item Elf Booting
\end{itemize}
However, the following standards are not supported until now, and will
probably not be supported in future revisions:
\begin{itemize}
-\item ACPI
\item APM
\end{itemize}
and platforms.
Since no memory is available during this early initialization point,
-romcc has to map all used variables in registers for their time being.
+romcc has to map all used variables in registers for the time being.
Same applies for their stack usage. Generally the less registers are
used up by the algorithms, the better code can be factored, resulting in
a smaller object size. Since getting the best register usage is an NP
your code.
\subsection{CMOS handling}
-LinuxBIOS can use the motherboard's CMOS memory to store information
+LinuxBIOS can use the mainboard's CMOS memory to store information
defined in a data structure called the CMOS table . This information
contains serial line speed, fallback boot control, output verbosity,
default boot device, ECC control, and more. It can be easily enhanced by
tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot
\end{verbatim}
-Then put your kernel image \texttt{vmlinuz.elf} to \texttt{/tftpboot} on
+Then put your kernel image \texttt{vmlinuz.elf} in \texttt{/tftpboot} on
the \texttt{tftp} server.
\newpage
%
-% 11 Glossary
+% 12. Advanced Device Initialization Mechanisms
+%
+
+\section{Advanced Device Initialization Mechanisms}
+
+Like software, today's hardware is getting more and more complex. To
+stay flexible many hardware vendors start breaking hardware
+compatibility to old standards like VGA. Thus, VGA is still supported by
+most cards, but emulation has to be enabled by the firmware for the
+device to operate properly. Also, many expansion cards are small
+discrete systems that have to initialize attached ram, download
+controller firmware and similar. Without this initialization, an
+operating system can not take advantage of the hardware, so there needs
+to be a way to address this issue. There are several alternatives:
+
+\subsection{Native LinuxBIOS Support}
+
+For some devices (ie Trident Cyberblade 3d) there is native LinuxBIOS
+support This means there is a small driver bound to the PCI id of the
+device that is called after PCI device ressources are allotted.
+
+PROs:
+ \begin{itemize}
+ \item open source
+ \item minimal driver
+ \item early control
+ \end{itemize}
+
+CONs:
+ \begin{itemize}
+ \item need an additional driver
+ \item viable for onboard devices only
+ \item not flexible for pci cards
+ \end{itemize}
+
+\subsection{Using Native Linux Support}
+
+A simple way of getting a whole lot of drivers available for LinuxBIOS
+is to reuse Linux drivers by putting a Linux kernel to flash. This
+works, because no drivers are needed to get the Linux kernel (as opposed
+to store the kernel on a harddisk connected to isa/scsi/raid storage)
+
+PROs:
+ \begin{itemize}
+ \item large number of open source drivers
+ \end{itemize}
+
+CONs:
+ \begin{itemize}
+ \item need Linux in Flash (BLOAT!)
+ \item drivers expect devices to be initialized (LSI1020/1030)
+ \item Linux only
+ \item large flash needed (4MBit minimum, normal operations 8+ MBit)
+ \end{itemize}
+
+
+\subsection{Running X86 Option ROMs}
+
+Especially SCSI/RAID controllers and graphics adapters come with a
+special option rom. This option rom usually contains x86 binary code
+that uses a legacy PCBIOS interface for device interaction. If this code
+gets executed, the device becomes operable in Linux and other operating
+systems.
+
+PROs:
+ \begin{itemize}
+ \item really flexible
+ \item no need for additional drivers on firmware layer
+ \item large number of supported devices
+ \end{itemize}
+
+CONs:
+ \begin{itemize}
+ \item non-x86 platforms need complex emulation
+ \item x86 platforms need legacy API
+ \item outdated concept
+ \end{itemize}
+
+
+\subsection{Running Open Firmware Option ROMs}
+
+Some PCI devices come with open firmware option roms. These devices are
+normally found in computers from SUN, Apple or IBM. Open Firmware is a
+instruction set architecture independent firmware standard that allows
+device specific initialization using simple, small, but flexible
+bytecode that runs with minimal footprint on all architectures that have
+an Open Firmware implementation.
+
+There is a free Open Firmware implementation available, called OpenBIOS,
+that runs on top of LinuxBIOS. See www.openbios.org
+
+PROs:
+ \begin{itemize}
+ \item architecture independence
+ \item small footprint
+ \item clean concept, less bugs
+ \end{itemize}
+
+CONs:
+ \begin{itemize}
+ \item only small number of devices come with OpenFirmware capable option roms
+ \end{itemize}
+
+
+%
+% 13 Glossary
%
\section{Glossary}
\newpage
%
-% 12 Bibliography
+% 14 Bibliography
%
\section{Bibliography}