Difference between revisions of "Developer Manual"

From coreboot
Jump to navigation Jump to search
(Move hardware tools section from FAQ to the developer manual.)
m (Move)
Line 5: Line 5:
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.
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.


== Required hardware and software tools for developers ==
== Recommended hardware and software tools for developers ==


Before starting to work on coreboot support for a new mainboard and/or chipset you'll want a few development tools (both hardware and software). Not all of them are strictly required, a lot depends on your specific task and needs.
See [[Developer Manual/Tools]] for a list of recommended tools which are useful for coreboot users and developers.
 
=== Basic requirements ===
 
* A mainboard you want to port coreboot to.
* Datasheets
* A Linux/UNIX machine for development purposes
** The coreboot build environment is not well-supported on Windows. It may be possible to do it under cygwin but nobody has tried.
It's also handy to have one/some/all of the following:
=== PLAICE: Programmer, Logic Analyzer and In-Circuit Emulator ===
 
The [http://flash-plaice.wikispaces.com PLAICE] is a powerful in circuit development tool that combines the features of programming and emulating FLASH devices as well as high speed multi-channel logic analysis into one device.
 
The FLASH BIOS emulator feature will help speed development of coreboot porting since the developer will no longer have to wait for either swapping FLASH devices or for lengthy FLASH programming cycles.
 
The design will also perform as a multi-channel logic analyzer with a JAVA client.
 
The PLAICE will make use of an adapter cable that will interface to the mainboard via the FLASH BIOS socket or onto the pins of a soldered in place FLASH device. It may also be used to program a FLASH device or emulate a FLASH device in circuit. Since the PLAICE attaches directly to the in-circuit FLASH device, the FLASH may be programmed without the need to reverse engineer any FLASH WRITE/ENABLE "security through obscurity" protection schemes incorporated into a mainboard.
 
See also: [http://hardware.slashdot.org/article.pl?sid=07/05/01/0017244 Slashdot: An Open Source Hardware Development Tool].
 
=== Artecgroup programmable LPC dongle ===
 
See [http://www.artecgroup.com/products/hardware-products/programmable-lpc-dongle.html] and [http://www.opencores.org/projects.cgi/web/usb_dongle_fpga/overview].
 
=== PC Engines lpc1A ===
 
[http://pcengines.ch/lpc1a.htm This board] is most useful if you are working on machines from the ALIX family, but could also be useful if you can expose an LPC header on another board.
 
=== External EPROM/Flash programmer that can program the flash chip on your motherboard ===
 
External programmers are not always necessary. Use your mainboard as a programmer instead. Boot up with a known-good image, then unplug the (DIP32, PLCC32, or DIP8) ROM chip while powered on. Reflash that secondary piece and try a reboot. Many boards allow for more than one type of flash to be programmed, but clearly are less versatile than real programmers.
 
list
* [http://www.conitec.net/english/software.htm GALEP-4]: Has [http://www.conitec.net/hardware/down/galep-linux-alpha1.html beta Linux drivers] ~$300. See [[Galep IV]] for a description on how to get the more modern Windows software working in Linux with '''wine'''.
 
=== BIOS Savior ===
 
[[Image:Bios savior.jpg|thumb|right|An installed BIOS Savior.]]
 
The '''BIOS Savior''' is a tool that plugs into and replaces the original mainboard Flash device. The BIOS Savior has its own Flash device and a socket for the original mainboard Flash device (PLCC or DIP versions are available). It features a switch to allow the developer to choose between which Flash device is accessed by the mainboard during read and write cycles.
 
This device helps to minimize the amount of hot swapping required and reduces mechanical and electrical stress on the BIOS chips.
 
The BIOS Savior is available from:
* http://www.ioss.com.tw/web/English/RD1BIOSSavior.html
 
=== Top Hat Flash ===
 
A similar function is achieved by the "'''top hat flash'''" which comes at no extra cost with many Elitegroup, and some Gigabyte and Albatron mainboards like ECS KN3 SLI2 Extreme with MCP55 southbridge (which is getting severely out of stock around central europe as of 8/2007 unfortunately). After bootup, it can manually be lifted off the original BIOS chip, so the original BIOS can be reflashed after a failure. '''/rst''' is wired to '''/oe''' on the spare chip otherwise 1:1. Top hat flash is equipped with a Winbond W39V040AP FWH. It may rely on particular circuitry on the mainboard to operate.
 
[[Image:Top_hat_flash.JPG|thumb|right|Top Hat Flash, PCB side to flip over soldered-on PLCC.]]
 
=== Chip removal tools ===
 
If you're hot-swapping your BIOS chips (i.e., removing the chip while your computer is running, then inserting another one) you'll usually need some tools.
 
There are different tools for DIP and PLCC chips (see photos). You can find them in most electronics stores, usually. Both types cost roughly 5-10 Euros.
 
Another very nifty idea is [http://www.linuxbios.org/pipermail/linuxbios/2007-April/019809.html clipping off the needle point of normal office push pins], and then attaching them to (PLCC) ROM chips with super glue. That makes it pretty easy to insert and remove the ROM chips without extra tools.
 
Since after bootup, flash mem is not accessed anymore, you can even hot plug (plug in and out '''while PC powered on''') push pin flashes. This way you save an external EEPROM programmer and mimic the procedure of top hat flash. Make sure you do not short circuit anything, though.
 
<gallery>
Image:Plcc tool.jpg|PLCC32 BIOS removal tool.
Image:Dip tool.jpg|DIP32 BIOS removal tool.
Image:Pushpin roms 1.jpg|Push pins with cut off needles, attached to ROM chips with super glue.
Image:Pushpin roms 2.jpg|More push pins on ROM chips.
</gallery>
 
=== POST card ===
 
A POST card will save your life: it's the only output device (beside beeper) you have during the boot process. The term POST means '''Power On Self Test''' and comes from the original IBM specifications for the BIOS. Port 80 is a pre-defined I/O port to which programs can output a byte. The POST card displays the byte in hex on its 2 digit display. We use a lot of POST codes in coreboot, so if you can tell us the POST code you see, we will have some idea of what happened.
 
If your coreboot machine is working properly, you will see it count up from 0xd0 to 0xd9 (while it is gunzipping the kernel) and then display 0x98 (Linux idle loop). There are POST cards with ISA bus, PCI bus, USB und parallel port connectors (the latter for laptops).
 
Often they carry status LEDs for ISA/PCI signals such as: IRDY, BIOS-access, FRAME, OSC, PCI-CLK, RESET, 12V, -12V, 5V, -5V, 3.3V. Some cards were known to not function because the mainboard switches off the CLK on their slot after non-standard registration on PCI.
 
<gallery>
Image:Post card1.jpg|BIOS POST card for PCI.
Image:Post card2.jpg|BIOS POST card for PCI and ISA.
</gallery>
 
PCI POST cards can be found in various places.
 
See also [[FAQ#How_can_I_write_to_port_0x80_from_userspace.3F|How can I write to port 0x80 from userspace]].
 
* http://siliconkit.dnsalias.com/cart/index.tpcip.html
* http://www.elstonsystems.com/prod/pc_analyzer.html
* http://shopv2.elstonsystems.com/product_info.php/products_id/57
* http://www.uxd.com/trio.html
* http://www.soyousa.com/products/proddesc.php?id=261
 
=== Null-modem cable ===
 
A so-called '''null-modem cable''' is used for transmitting the output from a serial coreboot (or GRUB- or Linux-) console to another computer where a terminal program (such as [[minicom]]) can be used to display/save the messages.
 
<gallery>
Image:Null modem cable.jpg|A null-modem cable.
</gallery>
 
=== Compact Flash IDE adaptor ===
 
Solid state disks (e.g. CompactFlash cards) save time during the repeated boot process compared with regular hard disks.
 
* http://siliconkit.dnsalias.com/cart/index.tcfdp.html
* http://www.cwlinux.com/eng/products/products_ide2cf.php
* http://www.mini-box.com/s.nl/sc.8/category.14/.f
* http://www.acscontrol.com/Index_ACS.asp?Page=/Pages/Products/CompactFlash/IDE_To_CF_Adapter.htm
* http://www.pcengines.ch/cflash.htm
* http://www.psism.com/adcf.htm
* http://www.hsc-us.com/industrial/adapter/ATP.html (2xCF, one with hotswap!)
* http://www.mesanet.com/ (Choose DISK EMULATORS then CFADPTHD in the menu. 2xCF)
 
=== Oscilloscope ===
 
For hardware debugging purposes when it goes down the most atomic details. Consider '''logic analyzers''' as alternative.
 
=== In Circuit Emulator hardware debugger ===
 
Allows very time-saving burn/debug cycles with added tracing capabilities but somewhat costly.
 
=== coreboot SDK ===
 
* http://www.cwlinux.com/eng/products/products_sdk.php
 
=== In Circuit chip programmer ===
 
Should allow you to program your BIOS even if it is soldered to the motherboard.
 
* http://www.xeltek.com/pages.php?pageid=8
 
=== EPROM emulators ===
 
These hardware devices pretend to be an EEPROM chip.
 
* http://www.tech-tools.com/romtools.htm
* http://xtronics.com/memory/pktROM.htm
* http://www.tribalmicro.com/multirom/
* http://www.linuxselfhelp.com/HOWTO/Diskless-HOWTO-10.html (a larger list -- outdated)
 
=== USB debug devices ===
 
[[Image:PLX_NET20DC.jpg|thumb|right|PLX NET20DC USB Debug Device.]]
 
An alternative to a serial console may be a USB debug device. They are not so common, yet. Their advantage is higher speed than a serial console. One might hook an FPGA to it for profiling purposes or some automated checks. Accessing a USB debug device from within BIOS is not different than other USB devices, and is part of the USB standard.
 
See also [[EHCI Debug Port]].


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

Revision as of 12:53, 24 June 2009

Retrieved from "https://www.coreboot.org/index.php?title=Developer_Manual&oldid=8682"