Motherboard Porting Guide
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 # lspnp <-- where do you actually get this? I couldn't find it anywhere. # lsusb # acpidump
- # modprobe msr
(this is for one of the steps below)
- Do this commands (# remove for the easy copypasting):
lspci -nnvvvxxxx > lspci.log 2>lspci.err.log lspnp -vv > lspnp.log 2>lspnp.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 > 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
- 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 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.