Developer Manual: Difference between revisions
Whiterocker (talk | contribs) |
|||
Line 40: | Line 40: | ||
## <code>(unlabeled)</code> from cpu/x86/sse/enable_sse.inc | ## <code>(unlabeled)</code> from cpu/x86/sse/enable_sse.inc | ||
## 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 | ## 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 <code>mainboardinit</code> fragment is mainboard-specific, in 'C', called | # the final <code>mainboardinit</code> fragment 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 | ## initializing MSRs, MTTRs, APIC | ||
## setting up the Southbridge minimally ("early setup") | ## setting up the Southbridge minimally ("early setup") |
Revision as of 19:50, 13 February 2010
Introduction
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.
Hardware Overview
Intel Architecture
Hardware Reset
The first instruction that is fetched and executed following a hardware reset is located at physical address 0xFFFFFFF0. This address is 16 bytes below the processors uppermost physical address. The EPROM containing the software-initialization code must be located at this address. The address 0xFFFFFFF0 is beyond the 1-MByte addressable range of the processor while in real-address mode. The processor is initialized to this starting address as follows. The CS register has two parts: the visible segment selector part and the hidden base address part. In real-address mode, the base address is normally formed by shifting the 16-bit segment selector value 4 bits to the left to produce a 20-bit base address. However, during a hardware reset, the segment selector in the CS register is loaded with 0xF000 and the base address is loaded with 0xFFFF0000. The starting address is thus formed by adding the base address to the value in the EIP register (that is, 0xFFFF0000 + 0xFFF0 = 0xFFFFFFF0). 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.
coreboot Overview
View From The CPU: Intel Architecture
- at
0xFFFFFFF0
, start execution atreset_vector
from src/cpu/x86/16bit/reset16.inc, which simply jumps to_start
_start
from 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_start
from src/cpu/x86/32bit/entry32.inc, sets all other segment registers to the 0x10 selector- execution continues with various
mainboardinit
fragments:__fpu_start
from cpu/x86/fpu/enable_fpu.inc(unlabeled)
from cpu/x86/sse/enable_sse.inc- 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
mainboardinit
fragment 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
__main
from 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
_start
arch/i386/lib/c_start.S, where new descriptor tables are set up, the stack and BSS are cleared, the IDT is initialized, andhardwaremain( )
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, orfilo( )
from boot/filo.c
Failover/Fallback/Normal images overview
See Anatomy of a Failover coreboot v2 Image.
See also Section overlaps if you get section .id lma 0xffffef64 overlaps previous sections and similar errors.
Memory map
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
See Developer Manual/Super IO.
Northbridge
RAM init
See Developer Manual/RAM init.
Southbridge
Mainboard
Config.lb
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.
Options.lb
irq_table.c
See Creating Valid IRQ Tables.
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.
Interrupts
- 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
Specific datasheets
See Datasheets.
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. |