Difference between revisions of "Motherboard Porting Guide"

From coreboot
Jump to: navigation, search
m (add new board)
(HOWTO to find a way)
 
(9 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
Please note that this is WIP work.
 
Please note that this is WIP work.
  
=== Selecting Similar Board ===
+
== HOWTO to find a way ==
  
TODO.
+
* 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
 +
  # lspnp
 +
  # lsusb
 +
  # acpidump
 +
* Do this commands (# remove for the easy copypasting):
 +
  lspci -nnvvvxxxx > lspci.log
 +
  lspnp -vv > lspnp.log
 +
  lsusb -vvv > lsusb.log
 +
  superiotool -deV > superiotool.log
 +
  inteltool -a > inteltool.log
 +
  ectool > ectool.log
 +
  msrtool > msrtool.log
 +
  dmidecode > dmidecode.log
 +
  biosdecode > biosdecode.log
 +
  nvramtool -x > nvramtool.log
 +
  dmesg > dmesg.log
 +
  flashrom -V -p internal:laptop=force_I_want_a_brick > flashrom_info.log
 +
  flashrom -V -p internal:laptop=force_I_want_a_brick -r rom.bin > flashrom_read.log
 +
  acpidump > acpidump.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
 +
* 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 [[http://flashrom.org/Technology]] 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 staff - 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
  
=== Modifying existing board ===
+
=== 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 [[http://flashrom.org/ISP]]
 +
* Hotswap. Consult [[http://flashrom.org/Technology]]
 +
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 [[http://flashrom.org/Technology]]. 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.
  
TODO.
 
  
 
=== Adding a new board ===
 
=== Adding a new board ===
Line 42: Line 93:
  
 
==== Adjusting contents of new board directory ====
 
==== 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.
 
Adjust Kconfig to fit the new vendor/model name and dont forget to change MAINBOARD_DIR and MAINBOARD_PART_NUMBER.

Latest revision as of 10:01, 22 November 2014

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
 # lspnp
 # lsusb
 # acpidump
  • Do this commands (# remove for the easy copypasting):
 lspci -nnvvvxxxx > lspci.log
 lspnp -vv > lspnp.log
 lsusb -vvv > lsusb.log
 superiotool -deV > superiotool.log
 inteltool -a > inteltool.log
 ectool > ectool.log
 msrtool > msrtool.log
 dmidecode > dmidecode.log
 biosdecode > biosdecode.log
 nvramtool -x > nvramtool.log
 dmesg > dmesg.log
 flashrom -V -p internal:laptop=force_I_want_a_brick > flashrom_info.log
 flashrom -V -p internal:laptop=force_I_want_a_brick -r rom.bin > flashrom_read.log
 acpidump > acpidump.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
  • 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 staff - 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.