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 cpu_cluster
0 on
143 chip cpu/amd/socket_F
144 device lapic
0 on end
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 a CPU 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 cpu
\_cluster device which we turn on,
159 which connects to a
{\it cpu/amd/socket
\_F},
160 which has a local 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.
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
341 \subsection{cpu socket
}
342 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
343 the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus
344 of all defines and Makefile controls for building the CPU components of a board.
346 \subsubsection{ cpu/Kconfig
}
347 Defines variables. Current variables are:
348 \input{cpukconfig.tex
}
349 Sources all Kconfig files in the vendor directories.
350 \subsubsection{ cpu/Makefile.inc
}
351 Unconditionally sources all Makefile.inc in the vendor directories.
353 \subsection{cpu/$<$vendor$>$/Kconfig
}
354 The only action currently taken is to source all Kconfig's in the
356 \subsection{cpu/$<$vendor$>$/Makefile.inc
}
357 {\em Conditionally
} source the socket directories.
360 subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F
363 CONFIG
\_CPU\_AMD\_SOCKET\_F is set in a mainboard file.
365 \subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig
}
366 Set variables that relate to this
{\em socket
}, and
{\em any models that plug into this socket
}. Note that
367 the socket, as much as possible, should control the models, because the models may plug into many sockets.
368 Socket
\_F currently sets:
369 \input{socketfkconfig.tex
}
371 It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced.
373 \subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig
}
374 CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that
376 \subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc
}
377 The Makefile.inc
{\em unconditionally
} specifies drivers and objects to be included in the build. There is no conditional
378 compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include
{em all
}
379 objects, because it is not possible to determine at build time what options may be needed for a given model CPU.
380 This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc.
382 \subsection{northbridge
}
383 \subsubsection{northbridge/Kconfig
}
384 No variables. Source all vendor directory Kconfigs.
385 \subsubsection{northbridge/Makefile.inc
}
386 No variables. unconditionally include all vendor Makefile.inc
387 \subsubsection{northbridge/$<$vendor$>$/Kconfig
}
388 No variables. Source all chip directory Kconfigs.
389 \subsubsection{northbridge/$<$vendor$>$/Makefile.inc
}
390 No variables.
{\em Conditionally
} include all chipset Makefile.inc. The variable
391 is the name of the part, e.g.
393 subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8
396 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig
}
397 Typically a small number of variables. One defines the part name. Here is an example
398 of the variables defined for the K8.
400 config NORTHBRIDGE_AMD_AMDK8
404 config AGP_APERTURE_SIZE
408 \subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc
}
409 Typically very small set of rules, and very simple.
410 Since this file is already conditionally included,
411 we don't need to test for the chipset CONFIG variable. We
412 can therefore test other variables (which is part of the reason
413 we set up conditional inclusion of this file, instead
414 of unconditionally including it). Here is an example from AMD K8.
415 Note that we can make a variable conditional on the ACPI tables.
417 driver-y += northbridge.o
418 driver-y += misc_control.o
419 obj-y += get_sblk_pci1234.o
420 obj-$(CONFIG_HAVE_ACPI_TABLES) += amdk8_acpi.o
423 \subsection{southbridge
}
424 \subsubsection{southbridge/Kconfig
}
425 No variables. Source all vendor directory Kconfigs.
426 \subsubsection{southbridge/Makefile.inc
}
427 No variables.
{\em Unconditionally
} include all vendor Makefile.inc
428 \subsubsection{southbridge/$<$vendor$>$/Kconfig
}
429 No variables. Source all chip directory Kconfigs.
430 \subsubsection{southbridge/$<$vendor$>$/Makefile.inc
}
431 No variables.
{\em Conditionally
} include all chipset Makefile.inc. The variable
432 is the name of the part, e.g.
434 subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111
437 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig
}
438 Typically a small number of variables. One defines the part name. Here is an example
439 of the variables defined for the K8.
441 config SOUTHBRIDGE_AMD_AMD8111
446 \subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc
}
447 Typically very small set of rules, and very simple.
448 Since this file is already conditionally included,
449 we don't need to test for the chipset CONFIG variable. We
450 can therefore test other variables (which is part of the reason
451 we set up conditional inclusion of this file, instead
452 of unconditionally including it). Here is an example from AMD
8111.
453 No conditionals in this one yet.
455 driver-y += amd8111.o
456 driver-y += amd8111_usb.o
457 driver-y += amd8111_lpc.o
458 driver-y += amd8111_ide.o
459 driver-y += amd8111_acpi.o
460 driver-y += amd8111_usb2.o
461 driver-y += amd8111_ac97.o
462 driver-y += amd8111_nic.o
463 driver-y += amd8111_pci.o
464 driver-y += amd8111_smbus.o
465 obj-y += amd8111_reset.o
468 \subsubsection{vendor and part
}
469 \subsection{southbridge
}
470 \subsubsection{vendor and part
}
472 \subsection{drivers/i2c
}
473 This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed.
474 To compile in one of these files, name the .o directory. E.g. in serengeti
\_cheetah we have:
478 \subsubsection{vendor and part
}