\title{LinuxBIOS on AMD64}
\author{Stefan Reinauer $<$stepan@openbios.org$>$}
-\date{February 10th, 2004}
+\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
\section{Changes}
\begin{itemize}
- \item 2003/11/18 initial release
+ \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}
\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}
}
\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
\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}.
%
\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
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:
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
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}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}
\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}
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"
\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:
\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
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}
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.
Like software, today's hardware is getting more and more complex. To
stay flexible many hardware vendors start breaking hardware
-compatibility to old standards as VGA. Thus, VGA is still supported by
+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
projects / coreboot.git / commitdiff