Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1 | % |
| 2 | % This document is released under the GPL |
| 3 | % Initially written by Stefan Reinauer, <stepan@openbios.org> |
| 4 | % |
| 5 | |
| 6 | \documentclass[titlepage,12pt]{article} |
| 7 | \usepackage{a4} |
| 8 | \usepackage{graphicx} |
| 9 | \usepackage{url} |
| 10 | \usepackage[pdftex]{hyperref} |
| 11 | % \usepackage{makeidx} |
| 12 | % \makeindex |
| 13 | |
| 14 | \hypersetup{ |
| 15 | urlbordercolor={1 1 1}, |
| 16 | menubordercolor={1 1 1}, |
| 17 | linkbordercolor={1 1 1}, |
| 18 | colorlinks=false, |
| 19 | % pdfpagemode=None, % PDF-Viewer starts without TOC |
| 20 | % pdfstartview=FitH, |
| 21 | pdftitle={LinuxBIOS on AMD64}, |
| 22 | pdfauthor={Stefan Reinauer}, |
| 23 | pdfsubject={LinuxBIOS configuration and build process}, |
| 24 | pdfkeywords={LinuxBIOS, Opteron, AMD64, Athlon64, Build} |
| 25 | } |
| 26 | |
| 27 | |
| 28 | % \newcommand{\sh}[1]{\begin{verbatim}\texttt{#1}\end{verbatim}} |
| 29 | % \newcommand{\prog}[1]{\textit{#1}} |
| 30 | |
| 31 | \setlength{\parindent}{0pt} |
| 32 | |
| 33 | \title{LinuxBIOS on AMD64} |
| 34 | \author{Stefan Reinauer $<$stepan@openbios.org$>$} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 35 | \date{June 2nd, 2004} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 36 | |
| 37 | \begin{document} |
| 38 | |
| 39 | \maketitle |
| 40 | |
| 41 | \thispagestyle{empty} |
| 42 | |
| 43 | \tableofcontents |
| 44 | |
| 45 | \newpage |
| 46 | |
| 47 | % |
| 48 | % 1 Abstract |
| 49 | % |
| 50 | |
| 51 | \section{Abstract} |
| 52 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 53 | This document targets porting LinuxBIOS to new mainboards and creating |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 54 | custom firmware images using LinuxBIOS. It describes how to build |
| 55 | LinuxBIOS images for the AMD64 platform, including hypertransport |
| 56 | configuration and pertinent utilities. If you are missing information or |
| 57 | find errors in the following descriptions, contact |
| 58 | \href{mailto:stepan@openbios.org}{\textit{Stefan Reinauer $<$stepan@openbios.org$>$}} |
| 59 | |
| 60 | |
| 61 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 62 | % 2 Changes |
| 63 | % |
| 64 | |
| 65 | \section{Changes} |
| 66 | \begin{itemize} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 67 | \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$ |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 68 | \item 2004/02/10 acpi and option rom updates |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 69 | \item 2003/11/18 initial release |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 70 | \end{itemize} |
| 71 | |
| 72 | |
| 73 | |
| 74 | % |
| 75 | % 3 What is LinuxBIOS |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 76 | % |
| 77 | |
| 78 | \section{What is LinuxBIOS?} |
| 79 | |
| 80 | LinuxBIOS aims to replace the normal BIOS found on PCs, Alphas, and |
| 81 | other machines with a Linux kernel that can boot Linux from a cold |
| 82 | start. The startup code of an average LinuxBIOS port is about 500 lines |
| 83 | of assembly and 5000 lines of C. It executes 16 instructions to get into |
| 84 | 32bit mode and then performs DRAM and other hardware initializations |
| 85 | required before Linux can take over. |
| 86 | |
| 87 | The projects primary motivation initially was maintenance of large |
| 88 | clusters. Not surprisingly interest and contributions have come from |
| 89 | people with varying backgrounds. Nowadays a large and growing number of |
| 90 | Systems can be booted with LinuxBIOS, including embedded systems, |
| 91 | Desktop PCs and Servers. |
| 92 | |
| 93 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 94 | % 4 Build Requirements |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 95 | % |
| 96 | |
| 97 | \section{Build Requirements} |
| 98 | To build LinuxBIOS for AMD64 from the sources you need a recent Linux |
| 99 | system for x86 or AMD64. SUSE Linux 8.2 or 9.0 are known to work fine. |
| 100 | The following toolchain is recommended: |
| 101 | |
| 102 | \begin{itemize} |
| 103 | \item GCC 3.3.1 |
| 104 | \item binutils 2.14.90.0.5 |
| 105 | \item Python 2.3 |
| 106 | \item CVS 1.11.6 |
| 107 | \end{itemize} |
| 108 | |
| 109 | \textbf{NOTE:} Later versions should also work. Prior versions might lead to problems. |
| 110 | |
| 111 | \newpage |
| 112 | |
| 113 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 114 | % 5 Getting the Sources |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 115 | % |
| 116 | |
| 117 | \section{Getting the Sources} |
| 118 | |
| 119 | The latest LinuxBIOS sources are available via CVS. The CVS repository |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 120 | is maintained at SourceForge.net (the project name is \emph{FreeBIOS}). |
| 121 | First you should create a directory for your LinuxBIOS trees: |
| 122 | |
| 123 | { \small |
| 124 | \begin{verbatim} |
| 125 | $ mkdir linuxbios |
| 126 | $ cd linuxbios |
| 127 | \end{verbatim} |
| 128 | } |
| 129 | |
| 130 | You can get the entire source tree via CVS: |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 131 | |
| 132 | { \small |
| 133 | \begin{verbatim} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 134 | $ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freebios login |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 135 | \end{verbatim} |
| 136 | } |
| 137 | |
| 138 | Hit return when you are asked for a password. Then checkout (or update) |
| 139 | the freebios source tree as follows: |
| 140 | |
| 141 | { \small |
| 142 | \begin{verbatim} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 143 | $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/freebios co freebios2 |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 144 | \end{verbatim} |
| 145 | } |
| 146 | |
| 147 | Once the source tree is checked out, it can be updated with: |
| 148 | |
| 149 | { \small |
| 150 | \begin{verbatim} |
Stefan Reinauer | e4ff2a51 | 2006-08-23 10:52:12 +0000 | [diff] [blame] | 151 | % cvs update -Pd |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 152 | \end{verbatim} |
| 153 | } |
| 154 | |
| 155 | Due to recent problems with SourceForge's CVS infrastructure we set up a |
| 156 | snapshot site that keeps hourly source trees of the last four days. It |
| 157 | is available at \url{http://snapshots.linuxbios.org/}. |
| 158 | Due to major structural enhancements to \hbox{LinuxBIOS}, AMD64 support |
| 159 | is only available in the \texttt{freebios2} tree. This tree reflects (as |
| 160 | of November 2003) LinuxBIOS version 1.1.5 and will lead to LinuxBIOS 2.0 |
| 161 | when finished. Most x86 hardware is currently only supported by the |
| 162 | LinuxBIOS 1.0 tree. |
| 163 | |
| 164 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 165 | % 6 LinuxBIOS configuration overview |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 166 | % |
| 167 | |
| 168 | \section{LinuxBIOS configuration overview} |
| 169 | To support a large variety of existing hardware LinuxBIOS allows for a |
| 170 | lot of configuration options that can be tweaked in several ways: |
| 171 | |
| 172 | \begin{itemize} |
| 173 | \item |
| 174 | Firmware image specific configuration options can be set in the image |
| 175 | configuration file which is usually found in |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 176 | \texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$/}. Such |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 177 | options are the default amount of output verbosity during bootup, image |
| 178 | size, use of fallback mechanisms, firmware image size and payloads |
| 179 | (Linux Kernel, Bootloader...) The default configuration file name is |
| 180 | \texttt{Config.lb}, but LinuxBIOS allows multiple configurations to |
| 181 | reside in that directory. |
| 182 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 183 | \item Mainboard specific configuration options can be set in the |
| 184 | mainboard configuration file placed in |
| 185 | \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$}. The |
| 186 | mainboard configuration file is always called \texttt{Config.lb}. It |
| 187 | contains information on the onboard components of the mainboard like |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 188 | CPU type, northbridge, southbridge, hypertransport configuration and |
| 189 | SuperIO configuration. This configuration file also allows to include |
| 190 | addon code to hook into the LinuxBIOS initialization mechanism at |
| 191 | basically any point. |
| 192 | |
| 193 | \end{itemize} |
| 194 | |
| 195 | This document describes different approaches of changing and configuring the |
| 196 | LinuxBIOS source tree when building for AMD64. |
| 197 | |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 198 | % |
| 199 | % 7 Building LinuxBIOS |
| 200 | % |
| 201 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 202 | \section{Building LinuxBIOS} |
| 203 | One of the design goals for building LinuxBIOS was to keep object files |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 204 | out of the source tree in a separate place. This is mandatory for |
| 205 | building parallel LinuxBIOS images for several distinct mainboards |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 206 | and/or platforms. Therefore building LinuxBIOS consists of two steps: |
| 207 | \begin{itemize} |
| 208 | \item |
| 209 | creating a build tree which holds all files automatically created by the |
| 210 | configuration utility and the object files |
| 211 | \item |
| 212 | compiling the LinuxBIOS code and creating a flashable firmware image. |
| 213 | \end{itemize} |
| 214 | |
| 215 | The first of these two steps is accomplished by the \texttt{buildtarget} |
| 216 | script found in \texttt{freebios2/targets/}. To build LinuxBIOS for |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 217 | instance for the AMD Solo Athlon64 mainboard enter: |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 218 | |
| 219 | \begin{verbatim} |
| 220 | % cd freebios2/targets |
| 221 | % ./buildtarget amd/solo |
| 222 | \end{verbatim} |
| 223 | |
| 224 | This will create a directory containing a Makefile and other software |
| 225 | components needed for this build. The directory name is defined in the |
| 226 | firmware image specific configuration file. In the case of AMD's Solo |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 227 | mainboard the default directory resides in |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 228 | \texttt{freebios2/targets/amd/solo/solo}. To build the LinuxBIOS image, do |
| 229 | |
| 230 | \begin{verbatim} |
| 231 | % cd amd/solo/solo |
| 232 | % make |
| 233 | \end{verbatim} |
| 234 | |
| 235 | The LinuxBIOS image filename is specified in the firmware image specific |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 236 | configuration file. The default filename for AMD's Solo mainboard is |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 237 | \texttt{solo.rom}. |
| 238 | |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 239 | % |
| 240 | % 8 Programming LinuxBIOS to flash memory |
| 241 | % |
| 242 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 243 | \section{Programming LinuxBIOS to flash memory} |
| 244 | The image resulting from a LinuxBIOS build can be directly programmed to |
| 245 | a flash device, either using a hardware flash programmer or by using the |
| 246 | Linux flash driver devbios or mtd. This document assumes that you use a |
| 247 | hardware flash programmer. If you are interested in doing in-system |
| 248 | software flash programming, find detailed information: |
| 249 | |
| 250 | \begin{itemize} |
| 251 | \item \url{http://www.openbios.org/development/devbios.html} (/dev/bios) |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 252 | \item \url{http://www.linux-mtd.infradead.org/} (Memory Technology Device Subsystem MTD) |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 253 | \end{itemize} |
| 254 | |
| 255 | \newpage |
| 256 | |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 257 | % |
| 258 | % 9 LinuxBIOS configuration |
| 259 | % |
| 260 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 261 | \section{LinuxBIOS configuration} |
| 262 | The following chapters will cope with configuring LinuxBIOS. All |
| 263 | configuration files share some basic rules |
| 264 | \begin{itemize} |
| 265 | \item |
| 266 | The default configuration file name in LinuxBIOS is \texttt{Config.lb}. |
| 267 | \item |
| 268 | All variables used in a configuration file have to be declared in this |
| 269 | file with \texttt{uses VARNAME} before usage. |
| 270 | \item |
| 271 | Comments can be added on a new line by using the comment identifier |
| 272 | \texttt{\#} at the beginning of the line. |
| 273 | \item |
| 274 | LinuxBIOS distinguishes between statements and options. Statements cause |
| 275 | the LinuxBIOS configuration mechanism to act, whereas options set |
| 276 | variables that are used by the build scripts or source code. |
| 277 | \item |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 278 | Default configuration values can be set in the mainboard configuration |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 279 | files (keyword default) |
| 280 | \item |
| 281 | Option overrides to the default configuration can only be specified in |
| 282 | the build target configuration file |
| 283 | \texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$/Config.lb} |
| 284 | (keyword option) |
| 285 | \end{itemize} |
| 286 | |
| 287 | \subsection{Common Configuration Statements} |
| 288 | |
| 289 | \begin{itemize} |
| 290 | |
| 291 | \item \begin{verbatim}uses\end{verbatim} |
| 292 | |
| 293 | All local configuration variables have to be declared before they can be |
| 294 | used. Example: |
| 295 | \begin{verbatim} |
| 296 | uses ROM_IMAGE_SIZE |
| 297 | \end{verbatim} |
| 298 | |
| 299 | \textbf{NOTE:} Only configuration variables known to the configuration |
| 300 | system can be used in configuration files. LinuxBIOS checks |
| 301 | \texttt{freebios2/src/config/Options.lb} to see whether a configuration |
| 302 | variable is known. |
| 303 | |
| 304 | \item \begin{verbatim}default\end{verbatim} |
| 305 | |
| 306 | The \texttt{default} statement is used to set a configuration variable |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 307 | with an overridable default value. It is commonly used in mainboard |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 308 | configuration files. |
| 309 | |
| 310 | Example: |
| 311 | |
| 312 | \begin{verbatim} |
| 313 | default ROM_IMAGE_SIZE=0x10000 |
| 314 | \end{verbatim} |
| 315 | |
| 316 | It is also possible to assign the value of one configuration variable to |
| 317 | another one, i.e.: |
| 318 | |
| 319 | \begin{verbatim} |
| 320 | default FALLBACK_SIZE=ROM_SIZE |
| 321 | \end{verbatim} |
| 322 | |
| 323 | Also, simple expressions are allowed: |
| 324 | |
| 325 | \begin{verbatim} |
| 326 | default FALLBACK_SIZE=(ROM_SIZE - NORMAL_SIZE) |
| 327 | \end{verbatim} |
| 328 | |
| 329 | If an option contains a string, this string has to be protected with |
| 330 | quotation marks: |
| 331 | |
| 332 | \begin{verbatim} |
Stefan Reinauer | e4ff2a51 | 2006-08-23 10:52:12 +0000 | [diff] [blame] | 333 | default CC="gcc -m32" |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 334 | \end{verbatim} |
| 335 | |
| 336 | \item \begin{verbatim}option\end{verbatim} |
| 337 | |
| 338 | The \texttt{option} statement basically behaves identically to the |
| 339 | \texttt{default} statement. But unlike default it can only be used in |
| 340 | build target configuration files |
| 341 | (\texttt{freebios2/targets/$<$vendor$>$/$<$mainboard$>$}). The option |
| 342 | statement allows either to set new options or to override default values |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 343 | set with the default statement in a mainboard configuration file. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 344 | Syntax and application are the same as with default. |
| 345 | |
| 346 | \end{itemize} |
| 347 | |
| 348 | \subsection{Firmware image specific configuration} |
| 349 | LinuxBIOS allows to create different firmware images for the same |
| 350 | hardware. Such images can differ in the amount of output they produce, |
| 351 | the payload, the number of subimages they consist of etc. |
| 352 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 353 | The firmware image specific configuration file can be found in \\ |
| 354 | \texttt{freebios2/targets/$<$vendor$>$/<mainboard$>$}. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 355 | |
| 356 | \subsubsection{Firmware image specific keywords} |
| 357 | In addition to the above described keywords the following statements are |
| 358 | available in firmware image specific configuration files: |
| 359 | |
| 360 | \begin{itemize} |
| 361 | \item \begin{verbatim}romimage\end{verbatim} |
| 362 | |
| 363 | The \texttt{romimage} definition describes a single rom build within the |
| 364 | final LinuxBIOS image. Normally there are two romimage definitions per |
| 365 | LinuxBIOS build: \texttt{normal} and \texttt{fallback}. |
| 366 | |
| 367 | Each \texttt{romimage} section needs to specify a mainboard directory and a |
| 368 | payload. The mainboard directory contains the mainboard specific |
| 369 | configuration file and source code. It is specified relatively to |
| 370 | \texttt{freebios2/src/mainboard}. The payload definition is an absolute |
| 371 | path to a static elf binary (i.e Linux kernel or etherboot) |
| 372 | |
| 373 | \begin{verbatim} |
| 374 | romimage "normal" |
| 375 | option USE_FALLBACK_IMAGE=0 |
| 376 | option ROM_IMAGE_SIZE=0x10000 |
Stefan Reinauer | f8ee180 | 2008-01-18 15:08:58 +0000 | [diff] [blame] | 377 | option COREBOOT_EXTRA_VERSION=".0Normal" |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 378 | mainboard amd/solo |
| 379 | payload /suse/stepan/tg3ide_ |
| 380 | disk.zelf |
| 381 | end |
| 382 | \end{verbatim} |
| 383 | |
| 384 | \item \begin{verbatim}buildrom\end{verbatim} |
| 385 | |
| 386 | The \texttt{buildrom} statement is used to determine which of the |
| 387 | LinuxBIOS image builds (created using \texttt{romimage}) are packed |
| 388 | together to the final LinuxBIOS image. It also specifies the order of |
| 389 | the images and the final image size: |
| 390 | |
| 391 | \begin{verbatim} |
| 392 | buildrom ./solo.rom ROM_SIZE "normal" "fallback" |
| 393 | \end{verbatim} |
| 394 | |
| 395 | \end{itemize} |
| 396 | |
| 397 | |
| 398 | \subsubsection{Firmware image configuration options} |
| 399 | In addition to the definitions described above there are a number of |
| 400 | commonly used options. Configuration options set in the firmware image |
| 401 | specific configuration file can override default selections from the |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 402 | Mainboard specific configuration. See above examples about |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 403 | option on how to set them. |
| 404 | |
| 405 | \begin{itemize} |
| 406 | |
| 407 | \item \begin{verbatim}CC\end{verbatim} |
| 408 | |
| 409 | Target C Compiler. Default is \texttt{\$(CROSS\_COMPILE)gcc}. Set to |
Stefan Reinauer | e4ff2a51 | 2006-08-23 10:52:12 +0000 | [diff] [blame] | 410 | \texttt{gcc -m32} for compiling AMD64 LinuxBIOS images on an AMD64 |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 411 | machine. |
| 412 | |
| 413 | \item \begin{verbatim}CONFIG_CHIP_CONFIGURE \end{verbatim} |
| 414 | |
| 415 | Use new \textit{chip\_configure} method for configuring (nonpci) |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 416 | devices. Set to \texttt{1} for all AMD64 mainboards. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 417 | |
| 418 | \item \begin{verbatim}MAXIMUM_CONSOLE_LOGLEVEL\end{verbatim} |
| 419 | |
| 420 | Errors or log messages up to this level can be printed. Default is |
| 421 | \texttt{8}, minimum is \texttt{0}, maximum is \texttt{10}. |
| 422 | |
| 423 | \item \begin{verbatim}DEFAULT_CONSOLE_LOGLEVEL\end{verbatim} |
| 424 | |
| 425 | Console will log at this level unless changed. Default is \texttt{7}, |
| 426 | minimum is \texttt{0}, maximum is \texttt{10}. |
| 427 | |
| 428 | \item \begin{verbatim}CONFIG_CONSOLE_SERIAL8250\end{verbatim} |
| 429 | |
| 430 | Log messages to 8250 uart based serial console. Default is \texttt{0} |
| 431 | (don't log to serial console). This value should be set to \texttt{1} |
| 432 | for all AMD64 builds. |
| 433 | |
| 434 | \item \begin{verbatim}ROM_SIZE\end{verbatim} |
| 435 | |
| 436 | Size of final ROM image. This option has no default value. |
| 437 | |
| 438 | \item \begin{verbatim}FALLBACK_SIZE\end{verbatim} |
| 439 | |
| 440 | Fallback image size. Defaults to \texttt{65536} bytes. \textbf{NOTE:} |
| 441 | This does not include the fallback payload. |
| 442 | |
| 443 | \item \begin{verbatim}HAVE_OPTION_TABLE\end{verbatim} |
| 444 | |
| 445 | Export CMOS option table. Default is \texttt{0}. Set to \texttt{1} if |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 446 | your mainboard has CMOS memory and you want to use it to store |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 447 | LinuxBIOS parameters (Loglevel, serial line speed, ...) |
| 448 | |
Ed Swierk | be13dc7 | 2006-12-15 12:56:28 +0000 | [diff] [blame] | 449 | \item \begin{verbatim}CONFIG_ROM_PAYLOAD\end{verbatim} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 450 | |
Ed Swierk | be13dc7 | 2006-12-15 12:56:28 +0000 | [diff] [blame] | 451 | Boot image is located in ROM (as opposed to \texttt{CONFIG\_IDE\_PAYLOAD}, which |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 452 | will boot from an IDE disk) |
| 453 | |
| 454 | \item \begin{verbatim}HAVE_FALLBACK_BOOT\end{verbatim} |
| 455 | |
| 456 | Set to \texttt{1} if fallback booting is required. Defaults to |
| 457 | \texttt{0}. |
| 458 | |
| 459 | \end{itemize} |
| 460 | |
| 461 | |
| 462 | The following options should be used within a romimage section: |
| 463 | |
| 464 | \begin{itemize} |
| 465 | |
| 466 | \item \begin{verbatim}USE_FALLBACK_IMAGE\end{verbatim} |
| 467 | |
| 468 | Set to \texttt{1} to build a fallback image. Defaults to \texttt{0} |
| 469 | |
| 470 | \item \begin{verbatim}ROM_IMAGE_SIZE\end{verbatim} |
| 471 | |
| 472 | Default image size. Defaults to \texttt{65535} bytes. |
| 473 | |
Stefan Reinauer | f8ee180 | 2008-01-18 15:08:58 +0000 | [diff] [blame] | 474 | \item \begin{verbatim}COREBOOT_EXTRA_VERSION\end{verbatim} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 475 | |
| 476 | LinuxBIOS extra version. This option has an empty string as default. Set |
| 477 | to any string to add an extra version string to your LinuxBIOS build. |
| 478 | |
| 479 | \end{itemize} |
| 480 | |
| 481 | \newpage |
| 482 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 483 | \subsection{Mainboard specific configuration} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 484 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 485 | Mainboard specific configuration files describe the onboard |
| 486 | mainboard components, i.e. bridges, number and type of CPUs. They also |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 487 | contain rules for building the low level start code which is translated |
| 488 | using romcc and/or the GNU assembler. This code enables caches and |
| 489 | registers, early mtrr settings, fallback mechanisms, dram init and |
| 490 | possibly more. |
| 491 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 492 | \textbf{NOTE:} The \texttt{option} keyword can not be used in mainboard |
| 493 | specific configuration files. Options shall instead be set using the |
| 494 | \texttt{default} keyword so that they can be overridden by the image |
| 495 | specific configuration files if needed. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 496 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 497 | \subsubsection{Mainboard specific keywords} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 498 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 499 | The following statements are used in mainboard specific configuration |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 500 | files: |
| 501 | |
| 502 | \begin{itemize} |
| 503 | \item \begin{verbatim}arch\end{verbatim} |
| 504 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 505 | Sets the CPU architecture. This should be \texttt{i386} for AMD64 boards.\\ |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 506 | Example: |
| 507 | |
| 508 | \begin{verbatim} |
| 509 | arch i386 end |
| 510 | \end{verbatim} |
| 511 | |
| 512 | \item \begin{verbatim}cpu\end{verbatim} |
| 513 | |
| 514 | The cpu statement is needed once per possibly available CPU. In a |
| 515 | one-node system, write: |
| 516 | |
| 517 | \begin{verbatim} |
| 518 | cpu k8 "cpu0" end |
| 519 | \end{verbatim} |
| 520 | |
| 521 | \item \begin{verbatim}driver\end{verbatim} |
| 522 | |
| 523 | The \texttt{driver} keyword adds an object file to the driver section of a |
| 524 | LinuxBIOS image. This means it can be used by the PCI device |
| 525 | initialization code. Example: |
| 526 | |
| 527 | \begin{verbatim} |
| 528 | driver mainboard.o |
| 529 | \end{verbatim} |
| 530 | |
| 531 | \item \begin{verbatim}object\end{verbatim} |
| 532 | |
| 533 | The \texttt{object} keyword adds an object file to the LinuxBIOS image. |
| 534 | Per default the object file will be compiled from a \texttt{.c} file |
| 535 | with the same name. Symbols defined in such an object file can be used |
| 536 | in other object files and drivers. Example: |
| 537 | |
| 538 | \begin{verbatim} |
| 539 | object reset.o |
| 540 | \end{verbatim} |
| 541 | |
| 542 | \item \begin{verbatim}makerule\end{verbatim} |
| 543 | |
| 544 | This keyword can be used to extend the existing file creation rules |
| 545 | during the build process. This is useful if external utilities have to |
| 546 | be used for the build. LinuxBIOS on AMD64 uses romcc for it's early |
| 547 | startup code placed in auto.c. |
| 548 | |
| 549 | To tell the configuration mechanism how to build \texttt{romcc} files, |
| 550 | do: |
| 551 | |
| 552 | \begin{verbatim} |
| 553 | makerule ./auto.E |
Eric Biederman | 018d8dd | 2004-11-04 11:04:33 +0000 | [diff] [blame] | 554 | depends "$(MAINBOARD)/auto.c option_table.h ./romcc" |
Stefan Reinauer | e4ff2a51 | 2006-08-23 10:52:12 +0000 | [diff] [blame] | 555 | action "./romcc -E -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ |
Eric Biederman | 018d8dd | 2004-11-04 11:04:33 +0000 | [diff] [blame] | 556 | $(MAINBOARD)/auto.c -o $@" |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 557 | end |
| 558 | makerule ./auto.inc |
Eric Biederman | 018d8dd | 2004-11-04 11:04:33 +0000 | [diff] [blame] | 559 | depends "$(MAINBOARD)/auto.c option_table.h ./romcc" |
Stefan Reinauer | e4ff2a51 | 2006-08-23 10:52:12 +0000 | [diff] [blame] | 560 | action "./romcc -mcpu=k8 -O2 -I$(TOP)/src -I. $(CPPFLAGS) \ |
Eric Biederman | 018d8dd | 2004-11-04 11:04:33 +0000 | [diff] [blame] | 561 | $(MAINBOARD)/auto.c -o $@" |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 562 | end |
| 563 | \end{verbatim} |
| 564 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 565 | Each \texttt{makerule} section contains file dependencies (using the |
| 566 | texttt{depends} keyword) and an action that is taken when the dependencies |
| 567 | are satisfied (using the \texttt{action} keyword). |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 568 | |
| 569 | \item \begin{verbatim}mainboardinit\end{verbatim} |
| 570 | |
| 571 | With the mainboardinit keyword it's possible to include assembler code |
| 572 | directly into the LinuxBIOS image. This is used for early infrastructure |
| 573 | initialization, i.e. to switch to protected mode. Example: |
| 574 | |
| 575 | \begin{verbatim} |
| 576 | mainboardinit cpu/i386/entry16.inc |
| 577 | \end{verbatim} |
| 578 | |
| 579 | \item \begin{verbatim}ldscript\end{verbatim} |
| 580 | |
| 581 | The GNU linker ld is used to link object files together to a LinuxBIOS |
| 582 | ROM image. |
| 583 | |
| 584 | Since it is a lot more comfortable and flexible to use the GNU linker |
| 585 | with linker scripts (ldscripts) than to create complex command line |
| 586 | calls, LinuxBIOS features including linker scripts to control image |
| 587 | creation. Example: |
| 588 | |
| 589 | \begin{verbatim} |
| 590 | ldscript /cpu/i386/entry16.lds |
| 591 | \end{verbatim} |
| 592 | |
| 593 | |
| 594 | \item \begin{verbatim}dir\end{verbatim} |
| 595 | |
| 596 | LinuxBIOS reuses as much code between the different ports as possible. |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 597 | To achieve this, commonly used code can be stored in a separate |
| 598 | directory. For a new mainboard, it is enough to know that the code in |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 599 | that directory can be used as is. |
| 600 | |
| 601 | LinuxBIOS will also read a \texttt{Config.lb} file stored in that |
| 602 | directory. This happens with: |
| 603 | |
| 604 | \begin{verbatim} |
| 605 | dir /pc80 |
| 606 | \end{verbatim} |
| 607 | |
| 608 | |
| 609 | \item \begin{verbatim}config\end{verbatim} |
| 610 | |
| 611 | This keyword is needed by the new chip configuration scheme. Should be |
| 612 | used as: |
| 613 | |
| 614 | \begin{verbatim} |
| 615 | config chip.h |
| 616 | \end{verbatim} |
| 617 | |
| 618 | \item \begin{verbatim}register\end{verbatim} |
| 619 | The \texttt{register} keyword can occur in any section, passing |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 620 | additional \\ |
| 621 | parameters to the code handling the associated device. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 622 | Example: |
| 623 | |
| 624 | \begin{verbatim} |
| 625 | register "com1" = "{1, 0, 0x3f8, 4}" |
| 626 | \end{verbatim} |
| 627 | |
| 628 | \item \begin{verbatim}northbridge\end{verbatim} |
| 629 | |
| 630 | The \texttt{northbridge} keyword describes a system northbridge. Some |
| 631 | systems, like AMD64, can have more than one northbridge, i.e. one per |
| 632 | CPU node. Each northbridge is described by the path to the northbridge |
| 633 | code in LinuxBIOS (relative to \texttt{freebios2/src/northbridge}), i.e. |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 634 | \texttt{amd/amdk8} and a unique name (i.e \texttt{mc0}) \\ |
| 635 | Example: |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 636 | |
| 637 | \begin{verbatim} |
| 638 | northbridge amd/amdk8 "mc0" |
| 639 | [..] |
| 640 | end |
| 641 | \end{verbatim} |
| 642 | |
| 643 | \item \begin{verbatim}southbridge\end{verbatim} |
| 644 | |
| 645 | To simplify the handling of bus bridges in a LinuxBIOS system, all |
| 646 | bridges available in a system that are not northbridges (i.e AGP, IO, |
| 647 | PCIX) are seen as southbridges. |
| 648 | |
| 649 | Since from the CPUs point of view any southbridge is connected via the |
| 650 | northbridge, a southbridge section is declared within the northbridge |
| 651 | section of the north bridge it is attached to. |
| 652 | |
| 653 | Like the northbridge, any other bridge is described by the path to it's |
| 654 | driver code, and a unique name. If the described bridge is a |
| 655 | hypertransport device, the northbridge's hypertransport link it connects |
| 656 | to can be specified using the \texttt{link} keyword. Example: |
| 657 | |
| 658 | \begin{verbatim} |
| 659 | northbridge amd/amdk8 "mc0" |
| 660 | [..] |
| 661 | southbridge amd/amd8111 "amd8111" link 0 |
| 662 | [..] |
| 663 | end |
| 664 | [..] |
| 665 | end |
| 666 | \end{verbatim} |
| 667 | |
| 668 | \item \begin{verbatim}pci\end{verbatim} |
| 669 | |
| 670 | The \texttt{pci} keyword can only occur within a \texttt{northbridge} or |
| 671 | \texttt{southbridge} section. It is used to describe the PCI devices |
| 672 | that are provided by the bridge. Generally all bridge sections have a |
| 673 | couple of \texttt{pci} keywords. |
| 674 | |
| 675 | The first occurrence of the \texttt{pci} keyword tells LinuxBIOS where |
| 676 | the bridge devices start, relative to the PCI configuration space used |
| 677 | by the bridge. The following occurences of the \texttt{pci} keyword |
| 678 | describe the provided devices. |
| 679 | |
| 680 | Adding the option \texttt{on} or \texttt{off} to a PCI device will |
| 681 | enable or disable this device. This feature can be used if some bridge |
| 682 | devices are not wired to hardware outputs and thus are not used. |
| 683 | |
| 684 | Example: |
| 685 | |
| 686 | \begin{verbatim} |
| 687 | northbridge amd/amdk8 "mc1" |
| 688 | pci 0:19.0 |
| 689 | pci 0:19.0 |
| 690 | pci 0:19.0 |
| 691 | pci 0:19.1 |
| 692 | pci 0:19.2 |
| 693 | pci 0:19.3 |
| 694 | end |
| 695 | \end{verbatim} |
| 696 | |
| 697 | or |
| 698 | |
| 699 | \begin{verbatim} |
| 700 | southbridge amd/amd8111 "amd8111" link 0 |
| 701 | pci 0:0.0 |
| 702 | pci 0:1.0 on |
| 703 | pci 0:1.1 on |
| 704 | pci 0:1.2 on |
| 705 | pci 0:1.3 on |
| 706 | pci 0:1.5 off |
| 707 | pci 0:1.6 off |
| 708 | pci 1:0.0 on |
| 709 | pci 1:0.1 on |
| 710 | pci 1:0.2 on |
| 711 | pci 1:1.0 off |
| 712 | [..] |
| 713 | end |
| 714 | \end{verbatim} |
| 715 | |
| 716 | \item \begin{verbatim}superio\end{verbatim} |
| 717 | |
| 718 | SuperIO devices are basically handled like brigdes. They are taking |
| 719 | their driver code from \texttt{freebios2/src/superio/}. They don't |
| 720 | provide a PCI compatible configuration interface, but instead are ISA |
| 721 | PnP devices. Normally they are connected to a southbridge. If this is |
| 722 | the case, the \texttt{superio} section will be a subsection of the |
| 723 | \texttt{southbridge} section of the southbridge it is connected to. |
| 724 | Example: |
| 725 | |
| 726 | \begin{verbatim} |
Uwe Hermann | d86417b | 2006-10-24 23:00:42 +0000 | [diff] [blame] | 727 | superio nsc/pc87360 link 1 |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 728 | pnp 2e.0 |
| 729 | pnp 2e.1 |
| 730 | pnp 2e.2 |
| 731 | pnp 2e.3 |
| 732 | pnp 2e.4 |
| 733 | pnp 2e.5 |
| 734 | pnp 2e.6 |
| 735 | pnp 2e.7 |
| 736 | pnp 2e.8 |
| 737 | pnp 2e.9 |
| 738 | pnp 2e.a |
| 739 | register "com1" = "{1, 0, 0x3f8, 4}" |
| 740 | register "lpt" = "{1}" |
| 741 | end |
| 742 | \end{verbatim} |
| 743 | |
| 744 | \end{itemize} |
| 745 | |
| 746 | \newpage |
| 747 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 748 | \subsubsection{Mainboard specific configuration options} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 749 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 750 | The following options are commonly used in mainboard specific |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 751 | configuration files. |
| 752 | |
| 753 | They should be set using the \texttt{default} keyword: |
| 754 | |
| 755 | \begin{itemize} |
| 756 | |
| 757 | \item \begin{verbatim}HAVE_HARD_RESET\end{verbatim} |
| 758 | |
| 759 | If set to \texttt{1}, this option defines that there is a hard reset |
| 760 | function for this mainboard. This option is not defined per default. |
| 761 | |
| 762 | \item \begin{verbatim}HAVE_PIRQ_TABLE\end{verbatim} |
| 763 | |
| 764 | If set to \texttt{1}, this option defines that there is an IRQ Table for |
| 765 | this mainboard. This option is not defined per default. |
| 766 | |
| 767 | \item \begin{verbatim}IRQ_SLOT_COUNT\end{verbatim} |
| 768 | |
| 769 | Number of IRQ slots. This option is not defined per default. |
| 770 | |
| 771 | \item \begin{verbatim}HAVE_MP_TABLE\end{verbatim} |
| 772 | |
| 773 | Define this option to build an MP table (v1.4). The default is not to |
| 774 | build an MP table. |
| 775 | |
| 776 | \item \begin{verbatim}HAVE_OPTION_TABLE\end{verbatim} |
| 777 | |
| 778 | Define this option to export a CMOS option table. The default is not to |
| 779 | export a CMOS option table. |
| 780 | |
| 781 | \item \begin{verbatim}CONFIG_SMP\end{verbatim} |
| 782 | |
| 783 | Set this option to \texttt{1} if the mainboard supports symmetric |
| 784 | multiprocessing (SMP). This option defaults to \texttt{0} (no SMP). |
| 785 | |
| 786 | \item \begin{verbatim}CONFIG_MAX_CPUS\end{verbatim} |
| 787 | |
| 788 | If \begin{verbatim}CONFIG_SMP\end{verbatim} is set, this option defines |
| 789 | the maximum number of CPUs (i.e. the number of CPU sockets) in the |
| 790 | system. Defaults to \texttt{1}. |
| 791 | |
| 792 | \item \begin{verbatim}CONFIG_IOAPIC\end{verbatim} |
| 793 | |
| 794 | Set this option to \texttt{1} to enable IOAPIC support. This is |
| 795 | mandatory if you want to boot a 64bit Linux kernel on an AMD64 system. |
| 796 | |
| 797 | \item \begin{verbatim}STACK_SIZE\end{verbatim} |
| 798 | |
| 799 | LinuxBIOS stack size. The size of the function call stack defaults to |
| 800 | \texttt{0x2000} (8k). |
| 801 | |
| 802 | \item \begin{verbatim}HEAP_SIZE\end{verbatim} |
| 803 | |
| 804 | LinuxBIOS heap size. The heap is used when LinuxBIOS allocates memory |
| 805 | with malloc(). The default heap size is \texttt{0x2000}, but AMD64 boards |
| 806 | generally set it to \texttt{0x4000} (16k) |
| 807 | |
| 808 | \item \begin{verbatim}XIP_ROM_BASE\end{verbatim} |
| 809 | |
| 810 | Start address of area to cache during LinuxBIOS execution directly from |
| 811 | ROM. |
| 812 | |
| 813 | \item \begin{verbatim}XIP_ROM_SIZE\end{verbatim} |
| 814 | |
| 815 | Size of area to cache during LinuxBIOS execution directly from ROM |
| 816 | |
| 817 | \item \begin{verbatim}CONFIG_COMPRESS\end{verbatim} |
| 818 | |
| 819 | Set this option to \texttt{1} for a compressed image. If set to |
| 820 | \texttt{0}, the image is bigger but will start slightly faster (since no |
| 821 | decompression is needed). |
| 822 | |
| 823 | \end{itemize} |
| 824 | |
| 825 | |
| 826 | \newpage |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 827 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 828 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 829 | % 10. Tweaking the source code |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 830 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 831 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 832 | \section{Tweaking the source code} |
| 833 | Besides configuring the existing code it is sometimes necessary or |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 834 | desirable to tweak certain parts of LinuxBIOS by direct changes to the |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 835 | code. This chapter covers some possible enhancements and changes that |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 836 | are needed when porting LinuxBIOS to a new mainboard or just come |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 837 | handy now and then. |
| 838 | |
| 839 | \subsection{Hypertransport configuration} |
| 840 | Before LinuxBIOS is able to activate all CPUs and detect bridges |
| 841 | attached to these CPUs (and thus, see all devices attached to the |
| 842 | system) it has to initialize the coherent hypertransport devices. |
| 843 | |
| 844 | The current algorithms to do coherent hypertransport initialization are |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 845 | not fully, automatically evaluating the hypertransport chain graph. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 846 | Therefore the code needs to be adapted when porting LinuxBIOS to a new |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 847 | AMD64 mainboard. An example arrangement of hypertransport devices |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 848 | looks like this: |
| 849 | |
| 850 | \begin{figure}[htb] |
| 851 | \centering |
| 852 | \includegraphics[scale=1.0]{hypertransport.pdf} |
| 853 | \caption{Example: Hypertransport Link Connections} |
| 854 | \label{fix:hypertransport} |
| 855 | \end{figure} |
| 856 | |
| 857 | Each hypertransport device has one to three hypertransport links that |
| 858 | are used for device interconnection. These links are called LDT$[$012$]$, or |
| 859 | accordingly UP, ACROSS, DOWN. Communication between the hypertransport |
| 860 | devices can be freely routed, honoring the physical wiring. Teaching the |
| 861 | coherent hypertransport initialization algorithm this wiring happens in |
| 862 | two steps. |
| 863 | |
| 864 | \newpage |
| 865 | |
| 866 | \begin{enumerate} |
| 867 | \item Setting outgoing connections |
| 868 | The algorithm needs to know which outgoing port of a CPU node is |
| 869 | connected to the directly succeeding node. This is done in |
| 870 | \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/auto.c} |
| 871 | with a number of preprocessor defines (one define for two-node systems, |
| 872 | three defines for four-node systems). |
| 873 | |
| 874 | The ports in question are flagged with a circle in the graph for |
| 875 | illustration. For the example graph above (all outgoing connections are |
| 876 | realized using LDT1/ACROSS) the defines are: |
| 877 | |
| 878 | \begin{verbatim} |
| 879 | #define CONNECTION_0_1 ACROSS |
| 880 | #define CONNECTION_0_2 ACROSS |
| 881 | #define CONNECTION_1_3 ACROSS |
| 882 | \end{verbatim} |
| 883 | |
| 884 | \item Describing routing information between CPUs. |
| 885 | |
| 886 | There are basically three different message types for hypertransport |
| 887 | communication: |
| 888 | \begin{enumerate} |
| 889 | \item request packages |
| 890 | \item response packages |
| 891 | \item broadcast packages |
| 892 | \end{enumerate} |
| 893 | |
| 894 | These three message types are routed using different hypertransport |
| 895 | ports. The routing information is written to the AMD K8 routing table. |
| 896 | In an Nnode system this routing table consists of 3*N*N entries , one |
| 897 | for each message type and for each possible CPU --> CPU communication. For |
| 898 | simplicity LinuxBIOS keeps the 3 routing entries for each CPU --> CPU |
| 899 | communication in one machine word. The routing table of each node looks |
| 900 | like this: |
| 901 | |
| 902 | \begin{verbatim} |
| 903 | /* Routing Table for Node i |
| 904 | * |
| 905 | * F0: 0x40, 0x44, 0x48, 0x4c, 0x50, 0x54, 0x58, 0x5c |
| 906 | * i: 0, 1, 2, 3, 4, 5, 6, 7 |
| 907 | * |
| 908 | * [ 0: 3] Request Route |
| 909 | * [0] Route to this node |
| 910 | * [1] Route to Link 0 |
| 911 | * [2] Route to Link 1 |
| 912 | * [3] Route to Link 2 |
| 913 | * [11: 8] Response Route |
| 914 | * [0] Route to this node |
| 915 | * [1] Route to Link 0 |
| 916 | * [2] Route to Link 1 |
| 917 | * [3] Route to Link 2 |
| 918 | * [19:16] Broadcast route |
| 919 | * [0] Route to this node |
| 920 | * [1] Route to Link 0 |
| 921 | * [2] Route to Link 1 |
| 922 | * [3] Route to Link 2 |
| 923 | */ |
| 924 | \end{verbatim} |
| 925 | |
| 926 | The routing table is passed to the coherent hypertransport |
| 927 | initialization algorithm by defining a function called |
| 928 | \texttt{generate\_row()} in \texttt{auto.c}: |
| 929 | |
| 930 | \begin{verbatim} |
| 931 | static unsigned int generate_row |
| 932 | (uint8_t node, uint8_t row, uint8_t maxnodes) |
| 933 | \end{verbatim} |
| 934 | |
| 935 | This function is trivial if there is only one CPU in the system, since |
| 936 | no routing has to be done: |
| 937 | |
| 938 | \begin{verbatim} |
| 939 | static unsigned int generate_row |
| 940 | (uint8_t node, uint8_t row, uint8_t maxnodes) |
| 941 | { |
| 942 | return 0x00010101; /* default row entry */ |
| 943 | } |
| 944 | \end{verbatim} |
| 945 | |
| 946 | On a two-node system things look slightly more complicated. Since the |
| 947 | coherent hypertransport initialization algorithm works by consecutively |
| 948 | enabling CPUs, it contains routing information for driving the system |
| 949 | with one node and two nodes: |
| 950 | |
| 951 | \begin{verbatim} |
| 952 | static unsigned int generate_row |
| 953 | (uint8_t node, uint8_t row, uint8_t maxnodes) |
| 954 | { |
| 955 | uint32_t ret=0x00010101; /* default row entry */ |
| 956 | static const unsigned int rows_2p[2][2] = { |
| 957 | { 0x00050101, 0x00010404 }, |
| 958 | { 0x00010404, 0x00050101 } |
| 959 | }; |
| 960 | if(maxnodes>2) maxnodes=2; |
| 961 | if (!(node>=maxnodes || row>=maxnodes)) { |
| 962 | ret=rows_2p[node][row]; |
| 963 | } |
| 964 | return ret; |
| 965 | } |
| 966 | \end{verbatim} |
| 967 | |
| 968 | Systems with four nodes have to contain routing information for one, two |
| 969 | and four-node setups: |
| 970 | |
| 971 | \begin{verbatim} |
| 972 | static unsigned int generate_row |
| 973 | (uint8_t node, uint8_t row, uint8_t maxnodes) |
| 974 | { |
| 975 | uint32_t ret=0x00010101; /* default row entry */ |
| 976 | static const unsigned int rows_2p[2][2] = { |
| 977 | { 0x00030101, 0x00010202 }, |
| 978 | { 0x00010202, 0x00030101 } |
| 979 | }; |
| 980 | static const unsigned int rows_4p[4][4] = { |
| 981 | { 0x00070101, 0x00010202, 0x00030404, 0x00010204 }, |
| 982 | { 0x00010202, 0x000b0101, 0x00010208, 0x00030808 }, |
| 983 | { 0x00030808, 0x00010208, 0x000b0101, 0x00010202 }, |
| 984 | { 0x00010204, 0x00030404, 0x00010202, 0x00070101 } |
| 985 | }; |
| 986 | if (!(node>=maxnodes || row>=maxnodes)) { |
| 987 | if (maxnodes==2) |
| 988 | ret=rows_2p[node][row]; |
| 989 | if (maxnodes==4) |
| 990 | ret=rows_4p[node][row]; |
| 991 | } |
| 992 | return ret; |
| 993 | } |
| 994 | \end{verbatim} |
| 995 | \end{enumerate} |
| 996 | |
| 997 | \subsection{DRAM configuration} |
| 998 | Setting up the RAM controller(s) is probably the most complex part of |
| 999 | LinuxBIOS. Basically LinuxBIOS serially initializes all RAM controllers |
| 1000 | in the system, using SPDROM (serial presence detect) data to set |
| 1001 | timings, size and other properties. The SPD data is usually read |
| 1002 | utilizing the I2C SMBUS interface of the southbridge. |
| 1003 | |
| 1004 | There is one central data structure that describes the RAM controllers |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1005 | available on an AMD64 system and the associated devices: |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1006 | |
| 1007 | \begin{verbatim} |
| 1008 | struct mem_controller { |
| 1009 | unsigned node_id; |
| 1010 | device_t f0, f1, f2, f3; |
| 1011 | uint8_t channel0[4]; |
| 1012 | uint8_t channel1[4]; |
| 1013 | }; |
| 1014 | \end{verbatim} |
| 1015 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1016 | Available mainboard implementations and CPUs create the need to add |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1017 | special setup code to RAM initialization in a number of places. |
| 1018 | LinuxBIOS provides hooks to easily add code in these places without |
| 1019 | having to change the generic code. Whether these hooks have to be used |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1020 | depends on the mainboard design. In many cases the functions executed |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1021 | by the hooks just carry out trivial default settings or they are even |
| 1022 | empty. |
| 1023 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1024 | Some mainboard/CPU combinations need to trigger an additional memory |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1025 | controller reset before the memory can be initialized properly. This is, |
| 1026 | for example, used to get memory working on preC stepping AMD64 |
| 1027 | processors. LinuxBIOS provides two hooks for triggering onboard memory |
| 1028 | reset logic: |
| 1029 | |
| 1030 | \begin{itemize} |
| 1031 | \item \begin{verbatim}static void memreset_setup(void)\end{verbatim} |
| 1032 | \item \begin{verbatim}static void memreset(int controllers, const struct |
| 1033 | mem_controller *ctrl)\end{verbatim} |
| 1034 | \end{itemize} |
| 1035 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1036 | Some mainboards utilize an SMBUS hub or possibly other mechanisms to |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1037 | allow using a large number of SPDROMs and thus ram sockets. The result |
| 1038 | is that only the SPDROM information of one cpu node is visible at a |
| 1039 | time. The following function, defined in \texttt{auto.c}, is called every time |
| 1040 | before a memory controller is initialized and gets the memory controller |
| 1041 | information of the next controller as a parameter: |
| 1042 | |
| 1043 | \begin{verbatim} |
| 1044 | static inline void activate_spd_rom (const struct mem_controller *ctrl) |
| 1045 | \end{verbatim} |
| 1046 | |
| 1047 | The way SMBUS hub information is coded into the \texttt{mem\_controller} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1048 | structure is mainboard implementation specific and not |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1049 | described here. See \texttt{freebios2/src/mainboard/amd/quartet/auto.c} |
| 1050 | for an example. |
| 1051 | |
| 1052 | LinuxBIOS folks have agreed on SPD data being the central information |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1053 | source for RAM specific information. But not all mainboards/RAM |
| 1054 | modules feature a physical SPD ROM. To still allow an easy to use SPD |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1055 | driven setup, there is a hook that abstracts reading the SPD ROM |
| 1056 | ingredients that are used by the memory initialization mechanism: |
| 1057 | |
| 1058 | \begin{verbatim} |
| 1059 | static inline int spd_read_byte(unsigned device, unsigned address) |
| 1060 | \end{verbatim} |
| 1061 | |
| 1062 | This function, defined in \texttt{auto.c}, directly maps it's calls to |
| 1063 | \texttt{smbus\_read\_byte()} calls if SPD ROM information is read via |
| 1064 | the I2C SMBUS: |
| 1065 | |
| 1066 | \begin{verbatim} |
| 1067 | static inline int spd_read_byte(unsigned device, unsigned address) |
| 1068 | { |
| 1069 | return smbus_read_byte(device & 0xff, address); |
| 1070 | } |
| 1071 | \end{verbatim} |
| 1072 | |
| 1073 | If there is no SPD ROM available in the system design, this function |
| 1074 | keeps an array of SPD ROM information hard coded per logical RAM module. |
| 1075 | It returns the ´faked' SPD ROM information using device and address |
| 1076 | as indices to this array. |
| 1077 | |
| 1078 | |
| 1079 | \subsection {IRQ Tables} |
| 1080 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1081 | Mainboards that provide an IRQ table should have the following two |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1082 | variables set in their \texttt{Config.lb} file: |
| 1083 | |
| 1084 | \begin{verbatim} |
| 1085 | default HAVE_PIRQ_TABLE=1 |
| 1086 | default IRQ_SLOT_COUNT=7 |
| 1087 | \end{verbatim} |
| 1088 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1089 | This will make LinuxBIOS look for the file \\ |
| 1090 | \texttt{freebios2/src/mainboard/<vendor>/<mainboard>/irq\_tables.c} which |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1091 | contains the source code definition of the IRQ table. LinuxBIOS corrects |
| 1092 | small inconsistencies in the IRQ table during startup (checksum and |
| 1093 | number of entries), but it is not yet writing IRQ tables in a completely |
| 1094 | dynamic way. |
| 1095 | |
| 1096 | \textbf{NOTE:} To get Linux to understand and actually use the IRQ |
| 1097 | table, it is not always a good idea to specify the vendor and device id |
| 1098 | of the actually present interrupt router device. Linux 2.4 for example |
| 1099 | does not know about the interrupt router of the AMD8111 southbridge. In |
| 1100 | such cases it is advised to choose the vendor/device id of a compatible |
| 1101 | device that is supported by the Linux kernel. In case of the AMD8111 |
| 1102 | interrupt router it is advised to specify the AMD768/Opus interrupt |
| 1103 | controller instead (vendor id=\texttt{0x1022}, device id=\texttt{0x7443}) |
| 1104 | |
| 1105 | \subsection {MP Tables} |
| 1106 | |
| 1107 | LinuxBIOS contains code to create MP tables conforming the |
| 1108 | Multiprocessor Specification V1.4. To include an MP Table in a LinuxBIOS |
| 1109 | image, the following configuration variables have to be set (in the |
| 1110 | mainboard specific configuration file |
| 1111 | \texttt{freebios2/src/mainboard/<vendor><mainboard>/Config.lb}): |
| 1112 | |
| 1113 | \begin{verbatim} |
| 1114 | default CONFIG_SMP=1 |
| 1115 | default CONFIG_MAX_CPUS=1 # 2,4,.. |
| 1116 | default HAVE_MP_TABLE=1 |
| 1117 | \end{verbatim} |
| 1118 | |
| 1119 | LinuxBIOS will then look for a function for setting up the MP table in |
| 1120 | the file \texttt{freebios2/src/mainboard<vendor>/<mainboard>/mptable.c}: |
| 1121 | |
| 1122 | \begin{verbatim} |
| 1123 | void *smp_write_config_table(void *v, unsigned long * processor_map) |
| 1124 | \end{verbatim} |
| 1125 | |
| 1126 | MP Table generation is still somewhat static, i.e. changing the bus |
| 1127 | numbering will force |
| 1128 | you to adopt the code in mptable.c. This is subject to change in future |
| 1129 | revisions. |
| 1130 | |
Stefan Reinauer | c0f4e2a | 2004-02-10 16:53:55 +0000 | [diff] [blame] | 1131 | \subsection {ACPI Tables} |
| 1132 | |
| 1133 | There is initial ACPI support in LinuxBIOS now. Currently the only gain with |
| 1134 | this is the ability to use HPET timers in Linux. To achieve this, there is a |
| 1135 | framework that can generate the following tables: |
| 1136 | \begin{itemize} |
| 1137 | \item RSDP |
| 1138 | \item RSDT |
| 1139 | \item MADT |
| 1140 | \item HPET |
| 1141 | \end{itemize} |
| 1142 | |
| 1143 | To enable ACPI in your LinuxBIOS build, add the following lines to your |
| 1144 | configuration files: |
| 1145 | \begin{verbatim} |
| 1146 | uses HAVE_ACPI_TABLES |
| 1147 | [..] |
| 1148 | option HAVE_ACPI_TABLES=1 |
| 1149 | \end{verbatim} |
| 1150 | |
| 1151 | To keep Linux doing it's pci ressource allocation based on IRQ tables and MP |
| 1152 | tables, you have to specify the kernel parameter \texttt{pci=noacpi} otherwise |
| 1153 | your PCI devices won't get interrupts. |
| 1154 | It's likely that more ACPI support will follow, when there is need for certain |
| 1155 | features. |
| 1156 | |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1157 | \subsection{POST} |
| 1158 | LinuxBIOS has three different methods of handling POST codes. They can |
| 1159 | be triggered using configuration file options. |
| 1160 | \begin{itemize} |
| 1161 | \item |
| 1162 | \emph{Ignore POST completely}. No early code debugging is possible with |
| 1163 | this setting. Set the configuration variable \texttt{NO\_POST} to |
| 1164 | \texttt{1} to switch off all POST handling in LinuxBIOS. |
| 1165 | \item |
| 1166 | \emph{Normal IO port 80 POST}. This is the default behavior of |
| 1167 | LinuxBIOS. No configuration variables have to be set. To be able to see |
| 1168 | port 80 POST output, you need a POST expansion card for ISA or PCI. Port |
| 1169 | 80 POST allows simple debugging without any other output method |
| 1170 | available (serial interface or VGA display) |
| 1171 | \item |
| 1172 | \emph{Serial POST}. |
| 1173 | This option allows to push POST messages to the serial interface instead |
| 1174 | of using IO ports. \textbf{NOTE:} The serial interface has to be |
| 1175 | initialized before serial POST can work. To use serial POST, set the |
| 1176 | configuration variable \texttt{CONFIG\_SERIAL\_POST} to the value 1. |
| 1177 | \end{itemize} |
| 1178 | |
| 1179 | |
| 1180 | \subsection{HDT Debugging} |
| 1181 | If you are debugging your LinuxBIOS code with a Hardware Debug Tool |
| 1182 | (HDT), you can find the source code line for a given physical EIP |
| 1183 | address as follows: Look the address up in the file linuxbios.map. Then |
| 1184 | search the label Lxx in the file auto.inc created by romcc. The original |
| 1185 | source code file and line number is mentioned in auto.inc. |
| 1186 | |
| 1187 | |
| 1188 | \subsection{Device Drivers} |
| 1189 | With only a few data structures LinuxBIOS features a simple but flexible |
| 1190 | device driver interface. This interface is not intended for autonomously |
| 1191 | driving the devices but to initialize all system components so that they |
| 1192 | can be used by the booted operating system. |
| 1193 | |
| 1194 | Since nowadays most systems are PCI centric, the data structures used |
| 1195 | are tuned towards (onboard and expansion bus) PCI devices. Each driver |
| 1196 | consists of at least two structures. |
| 1197 | |
| 1198 | The \texttt{pci\_driver} structure maps PCI vendor/device id pairs to a |
| 1199 | second structure that describes a set of functions that together |
| 1200 | initialize and operate the device: |
| 1201 | |
| 1202 | \begin{verbatim} |
| 1203 | static void adaptec_scsi_init(struct device *dev) |
| 1204 | { |
| 1205 | [..] |
| 1206 | } |
| 1207 | static struct device_operations lsi_scsi_ops = { |
| 1208 | .read_resources = pci_dev_read_resources, |
| 1209 | .set_resources = pci_dev_set_resources, |
| 1210 | .enable_resources = pci_dev_enable_resources, |
| 1211 | .init = lsi_scsi_init, |
| 1212 | .scan_bus = 0, |
| 1213 | }; |
| 1214 | static struct pci_driver lsi_scsi_driver __pci_driver = { |
| 1215 | .ops = &lsi_scsi_ops, |
| 1216 | .vendor = 0xXXXX, |
| 1217 | .device = 0xXXXX, |
| 1218 | }; |
| 1219 | \end{verbatim} |
| 1220 | |
| 1221 | By separating the two structures above, M:N relations between compatible |
| 1222 | devices and drivers can be described. The driver source code containing |
| 1223 | above data structures and code have to be added to a LinuxBIOS image |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1224 | using the driver keyword in the mainboard specific configuration file \\ |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1225 | \texttt{freebios2/src/mainboard/<vendor>/<mainboard>/Config.lb}: |
| 1226 | |
| 1227 | \begin{verbatim} |
| 1228 | driver lsi_scsi.o |
| 1229 | \end{verbatim} |
| 1230 | |
| 1231 | \subsection{Bus Bridges} |
| 1232 | |
| 1233 | Currently all bridges supported in the LinuxBIOS2 tree are transparent |
| 1234 | bridges. This means, once the bridge is initialized, it's remote devices |
| 1235 | are visible on one of the PCI buses without special probing. LinuxBIOS |
| 1236 | supports also bridges that are nontransparent. The driver support code |
| 1237 | can provide a \texttt{scan\_bus} function to scan devices behind the bridge. |
| 1238 | |
| 1239 | \subsection{CPU Reset} |
| 1240 | When changing speed and width of hypertransport chain connections |
| 1241 | LinuxBIOS has to either assert an LDTSTOP or a reset to make the changes |
| 1242 | become active. Additionally Linux can do a firmware reset, if LinuxBIOS |
| 1243 | provides the needed infrastructure. To use this capability, define the |
| 1244 | option \texttt{HAVE\_HARD\_RESET} and add an object file specifying the |
| 1245 | reset code in your mainboard specific configuration file |
| 1246 | \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/Config.lb}: |
| 1247 | |
| 1248 | \begin{verbatim} |
| 1249 | default HAVE_HARD_RESET=1 |
| 1250 | object reset.o |
| 1251 | \end{verbatim} |
| 1252 | |
| 1253 | The C source file \texttt{reset.c} (resulting in \texttt{reset.o} |
| 1254 | during compilation) shall define the following function to take care |
| 1255 | of the system reset: |
| 1256 | |
| 1257 | \begin{verbatim} |
| 1258 | void hard_reset(void); |
| 1259 | \end{verbatim} |
| 1260 | |
| 1261 | See \texttt{freebios2/src/mainboard/arima/hdama/reset.c} for an example |
| 1262 | implementation. |
| 1263 | |
| 1264 | \newpage |
| 1265 | |
| 1266 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 1267 | % 11. LinuxBIOS Internals |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1268 | % |
| 1269 | |
| 1270 | \section{LinuxBIOS Internals} |
| 1271 | This chapter covers some of the internal structures and algorithms of |
| 1272 | LinuxBIOS that have not been mentioned so far. |
| 1273 | |
| 1274 | \subsection{Code Flow} |
| 1275 | |
| 1276 | \begin{figure}[htb] |
| 1277 | \centering |
| 1278 | \includegraphics[scale=0.7]{codeflow.pdf} |
| 1279 | \caption{LinuxBIOS rough Code Flow} |
| 1280 | \label{fix:codeflow} |
| 1281 | \end{figure} |
| 1282 | |
| 1283 | \newpage |
| 1284 | |
| 1285 | \subsection{Fallback mechanism} |
| 1286 | LinuxBIOS provides a mechanism to pack two different LinuxBIOS builds |
| 1287 | within one LinuxBIOS ROM image. Using the system CMOS memory LinuxBIOS |
| 1288 | determines whether the last boot with a default image succeeded and |
| 1289 | boots a failsafe image on failure. This allows insystem testing without |
| 1290 | the risk to render the system unusable. See |
| 1291 | \texttt{freebios2/src/mainboard/arima/hdama/failover.c} for example |
| 1292 | code. The fallback mechanism can be used with the \texttt{cmos\_util}. |
| 1293 | |
| 1294 | \subsection{(Un) Supported Standards} |
| 1295 | LinuxBIOS supports the following standards |
| 1296 | \begin{itemize} |
| 1297 | \item Multiprocessing Specification (MPSPEC) 1.4 |
Stefan Reinauer | c0f4e2a | 2004-02-10 16:53:55 +0000 | [diff] [blame] | 1298 | \item IRQ Tables (PIRQ) |
| 1299 | \item ACPI (initial support on AMD64) |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1300 | \item Elf Booting |
| 1301 | \end{itemize} |
| 1302 | However, the following standards are not supported until now, and will |
| 1303 | probably not be supported in future revisions: |
| 1304 | \begin{itemize} |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1305 | \item APM |
| 1306 | \end{itemize} |
| 1307 | |
| 1308 | \subsection{LinuxBIOS table} |
| 1309 | LinuxBIOS stores information about the system in a data structure called |
| 1310 | the LinuxBIOS table. This table can be read under Linux using the tool |
| 1311 | lxbios from the Lawrence Livermore National Laboratory. |
| 1312 | |
| 1313 | Get more information about lxbios and the utility itself at |
| 1314 | \url{http://www.llnl.gov/linux/lxbios/lxbios.html} |
| 1315 | |
| 1316 | \subsection{ROMCC limitations} |
| 1317 | ROMCC, part of the LinuxBIOS project, is a C compiler that translates to |
| 1318 | completely rommable code. This means the resulting code does not need |
| 1319 | any memory to work. This is one of the major improvements in LinuxBIOS |
| 1320 | V2, since it allows almost all code to be written in C. DRAM |
| 1321 | initialization can be factored and reused more easily among mainboards |
| 1322 | and platforms. |
| 1323 | |
| 1324 | Since no memory is available during this early initialization point, |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1325 | romcc has to map all used variables in registers for the time being. |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1326 | Same applies for their stack usage. Generally the less registers are |
| 1327 | used up by the algorithms, the better code can be factored, resulting in |
| 1328 | a smaller object size. Since getting the best register usage is an NP |
| 1329 | hard problem, some heuristics are used to get reasonable translation |
| 1330 | time. If you run out of registers during compilation, try to refactor |
| 1331 | your code. |
| 1332 | |
| 1333 | \subsection{CMOS handling} |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1334 | LinuxBIOS can use the mainboard's CMOS memory to store information |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1335 | defined in a data structure called the CMOS table . This information |
| 1336 | contains serial line speed, fallback boot control, output verbosity, |
| 1337 | default boot device, ECC control, and more. It can be easily enhanced by |
| 1338 | enhancing the CMOS table. This table, if present, is found at |
| 1339 | \texttt{freebios2/src/mainboard/$<$vendor$>$/$<$mainboard$>$/cmos.layout}. |
| 1340 | It describes the available options, their possible values and their |
| 1341 | position within the CMOS memory. The layout file looks as follows: |
| 1342 | \begin{verbatim} |
| 1343 | # startbit length config configID name |
| 1344 | [..] |
| 1345 | 392 3 e 5 baud_rate |
| 1346 | [..] |
| 1347 | |
| 1348 | # configid value human readable description |
| 1349 | 5 0 115200 |
| 1350 | 5 1 57600 |
| 1351 | 5 2 38400 |
| 1352 | 5 3 19200 |
| 1353 | 5 4 9600 |
| 1354 | 5 5 4800 |
| 1355 | 5 6 2400 |
| 1356 | 5 7 1200 |
| 1357 | |
| 1358 | \end{verbatim} |
| 1359 | |
| 1360 | To change CMOS values from a running Linux system, use the |
| 1361 | \texttt{cmos\_util}, provided by Linux Networks as part of the LinuxBIOS |
| 1362 | utilities suite. Get it at |
| 1363 | \textit{ftp://ftp.lnxi.com/pub/linuxbios/utilities/} |
| 1364 | |
| 1365 | \subsection {Booting Payloads} |
| 1366 | LinuxBIOS can load a payload binary from a Flash device or IDE. This |
| 1367 | payload can be a boot loader, like FILO or Etherboot, a kernel image, or |
| 1368 | any other static ELF binary. |
| 1369 | |
| 1370 | To create a Linux kernel image, that is bootable in LinuxBIOS, you have |
| 1371 | to use mkelfImage. The command line I used, looks like follows: |
| 1372 | |
| 1373 | \begin{verbatim} |
| 1374 | objdir/sbin/mkelfImage Ât bzImagei386 Âkernel /boot/vmlinuz \ |
| 1375 | Âcommandline="console=ttyS0,115200 root=/dev/hda3" \ |
| 1376 | Âinitrd=/boot/initrd Âoutput vmlinuz.elf |
| 1377 | \end{verbatim} |
| 1378 | |
| 1379 | |
| 1380 | This will create the file \texttt{vmlinuz.elf} from a distribution |
| 1381 | kernel, console redirected to the serial port and using an initial |
| 1382 | ramdisk. |
| 1383 | |
| 1384 | \subsection{Kernel on dhcp/tftp} |
| 1385 | |
| 1386 | One possible scenario during testing is that you keep your kernel (or |
| 1387 | any additional payload) on a different machine on the network. This can |
| 1388 | quickly be done using a DHCP and TFTP server. |
| 1389 | |
| 1390 | Use for example following \texttt{/etc/dhcpd.conf} (adapt to your |
| 1391 | network): |
| 1392 | |
| 1393 | \begin{verbatim} |
| 1394 | subnet 192.168.1.0 netmask 255.255.255.0 { |
| 1395 | range 192.168.1.0 192.168.1.31; |
| 1396 | option broadcastaddress 192.168.1.255; |
| 1397 | } |
| 1398 | |
| 1399 | ddnsupdatestyle adhoc; |
| 1400 | |
| 1401 | host hammer12 { |
| 1402 | hardware ethernet 00:04:76:EA:64:31; |
| 1403 | fixedaddress 192.168.1.24; |
| 1404 | filename "vmlinuz.elf"; |
| 1405 | } |
| 1406 | \end{verbatim} |
| 1407 | |
| 1408 | |
| 1409 | Additionally you have to run a \texttt{tftp} server. You can start one |
| 1410 | using \texttt{inetd}. To do this, you have to remove the comment from |
| 1411 | the following line in \texttt{/etc/inetd.conf}: |
| 1412 | |
| 1413 | \begin{verbatim} |
| 1414 | tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot |
| 1415 | \end{verbatim} |
| 1416 | |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1417 | Then put your kernel image \texttt{vmlinuz.elf} in \texttt{/tftpboot} on |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1418 | the \texttt{tftp} server. |
| 1419 | |
| 1420 | |
| 1421 | \newpage |
| 1422 | |
| 1423 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 1424 | % 12. Advanced Device Initialization Mechanisms |
| 1425 | % |
| 1426 | |
| 1427 | \section{Advanced Device Initialization Mechanisms} |
| 1428 | |
| 1429 | Like software, today's hardware is getting more and more complex. To |
| 1430 | stay flexible many hardware vendors start breaking hardware |
Stefan Reinauer | 2c83b27 | 2004-06-02 11:25:31 +0000 | [diff] [blame] | 1431 | compatibility to old standards like VGA. Thus, VGA is still supported by |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 1432 | most cards, but emulation has to be enabled by the firmware for the |
| 1433 | device to operate properly. Also, many expansion cards are small |
| 1434 | discrete systems that have to initialize attached ram, download |
| 1435 | controller firmware and similar. Without this initialization, an |
| 1436 | operating system can not take advantage of the hardware, so there needs |
| 1437 | to be a way to address this issue. There are several alternatives: |
| 1438 | |
| 1439 | \subsection{Native LinuxBIOS Support} |
| 1440 | |
| 1441 | For some devices (ie Trident Cyberblade 3d) there is native LinuxBIOS |
| 1442 | support This means there is a small driver bound to the PCI id of the |
| 1443 | device that is called after PCI device ressources are allotted. |
| 1444 | |
| 1445 | PROs: |
| 1446 | \begin{itemize} |
| 1447 | \item open source |
| 1448 | \item minimal driver |
| 1449 | \item early control |
| 1450 | \end{itemize} |
| 1451 | |
| 1452 | CONs: |
| 1453 | \begin{itemize} |
| 1454 | \item need an additional driver |
| 1455 | \item viable for onboard devices only |
| 1456 | \item not flexible for pci cards |
| 1457 | \end{itemize} |
| 1458 | |
| 1459 | \subsection{Using Native Linux Support} |
| 1460 | |
| 1461 | A simple way of getting a whole lot of drivers available for LinuxBIOS |
| 1462 | is to reuse Linux drivers by putting a Linux kernel to flash. This |
| 1463 | works, because no drivers are needed to get the Linux kernel (as opposed |
| 1464 | to store the kernel on a harddisk connected to isa/scsi/raid storage) |
| 1465 | |
| 1466 | PROs: |
| 1467 | \begin{itemize} |
| 1468 | \item large number of open source drivers |
| 1469 | \end{itemize} |
| 1470 | |
| 1471 | CONs: |
| 1472 | \begin{itemize} |
| 1473 | \item need Linux in Flash (BLOAT!) |
| 1474 | \item drivers expect devices to be initialized (LSI1020/1030) |
| 1475 | \item Linux only |
| 1476 | \item large flash needed (4MBit minimum, normal operations 8+ MBit) |
| 1477 | \end{itemize} |
| 1478 | |
| 1479 | |
| 1480 | \subsection{Running X86 Option ROMs} |
| 1481 | |
| 1482 | Especially SCSI/RAID controllers and graphics adapters come with a |
| 1483 | special option rom. This option rom usually contains x86 binary code |
| 1484 | that uses a legacy PCBIOS interface for device interaction. If this code |
| 1485 | gets executed, the device becomes operable in Linux and other operating |
| 1486 | systems. |
| 1487 | |
| 1488 | PROs: |
| 1489 | \begin{itemize} |
| 1490 | \item really flexible |
| 1491 | \item no need for additional drivers on firmware layer |
| 1492 | \item large number of supported devices |
| 1493 | \end{itemize} |
| 1494 | |
| 1495 | CONs: |
| 1496 | \begin{itemize} |
| 1497 | \item non-x86 platforms need complex emulation |
| 1498 | \item x86 platforms need legacy API |
| 1499 | \item outdated concept |
| 1500 | \end{itemize} |
| 1501 | |
| 1502 | |
| 1503 | \subsection{Running Open Firmware Option ROMs} |
| 1504 | |
| 1505 | Some PCI devices come with open firmware option roms. These devices are |
| 1506 | normally found in computers from SUN, Apple or IBM. Open Firmware is a |
| 1507 | instruction set architecture independent firmware standard that allows |
| 1508 | device specific initialization using simple, small, but flexible |
| 1509 | bytecode that runs with minimal footprint on all architectures that have |
| 1510 | an Open Firmware implementation. |
| 1511 | |
| 1512 | There is a free Open Firmware implementation available, called OpenBIOS, |
| 1513 | that runs on top of LinuxBIOS. See www.openbios.org |
| 1514 | |
| 1515 | PROs: |
| 1516 | \begin{itemize} |
| 1517 | \item architecture independence |
| 1518 | \item small footprint |
| 1519 | \item clean concept, less bugs |
| 1520 | \end{itemize} |
| 1521 | |
| 1522 | CONs: |
| 1523 | \begin{itemize} |
| 1524 | \item only small number of devices come with OpenFirmware capable option roms |
| 1525 | \end{itemize} |
| 1526 | |
| 1527 | |
| 1528 | % |
| 1529 | % 13 Glossary |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1530 | % |
| 1531 | |
| 1532 | \section{Glossary} |
| 1533 | \begin{itemize} |
| 1534 | \item payload |
| 1535 | |
| 1536 | LinuxBIOS only cares about lowlevel machine initialization, but also has |
| 1537 | very simple mechanisms to boot a file either from FLASHROM or IDE. That |
| 1538 | file, possibly a Linux Kernel, a boot loader or Etherboot, are called |
| 1539 | payload, since it is the first software executed that does not cope with |
| 1540 | pure initialization. |
| 1541 | |
| 1542 | \item flash device |
| 1543 | |
| 1544 | Flash devices are commonly used in all different computers since unlike |
| 1545 | ROMs they can be electronically erased and reprogrammed. |
| 1546 | \end{itemize} |
| 1547 | |
| 1548 | \newpage |
| 1549 | |
| 1550 | % |
Stefan Reinauer | f69f7e2 | 2004-02-10 17:30:04 +0000 | [diff] [blame] | 1551 | % 14 Bibliography |
Stefan Reinauer | 37414ca | 2003-11-22 15:15:47 +0000 | [diff] [blame] | 1552 | % |
| 1553 | |
| 1554 | \section{Bibliography} |
| 1555 | \subsection{Additional Papers on LinuxBIOS} |
| 1556 | |
| 1557 | \begin{itemize} |
| 1558 | \item { \small |
| 1559 | \textit{\url{http://www.linuxnetworx.com/products/linuxbios_white_paper.pdf}} |
| 1560 | } |
| 1561 | \item |
| 1562 | \textit{\url{http://www.linuxbios.org/papers/}} |
| 1563 | \item |
| 1564 | \textit{\url{http://www.lysator.liu.se/upplysning/fa/linuxbios.pdf}} |
| 1565 | \item |
| 1566 | \textit{\url{http://portal.acm.org/citation.cfm?id=512627}} |
| 1567 | \end{itemize} |
| 1568 | |
| 1569 | \subsection {Links} |
| 1570 | |
| 1571 | \begin{itemize} |
| 1572 | \item Etherboot: \textit{\url{http://www.etherboot.org/}} |
| 1573 | \item Filo: \textit{\url{http://te.to/~ts1/filo/}} |
| 1574 | \item OpenBIOS: \textit{\url{http://www.openbios.org/}} |
| 1575 | \end{itemize} |
| 1576 | |
| 1577 | \end{document} |