Difference between revisions of "Developer Manual"

From coreboot
Jump to navigation Jump to search
(→‎Serial output and the Super I/O: Some text and photos.)
m (Protected "Developer Manual" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite)))
(47 intermediate revisions by 15 users not shown)
Line 1: Line 1:
<div style="color: red">'''This is work in progress!'''</div>
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 covers coreboot v4.
== How to support a new board ==
People often ask how to support a new board. If you are willing to put in the effort to write the port, then there is a good chance that you will succeed. Supporting a new board that uses a chipset that is already supported by coreboot is much less work for obvious reasons than supporting a new board with an unsupported chipset. Don't expect a new board to be supported by developers, especially an Intel board just because you would like it supported. Supporting a new board can take from an hour to over a year of time. If you would like a new board supported then you should expect to do the work on the port yourself.
====Supporting a new board with the same cpu family, chipset and superIO====
To support a new board with an already supported chipset look for the most similar board in the coreboot tree to the new board that you wish to support. After you find the most similar board, look for the differences between your new board and the most similar board.
If your new board has the same cpu family, cpu socket, chipset and superIO then you can try the coreboot build for the supported board on the new board with a backup flash device and debugging turned on. Look at the debug output to determine where the boot process stops or what errors are encountered on the way. Common differences between boards with exactly the same cpu, chipset and superIO are IRQ routing, ACPI and flash write enable routines or jumpers. Make changes to the board configuration, ACPI or IRQ routing etc etc until you find the proper settings. This can take from an hour of time to a few months based upon your coding skills and hardware issues.
====Supporting a new board with the same cpu family, chipset but different superIO====
If your new board has the same cpu family, cpu socket, chipset but the superIO is different but it is a supported superIO then you will have to change the board config to use the different superIO. More on this later....
Common differences between boards with exactly the same cpu, chipset but a different superIO are IRQ routing, ACPI and flash write enable routines or jumpers. Make changes to the board configuration, ACPI or IRQ routing etc etc until you find the proper settings. This can take from an hour of time to a few months based upon your coding skills and hardware issues.
====Supporting a new board with a unsupported cpu, chipset or superIO====
If your new board uses a cpu, chipset or superIO not supported by coreboot then you will have a lot of work in front of you. You will need developer data sheets for the cpu, chipset and superIO. AMD has been releasing data sheets to the public that includes most of the information required to support a new cpu and chipset. AMD has also been releasing complete coreboot patches to many of their recent cpu's and chipsets. Many of the superIO vendors have public documents available. Intel has been closed about releasing specifications at a low enough level to support a new cpu or chipset. Specifications are generally only provided to high volume OEM's. New developers requesting data sheets might have to wait for several months after signing NDA's until they receive the specifications.

'''This is work in progress!'''
== Recommended hardware and software tools ==

== Introduction ==
See [[Developer Manual/Tools]] for a list of recommended tools which are useful for coreboot users and developers.

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

== LinuxBIOS Overview ==
=== Intel Architecture ===
==== Hardware Reset ====
<br />
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).
<br />
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 at '''reset_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.inc'''.
## '''(unlabeled)''' from '''cpu/x86/sse_enable.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, MTRRs, APIC.
## Setting up the southbridge minimally ("early setup").
## Setting up Super I/O serial.
## Initializing the console.
## Initializing RAM controller and RAM itself.
# Execution continues at '''__main''' from '''src/arch/x86/init/crt0_romcc_epilogue.inc''', 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''' in '''src/arch/x86/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 '''src/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 [[Developer Manual/Bootblock]]
== Reading Coreboot Crash Dumps Overview ==
See [[Developer Manual/Crashdump]]
== 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 ==
== Serial output and the Super I/O ==

The '''Super I/O''' is a chip found on most of today's mainboards which is &mdash; among other things &mdash; responsible for the serial ports of the mainboard (e.g. COM1, COM2). This chip 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]]).
See [[Developer Manual/Super IO]].
Image:Winbond w83977ef.jpg|Winbond W83977EF Super I/O.
Image:Ite it8705f.jpg|ITE IT8705F Super I/O.

== Northbridge ==
== Northbridge ==
Line 22: Line 89:
== RAM init ==
== RAM init ==

See [[Developer Manual/RAM init]].
* [http://www.simmtester.com/page/news/showpubnews.asp?num=101 Understanding DDR Serial Presence Detect (SPD) Table]
* [http://download.micron.com/pdf/datasheets/dram/sdram/512MbSDRAM.pdf Micron 512 MB SDRAM Datasheet] (PDF) -- contains some helpful explanations

== Southbridge ==
== Southbridge ==
Line 30: Line 95:
== Mainboard ==
== Mainboard ==

=== IRQ Table ===
=== devicetree.cb ===
The mainboard's '''devicetree.cb''' file 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 '''devicetree.cb''' if it requires more setup than standard PCI initialization (resource allocation). Typically, that includes the CPU, northbridge, southbridge, and Super I/O. These devices are usually required for system specific configuration as well as indicate the system bus structure ('''pci_domain''').
When a device in '''devicetree.cb''' 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.
See [[Creating A devicetree.cb]].
=== 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).
== Documentation and datasheets ==

== Creating a new Target ==
=== Useful hardware/concepts documentation for developers ===

== Miscellaneous Tips ==
These external documents and slides explain fundamental concepts of hardware that coreboot supports.

=== minicom ===
* [http://www.bsdcan.org/2007/schedule/attachments/13-PCI_Interrupts_for_x86_Machines_under_FreeBSD_John_Baldwin PCI Interrupts on x86 machines] from John Baldwin
* [http://www.microsoft.com/taiwan/whdc/archive/ACPI-MP.mspx PCI IRQ Routing on a Multiprocessor ACPI System] at Microsoft's Windows Hardware Developer Central
'''System Managment Mode'''
* [http://www.rcollins.org/ddj/Jan97/Jan97.html System Managment Mode Overview] by Robery R. Collins
=== Specific datasheets ===
See [[Datasheets]].

Latest revision as of 16:10, 1 September 2014