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{defines}
100 There are variables that should never be definable by users, as changing them will break the build or the image. These are set
101 in MAINBOARD\_OPTIONS.
104 -DCONFIG_AP_IN_SIPI_WAIT=0 \
105 -DCONFIG_USE_PRINTK_IN_CAR=1 \
106 -DCONFIG_HAVE_HIGH_TABLES=1
108 \subsubsection{POST\_EVALUATION}
109 POST\_EVALUATION rules should be placed after this section:
111 ifdef POST_EVALUATION
113 to ensure that the values of variables are correct.
114 Here are the post-evaluation rules for this mainboard:
116 $(obj)/dsdt.c: $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
117 iasl -p dsdt -tc $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
120 $(obj)/mainboard/$(MAINBOARDDIR)/dsdt.o: $(obj)/dsdt.c
121 $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c $< -o $@
123 $(obj)/ssdt2.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci2.asl
124 iasl -p $(CURDIR)/pci2 -tc $(CONFIG_MAINBOARD)/dx/pci2.asl
125 perl -pi -e 's/AmlCode/AmlCode_ssdt2/g' pci2.hex
128 $(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl"
129 iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/
130 perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex
133 $(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl"
134 iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl
135 perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex
138 $(obj)/mainboard/$(MAINBOARDDIR)/auto.inc: $(src)/mainboard/$(MAINBOARDDIR)/rom.c $(obj)/option_table.h
139 $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c -S $(src)/mainboard/$(MAINBOARDDIR)/rom.c -o $@
140 perl -e 's/\.rodata/.rom.data/g' -pi $@
141 perl -e 's/\.text/.section .rom.text/g' -pi $@
144 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.
145 \subsubsection{devicetree.cb}
146 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
147 properly, as it defines topology and chips that can be defined no other way.
148 Let's go through the tree.
150 chip northbridge/amd/amdk8/root_complex
151 device apic_cluster 0 on
152 chip cpu/amd/socket_F
157 This topology is always somewhat confusing to newcomers, and even to coreboot veterans.
159 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
160 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
161 somewhere, since it runs memory.
164 What is the APIC? Northbridges always have an Advanced Programmable Interrupt Controller, and that {\it APIC cluster} is a topological connection to the
165 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
166 its own APIC, and will define any parameters needed. In this case, we have a northbridge of type
167 {\it northbridge/amd/amdk8/root\_complex}, with its own apic\_cluster device which we turn on,
168 which connects to a {\it cpu/amd/socket\_F},
169 which has an apic, which is on.
171 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
172 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
173 BIOSes) that the BSP be CPU 0; any CPU will do.
175 device pci_domain 0 on
176 chip northbridge/amd/amdk8
177 device pci 18.0 on # northbridge
178 # devices on link 0, link 0 == LDT 0
180 Here begins the pci domain, which usually starts with 0. Then there is the northbridge, which bridges to the PCI bus. On
181 Opterons, certain CPU control registers are managed in PCI config space in device 18.0 (BSP), 19.0 (AP), and up.
183 chip southbridge/amd/amd8132
184 # the on/off keyword is mandatory
185 device pci 0.0 on end
186 device pci 0.1 on end
187 device pci 1.0 on end
188 device pci 1.1 on end
191 This is the 8132, a bridge to a secondary PCI bus.
193 chip southbridge/amd/amd8111
194 # this "device pci 0.0" is the parent the next one
197 device pci 0.0 on end
198 device pci 0.1 on end
199 device pci 0.2 off end
200 device pci 1.0 off end
203 The 8111 is a bridge to other busses and to the legacy ISA devices such as superio.
206 chip superio/winbond/w83627hf
207 device pnp 2e.0 off # Floppy
212 device pnp 2e.1 off # Parallel Port
216 device pnp 2e.2 on # Com1
220 device pnp 2e.3 off # Com2
224 device pnp 2e.5 on # Keyboard
230 device pnp 2e.6 off # CIR
233 device pnp 2e.7 off # GAME_MIDI_GIPO1
238 device pnp 2e.8 off end # GPIO2
239 device pnp 2e.9 off end # GPIO3
240 device pnp 2e.a off end # ACPI
241 device pnp 2e.b on # HW Monitor
248 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
249 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.
251 device pci 1.1 on end
252 device pci 1.2 on end
254 More devices. These statements set up placeholders in the device tree.
257 chip drivers/i2c/i2cmux # pca9556 smbus mux
258 device i2c 18 on #0 pca9516 1
259 chip drivers/generic/generic #dimm 0-0-0
262 chip drivers/generic/generic #dimm 0-0-1
265 chip drivers/generic/generic #dimm 0-1-0
268 chip drivers/generic/generic #dimm 0-1-1
272 device i2c 18 on #1 pca9516 2
273 chip drivers/generic/generic #dimm 1-0-0
276 chip drivers/generic/generic #dimm 1-0-1
279 chip drivers/generic/generic #dimm 1-1-0
282 chip drivers/generic/generic #dimm 1-1-1
285 chip drivers/generic/generic #dimm 1-2-0
288 chip drivers/generic/generic #dimm 1-2-1
291 chip drivers/generic/generic #dimm 1-3-0
294 chip drivers/generic/generic #dimm 1-3-1
301 These are the i2c devices.
303 device pci 1.5 off end
304 device pci 1.6 off end
308 register "ide0_enable" = "1"
309 register "ide1_enable" = "1"
311 end # device pci 18.0
314 These "register" commands set controls in the southbridge.
316 device pci 18.0 on end
317 device pci 18.0 on end
319 These are the other two hypertransport links.
321 device pci 18.1 on end
322 device pci 18.2 on end
323 device pci 18.3 on end
325 The 18.1 devices are, again, northbridge control for various k8 functions.
329 That's it for the BSP I/O and HT busses. Now we begin the AP busses. Not much here.
331 chip northbridge/amd/amdk8
332 device pci 19.0 on # northbridge
333 chip southbridge/amd/amd8151
334 # the on/off keyword is mandatory
335 device pci 0.0 on end
336 device pci 1.0 on end
338 end # device pci 19.0
340 device pci 19.0 on end
341 device pci 19.0 on end
342 device pci 19.1 on end
343 device pci 19.2 on end
344 device pci 19.3 on end
351 # chip drivers/generic/debug
352 # device pnp 0.0 off end # chip name
353 # device pnp 0.1 on end # pci_regs_all
354 # device pnp 0.2 off end # mem
355 # device pnp 0.3 off end # cpuid
356 # device pnp 0.4 off end # smbus_regs_all
357 # device pnp 0.5 off end # dual core msr
358 # device pnp 0.6 off end # cache size
359 # device pnp 0.7 off end # tsc
364 This is a trick used to debug by creating entries in the device tree.
366 \subsection{cpu socket}
367 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
368 the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus
369 of all defines and Makefile controls for building the CPU components of a board.
371 \subsubsection{ cpu/Kconfig}
372 Defines variables. Current variables are:
373 \input{cpukconfig.tex}
374 Sources all Kconfig files in the vendor directories.
375 \subsubsection{ cpu/Makefile.inc}
376 Unconditionally sources all Makefile.inc in the vendor directories.
378 \subsection{cpu/$<$vendor$>$/Kconfig}
379 The only action currently taken is to source all Kconfig's in the
381 \subsection{cpu/$<$vendor$>$/Makefile.inc}
382 {\em Conditionally} source the socket directories.
385 subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F
388 CONFIG\_CPU\_AMD\_SOCKET\_F is set in a mainboard file.
390 \subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig}
391 Set variables that relate to this {\em socket}, and {\em any models that plug into this socket}. Note that
392 the socket, as much as possible, should control the models, because the models may plug into many sockets.
393 Socket\_F currently sets:
394 \input{socketfkconfig.tex}
396 It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced.
398 \subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig}
399 CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that
401 \subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc}
402 The Makefile.inc {\em unconditionally} specifies drivers and objects to be included in the build. There is no conditional
403 compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include {em all}
404 objects, because it is not possible to determine at build time what options may be needed for a given model CPU.
405 This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc.
407 \subsection{northbridge}
408 \subsubsection{northbridge/Kconfig}
409 No variables. Source all vendor directory Kconfigs.
410 \subsubsection{northbridge/Makefile.inc}
411 No variables. unconditionally include all vendor Makefile.inc
412 \subsubsection{northbridge/$<$vendor$>$/Kconfig}
413 No variables. Source all chip directory Kconfigs.
414 \subsubsection{northbridge/$<$vendor$>$/Makefile.inc}
415 No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
416 is the name of the part, e.g.
418 subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8
421 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
422 Typically a small number of variables. One defines the part name. Here is an example
423 of the variables defined for the K8.
425 config NORTHBRIDGE_AMD_AMDK8
429 config AGP_APERTURE_SIZE
433 config HAVE_HIGH_TABLES
437 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
438 Typically very small set of rules, and very simple.
439 Since this file is already conditionally included,
440 we don't need to test for the chipset CONFIG variable. We
441 can therefore test other variables (which is part of the reason
442 we set up conditional inclusion of this file, instead
443 of unconditionally including it). Here is an example from AMD K8.
444 Note that we can make a variable conditional on the ACPI tables.
446 driver-y += northbridge.o
447 driver-y += misc_control.o
448 obj-y += get_sblk_pci1234.o
449 obj-$(CONFIG_HAVE_ACPI_TABLES) += amdk8_acpi.o
452 \subsection{southbridge}
453 \subsubsection{southbridge/Kconfig}
454 No variables. Source all vendor directory Kconfigs.
455 \subsubsection{southbridge/Makefile.inc}
456 No variables. {\em Unconditionally} include all vendor Makefile.inc
457 \subsubsection{southbridge/$<$vendor$>$/Kconfig}
458 No variables. Source all chip directory Kconfigs.
459 \subsubsection{southbridge/$<$vendor$>$/Makefile.inc}
460 No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
461 is the name of the part, e.g.
463 subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111
466 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
467 Typically a small number of variables. One defines the part name. Here is an example
468 of the variables defined for the K8.
470 config SOUTHBRIDGE_AMD_AMD8111
475 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
476 Typically very small set of rules, and very simple.
477 Since this file is already conditionally included,
478 we don't need to test for the chipset CONFIG variable. We
479 can therefore test other variables (which is part of the reason
480 we set up conditional inclusion of this file, instead
481 of unconditionally including it). Here is an example from AMD 8111.
482 No conditionals in this one yet.
484 driver-y += amd8111.o
485 driver-y += amd8111_usb.o
486 driver-y += amd8111_lpc.o
487 driver-y += amd8111_ide.o
488 driver-y += amd8111_acpi.o
489 driver-y += amd8111_usb2.o
490 driver-y += amd8111_ac97.o
491 driver-y += amd8111_nic.o
492 driver-y += amd8111_pci.o
493 driver-y += amd8111_smbus.o
494 obj-y += amd8111_reset.o
497 \subsubsection{vendor and part}
498 \subsection{southbridge}
499 \subsubsection{vendor and part}
501 \subsection{drivers/i2c}
502 This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed.
503 To compile in one of these files, name the .o directory. E.g. in serengeti\_cheetah we have:
507 \subsubsection{vendor and part}