The wiki is being retired!
Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
- 1 Introduction
- 2 Recommended hardware and software tools for developers
- 3 Hardware Overview
- 4 coreboot Overview
- 5 Failover/Fallback/Normal images overview
- 6 Memory map
- 7 Serial output and the Super I/O
- 8 Northbridge
- 9 RAM init
- 10 Southbridge
- 11 Mainboard
- 12 Creating a new Target
- 13 Documentation and datasheets
This manual is intended for aspiring coreboot developers to help them get up to speed with the code base and the tasks required to add support for new chipsets, devices, and mainboards. It currently covers coreboot v2, but will be extended to also cover the development version coreboot v3 later.
Recommended hardware and software tools for developers
See Developer Manual/Tools for a list of recommended tools which are useful for coreboot users and developers.
The first time the CS register is loaded with a new value after a hardware reset, the processor will follow the normal rule for address translation in real-address mode (that is, [CS base address = CS segment selector * 16]). To insure that the base address in the CS register remains unchanged until the EPROM based software-initialization code is completed, the code must not contain a far jump or far call or allow an interrupt to occur (which would cause the CS selector value to be changed).
FWH/LPC Flash Memory
Modern mainboards are often equipped with Firmware Hub (
FWH) or Low Pin Count (
LPC) flash memory used to store the system bootloader ("BIOS"). Execution begins by fetching instructions 16 bytes below the flash memory's uppermost physical address.
View From The CPU: Intel Architecture
0xFFFFFFF0, start execution at
reset_vectorfrom src/cpu/x86/16bit/reset16.inc, which simply jumps to
_startfrom src/cpu/x86/16bit/entry16.inc, invalidates the TLBs, sets up a GDT for selector 0x08 (code) and 0x10 (data), switches to protected mode, and jumps to
__protected_start(setting the CS to the new selector 0x08). The selectors provide full flat access to the entire physical memory map.
__protected_startfrom src/cpu/x86/32bit/entry32.inc, sets all other segment registers to the 0x10 selector
- execution continues with various
- some CPUs enable their on-chip cache to be used temporarily as a scratch RAM (stack), e.g. cpu/amd/model_lx/cache_as_ram.inc
- the final
mainboardinitfragment is mainboard-specific, in 'C', called romstage.c. For non-cache-as-RAM targets, it is compiled with 'romcc'. It includes and uses other C-code fragments for:
- initializing MSRs, MTTRs, APIC
- setting up the Southbridge minimally ("early setup")
- setting up SuperIO serial
- initializing the console
- initializing RAM controller and RAM itself
- execution continues at
__mainfrom src/arch/i386/init/crt0.S.lb, where the non-romcc 'C' coreboot code is copied (possibly decompressed) to RAM, then the RAM entry point is jumped to.
- the RAM entry point is
_startarch/i386/lib/c_start.S, where new descriptor tables are set up, the stack and BSS are cleared, the IDT is initialized, and
hardwaremain( )is called (operation is now full 32-bit protected mode 'C' program with stack)
hardwaremain( )is from boot/hardwaremain.c, the console is initialized, devices are enumerated and initialized, configured and enabled
- the payload is called, either via
elfboot( )from boot/elfboot.c, or
filo( )from boot/filo.c
Failover/Fallback/Normal images overview
See also Section overlaps if you get section .id lma 0xffffef64 overlaps previous sections and similar errors.
On x86 systems, many memory ranges are reserved for special purposes or have some other peculiar properties. The article Developer Manual/Memory map has details about this fact.
Serial output and the Super I/O
The mainboard config.lb contains many build and platform configuration settings. One of the most important items is the mainboard device list.
A device needs to be listed in the mainboard config.lb if it requires more setup than standard PCI initialization (resource allocation). Typically, that includes the CPU, northbridge, southbridge, and SIO. These devices are usually required for system specific configuration as well as indicate the system bus structure (pci_domain).
When a device in config.lb is found during the coreboot PCI/system scan process the functions to do customized initialization are called via the device_operations and the chip_operations structures. You will find these structures in the devices source files.
Creating a new Target
To create a new mainboard target you have to add several files.
- Multiple files in src/mainboard/vendorname/mainboardname (replace vendorname and mainboardname, of course).
- A file targets/vendorname/mainboardname/Config.lb which specifies a few target-specific config options, e.g. the ROM chip size, the payload, etc.
Documentation and datasheets
Useful hardware/concepts documentation for developers
These external documents and slides explain fundamental concepts of hardware that coreboot supports.
- PCI Interrupts on x86 machines from John Baldwin
- PCI IRQ Routing on a Multiprocessor ACPI System at Microsoft's Windows Hardware Developer Central
System Managment Mode
- System Managment Mode Overview by Robery R. Collins
|This work is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version. This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.|