Motherboard Porting Guide

From coreboot
Revision as of 08:17, 26 January 2016 by PatrickGeorgi (talk | contribs) (remove references to lspnp. outdated, not very useful, and hard to obtain)
Jump to navigation Jump to search

The wiki is being retired!

Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!

Motherboard Porting Guide

Please note that this is WIP work.

HOWTO to find a way

  • find a model and manufacturer of your mobo
  • 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 svn://coreboot.org/flashrom/trunk flashrom )
  • make and install them (make; sudo make install) - you need at least libpci/pciutils
  • check that your distro have this tools and install them:
 # lspci
 # dmesg
 # acpitool
 # lsusb
 # acpidump
  • # modprobe msr
 (this is for one of the steps below) 
  • Do this commands as root (# remove for the easy copypasting):
 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 safe place, and also rom.bin file.
  • Find what chip does your mobo 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 [[1]] for more info on possible chip formats. If possible make a high-resolution (600dpi or higher) scan of motherboard. Make a scan, not a photo as cameras typically don't have enough resolution to identify individual chips.
  • try to find information - what EC (if on laptop) or Super I/O chip (if any) is used in your mobo (may be some info in Service Manuals or Disassembly guides)
  • try to find your Super I/O / EC chip datasheet

For laptop, additionally:

  • if you see that ectool return some fake stuff - like only 'FF' or '00' - so you have custom EC configuration, it's a hard work for support
  • if you see that ectool return looks like 'right' output - you have a big chances for support
  • you need to find from thease outputs Super I/O / EC chip name, or if not see this - disassembly your laptop

Preparing recovery method

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

  • In-system Programming. For more info consult [[2]]
  • Hotswap. Consult [[3]]

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 [[4]]. If you have a scanner, do a high-resolution scan of your board, it may be useful later.

Selecting Similar Board

Most important criteria for finding similar board is chipset. Look at northbridge (device 0:0.0) and southbridge (LPC controller) in the lspci output. grep through coreboot tree to find how those chipsets are named, then grep for 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) system type (desktop/laptop), SuperI/O and manufacturer.


Adding a new board

This is a two step process. If you mainboard already exists, skip to next section.

Adding a new vendor to tree

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

config VENDOR_FOO
      bool "Foo"

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

source "src/mainboard/foo/Kconfig"

Create a src/mainboard/foo/Kconfig, copy from other vendor, and change the vendor name. Delete all mainboards.

Adding a new motherboard to tree

Asume that vendor name is foo and board type is bar. Add new configuration item in src/mainboard/foo/Kconfig

config BOARD_FOO_BAR
       bool "BAR"

Add include for board specific config:

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

Adjusting contents of new board directory

Now copy your similar board and start adjusting. Your first stop is the Kconfig.

  • You need to change the condition 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 go to mainboard.c and adjust GPIO config based on inteltool dump above.
  • Now you can flash the 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 dont forget to change MAINBOARD_DIR and MAINBOARD_PART_NUMBER.