Difference between revisions of "Developer Manual"
Jump to navigation
Jump to search
Whiterocker (talk | contribs) |
m (Protected "Developer Manual" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))) |
||
| (10 intermediate revisions by 5 users not shown) | |||
| Line 2: | Line 2: | ||
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. | 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. | |||
== Recommended hardware and software tools == | == Recommended hardware and software tools == | ||
| Line 36: | Line 56: | ||
# Execution continues with various '''mainboardinit''' fragments: | # Execution continues with various '''mainboardinit''' fragments: | ||
## '''__fpu_start''' from '''cpu/x86/fpu_enable.inc'''. | ## '''__fpu_start''' from '''cpu/x86/fpu_enable.inc'''. | ||
## '''(unlabeled)''' from '''cpu/x86/ | ## '''(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'''. | ## 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: | # 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, | ## Initializing MSRs, MTRRs, APIC. | ||
## Setting up the southbridge minimally ("early setup"). | ## Setting up the southbridge minimally ("early setup"). | ||
## Setting up Super I/O serial. | ## Setting up Super I/O serial. | ||
## Initializing the console. | ## Initializing the console. | ||
## Initializing RAM controller and RAM itself. | ## Initializing RAM controller and RAM itself. | ||
# Execution continues at '''__main''' from '''src/arch/ | # 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 '''arch/ | # 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 '''boot/hardwaremain.c''', the console is initialized, devices are enumerated and initialized, configured and enabled. | # '''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'''. | # The payload is called, either via '''elfboot()''' from '''boot/elfboot.c''', or '''filo()''' from '''boot/filo.c'''. | ||
| Line 52: | Line 72: | ||
See [[Developer Manual/Bootblock]] | See [[Developer Manual/Bootblock]] | ||
== Reading Coreboot Crash Dumps Overview == | |||
See [[Developer Manual/Crashdump]] | |||
== Memory map == | == Memory map == | ||
| Line 78: | Line 102: | ||
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. | 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 === | === irq_table.c === | ||