Difference between revisions of "Developer Manual"

Revision as of 12:53, 24 June 2009

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

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

1. at 0xFFFFFFF0, start execution at reset_vector from src/cpu/x86/16bit/reset16.inc, which simply jumps to _start
2. _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.
3. __protected_start from src/cpu/x86/32bit/entry32.inc, sets all other segment registers to the 0x10 selector
4. execution continues with various mainboardinit fragments:
   1. __fpu_start from cpu/x86/fpu/enable_fpu.inc
   2. (unlabeled) from cpu/x86/sse/enable_sse.inc
   3. 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
5. the final mainboardinit fragment is mainboard-specific, in 'C', called auto.c (or cache_as_ram_auto.c). It is compiled with 'romcc', and it includes and uses other C-code fragments for:
   1. initializing MSRs, MTTRs, APIC
   2. setting up the Southbridge minimally ("early setup")
   3. setting up SuperIO serial
   4. initializing the console
   5. initializing RAM controller and RAM itself
6. 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.
7. 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, and hardwaremain( ) is called (operation is now full 32-bit protected mode 'C' program with stack)
8. hardwaremain( ) is from boot/hardwaremain.c, the console is initialized, devices are enumerated and initialized, configured and enabled
9. the payload is called, either via elfboot( ) from boot/elfboot.c, or filo( ) from boot/filo.c

Memory map

On x86 systems, many memory ranges are reserved for special purposes or have some other peculiar properties. The article Memory map has details about this fact.

Serial output and the Super I/O

The Super I/O is a chip found on most of today's mainboards which is — among other things — responsible for the serial ports of the mainboard (e.g. COM1, COM2). This chip is usually the first thing you'll want to support, as it's required to get serial debugging output from the mainboard (via a null-modem cable and the proper software, e.g. minicom or CuteCom).

Winbond W83977EF Super I/O

ITE IT8705F Super I/O

The steps for adding support for a new Super I/O chip are:

• Add a directory src/superio/vendor/device (e.g. src/superio/winbond/w83627ehg).
• In that directory, add a file device_early_serial.c (e.g. w83627ehg_early_serial.c). This file will be responsible to setup a serial port on the mainboard so that you can get serial debugging output. This will work even before the RAM is initialized, thus is useful/required for debugging the RAM initialization process.
• In this file you now declare a function device_enable_serial() which enables the requested serial port. Example:

 static void w83627ehg_enable_serial(device_t dev, unsigned int iobase)
 {
        pnp_enter_ext_func_mode(dev);
        pnp_set_logical_device(dev);
        pnp_set_enable(dev, 0);
        pnp_set_iobase(dev, PNP_IDX_IO0, iobase);
        pnp_set_enable(dev, 1);
        pnp_exit_ext_func_mode(dev);
 }

• Mainboards which have this Super I/O chip, will call this function in their auto.c or cache_as_ram_auto.c file. Example:

 #include "superio/winbond/w83627ehg/w83627ehg_early_serial.c"
 [...]
 #define SERIAL_DEV PNP_DEV(0x2e, W83627EHG_SP1)
 [...]
 w83627ehg_enable_dev(SERIAL_DEV, TTYS0_BASE);
 uart_init();
 console_init();

Whether the Super I/O is at config address 0x2e (the usual case) or 0x4e (or some other address) is mainboard-dependent. You can find out the address by running superiotool.

Virtual logical devices

Some Super I/Os use register 0x30 of one logical device number (LDN) for more then one function enable. For example, it can be used to enable some GPIOs, GAME, MIDI etc. To overcome this issue a concept of virtual LDN has been introduced. Virtual LDNs can be used in coreboot to map the enable bit position in register 0x30 to virtual LDN, which will just enable the functionality map to that bit.

Original LDN always just switch on or off bit0 of register 0x30. Virtual LDN is created as follows. Low [7:0] bits are used to describe the original LDN. High [10:8] bits select the position of the bit enable in the register 0x30.

If LDN is 0x7 it will handle bit0 of register 0x30. If the (virtual) LDN is 0x107 it will handle bit1 of same register etc.

Northbridge

RAM init

One of the most important tasks of coreboot is to initialize your system RAM.

SDRAM

There are a number of steps you have to perform to properly initialize SDRAM. This depends on the chipset, as well as the DIMMs which are inserted into the mainboard (and their properties, such as CAS latencies, and so on).

Sample northbridge datasheets:

• http://support.intel.com/design/chipsets/810/
• http://support.intel.com/design/chipsets/datashts/290656.htm
• http://download.intel.com/design/chipsets/datashts/29065602.pdf

Sample SDRAM datasheets:

• http://www.micron.com/products/partdetail?part=MT48LC16M16A2BG-75
• http://download.micron.com/pdf/datasheets/dram/sdram/256MSDRAM.pdf

DDR

DDR2

DDR3

Resources

SDRAM:

• Intel SPD Standard
• Micron 512 MB SDRAM Datasheet (PDF) -- contains some helpful explanations

DDR SDRAM:

• JEDEC DDR SPD Standard (PDF)
• Understanding DDR Serial Presence Detect (SPD) Table
• Micron DDR400 Datasheet

DDR2 SDRAM

• JEDEC DDR2 Standard (PDF)
• JEDEC DDR2 SPD Standard (PDF)
• DDR2 DIMM SPD Definition

DDR3 SDRAM

• Understanding DDR3 Serial Presence Detect (SPD) Table

Note: Micron lists SPD values for all the memory they produce. This really helps when trying to trouble shoot memory and SPD values. Micron SPD Lookup

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

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.

Miscellaneous Tips

minicom

Minicom is not just a serial terminal. It was written long before the internet existed and electronic communication was only possible with a modem to a mailbox-computer. Minicom is written with the ncurses library and provides its magic via a text interface. Other than logging, it provides z-modem up- and download-capability.

CuteCom

This is an easy to use serial-terminal-program which is even able to write all communication into a log-file. It needs a computer with installed Qt-libs.

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

TODO.

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.