1 \documentclass[10pt,letterpaper]{article}
2 \usepackage[latin1]{inputenc}
7 \title{Kconfig usage in coreboot v2}
10 This document describes how to use Kconfig in v2. We describe our usage of Kconfig files, Makefile.inc files, when and where to use them, how to use them, and, interestingly, when and where not to use them.
11 \section{Kconfig variations}
12 Most Kconfig files set variables, which can be set as part of the Kconfig dialog. Not all Kconfig variables are set by the user, however; some are too dangerous. These are merely enabled by the mainboard.
14 For variables set by the user, see src/console/Kconfig.
16 For variables not set by the user, see src/mainboard/amd/serengeti\_cheetah/Kconfig. Users should never set such variables as the cache as ram base. These are highly mainboard dependent.
18 Kconfig files use the source command to include subdirectories. In most cases, save for limited cases described below, subdirectories have Kconfig files. They are always sourced unconditionally.
20 \section{Makefile and Makefile.inc}
21 There is only one Makefile, at the top level. All other makefiles are included as Makefile.inc. All the next-level Makefile.inc files are selected in the top level Makefile. Directories that are platform-independent are in BUILD-y; platform-dependent (e.g. Makefile.inc's that depend on architecture) are included in PLATFORM-y.
23 Make is not recursive. There is only one make process.
24 \subsection{subdirs usage}
25 Further includes of Makefile.inc, if needed, are done via subdirs-y commands. As in Linux, the subdirs can be conditional or unconditional. Conditional includes are done via subdirs-\$(CONFIG\_VARIABLE) usage; unconditional are done via subdirs-y.
27 We define the common rules for which variation to use below.
28 \subsection{object file specification}
29 There are several different types of objects specified in the tree. They are:
31 \item[obj]objects for the ram part of the code
32 \item[driver]drivers for the ram part. Drivers are not represented in the device tree but do have a driver struct attached in the driver section.
33 \item[initobj]seperately-compiled code for the ROM section of coreboot
35 These items are specified via the -y syntax as well. Conditional object inclusion is done via the -\$(CONFIG\_VARIABLE) syntax.
37 \section{Example: AMD serengeti cheetah}
38 \subsection{mainboard/Kconfig}
39 Defines Vendor variables. Currently defined variables are:
40 Sources all Kconfig files in the vendor directories.
41 \input{ mainboardkconfig.tex}
42 \subsection{mainboard/Makefile.inc}
43 There is none at this time.
44 \subsection{mainboard/$<$vendor$>$/Kconfig}
45 We use the amd as a model. The only action currently taken is to source all Kconfig's in the
47 \subsection{mainboard/$<$vendor$>$/Makefile.inc}
48 We use amd as a model. There is currently no Makefile.inc at this level.
49 \subsection{mainboard/$<$vendor$>$/$<$board$>$/Kconfig}
50 The mainboard Kconfig and Makefile.inc are designed to be the heart of the build. The defines
51 and rules in here determine everything about how a mainboard target is built.
52 We will use serengeti\_cheetah as a model. It defines these variables.
53 \input{ mainboardkconfig.tex}
54 \subsection{mainboard/$<$vendor$>$/$<$board$>$/Makefile.inc}
55 This is a fairly complex Makefile.inc. Because this is such a critical component, we are going to excerpt and take it piece by piece.
56 Note that this is the mainboard as of August, 2009, and it may change over time.
57 \subsubsection{objects}
58 We define objects in the first part. The mainbard itself is a driver and included unconditionally. Other objects are conditional:
60 driver-y += mainboard.o
62 #needed by irq_tables and mptable and acpi_tables
63 obj-y += get_bus_conf.o
64 obj-$(CONFIG_HAVE_MP_TABLE) += mptable.o
65 obj-$(CONFIG_HAVE_PIRQ_TABLE) += irq_tables.o
66 obj-$(CONFIG_HAVE_ACPI_TABLES) += dsdt.o
67 obj-$(CONFIG_HAVE_ACPI_TABLES) += acpi_tables.o
68 obj-$(CONFIG_HAVE_ACPI_TABLES) += fadt.o
70 #./ssdt.o is in northbridge/amd/amdk8/Config.lb
71 obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt2.o
72 obj-$(CONFIG_ACPI_SSDTX_NUM) += ssdt3.o
73 obj-$(CONFIG_HAVE_ACPI_TABLES) += ssdt4.o
74 driver-y += ../../../drivers/i2c/i2cmux/i2cmux.o
76 # This is part of the conversion to init-obj and away from included code.
80 \subsubsection{romcc legacy support}
81 We hope to move away from romcc soon, but for now, if one is using romcc, the Makefile.inc must define
82 crt0 include files (assembly code for startup, usually); and several ldscripts. These are taken directly from the
83 old Config.lb. Note that these use the -y syntax and can use the ability to be included conditionally.
85 crt0-y += ../../../../src/cpu/x86/16bit/entry16.inc
86 crt0-y += ../../../../src/cpu/x86/32bit/entry32.inc
87 crt0-y += ../../../../src/cpu/x86/16bit/reset16.inc
88 crt0-y += ../../../../src/arch/i386/lib/id.inc
89 crt0-y += ../../../../src/cpu/amd/car/cache_as_ram.inc
92 ldscript-y += ../../../../src/arch/i386/init/ldscript_fallback_cbfs.lb
93 ldscript-y += ../../../../src/cpu/x86/16bit/entry16.lds
94 ldscript-y += ../../../../src/cpu/x86/16bit/reset16.lds
95 ldscript-y += ../../../../src/arch/i386/lib/id.lds
96 ldscript-y += ../../../../src/arch/i386/lib/failover.lds
99 \subsubsection{POST\_EVALUATION}
100 POST\_EVALUATION rules should be placed after this section:
102 ifdef POST_EVALUATION
104 to ensure that the values of variables are correct.
105 Here are the post-evaluation rules for this mainboard:
107 $(obj)/dsdt.c: $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
108 iasl -p dsdt -tc $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
111 $(obj)/mainboard/$(MAINBOARDDIR)/dsdt.o: $(obj)/dsdt.c
112 $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c $< -o $@
114 $(obj)/ssdt2.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci2.asl
115 iasl -p $(CURDIR)/pci2 -tc $(CONFIG_MAINBOARD)/dx/pci2.asl
116 perl -pi -e 's/AmlCode/AmlCode_ssdt2/g' pci2.hex
119 $(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl"
120 iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/
121 perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex
124 $(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl"
125 iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl
126 perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex
129 $(obj)/mainboard/$(MAINBOARDDIR)/auto.inc: $(src)/mainboard/$(MAINBOARDDIR)/rom.c $(obj)/option_table.h
130 $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c -S $(src)/mainboard/$(MAINBOARDDIR)/rom.c -o $@
131 perl -e 's/\.rodata/.rom.data/g' -pi $@
132 perl -e 's/\.text/.section .rom.text/g' -pi $@
135 The last rule is for romcc, and, again, we hope to eliminate romcc usage and this rule soon. The first set of rules concern ACPI tables.
136 \subsubsection{devicetree.cb}
137 Most of the old Config.lb is gone, but one piece remains: the device tree specification. This tree is still required to build a mainboard
138 properly, as it defines topology and chips that can be defined no other way.
139 Let's go through the tree.
141 chip northbridge/amd/amdk8/root_complex
142 device apic_cluster 0 on
143 chip cpu/amd/socket_F
148 This topology is always somewhat confusing to newcomers, and even to coreboot veterans.
150 We root the tree at the pci-e {\it root complex}. There is always the question of how and where to root the tree. Over the years we
151 have found that the one part that never goes away is the root complex. CPU sockets may be empty or full; but there is always a northbridge
152 somewhere, since it runs memory.
155 What is the APIC? Northbridges always have an Advanced Programmable Interrupt Controller, and that {\it APIC cluster} is a topological connection to the
156 CPU socket. So the tree is rooted at the northbridge, which has a link to an apic cluster, and then the CPU. The CPU contains
157 its own APIC, and will define any parameters needed. In this case, we have a northbridge of type
158 {\it northbridge/amd/amdk8/root\_complex}, with its own apic\_cluster device which we turn on,
159 which connects to a {\it cpu/amd/socket\_F},
160 which has an apic, which is on.
162 Note that we do not enumerate all CPUs, even on this SMP mainboard. The reason is they may not all be there. The CPU we define here
163 is the so-called Boot Strap Processor, or BSP; the other CPUs will come along later, as the are discovered. We do not require (unlike many
164 BIOSes) that the BSP be CPU 0; any CPU will do.
166 device pci_domain 0 on
167 chip northbridge/amd/amdk8
168 device pci 18.0 on # northbridge
169 # devices on link 0, link 0 == LDT 0
171 Here begins the pci domain, which usually starts with 0. Then there is the northbridge, which bridges to the PCI bus. On
172 Opterons, certain CPU control registers are managed in PCI config space in device 18.0 (BSP), 19.0 (AP), and up.
174 chip southbridge/amd/amd8132
175 # the on/off keyword is mandatory
176 device pci 0.0 on end
177 device pci 0.1 on end
178 device pci 1.0 on end
179 device pci 1.1 on end
182 This is the 8132, a bridge to a secondary PCI bus.
184 chip southbridge/amd/amd8111
185 # this "device pci 0.0" is the parent the next one
188 device pci 0.0 on end
189 device pci 0.1 on end
190 device pci 0.2 off end
191 device pci 1.0 off end
194 The 8111 is a bridge to other busses and to the legacy ISA devices such as superio.
197 chip superio/winbond/w83627hf
198 device pnp 2e.0 off # Floppy
203 device pnp 2e.1 off # Parallel Port
207 device pnp 2e.2 on # Com1
211 device pnp 2e.3 off # Com2
215 device pnp 2e.5 on # Keyboard
221 device pnp 2e.6 off # CIR
224 device pnp 2e.7 off # GAME_MIDI_GIPO1
229 device pnp 2e.8 off end # GPIO2
230 device pnp 2e.9 off end # GPIO3
231 device pnp 2e.a off end # ACPI
232 device pnp 2e.b on # HW Monitor
239 The pnp refers to the many Plug N Play devices on a superio. 2e refers to the base I/O address of the superio, and the number following the
240 2e (i.e. 2e.1) is the Logical Device Number, or LDN. Each LDN has a common configuration (base, irq, etc.) and these are set by the statements under the LDN.
242 device pci 1.1 on end
243 device pci 1.2 on end
245 More devices. These statements set up placeholders in the device tree.
248 chip drivers/i2c/i2cmux # pca9556 smbus mux
249 device i2c 18 on #0 pca9516 1
250 chip drivers/generic/generic #dimm 0-0-0
253 chip drivers/generic/generic #dimm 0-0-1
256 chip drivers/generic/generic #dimm 0-1-0
259 chip drivers/generic/generic #dimm 0-1-1
263 device i2c 18 on #1 pca9516 2
264 chip drivers/generic/generic #dimm 1-0-0
267 chip drivers/generic/generic #dimm 1-0-1
270 chip drivers/generic/generic #dimm 1-1-0
273 chip drivers/generic/generic #dimm 1-1-1
276 chip drivers/generic/generic #dimm 1-2-0
279 chip drivers/generic/generic #dimm 1-2-1
282 chip drivers/generic/generic #dimm 1-3-0
285 chip drivers/generic/generic #dimm 1-3-1
292 These are the i2c devices.
294 device pci 1.5 off end
295 device pci 1.6 off end
299 register "ide0_enable" = "1"
300 register "ide1_enable" = "1"
302 end # device pci 18.0
305 These "register" commands set controls in the southbridge.
307 device pci 18.0 on end
308 device pci 18.0 on end
310 These are the other two hypertransport links.
312 device pci 18.1 on end
313 device pci 18.2 on end
314 device pci 18.3 on end
316 The 18.1 devices are, again, northbridge control for various k8 functions.
320 That's it for the BSP I/O and HT busses. Now we begin the AP busses. Not much here.
322 chip northbridge/amd/amdk8
323 device pci 19.0 on # northbridge
324 chip southbridge/amd/amd8151
325 # the on/off keyword is mandatory
326 device pci 0.0 on end
327 device pci 1.0 on end
329 end # device pci 19.0
331 device pci 19.0 on end
332 device pci 19.0 on end
333 device pci 19.1 on end
334 device pci 19.2 on end
335 device pci 19.3 on end
342 # chip drivers/generic/debug
343 # device pnp 0.0 off end # chip name
344 # device pnp 0.1 on end # pci_regs_all
345 # device pnp 0.2 off end # mem
346 # device pnp 0.3 off end # cpuid
347 # device pnp 0.4 off end # smbus_regs_all
348 # device pnp 0.5 off end # dual core msr
349 # device pnp 0.6 off end # cache size
350 # device pnp 0.7 off end # tsc
355 This is a trick used to debug by creating entries in the device tree.
357 \subsection{cpu socket}
358 The CPU socket is the key link from mainboard to its CPUs. Since many models of CPU can go in a socket, the mainboard mentions only
359 the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus
360 of all defines and Makefile controls for building the CPU components of a board.
362 \subsubsection{ cpu/Kconfig}
363 Defines variables. Current variables are:
364 \input{cpukconfig.tex}
365 Sources all Kconfig files in the vendor directories.
366 \subsubsection{ cpu/Makefile.inc}
367 Unconditionally sources all Makefile.inc in the vendor directories.
369 \subsection{cpu/$<$vendor$>$/Kconfig}
370 The only action currently taken is to source all Kconfig's in the
372 \subsection{cpu/$<$vendor$>$/Makefile.inc}
373 {\em Conditionally} source the socket directories.
376 subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F
379 CONFIG\_CPU\_AMD\_SOCKET\_F is set in a mainboard file.
381 \subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig}
382 Set variables that relate to this {\em socket}, and {\em any models that plug into this socket}. Note that
383 the socket, as much as possible, should control the models, because the models may plug into many sockets.
384 Socket\_F currently sets:
385 \input{socketfkconfig.tex}
387 It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced.
389 \subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig}
390 CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that
392 \subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc}
393 The Makefile.inc {\em unconditionally} specifies drivers and objects to be included in the build. There is no conditional
394 compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include {em all}
395 objects, because it is not possible to determine at build time what options may be needed for a given model CPU.
396 This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc.
398 \subsection{northbridge}
399 \subsubsection{northbridge/Kconfig}
400 No variables. Source all vendor directory Kconfigs.
401 \subsubsection{northbridge/Makefile.inc}
402 No variables. unconditionally include all vendor Makefile.inc
403 \subsubsection{northbridge/$<$vendor$>$/Kconfig}
404 No variables. Source all chip directory Kconfigs.
405 \subsubsection{northbridge/$<$vendor$>$/Makefile.inc}
406 No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
407 is the name of the part, e.g.
409 subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8
412 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
413 Typically a small number of variables. One defines the part name. Here is an example
414 of the variables defined for the K8.
416 config NORTHBRIDGE_AMD_AMDK8
420 config AGP_APERTURE_SIZE
424 config HAVE_HIGH_TABLES
428 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
429 Typically very small set of rules, and very simple.
430 Since this file is already conditionally included,
431 we don't need to test for the chipset CONFIG variable. We
432 can therefore test other variables (which is part of the reason
433 we set up conditional inclusion of this file, instead
434 of unconditionally including it). Here is an example from AMD K8.
435 Note that we can make a variable conditional on the ACPI tables.
437 driver-y += northbridge.o
438 driver-y += misc_control.o
439 obj-y += get_sblk_pci1234.o
440 obj-$(CONFIG_HAVE_ACPI_TABLES) += amdk8_acpi.o
443 \subsection{southbridge}
444 \subsubsection{southbridge/Kconfig}
445 No variables. Source all vendor directory Kconfigs.
446 \subsubsection{southbridge/Makefile.inc}
447 No variables. {\em Unconditionally} include all vendor Makefile.inc
448 \subsubsection{southbridge/$<$vendor$>$/Kconfig}
449 No variables. Source all chip directory Kconfigs.
450 \subsubsection{southbridge/$<$vendor$>$/Makefile.inc}
451 No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
452 is the name of the part, e.g.
454 subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111
457 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
458 Typically a small number of variables. One defines the part name. Here is an example
459 of the variables defined for the K8.
461 config SOUTHBRIDGE_AMD_AMD8111
466 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
467 Typically very small set of rules, and very simple.
468 Since this file is already conditionally included,
469 we don't need to test for the chipset CONFIG variable. We
470 can therefore test other variables (which is part of the reason
471 we set up conditional inclusion of this file, instead
472 of unconditionally including it). Here is an example from AMD 8111.
473 No conditionals in this one yet.
475 driver-y += amd8111.o
476 driver-y += amd8111_usb.o
477 driver-y += amd8111_lpc.o
478 driver-y += amd8111_ide.o
479 driver-y += amd8111_acpi.o
480 driver-y += amd8111_usb2.o
481 driver-y += amd8111_ac97.o
482 driver-y += amd8111_nic.o
483 driver-y += amd8111_pci.o
484 driver-y += amd8111_smbus.o
485 obj-y += amd8111_reset.o
488 \subsubsection{vendor and part}
489 \subsection{southbridge}
490 \subsubsection{vendor and part}
492 \subsection{drivers/i2c}
493 This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed.
494 To compile in one of these files, name the .o directory. E.g. in serengeti\_cheetah we have:
498 \subsubsection{vendor and part}