Developer Manual: Difference between revisions

From coreboot
Jump to navigation Jump to search
No edit summary
Line 3: Line 3:
== Introduction ==
== Introduction ==


This manual is intended for aspiring LinuxBIOS 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 LinuxBIOSv2, but will be extended to also cover the development version LinuxBIOSv3 later.
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.


== Hardware Overview ==
== Hardware Overview ==


== LinuxBIOS Overview ==
== coreboot Overview ==


== Serial output and the Super I/O ==
== Serial output and the Super I/O ==
Line 77: Line 77:
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).  
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 LinuxBIOS 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.
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 ===
=== Options.lb ===

Revision as of 15:04, 15 January 2008

This is work in progress!

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.

Hardware Overview

coreboot Overview

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.

Northbridge

RAM init

Resources:
SDRAM:

DDR SDRAM:

DDR2 SDRAM

DDR3 SDRAM

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.

GNU head 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.