Updating documentation as I get ready to put v3-style startup in (which

I have working in an early version in my tree).

Corrections welcome.

Signed-off-by: Ronald G. Minnich <rminnich@gmail.com>
Acked-by: Ronald G. Minnich <rminnich@gmail.com>


git-svn-id: svn://svn.coreboot.org/coreboot/trunk@4129 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

1 files changed, 118 insertions, 6 deletions

diff --git a/documentation/LinuxBIOS-AMD64.tex b/documentation/LinuxBIOS-AMD64.tex
index 316d37be2b..f2533fc5e8 100644
--- a/documentation/LinuxBIOS-AMD64.tex
+++ b/documentation/LinuxBIOS-AMD64.tex
@@ -1072,7 +1072,7 @@ static inline int spd_read_byte(unsigned device, unsigned address)
 
 If there is no SPD ROM available in the system design, this function
 keeps an array of SPD ROM information hard coded per logical RAM module.
-It returns the ´faked' SPD ROM information using device and address
+It returns the faked' SPD ROM information using device and address
 as indices to this array.
 
 
@@ -1371,9 +1371,9 @@ To create a Linux kernel image, that is bootable in LinuxBIOS, you have
 to use mkelfImage. The command line I used, looks like follows:
 
 \begin{verbatim}
-    objdir/sbin/mkelfImage ­t bzImagei386 ­kernel /boot/vmlinuz \
-             ­commandline="console=ttyS0,115200 root=/dev/hda3" \
-             ­initrd=/boot/initrd ­output vmlinuz.elf
+    objdir/sbin/mkelfImage t bzImagei386 kernel /boot/vmlinuz \
+             commandline="console=ttyS0,115200 root=/dev/hda3" \
+             initrd=/boot/initrd output vmlinuz.elf
 \end{verbatim}
 
 
@@ -1524,16 +1524,128 @@ CONs:
  \item only small number of devices come with OpenFirmware capable option roms
  \end{itemize}
 
+%
+% 13 image types
+%
+
+\section{Image types}
+There used to be one image type for LinuxBIOS, 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, Ying-Hai Liu, then of AMD, now of Sun, added Cache As Ram support (CAR) 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. 
+
+\begin{itemize}
+\item \begin{verbatim}USE_DCACHE_RAM\end{verbatim}
+
+Set to \texttt{1} to use Cache As Ram (CAR). Defaults to \texttt{0}
+
+\item \begin{verbatim}CONFIG_USE_INIT\end{verbatim}
+
+Set to \texttt{1} to figure this out. Defaults to \texttt{0}
+
+\item \begin{verbatim}CONFIG_USE_PRINTK_IN_CAR\end{verbatim}
+
+Set to \texttt{1} to use printk, instead of the primitive print functions, in CAR. Defaults to \texttt{0}
+
+\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. 
+
+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}
+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 CRT0\_INCLUDES variable. crt0.s is then assembled. 
+
+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: 
+\begin{verbatim}
+  [Nr] Name              Type            Addr     Off    Size   ES Flg Lk Inf Al
+  [ 0]                   NULL            00000000 000000 000000 00      0   0  0
+  [ 1] .ram              PROGBITS        ffff0000 001000 005893 00  WA  0   0  1
+  [ 2] .rom              PROGBITS        ffff5893 006893 00029d 00  AX  0   0 16
+  [ 3] .reset            PROGBITS        fffffff0 006ff0 000010 00   A  0   0  1
+  [ 4] .id               PROGBITS        ffffffd1 006fd1 00001f 00   A  0   0  1
+  [ 5] .shstrtab         STRTAB          00000000 007000 000030 00      0   0  1
+  [ 6] .symtab           SYMTAB          00000000 007170 000c30 10      7  37  4
+  [ 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. 
+\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. 
+
+\begin{itemize}
+\item PAYLOAD\_SIZE. Each image may have a different payload size. 
+\item \_ROMBASE Each image must have a different base in rom. 
+\item \_RESET Unclear what this is used for. 
+\item \_EXCEPTION\_VECTORS where an optional IDT might go.
+\item 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 USE\_FALLBACK\_IMAGE Whether this is a fallback or normal image
+\item ROM\_SECTION\_SIZE Essentially, the payload size. Soon to be deprecated. 
+\item ROM\_IMAGE\_SIZE Size of this image (i.e. fallback or normal image)
+\item ROM\_SIZE Total size of the ROM
+\item 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. 
+
+\subsubsection{boot sequence}
+We boot and start at fffffff0. We then jump to the entry point at \_start.  Protected\_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: 
+\begin{verbatim}
+        /* This is the primary cpu how should I boot? */
+        else if (do_normal_boot()) {
+                goto normal_image;
+        }
+        else {
+                goto fallback_image;
+        }
+ normal_image:
+        __asm__ volatile ("jmp __normal_image"
+                : /* outputs */
+                : "a" (bist), "b" (cpu_init_detectedx) /* inputs */
+                );
+
+ fallback_image:
+#if HAVE_FAILOVER_BOOT==1
+        __asm__ volatile ("jmp __fallback_image"
+                : /* outputs */
+                : "a" (bist), "b" (cpu_init_detectedx) /* inputs */
+                )
+#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. 
+\subsection{car images}
+\subsubsection{how it is built}
+\subsubsection{layout}
+\subsubsection{boot sequence}
+We boot and start at fffffff0. We then jump to the entry point at protected\_start (a clear misnomer, since we're not in protected mode at that 
+point). Protected\_start does an lgdt and jumps to \_\_protected\_start, at which point we are in protected mode. 
+
+\subsection{car + config\_use\_init images}
+\subsubsection{how it is built}
+\subsubsection{layout}
+\subsubsection{boot sequence}
+
+\subsection{failover}
 
 %
-% 13 Glossary
+% 14 Glossary
 %
 
 \section{Glossary}
 \begin{itemize}
 \item payload
 
-LinuxBIOS only cares about lowlevel machine initialization, but also has
+LinuxBIOS only cares about low level machine initialization, but also has
 very simple mechanisms to boot a file either from FLASHROM or IDE. That
 file, possibly a Linux Kernel, a boot loader or Etherboot, are called
 payload, since it is the first software executed that does not cope with