Motherboard Porting Guide

Motherboard Porting Guide

Please note that this is WIP work.

HOWTO to find a way

• find the model and manufacturer of your motherboard.
• download these tools:

 # git clone http://review.coreboot.org/p/coreboot
 # superiotool (  cd coreboot/util/superiotool ; make ; sudo make install )
 # inteltool ( cd coreboot/util/inteltool ; make ; sudo make install )
 # ectool ( cd coreboot/util/ectool ; make ; sudo make install )
 # dmidecode ( cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/dmidecode co dmidecode )
 # msrtool ( cd coreboot/util/msrtool ; ./configure ; make ; sudo make install )
 # nvramtool ( cd coreboot/util/nvramtool ; make ; sudo make install )
 # flashrom ( svn co https://code.coreboot.org/svn/flashrom/trunk flashrom )

• make and install them (make; sudo make install) - you'll need at least libpci and pciutils
• check that your distro have these tools and install them:

 # lspci
 # dmesg
 # acpitool
 # lsusb
 # acpidump

• # modprobe msr

 (this will be needed for one of the steps below) 

• Perform these commands as root:

 lspci -nnvvvxxxx > lspci.log 2> lspci.err.log
 lsusb -vvv > lsusb.log 2> lsusb.err.log
 superiotool -deV > superiotool.log 2> superiotool.err.log
 inteltool -a > inteltool.log 2> inteltool.err.log
 ectool -i > ectool.log 2> ectool.err.log
 msrtool > msrtool.log 2> msrtool.err.log
 dmidecode > dmidecode.log 2> dmidecode.err.log
 biosdecode > biosdecode.log 2> biosdecode.err.log
 nvramtool -x > nvramtool.log 2> nvramtool.err.log
 dmesg > dmesg.log 2> dmesg.err.log
 flashrom -V -p internal:laptop=force_I_want_a_brick > flashrom_info.log 2> flashrom_info.err.log # this won't work on some vendor firmware
 flashrom -V -p internal:laptop=force_I_want_a_brick -r rom.bin > flashrom_read.log 2> flashrom_read.err.log # this won't work on some vendor firmware
 acpidump > acpidump.log 2> acpidump.err.log
 for x in /sys/class/sound/card0/hw*; do cat "$x/init_pin_configs" > pin_"$(basename "$x")"; done
 for x in /proc/asound/card0/codec#*; do cat "$x" > "$(basename "$x")"; done
 cat /proc/cpuinfo > cpuinfo.log 2> cpuinfo.err.log
 cat /proc/ioports > ioports.log 2> ioports.err.log
 cat /sys/class/input/input*/id/bustype > input_bustypes.log

• Save all logs in a safe place, as well as the rom.bin file.
• Find what chip does your motherboard use. The name of the chip is present in flashrom_info.log but is not always exact as some chips have several packaging variants (e.g. SOIC-16, SOIC-8 and TSOP). Consult this page for more info on possible chip formats. If possible make a high-resolution (600dpi or higher) scan of the motherboard. Make a scan, not a photo, as cameras typically lack enough resolution to properly identify individual chips.
• try to find information about which EC (if on laptop) or Super I/O chip (if any) is used in your mther board (You may also find some info in Service Manuals or Disassembly Guides)
• try to find the datasheets for your Super I/O / EC chip

For laptop, additionally:

• if you see that ectool returns some fake stuff, like only 'FF' or '00', then you have a custom EC configuration and it'll be a harder work for supporting it.
• if you see that ectool return looks like 'right' output - you have a big chance for support
• you need to figure out the name of the Super I/O / EC chip based on the above log outputs. If you can't find it on the logs, then you'll have to disassemble your laptop to look at the actual chips.

Preparing recovery method

Inevitably when you develop coreboot there will be unbootable builds and so you'll need a way to unbrick your machine after installing a failed image. There are several ways to do so. Main ones are:

• In-system Programming. For more info consult this page.
• Hotswap. Consult this page.

In any case you have to locate the flash chip. Note the chipname from flashrom output. Teardown your system and find that chip. For how it usually looks like, consult this page. If you have a scanner, take a high-resolution scan of your motherboard since it may be useful later.

Selecting a Similar Board

The most important criteria for finding a similar board is the chipset. Look at northbridge (device 0:0.0) and southbridge (LPC controller) in the lspci output. Use grep on the coreboot tree to find how those chipsets are named, and then grep for the chipset name (case-insensitive) to find a board which uses it. If there are several of them, try to match (in order of decreasing importance) the system type (desktop/laptop), Super I/O and manufacturer.

Adding a new board

This is a two step process. If your mainboard already exists in the coreboot source tree, skip to next section.

Adding a new vendor to the tree

Create a directory in src/mainboard with the same name as the vendor name. Add to src/mainboard/Kconfig a new vendor entry. The rest of this example uses "foo" vendor.

config VENDOR_FOO
      bool "Foo"

Add also an include for the new Kconfig file which holds the vendor motherboards in the vendor directory:

source "src/mainboard/foo/Kconfig"

Create a src/mainboard/foo/Kconfig file, copying it from some other vendor, and then change the vendor name. Delete all mainboards.

Adding a new motherboard to the tree

Assume in these examples that the vendor name is foo and the board type is bar. Add a new configuration item in src/mainboard/foo/Kconfig:

config BOARD_FOO_BAR
       bool "BAR"

Add include a board specific config:

source "src/mainboard/foo/bar/Kconfig"

Adjusting the contents of the new board directory

Now copy the files of your similar board and start adjusting them. Your first stop is the Kconfig file.

• You need to change the conditional statement in the first line to match your board:

-if BOARD_VENDOR_BAR +if BOARD_VENDOR_BAZ

• Change MAINBOARD_DIR and names
• Change device options to match your config
• Next stop is mainboard.c where you should adjust the GPIO config based on the inteltool dump performed above.
• Now you can build it, flash the resulting image and see what fails.
• Later adjust hda_verb.h to get sound working properly (use initial pin dumps for reference).

Look through the options and adjust.

Adjust Kconfig to fit the new vendor/model name and don't forget to change MAINBOARD_DIR and MAINBOARD_PART_NUMBER.