sravan/system76-coreboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Since some people disapprove of white space cleanups mixed in regular commits

Browse Source 
while others dislike them being extra commits, let's clean them up once and
for all for the existing code. If it's ugly, let it only be ugly once :-)

Signed-off-by: Stefan Reinauer <stepan@coresystems.de>
Acked-by: Stefan Reinauer <stepan@coresystems.de>



git-svn-id: svn://svn.coreboot.org/coreboot/trunk@5507 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1
This commit is contained in:
Stefan Reinauer
2010-04-27 06:56:47 +00:00
committed by Stefan Reinauer
parent 0e1e8065e3
commit 14e2277962
1022 changed files with 9209 additions and 9210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
documentation/Kconfig.tex
View File

@ -120,7 +120,7 @@ $(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl"
iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/
perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex
mv pci3.hex ssdt3.c
$(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl"
iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl
perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex
@ -470,7 +470,7 @@ we don't need to test for the chipset CONFIG variable. We
can therefore test other variables (which is part of the reason
we set up conditional inclusion of this file, instead
of unconditionally including it). Here is an example from AMD 8111.
No conditionals in this one yet.
No conditionals in this one yet.
\begin{verbatim}
driver-y += amd8111.o
driver-y += amd8111_usb.o

194
documentation/LinuxBIOS-AMD64.tex
View File

@ -1,7 +1,7 @@
%
% This document is released under the GPL
% Initially written by Stefan Reinauer, <stepan@coresystems.de>
%
%
\documentclass[titlepage,12pt]{article}
\usepackage{a4}
@ -38,7 +38,7 @@
\maketitle
\thispagestyle{empty}
\thispagestyle{empty}
\tableofcontents
@ -67,7 +67,7 @@ find errors in the following descriptions, contact
\item 2009/04/19 replace LinuxBIOS with coreboot
\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
\item 2003/11/18 initial release
\end{itemize}
@ -78,7 +78,7 @@ find errors in the following descriptions, contact
\section{What is coreboot?}
coreboot aims to replace the normal BIOS found on x86, AMD64, PPC,
coreboot aims to replace the normal BIOS found on x86, AMD64, PPC,
Alpha, and other machines with a Linux kernel that can boot Linux from a cold
start. The startup code of an average coreboot port is about 500 lines of
assembly and 5000 lines of C. It executes 16 instructions to get into 32bit
@ -131,7 +131,7 @@ $ cd coreboot
You can get the entire source tree via SVN:
{ \small
{ \small
\begin{verbatim}
$ svn co svn://coreboot.org/repos/trunk/coreboot-v2
\end{verbatim}
@ -151,7 +151,7 @@ is available at \url{http://qa.coreboot.org/}.
Due to major structural enhancements to \hbox{coreboot}, AMD64 support
is only available in the \texttt{coreboot-v2} tree. This tree reflects (as
of November 2003) coreboot version 1.1.5 and will lead to coreboot 2.0
when finished. Most x86 hardware is currently only supported by the
when finished. Most x86 hardware is currently only supported by the
coreboot 1.0 tree.
%
@ -163,7 +163,7 @@ To support a large variety of existing hardware coreboot allows for a
lot of configuration options that can be tweaked in several ways:
\begin{itemize}
\item
\item
Firmware image specific configuration options can be set in the image
configuration file which is usually found in
\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/}. Such
@ -217,7 +217,7 @@ instance for the AMD Solo Athlon64 mainboard enter:
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
mainboard the default directory resides in
mainboard the default directory resides in
\texttt{coreboot-v2/targets/amd/solo/solo}. To build the coreboot image, do
\begin{verbatim}
@ -257,7 +257,7 @@ configuration files share some basic rules
\begin{itemize}
\item
The default configuration file name in coreboot is \texttt{Config.lb}.
\item
\item
All variables used in a configuration file have to be declared in this
file with \texttt{uses VARNAME} before usage.
\item
@ -267,13 +267,13 @@ Comments can be added on a new line by using the comment identifier
coreboot distinguishes between statements and options. Statements cause
the coreboot configuration mechanism to act, whereas options set
variables that are used by the build scripts or source code.
\item
\item
Default configuration values can be set in the mainboard configuration
files (keyword default)
\item
\item
Option overrides to the default configuration can only be specified in
the build target configuration file
\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb}
\texttt{coreboot-v2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb}
(keyword option)
\end{itemize}
@ -290,7 +290,7 @@ used. Example:
\end{verbatim}
\textbf{NOTE:} Only configuration variables known to the configuration
system can be used in configuration files. coreboot checks
system can be used in configuration files. coreboot checks
\texttt{coreboot-v2/src/config/Options.lb} to see whether a configuration
variable is known.
@ -298,7 +298,7 @@ variable is known.
The \texttt{default} statement is used to set a configuration variable
with an overridable default value. It is commonly used in mainboard
configuration files.
configuration files.
Example:
@ -320,7 +320,7 @@ Also, simple expressions are allowed:
\end{verbatim}
If an option contains a string, this string has to be protected with
quotation marks:
quotation marks:
\begin{verbatim}
default CC="gcc -m32"
@ -400,7 +400,7 @@ option on how to set them.
\item \begin{verbatim}CC\end{verbatim}
Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to
\texttt{gcc -m32} for compiling AMD64 coreboot images on an AMD64
\texttt{gcc -m32} for compiling AMD64 coreboot images on an AMD64
machine.
\item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim}
@ -415,7 +415,7 @@ Errors or log messages up to this level can be printed. Default is
\item \begin{verbatim}CONFIG_DEFAULT_CONSOLE_LOGLEVEL\end{verbatim}
Console will log at this level unless changed. Default is \texttt{7},
Console will log at this level unless changed. Default is \texttt{7},
minimum is \texttt{0}, maximum is \texttt{10}.
\item \begin{verbatim}CONFIG_CONSOLE_SERIAL8250\end{verbatim}
@ -430,7 +430,7 @@ Size of final ROM image. This option has no default value.
\item \begin{verbatim}CONFIG_FALLBACK_SIZE\end{verbatim}
Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:}
Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:}
This does not include the fallback payload.
\item \begin{verbatim}CONFIG_HAVE_OPTION_TABLE\end{verbatim}
@ -482,9 +482,9 @@ 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 \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
\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{Mainboard specific keywords}
@ -539,7 +539,7 @@ during the build process. This is useful if external utilities have to
be used for the build. coreboot on AMD64 uses romcc for it's early
startup code placed in auto.c.
To tell the configuration mechanism how to build \texttt{romcc} files,
To tell the configuration mechanism how to build \texttt{romcc} files,
do:
\begin{verbatim}
@ -556,7 +556,7 @@ end
\end{verbatim}
Each \texttt{makerule} section contains file dependencies (using the
texttt{depends} keyword) and an action that is taken when the dependencies
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}
@ -668,7 +668,7 @@ couple of \texttt{pci} keywords.
The first occurrence of the \texttt{pci} keyword tells coreboot where
the bridge devices start, relative to the PCI configuration space used
by the bridge. The following occurences of the \texttt{pci} keyword
describe the provided devices.
describe the provided devices.
Adding the option \texttt{on} or \texttt{off} to a PCI device will
enable or disable this device. This feature can be used if some bridge
@ -820,7 +820,7 @@ decompression is needed).
%
% 10. Tweaking the source code
%
%
\section{Tweaking the source code}
Besides configuring the existing code it is sometimes necessary or
@ -1083,7 +1083,7 @@ This will make coreboot look for the file \\
\texttt{coreboot-v2/src/mainboard/<vendor>/<mainboard>/irq\_tables.c} which
contains the source code definition of the IRQ table. coreboot 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
number of entries), but it is not yet writing IRQ tables in a completely
dynamic way.
\textbf{NOTE:} To get Linux to understand and actually use the IRQ
@ -1125,7 +1125,7 @@ revisions.
There is initial ACPI support in coreboot 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:
framework that can generate the following tables:
\begin{itemize}
\item RSDP
\item RSDT
@ -1143,7 +1143,7 @@ option CONFIG_HAVE_ACPI_TABLES=1
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.
your PCI devices won't get interrupts.
It's likely that more ACPI support will follow, when there is need for certain
features.
@ -1162,7 +1162,7 @@ port 80 POST output, you need a POST expansion card for ISA or PCI. Port
80 POST allows simple debugging without any other output method
available (serial interface or VGA display)
\item
\emph{Serial POST}.
\emph{Serial POST}.
This option allows to push POST messages to the serial interface instead
of using IO ports. \textbf{NOTE:} The serial interface has to be
initialized before serial POST can work. To use serial POST, set the
@ -1244,7 +1244,7 @@ reset code in your mainboard specific configuration file
\end{verbatim}
The C source file \texttt{reset.c} (resulting in \texttt{reset.o}
during compilation) shall define the following function to take care
during compilation) shall define the following function to take care
of the system reset:
\begin{verbatim}
@ -1337,7 +1337,7 @@ position within the CMOS memory. The layout file looks as follows:
[..]
392 3 e 5 baud_rate
[..]
# configid value human readable description
5 0 115200
5 1 57600
@ -1347,7 +1347,7 @@ position within the CMOS memory. The layout file looks as follows:
5 5 4800
5 6 2400
5 7 1200
\end{verbatim}
To change CMOS values from a running Linux system, use the
@ -1388,9 +1388,9 @@ network):
range 192.168.1.0 192.168.1.31;
option broadcastaddress 192.168.1.255;
}
ddnsupdatestyle adhoc;
host hammer12 {
hardware ethernet 00:04:76:EA:64:31;
fixedaddress 192.168.1.24;
@ -1522,11 +1522,11 @@ CONs:
%
\section{Image types}
There used to be one image type for coreboot, as described above. Since this paper was written (2004) there have been many changes. First, the name
There used to be one image type for coreboot, as described above. Since this paper was written (2004) there have been many changes. First, the name
was changed to coreboot, for many reasons. Second, Cache As Ram support (CAR)
was added for many AMD CPUs, which both simplified and complicated things. Simplification came with the removal of romcc; complication came with the addition of new ways to build.
was added for many AMD CPUs, which both simplified and complicated things. Simplification came with the removal of romcc; complication came with the addition of new ways to build.
There are two big additions to the build process and, furthermore, more than two new CONFIG variables to control them.
There are two big additions to the build process and, furthermore, more than two new CONFIG variables to control them.
\begin{itemize}
\item \begin{verbatim}CONFIG_USE_DCACHE_RAM\end{verbatim}
@ -1544,19 +1544,19 @@ Set to \texttt{1} to use printk, instead of the primitive print functions, in CA
\end{itemize}
Before going over the new image types, derived from v3, we will quickly review the standard v2 image types. We are hoping this review will
aid comprehension.
aid comprehension.
A coreboot rom file consists of one or more \textit{images}. All images consist of a part that runs in ROM, and a part that runs in RAM. The RAM can be in compressed form and is decompressed when needed by the ROM code. The main function of the ROM code is to get memory working. Both ROM and RAM consist of a very small amount of assembly code and mostly C code.
A coreboot rom file consists of one or more \textit{images}. All images consist of a part that runs in ROM, and a part that runs in RAM. The RAM can be in compressed form and is decompressed when needed by the ROM code. The main function of the ROM code is to get memory working. Both ROM and RAM consist of a very small amount of assembly code and mostly C code.
\subsection{romcc images (from emulation/qemu)}
ROMCC images are so-called because C code for the ROM part is compiled with romcc. romcc is an optimizing C compiler which compiles one, and only
one file; to get more than one file, one must include the C code via include statements. The main ROM code .c file is usually called auto.c.
ROMCC images are so-called because C code for the ROM part is compiled with romcc. romcc is an optimizing C compiler which compiles one, and only
one file; to get more than one file, one must include the C code via include statements. The main ROM code .c file is usually called auto.c.
\subsubsection{How it is built}
Romcc compiles auto.c to produce auto.inc. auto.inc is included in the main crt0.S, which is then preprocessed to produce crt0.s. The inclusion of files into crt0.S is controlled by the CONFIG\_CRT0\_INCLUDES variable. crt0.s is then assembled.
Romcc compiles auto.c to produce auto.inc. auto.inc is included in the main crt0.S, which is then preprocessed to produce crt0.s. The inclusion of files into crt0.S is controlled by the CONFIG\_CRT0\_INCLUDES variable. crt0.s is then assembled.
File for the ram part are compiled in a conventional manner.
File for the ram part are compiled in a conventional manner.
The final step is linking. The use of named sections is used very heavily in coreboot to control where different bits of code go. The reset vector must go in the top 16 bytes. The start portion of the ROM code must go in the top 64K bytes, since most chipsets only enable this much ROM at startup time. Here is a quick look at a typical image:
The final step is linking. The use of named sections is used very heavily in coreboot to control where different bits of code go. The reset vector must go in the top 16 bytes. The start portion of the ROM code must go in the top 64K bytes, since most chipsets only enable this much ROM at startup time. Here is a quick look at a typical image:
\begin{verbatim}
[Nr] Name Type Addr Off Size ES Flg Lk Inf Al
[ 0] NULL 00000000 000000 000000 00 0 0 0
@ -1569,30 +1569,30 @@ The final step is linking. The use of named sections is used very heavily in cor
[ 7] .strtab STRTAB 00000000 007da0 000bfd 00 0 0 1
\end{verbatim}
The only sections that get loaded into a ROM are the Allocated ones. We can see the .ram, .rom, .reset and .id sections.
The only sections that get loaded into a ROM are the Allocated ones. We can see the .ram, .rom, .reset and .id sections.
\subsubsection{layout}
As we mentioned, the ROM file consists of multiple images. In the basic file, there are two full coreboot rom images. The build sequence for each is the same, and in fact the ldscript.ld files are almost identical. The only difference is in a few makefile variables, generated by the config tool.
As we mentioned, the ROM file consists of multiple images. In the basic file, there are two full coreboot rom images. The build sequence for each is the same, and in fact the ldscript.ld files are almost identical. The only difference is in a few makefile variables, generated by the config tool.
\begin{itemize}
\item CONFIG\_PAYLOAD\_SIZE. Each image may have a different payload size.
\item CONFIG\_ROMBASE Each image must have a different base in rom.
\item CONFIG\_RESET Unclear what this is used for.
\item CONFIG\_PAYLOAD\_SIZE. Each image may have a different payload size.
\item CONFIG\_ROMBASE Each image must have a different base in rom.
\item CONFIG\_RESET Unclear what this is used for.
\item CONFIG\_EXCEPTION\_VECTORS where an optional IDT might go.
\item CONFIG\_USE\_OPTION\_TABLE if set, an option table section will be linked in.
\item CONFIG\_ROM\_PAYLOAD\_START This is the soon-to-be-deprecated way of locating a payload. cbfs eliminates this.
\item CONFIG\_USE\_OPTION\_TABLE if set, an option table section will be linked in.
\item CONFIG\_ROM\_PAYLOAD\_START This is the soon-to-be-deprecated way of locating a payload. cbfs eliminates this.
\item CONFIG\_USE\_FALLBACK\_IMAGE Whether this is a fallback or normal image
\item CONFIG\_ROM\_SECTION\_SIZE Essentially, the payload size. Soon to be deprecated.
\item CONFIG\_ROM\_SECTION\_SIZE Essentially, the payload size. Soon to be deprecated.
\item CONFIG\_ROM\_IMAGE\_SIZE Size of this image (i.e. fallback or normal image)
\item CONFIG\_ROM\_SIZE Total size of the ROM
\item CONFIG\_XIP\_RAM\_BASE The start of eXecute In Place code. XIP allows for not copying code to ram, but just running it from ROM.
\item CONFIG\_XIP\_RAM\_BASE The start of eXecute In Place code. XIP allows for not copying code to ram, but just running it from ROM.
\end{itemize}
Each image (normal or fallback) is built completely independently and does not get linked to the other. They are assembled into one ROM image by the (soon to be deprecated) buildrom tool, or by the cbfs tool.
Each image (normal or fallback) is built completely independently and does not get linked to the other. They are assembled into one ROM image by the (soon to be deprecated) buildrom tool, or by the cbfs tool.
\subsubsection{boot sequence}
We boot and start at fffffff0. We then jump to the entry point at \_start. \_start does some machine init and an lgdt and jumps to \_\_protected\_start, at which point we are in protected mode. The code does a bit more machine setup and then starts executing the romcc code.
We boot and start at fffffff0. We then jump to the entry point at \_start. \_start does some machine init and an lgdt and jumps to \_\_protected\_start, at which point we are in protected mode. The code does a bit more machine setup and then starts executing the romcc code.
If fallback has been built in, some setup needs to be done. On some machines, it is extensive. Full rom decoding must be enabled. This may in turn require additional PCI setup to enable decoding to be enabled (!). To decided which image to use, hardware registers (cold boot on the Opteron) or CMOS are checked. Finally, once the image to use has been decided, a jmp is performed, viz:
If fallback has been built in, some setup needs to be done. On some machines, it is extensive. Full rom decoding must be enabled. This may in turn require additional PCI setup to enable decoding to be enabled (!). To decided which image to use, hardware registers (cold boot on the Opteron) or CMOS are checked. Finally, once the image to use has been decided, a jmp is performed, viz:
\begin{verbatim}
/* This is the primary cpu how should I boot? */
else if (do_normal_boot()) {
@ -1616,8 +1616,8 @@ If fallback has been built in, some setup needs to be done. On some machines, it
#endif
;
\end{verbatim}
How does the fallback image get the symbol for normal entry? Via magic in the ldscript.ld -- remember, the images are not linked to each other.
Finally, we can see this in the Config.lb for most mainboards:
How does the fallback image get the symbol for normal entry? Via magic in the ldscript.ld -- remember, the images are not linked to each other.
Finally, we can see this in the Config.lb for most mainboards:
\begin{verbatim}
if CONFIG_USE_FALLBACK_IMAGE
mainboardinit cpu/x86/16bit/reset16.inc
@ -1627,27 +1627,27 @@ else
ldscript /cpu/x86/32bit/reset32.lds
end
\end{verbatim}
What does this mean? the non-fallback image has a 32-bit entry point; fallback has a 16-bit entry point. The reason for this is that some code from fallback always runs, so as to pick fallback or normal; but the normal is always called from 32-bit code.
What does this mean? the non-fallback image has a 32-bit entry point; fallback has a 16-bit entry point. The reason for this is that some code from fallback always runs, so as to pick fallback or normal; but the normal is always called from 32-bit code.
\subsection{car images (from lippert/roadrunner-lx)}
CAR images in their simplest form are modified romcc images. The file is usually cache\_as\_ram\_auto.c. C inclusion is still used. The main difference is in the build sequence. The compiler command line is a very slight changed: instead of using romcc to generate an auto.inc include file, gcc us used. Then, two perl scripts are used to rename the .text and .data sections to .rom.text and .rom.data respectively.
CAR images in their simplest form are modified romcc images. The file is usually cache\_as\_ram\_auto.c. C inclusion is still used. The main difference is in the build sequence. The compiler command line is a very slight changed: instead of using romcc to generate an auto.inc include file, gcc us used. Then, two perl scripts are used to rename the .text and .data sections to .rom.text and .rom.data respectively.
\subsubsection{How it is built}
The build is almost identical to the romcc build. Since the auto.inc file exists, it can be included as before. The crt0\_includes.h file has one addition: a file that enables CAR, in this case it is \textit{src/cpu/amd/model\_lx/cache\_as\_ram.inc}.
The build is almost identical to the romcc build. Since the auto.inc file exists, it can be included as before. The crt0\_includes.h file has one addition: a file that enables CAR, in this case it is \textit{src/cpu/amd/model\_lx/cache\_as\_ram.inc}.
\subsubsection{layout}
No significant change from romcc code.
No significant change from romcc code.
\subsubsection{boot sequence}
No significant change from romcc code, except that the CAR code has to set up a stack.
No significant change from romcc code, except that the CAR code has to set up a stack.
\subsection{car + CONFIG\_USE\_INIT images (new emulation/qemu}
This type of image makes more use of the C compiler. In this type of image, in fact,
seperate compilation is possible but is not always used. Oddly enough, this option is only used in PPC boards. That said, we need to move to this way of building. Including C code is poor style.
This type of image makes more use of the C compiler. In this type of image, in fact,
seperate compilation is possible but is not always used. Oddly enough, this option is only used in PPC boards. That said, we need to move to this way of building. Including C code is poor style.
\subsubsection{How it is built}
There is a make variable, INIT-OBJECTS, that for all our other targets is empty. In this type of build, INIT-OBJECTS is a list of C files that are created from the config tool initobject command. Again, with INIT-OBJECTS we can finally stop including .c files and go with seperate compilation.
\subsubsection{layout}
No significant change from romcc code.
No significant change from romcc code.
\subsubsection{boot sequence}
No significant change from romcc code, except that the CAR code has to set up a stack.
No significant change from romcc code, except that the CAR code has to set up a stack.
\subsection{car + CONFIG\_USE\_PRINTK\_IN\_CAR images}
When CONFIG\_USE\_PRINTK\_IN\_CAR is set, the CAR code can use printk instead of the primitive print functions. This config variable is used in one of two ways. If CONFIG\_USE\_INIT is 0, then different .c files just include other .c files, as in console.c:
When CONFIG\_USE\_PRINTK\_IN\_CAR is set, the CAR code can use printk instead of the primitive print functions. This config variable is used in one of two ways. If CONFIG\_USE\_INIT is 0, then different .c files just include other .c files, as in console.c:
\begin{verbatim}
#if CONFIG_USE_PRINTK_IN_CAR == 0
static void __console_tx_byte(unsigned char byte)
@ -1670,9 +1670,9 @@ static void __console_tx_byte(unsigned char byte)
#endif /* CONFIG_USE_PRINTK_IN_CAR */
\end{verbatim}\footnote{yuck!}
\end{verbatim}\footnote{yuck!}
If CONFIG\_USE\_INIT is 1, then the Config.lb is configured differently:
If CONFIG\_USE\_INIT is 1, then the Config.lb is configured differently:
\begin{verbatim}
if CONFIG_USE_INIT
if CONFIG_USE_PRINTK_IN_CAR
@ -1680,14 +1680,14 @@ if CONFIG_USE_INIT
end
end
\end{verbatim}\footnote{see previous footnote}
\end{verbatim}\footnote{see previous footnote}
\subsubsection{layout}
No significant change from romcc code.
No significant change from romcc code.
\subsubsection{boot sequence}
No significant change from romcc code, except that the CAR code has to set up a stack.
No significant change from romcc code, except that the CAR code has to set up a stack.
\subsection{failover}
Failover is the newest way to lay out a ROM. The choice of which image to run is removed from the fallback image and moved into a small, standalone piece of code. The code is simple enough to show here:
Failover is the newest way to lay out a ROM. The choice of which image to run is removed from the fallback image and moved into a small, standalone piece of code. The code is simple enough to show here:
\begin{verbatim}
static unsigned long main(unsigned long bist)
{
@ -1707,7 +1707,7 @@ fallback_image:
}
\end{verbatim}
Some motherboards have a more complex bus structure (e.g. Opteron). In those cases, the failover can be more complex, as it requires some hardware initialization to work correctly. As of this writing (April 2009), these boards have their own failover:
Some motherboards have a more complex bus structure (e.g. Opteron). In those cases, the failover can be more complex, as it requires some hardware initialization to work correctly. As of this writing (April 2009), these boards have their own failover:
\begin{quote}
./src/mainboard/iei/nova4899r/failover.c
./src/mainboard/emulation/qemu-x86/failover.c
@ -1723,7 +1723,7 @@ Some motherboards have a more complex bus structure (e.g. Opteron). In those cas
./src/mainboard/olpc/rev\_a/failover.c
./src/mainboard/via/epia-m/failover.c
\end{quote}
Here is one of the more complicated ones:
Here is one of the more complicated ones:
\begin{verbatim}
static unsigned long main(unsigned long bist)
{
@ -1760,15 +1760,15 @@ static unsigned long main(unsigned long bist)
}
\end{verbatim}
They're not that different, in fact. So why are there different copies all over the tree? Simple: code inclusion. Most of the failover.c are different because they include different bits of code. Here is a key reason for killing C code inclusion in the tree.
They're not that different, in fact. So why are there different copies all over the tree? Simple: code inclusion. Most of the failover.c are different because they include different bits of code. Here is a key reason for killing C code inclusion in the tree.
\subsubsection{How it is built}
There two additional config variables:
There two additional config variables:
\begin{itemize}
\item HAVE\_FAILOVER\_IMAGE Has to be defined when certain files are included.
\item HAVE\_FAILOVER\_IMAGE Has to be defined when certain files are included.
\item USE\_FAILOVER\_IMAGE Enables the use of the failover image
\end{itemize}
Confusingly enough, almost all the uses of these two variables are either nested or both required to be set, e.g.
The fallback and normal builds are the same. The target config has a new clause that looks like this:
Confusingly enough, almost all the uses of these two variables are either nested or both required to be set, e.g.
The fallback and normal builds are the same. The target config has a new clause that looks like this:
\begin{verbatim}
romimage "failover"
option CONFIG_USE_FAILOVER_IMAGE=1
@ -1778,36 +1778,36 @@ romimage "failover"
option COREBOOT_EXTRA_VERSION="\$(shell cat ../../VERSION)\_Failover"
end
\end{verbatim}
This new section uses some constructs not yet discussed in detail. XIP\_ROM\_SIZE just refers to the
fact that the failover code is eXecute In Place, i.e. not copied to RAM. Of course, the ROM part of normal/fallback is as well, so the usage of XIP here is somewhat confusing. Finally, the USE\_FAILOVER\_IMAGE variable is set, which changes code compilation in a few places. If we just consider non-mainbard files, there are:
This new section uses some constructs not yet discussed in detail. XIP\_ROM\_SIZE just refers to the
fact that the failover code is eXecute In Place, i.e. not copied to RAM. Of course, the ROM part of normal/fallback is as well, so the usage of XIP here is somewhat confusing. Finally, the USE\_FAILOVER\_IMAGE variable is set, which changes code compilation in a few places. If we just consider non-mainbard files, there are:
\begin{verbatim}
src/cpu/amd/car/cache_as_ram.inc
src/arch/i386/Config.lb
\end{verbatim}
For the cache\_as\_ram.inc file, the changes relate to the fact that failover code sets up CAR, so that fallback code need not.
For the Config.lb, several aspects of build change.
When USE\_FAILOVER\_IMAGE, entry into both normal and fallback bios images is via a 32-bit entry point (when not defined, entry into fallback is a 16-entry point at the power-on reset vector).
For the Config.lb, several aspects of build change.
When USE\_FAILOVER\_IMAGE, entry into both normal and fallback bios images is via a 32-bit entry point (when not defined, entry into fallback is a 16-entry point at the power-on reset vector).
\subsubsection{layout}
Failover.c becomes the new bootblock at the top of memory. It calls either normal or fallback. The address of normal and fallback is determined by ldscript magic.
Failover.c becomes the new bootblock at the top of memory. It calls either normal or fallback. The address of normal and fallback is determined by ldscript magic.
\subsubsection{boot sequence}
failover.c tests a few variables and the calls the normal or fallback payload depending on those variables; usually they are CMOS settings.
failover.c tests a few variables and the calls the normal or fallback payload depending on those variables; usually they are CMOS settings.
\subsection{Proposed new image forat}
The new image format will use seperate compilation -- no C code included! -- on all files.
The new image format will use seperate compilation -- no C code included! -- on all files.
The new design has a few key goals:
The new design has a few key goals:
\begin{itemize}
\item Always use a bootblock (currently called failover).
The name failover.c, being utterly obscure, will not be used; instead, we will name the file bootblock.c. Instead of having a different copy for each mainboard, we can have just one copy.
\item Always use a bootblock (currently called failover).
The name failover.c, being utterly obscure, will not be used; instead, we will name the file bootblock.c. Instead of having a different copy for each mainboard, we can have just one copy.
\item Always use seperate compilation
\item Always use printk etc. in the ROM code
\item (longer term) from the bootblock, always use cbfs to locate the normal/fallback etc. code. This code will be XIP.
\item (longer term) from the bootblock, always use cbfs to locate the normal/fallback etc. code. This code will be XIP.
\end{itemize}
\subsubsection{How it is built}
For now, since we are still using the config tool, we'll need a new command: bootblockobject, which creates a list of files to be included in the bootblock. Not a lot else will have to change. We are going to move to using the v3 CAR code assembly code (one or two files at most, instead of many) and, instead of the thicket of little ldscript files, one ldscript file. This strategy is subject to modification as events dictate.
For now, since we are still using the config tool, we'll need a new command: bootblockobject, which creates a list of files to be included in the bootblock. Not a lot else will have to change. We are going to move to using the v3 CAR code assembly code (one or two files at most, instead of many) and, instead of the thicket of little ldscript files, one ldscript file. This strategy is subject to modification as events dictate.
\subsubsection{layout}
Almost the same, for now, as the current failover code.
Almost the same, for now, as the current failover code.
\subsubsection{boot sequence}
%
% 14 Glossary
@ -1839,11 +1839,11 @@ ROMs they can be electronically erased and reprogrammed.
\subsection{Additional Papers on coreboot}
\begin{itemize}
\item
\item
\textit{\url{http://www.coreboot.org/Documentation}}
\item
\item
\textit{\url{http://www.lysator.liu.se/upplysning/fa/linuxbios.pdf}}
\item
\item
\textit{\url{http://portal.acm.org/citation.cfm?id=512627}}
\end{itemize}

2
documentation/Makefile
View File

@ -31,7 +31,7 @@ else ifneq ($(strip $(CONVERT)),)
convert $< $@
endif
LinuxBIOS-AMD64.toc: $(FIGS) LinuxBIOS-AMD64.tex
LinuxBIOS-AMD64.toc: $(FIGS) LinuxBIOS-AMD64.tex
# 2 times to make sure we have a current toc.
$(PDFLATEX) LinuxBIOS-AMD64.tex
$(PDFLATEX) LinuxBIOS-AMD64.tex

154
documentation/RFC/chip.tex
View File

@ -2,17 +2,17 @@
\begin{abstract}
At the end of this document is the original message that motivated the
change.
change.
\end{abstract}
\section{Scope}
This document defines how LinuxBIOS programmers can specify chips that
are used, specified, and initalized. The current scope is for superio
chips, but the architecture should allow for specification of other chips such
as southbridges. Multiple chips of same or different type are supported.
are used, specified, and initalized. The current scope is for superio
chips, but the architecture should allow for specification of other chips such
as southbridges. Multiple chips of same or different type are supported.
\section{Goals}
The goals of the new chip architecture are these:
The goals of the new chip architecture are these:
\begin{itemize}
\item seperate implementation details from specification in the Config file
(translation: no more C code in Config files)
@ -27,33 +27,33 @@ The specification looks like this:
\begin{verbatim}
chip <name> [path=<path>] ["<configuration>"]
\end{verbatim}
The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
chip is derived from the first pathname component of the name, and the chip
configuration is derived from the following components.
The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
chip is derived from the first pathname component of the name, and the chip
configuration is derived from the following components.
The path defines the access mechanism to the chip.
It is optional. If present, it overrides the default path to the chip.
The path defines the access mechanism to the chip.
It is optional. If present, it overrides the default path to the chip.
The configuration defines chip-specific configuration details, and is also
optional. Note that an empty configuration will leave the chip with
no enabled resources. This may be desirable in some cases.
optional. Note that an empty configuration will leave the chip with
no enabled resources. This may be desirable in some cases.
\section{Results of specifying a chip}
When one or more chips are specified, the data about the chips
is saved until the entire file is parsed. At this point, the config tool
creates a file in the build directory called chip.c This file contains
a common struct containing information about
each individual chip and an array of pointers to these structures.
a common struct containing information about
each individual chip and an array of pointers to these structures.
For each chip, there are two structures. The structures contain control
information for the chip, and register initialization information. The
names of the structures are derived by ``flattening'' the chip name,
as in the current linuxbios. For example, superio/ite/xyz uses
For each chip, there are two structures. The structures contain control
information for the chip, and register initialization information. The
names of the structures are derived by ``flattening'' the chip name,
as in the current linuxbios. For example, superio/ite/xyz uses
two structs, one called superio_ite_xyz_control and one called
superio_ite_xyz_init. The control struct is initialized from the
chip name and path information, and has a pointer to the
superio_ite_xyz_init. The control struct is initialized from the
chip name and path information, and has a pointer to the
config struct. The config struct is initialized from the quote string
\begin{verbatim}
@ -64,29 +64,29 @@ To: linuxbios@clustermatic.org
Subject: RFC:new superio proposal
Abstract:
The superio architecture for linuxbios has worked for the last 2
years but is being stretched to the limit by the changes in superio chips.
The architecture depended on superio resources being relatively constant
between chips, but this assumption no longer holds. In this document we
propose several alternatives and solicit comments.
The superio architecture for linuxbios has worked for the last 2
years but is being stretched to the limit by the changes in superio chips.
The architecture depended on superio resources being relatively constant
between chips, but this assumption no longer holds. In this document we
propose several alternatives and solicit comments.
Overview:
The superio architecture in linuxbios was developed over time, and
modified as circumstances required. In the beginning it was relatively
simple and assumed only one superio per mainboard. The latest version
The superio architecture in linuxbios was developed over time, and
modified as circumstances required. In the beginning it was relatively
simple and assumed only one superio per mainboard. The latest version
allows an arbitrary number of superios per mainboard, and allows complete
specification of the superio base I/O address along with the specification
of reasonable default valures for both the base I/O address and the
superio parameters such as serial enable, baud rate, and so on.
of reasonable default valures for both the base I/O address and the
superio parameters such as serial enable, baud rate, and so on.
Specification of superio control parameters is done by a configuration
Specification of superio control parameters is done by a configuration
line such as:
nsuperio sis/950 com1={1} floppy=1 lpt=1
This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
default values.
This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
default values.
While it is not obvious, these configuration parameters are fragments of a
C initializer. The initializers are used to build a statically initialized
@ -96,7 +96,7 @@ struct superio {
struct superio_control *super; // the ops for the device.
unsigned int port; // if non-zero, overrides the default port
// com ports. This is not done as an array (yet).
// We think it's easier to set up from python if it is not an
// We think it's easier to set up from python if it is not an
// array.
struct com_ports com1, com2, com3, com4;
// DMA, if it exists.
@ -114,14 +114,14 @@ struct superio {
These structures are, in turn, created and statically initialized by a
config-tool-generated structure that defines all the superios. This file
is called nsuperio.c, is created for each mainboard you build, only
is called nsuperio.c, is created for each mainboard you build, only
appears in the build directory, and looks like this:
===
extern struct superio_control superio_winbond_w83627hf_control;
extern struct superio_control superio_winbond_w83627hf_control;
struct superio superio_winbond_w83627hf= {
&superio_winbond_w83627hf_control,
struct superio superio_winbond_w83627hf= {
&superio_winbond_w83627hf_control,
.com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
struct superio *all_superio[] = {&superio_winbond_w83627hf,
@ -131,12 +131,12 @@ unsigned long nsuperio = 1;
===
This example shows a board with one superio (nsuperio). The superio
consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
and hwmonitor enabled. Note that this structure also allows for
over-riding the default superio base, although that capability is rarely
used.
consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
and hwmonitor enabled. Note that this structure also allows for
over-riding the default superio base, although that capability is rarely
used.
The control structure is used to define how to access the superio for
The control structure is used to define how to access the superio for
purposes of control. It looks like this:
===
struct superio_control {
@ -151,13 +151,13 @@ struct superio_control {
};
===
There are three methods for stages of hardwaremain. First is pre_pci_init
(for chips like the acer southbridge that require you to enable some
resources BEFORE pci scan); init, called during the 'middle' phase of
hardwaremain; and finishup, called before the payload is loaded.
There are three methods for stages of hardwaremain. First is pre_pci_init
(for chips like the acer southbridge that require you to enable some
resources BEFORE pci scan); init, called during the 'middle' phase of
hardwaremain; and finishup, called before the payload is loaded.
This approach was inspired by and borrows heavily on the Plan 9 kernel
configuration tools.
This approach was inspired by and borrows heavily on the Plan 9 kernel
configuration tools.
The problem:
@ -166,22 +166,22 @@ smaller. It has grown and in the limit this structure is the union of all
possibly superio chips. Obviously, in the long term, this is not
practical: we can not anticipate all possible superio chips for all time.
The common PC BIOS solution to this type of problem is to continue with
binary structures but add version numbers to them, so that all code that
uses a given structure has to check the version number. Personally, I find
this grotesque and would rather not work this way.
The common PC BIOS solution to this type of problem is to continue with
binary structures but add version numbers to them, so that all code that
uses a given structure has to check the version number. Personally, I find
this grotesque and would rather not work this way.
Using textual strings for configuration is something I find far more
attractive. Plan 9 has shown that this approach has no real limits and
suffices for configuration tasks. The Linux kernel does more limited use
of strings for configuration, but still depends on them. Strings are
easier to read and work with than binary structures, and more important, a
lot easier to deal with when things start going wrong.
Using textual strings for configuration is something I find far more
attractive. Plan 9 has shown that this approach has no real limits and
suffices for configuration tasks. The Linux kernel does more limited use
of strings for configuration, but still depends on them. Strings are
easier to read and work with than binary structures, and more important, a
lot easier to deal with when things start going wrong.
The proposed solution:
What follows are three possible ideas for specifying superio resources and
their settings.
What follows are three possible ideas for specifying superio resources and
their settings.
A common part of the new idea is to eliminate the common superio
structure, due to the many variations in chips, and make it invisible
@ -203,9 +203,9 @@ struct superio_control {
char *name;
};
I.e. we add a new function for creating the superio.
I.e. we add a new function for creating the superio.
Communication of superio settings from linuxbios to the superio would be
Communication of superio settings from linuxbios to the superio would be
via textual strings. The superio structure becomes this:
struct superio {
@ -215,7 +215,7 @@ struct superio {
};
So now the question becomes, what is the configuration structure?
So now the question becomes, what is the configuration structure?
There are several choices. The simplest, from my point of view, are
keyword-value pairs:
struct configuration {
@ -223,11 +223,11 @@ struct configuration {
const char *value;
};
These get filled in by the config tool as before. The linuxbios libary can
then provide a generic parsing function for the superios to use.
These get filled in by the config tool as before. The linuxbios libary can
then provide a generic parsing function for the superios to use.
The remaining question is how should the superio command look in
freebios2?
The remaining question is how should the superio command look in
freebios2?
superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
@ -242,22 +242,22 @@ superio sis/950 ((com1 115200 8n1) (lpt 1))
So, my questions:
1. Does this new scheme look workable. If not, what needs to change?
2. What should the 'struct configuration' be? does keyword/value work?
3. what should the superio command look like?
2. What should the 'struct configuration' be? does keyword/value work?
3. what should the superio command look like?
Comments welcome.
I'd like to adopt this "RFC" approach for freebios2 as much as we can.
I'd like to adopt this "RFC" approach for freebios2 as much as we can.
There was a lot of give-and-take in the early days of linuxbios about
structure and it proved useful. There's a lot that will start happening in
freebios2 now, and we need to try to make sure it will work for everyone.
Those of you who are doing mainboards, please look at freebios2 and see
how it looks for you. There's a lot of good work that has been done (not
by me so far, thanks Eric and Stefan), and more that needs to be done.
Consider trying out romcc as an "assembly code killer". See how it fits
together and if you can work with it or need changes. Bring comments back
to this list.
by me so far, thanks Eric and Stefan), and more that needs to be done.
Consider trying out romcc as an "assembly code killer". See how it fits
together and if you can work with it or need changes. Bring comments back
to this list.
thanks

62
documentation/RFC/config.tex
View File

@ -8,7 +8,7 @@ We describe the new configuration language for LinuxBIOS.
This document defines the new configuration language for LinuxBIOS.
\section{Goals}
The goals of the new language are these:
The goals of the new language are these:
\begin{itemize}
\item Simplified Makefiles so people can see what is set
\item Move from the regular-expression-based language to something
@ -16,22 +16,22 @@ a bit more comprehensible and flexible
\item make the specification easier for people to use and understand
\item allow unique register-set-specifiers for each chip
\item allow generic register-set-specifiers for each chip
\item generate static initialization code, as needed, for the
specifiers.
\item generate static initialization code, as needed, for the
specifiers.
\end{itemize}
\section{Language}
Here is the new language. It is very similar to the old one, differing
in only a few respects. It borrows heavily from Greg Watson's suggestions.
in only a few respects. It borrows heavily from Greg Watson's suggestions.
I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
in '' are keywords; things in ``'' are strings in the actual text.
I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
in '' are keywords; things in ``'' are strings in the actual text.
\begin{verbatim}
#exprs are composed of factor or factor + factor etc.
expr ::= factor ( ``+'' factor | ``-'' factor | )*
#factors are term or term * term or term / term or ...
factor ::= term ( ``*'' term | ``/'' term | ... )*
#
#
unary-op ::= ``!'' ID
# term is a number, hexnumber, ID, unary-op, or a full-blown expression
term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
@ -39,27 +39,27 @@ term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
# Option command. Can be an expression or quote-string.
# Options are used in the config tool itself (in expressions and 'if')
# and are also passed to the C compiler when building linuxbios.
# It is an error to have two option commands in a file.
# It is an error to have two option commands in a file.
# It is an error to have an option command after the ID has been used
# in an expression (i.e. 'set after used' is an error)
option ::= 'option' ID '=' (``value'' | term)
# Default command. The ID is set to this value if no option command
# is scanned.
# Multiple defaults for an ID will produce warning, but not errors.
# is scanned.
# Multiple defaults for an ID will produce warning, but not errors.
# It is OK to scan a default command after use of an ID.
# Options always over-ride defaults.
default ::= 'default' ID '=' (``value'' | term)
# the mainboard, southbridge, northbridge commands
# cause sourcing of Config.lb files as in the old config tool
# as parts are sourced, a device tree is built. The structure
# as parts are sourced, a device tree is built. The structure
# of the tree is determined by the structure of the components
# as they are specified. To attach a superio to a southbridge, for
# example, one would do this:
# southbridge acer/5432
# superio nsc/123
# end
# southbridge acer/5432
# superio nsc/123
# end
# end
# the tool generates static initializers for this hierarchy.
@ -79,17 +79,17 @@ register ::= 'register' ``CODE''
mainboard ::= 'mainboard' PATH (statements)* 'end'
# standard linuxbios commands
southbridge ::= 'southbridge' PATH (statemnts)* 'end'
northbridge ::= 'northbridge' PATH (statemnts)* 'end'
superio ::= 'superio PATH (statemnts)* 'end'
cpu ::= 'cpu' PATH (statemnts)* 'end'
arch ::= 'arch' PATH (statemnts)* 'end'
southbridge ::= 'southbridge' PATH (statemnts)* 'end'
northbridge ::= 'northbridge' PATH (statemnts)* 'end'
superio ::= 'superio PATH (statemnts)* 'end'
cpu ::= 'cpu' PATH (statemnts)* 'end'
arch ::= 'arch' PATH (statemnts)* 'end'
# files for building linuxbios
# include a file in crt0.S
mainboardinit ::= 'mainboardinit' PATH
# include a file in crt0.S
mainboardinit ::= 'mainboardinit' PATH
# object file
# object file
object ::= 'object' PATH
# driver objects are just built into the image in a different way
driver ::= 'driver' PATH
@ -116,7 +116,7 @@ makedefine ::= 'makedefine' ``RAWTEXT''
addaction ::= 'addaction' PATH ``ACTION''
# statements
statement ::=
statement ::=
option
| default
| cpu
@ -204,12 +204,12 @@ ldscript cpu/i386/entry32.lds
###
### Build our reset vector (This is where linuxBIOS is entered)
###
if CONFIG_USE_FALLBACK_IMAGE
mainboardinit cpu/i386/reset16.inc
ldscript cpu/i386/reset16.lds
if CONFIG_USE_FALLBACK_IMAGE
mainboardinit cpu/i386/reset16.inc
ldscript cpu/i386/reset16.lds
else
mainboardinit cpu/i386/reset32.inc
ldscript cpu/i386/reset32.lds
mainboardinit cpu/i386/reset32.inc
ldscript cpu/i386/reset32.lds
end
.
.
@ -227,7 +227,7 @@ makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
mainboardinit ./auto.inc
#
###
### Include the secondary Configuration files
### Include the secondary Configuration files
###
northbridge amd/amdk8
end
@ -286,6 +286,6 @@ export CC:=$(CONFIG_CROSS_COMPILE)gcc
\end{verbatim}
In other words, instead of expressions, we see the values. It's easier to
deal with.
In other words, instead of expressions, we see the values. It's easier to
deal with.

94
documentation/cbfs.txt
View File

@ -4,71 +4,71 @@ Received: from www.crouse-house.com ([199.45.160.146]
From: Jordan Crouse <jordan@cosmicpenguin.net>
Greetings. I apologize for the incompleteness of what I am about to
discuss. I was planning on working on it leisurely, but my employment
circumstances changed and I've been trying to get it completed in a
Greetings. I apologize for the incompleteness of what I am about to
discuss. I was planning on working on it leisurely, but my employment
circumstances changed and I've been trying to get it completed in a
hurry before I had to leave it behind.
I've been thinking a lot about LAR lately, and ways to make it more
extensible and robust. Marc and I have been trading ideas back and
forth for a number of months, and over time a clear idea of what I
I've been thinking a lot about LAR lately, and ways to make it more
extensible and robust. Marc and I have been trading ideas back and
forth for a number of months, and over time a clear idea of what I
wanted to do started to take shape.
My goal was to add small things to LAR while retaining the overall
scheme. Over time, the scheme evolved slightly, but I think you'll find
that it remains true to the original idea. Below is the beginnings of
an architecture document - I did it in text form, but if met with
aclaim, it should be wikified. This presents what I call CBFS - the
next generation LAR for next generation Coreboot. Its easier to
My goal was to add small things to LAR while retaining the overall
scheme. Over time, the scheme evolved slightly, but I think you'll find
that it remains true to the original idea. Below is the beginnings of
an architecture document - I did it in text form, but if met with
aclaim, it should be wikified. This presents what I call CBFS - the
next generation LAR for next generation Coreboot. Its easier to
describe what it is by describing what changed:
A header has been added somewhere in the bootblock similar to Carl
Daniel's scheme. In addition to the coreboot information, the header
reports the size of the ROM, the alignment of the blocks, and the offset
of the first component in the CBFS. The master header provides all
A header has been added somewhere in the bootblock similar to Carl
Daniel's scheme. In addition to the coreboot information, the header
reports the size of the ROM, the alignment of the blocks, and the offset
of the first component in the CBFS. The master header provides all
the information LAR needs plus the magic number information flashrom needs.
Each "file" (or component, as I style them) now has a type associated
with it. The type is used by coreboot to identify the type of file that
it is loading, and it can also be used by payloads to group items in the
Each "file" (or component, as I style them) now has a type associated
with it. The type is used by coreboot to identify the type of file that
it is loading, and it can also be used by payloads to group items in the
CBFS by type (i.e - bayou can ask for all components that are payloads).
The header on each "file" (or component, as I like to style them) has
been simplified - We now only store the length, the type, the checksum,
and the offset to the data. The name scheme remains the same. The
addtional information, which is component specific, has been moved to
The header on each "file" (or component, as I like to style them) has
been simplified - We now only store the length, the type, the checksum,
and the offset to the data. The name scheme remains the same. The
addtional information, which is component specific, has been moved to
the component itself (see below).
The components are arranged in the ROM aligned along the specified
The components are arranged in the ROM aligned along the specified
alignment from the master header - this is to facilitate partial re-write.
Other then that, the LAR ideas remain pretty much the same.
The plan for moving the metadata to the components is to allow many
different kinds of components, not all of which are groked by coreboot.
However, there are three essential component types that are groked by
The plan for moving the metadata to the components is to allow many
different kinds of components, not all of which are groked by coreboot.
However, there are three essential component types that are groked by
coreboot, and they are defined:
stage - the stage is being parsed from the original ELF, and stored in
the ROM as a single blob of binary data. The load address, start
stage - the stage is being parsed from the original ELF, and stored in
the ROM as a single blob of binary data. The load address, start
address, compression type and length are stored in the component sub-header.
payload - this is essentially SELF in different clothing - same idea as
payload - this is essentially SELF in different clothing - same idea as
SELF, with the sub-header as above.
optionrom - This is in flux - right now, the optionrom is stored
optionrom - This is in flux - right now, the optionrom is stored
unadulterated and uncompressed, but that is likely to be changed.
Following this email are two replies containing the v3 code and a new
ROM tool to implement this respectively. I told you that I was trying
to get this out before I disappear, and I'm not kidding - the code is
compile tested and not run-tested. I hope that somebody will embrace
this code and take it the rest of the way, otherwise it will die a
Following this email are two replies containing the v3 code and a new
ROM tool to implement this respectively. I told you that I was trying
to get this out before I disappear, and I'm not kidding - the code is
compile tested and not run-tested. I hope that somebody will embrace
this code and take it the rest of the way, otherwise it will die a
pretty short death.
I realize that this will start an awesome flamewar, and I'm looking
forward to it. Thanks for listening to me over the years - and good
luck with coreboot. When you all make a million dollars, send me a few
I realize that this will start an awesome flamewar, and I'm looking
forward to it. Thanks for listening to me over the years - and good
luck with coreboot. When you all make a million dollars, send me a few
bucks, will you?
Jordan
@ -152,7 +152,7 @@ struct cbfs_header {
The meaning of each member is as follows:
'magic' is a 32 bit number that identifies the ROM as a CBFS type. The
'magic' is a 32 bit number that identifies the ROM as a CBFS type. The
magic
number is 0x4F524243, which is 'ORBC' in ASCII.
@ -160,7 +160,7 @@ number is 0x4F524243, which is 'ORBC' in ASCII.
0xFFFFFFFF to locate the beginning of the ROM in memory.
'align' is the number of bytes that each component is aligned to within the
ROM. This is used to make sure that each component is aligned correctly
ROM. This is used to make sure that each component is aligned correctly
with
regards to the erase block sizes on the ROM - allowing one to replace a
component at runtime without disturbing the others.
@ -170,7 +170,7 @@ the ROM). This is to allow for arbitrary space to be left at the beginning
of the ROM for things like embedded controller firmware.
= Bootblock =
The bootblock is a mandatory component in the ROM. It is located in the
The bootblock is a mandatory component in the ROM. It is located in the
last
20k of the ROM space, and contains, among other things, the location of the
master header and the entry point for the loader firmware. The bootblock
@ -179,11 +179,11 @@ does not have a component header attached to it.
= Components =
CBFS components are placed in the ROM starting at 'offset' specified in
the master header and ending at the bootblock. Thus the total size
the master header and ending at the bootblock. Thus the total size
available
for components in the ROM is (ROM size - 20k - 'offset'). Each CBFS
component is to be aligned according to the 'align' value in the header.
Thus, if a component of size 1052 is located at offset 0 with an 'align'
Thus, if a component of size 1052 is located at offset 0 with an 'align'
value
of 1024, the next component will be located at offset 2048.
@ -214,12 +214,12 @@ below.
'checksum' is a 32bit checksum of the entire component, including the
header and name.
'offset' is the start of the component data, based off the start of the
'offset' is the start of the component data, based off the start of the
header.
The difference between the size of the header and offset is the size of the
component name.
Immediately following the header will be the name of the component,
Immediately following the header will be the name of the component,
which will
null terminated and 16 byte aligned. The following picture shows the
structure of the header:
@ -248,7 +248,7 @@ component was found.
Upon recognizing a component, the software then has to search for the
specific name of the component. This is accomplished by comparing the
desired name with the string on the component located at
offset + sizeof(struct cbfs_file). If the string matches, then the
offset + sizeof(struct cbfs_file). If the string matches, then the
component
has been located, otherwise the software should add 'offset' + 'len' to
the offset and resume the search for the magic value.

14
documentation/codeflow.svg
View File

@ -97,7 +97,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7
132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439 "/>
</g>
<polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181 "/>
@ -117,7 +117,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7
132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439 "/>
</g>
<polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181 "/>
@ -137,7 +137,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041
132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78 "/>
</g>
<polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522 "/>
@ -157,7 +157,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467
132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207 "/>
</g>
<polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948 "/>
@ -177,7 +177,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468
132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207 "/>
</g>
<polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948 "/>
@ -197,7 +197,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327
132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066 "/>
</g>
<polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808 "/>
@ -217,7 +217,7 @@
<g>
<g>
<g>
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608
<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608
132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347 "/>
</g>
<polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089 "/>

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 17 KiB

After

Width:  |  Height:  |  Size: 17 KiB