Nicholas Chin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/85912?usp=email )
Change subject: [WIP] Docs: Start adding mainboard porting guide ......................................................................
[WIP] Docs: Start adding mainboard porting guide
Add some initial information about porting mainboards to coreboot to replace and extend the limited information from the guide in the old wiki. It is not intended (nor would it be practical) to be a step-by-step guide for any board, but rather a general collection of common tasks when porting and where to look for determining the values to set for board specific configurations. The techniques described are generally applicable to ports being created by setting values based on vendor firmware.
Change-Id: I4680becebd8733ea7a23085c1832e9eb914138b3 Signed-off-by: Nicholas Chin nic.c3.14@gmail.com --- M Documentation/getting_started/index.md A Documentation/getting_started/porting/index.md A Documentation/getting_started/porting/intel.md A Documentation/getting_started/porting/x86_mainboard_porting.md 4 files changed, 133 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/12/85912/1
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 7180c96..20cac4e 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -7,6 +7,7 @@ Build System <build_system.md> Submodules <submodules.md> Kconfig <kconfig.md> +Porting Mainboards <porting/index.md> Writing Documentation <writing_documentation.md> Setting up GPIOs <gpio.md> Adding devices to a device tree <devicetree.md> diff --git a/Documentation/getting_started/porting/index.md b/Documentation/getting_started/porting/index.md new file mode 100644 index 0000000..73f731c --- /dev/null +++ b/Documentation/getting_started/porting/index.md @@ -0,0 +1,59 @@ +# Porting coreboot to a new mainboard + +## General +The first step in porting a board to coreboot is determining whether +coreboot supports the main chips on your board. The most critical of +these are the processor, chipset, and/or SoC. Refer to the [supported +chips] page for a list of chips that coreboot supports. If one of these +isn't supported, then support for that chip would need to be added first +before a board based on it could be ported. Other chips that should be +supported if possible include SuperIOs and Embedded Controllers (EC), +but these are often less critical in terms of being able to boot. + +One method of porting a board is to find an existing board with coreboot +support and using it as a template for the new port. This is a common +method to "retrofit" coreboot onto a board that originally shipped with +a proprietary firmware implementation from the vendor. + +### Adding a new vendor +If the vendor of your board does not have any boards currently supported +by coreboot, you will need to create a new directory in `src/mainboard` +as well as Kconfig entries for it. If your vendor is "foo": + +- Create a `src/mainboard/foo` directory +- Create `src/mainboard/foo/Kconfig` +- Create `src/mainboard/foo/Kconfig.name` + +The `Kconfig` and `Kconfig.name` files can be copied from other vendors +and edited to reflect the new vendor. + +### Adding a new mainboard +A new directory in `src/mainboard/vendorname/` needs to be created for +your board. If starting with a similar existing port, copy the directory +for that board to the directory for your board's vendor. As with the +vendor directory, the board directory will need a `Kconfig` and a +`Kconfig.name` file. If starting from an existing port, edit mainboard +related Kconfigs to reflect the board you are porting. + +### Board specific configuration +Various settings in files such as hda_verb.c, Kconfig, devicetree.cb, +gpio.c and more need to be set to reflect the hardware configuration of +your board. If starting from an existing board, values + +### General Porting Hints +- If you don't know what a configuration variable means, search for its + name in the code for your board's platform. That often will lead to a + register address, which can be looked up in the output of various + utilities to determine the value that the vendor firmware sets it to, + as well as the chip datasheet which will document what each bit means. +- Don't be afraid to ask for help! There are many coreboot developers + who are willing to help on various [forums]. + +## Architecture Specific Porting Information +```{toctree} +:maxdepth: 1 + +Porting x86 systems <x86_mainboard_porting.md> +``` + +[forums]: ../../community/forums.md diff --git a/Documentation/getting_started/porting/intel.md b/Documentation/getting_started/porting/intel.md new file mode 100644 index 0000000..f07ff40 --- /dev/null +++ b/Documentation/getting_started/porting/intel.md @@ -0,0 +1,42 @@ +# Porting Intel x86 based mainboards + +## GPIO +If you have access to the schematics of your board, you should refer to +that to ensure the GPIO configurations are correct for the physical +design of the board and intended usages of each GPIO pin. + +For platforms using an ICH7 through ICH10 southbridge or Ibex Peak (1st +Gen Intel Core/Ironlake) through Lynx Point (4th Gen Intel Core/Haswell) +PCH, a [utility] exists which can generate gpio.c based on the GPIO +section in the `inteltool` output. Note that depending on the chipset, +not all GPIOs will exist. Refer to the chipset datasheet to determine +which ones exist. + +For platforms based on Skylake and newer, the `util/intelp2m` utility +can be used to generate a GPIO config based on the current configuration +set by the vendor firmware. + +## SPD Mapping +For boards with slotted memory, the raminit code needs to know how each +physical slot maps to an SMBUS address to access the SPD EEPROM on each +memory module. If you have access to the schematics or boardview, the +addresses of each slot can be determined from the pull-up/pull-down +resistors on the SA0-SA2 pins. The mapping can also be determined +experimentally by booting with one slot populated at a time, determining +which SMBUS address is active, and checking memory controller registers +to determine which channel/slot is populated. + +Many boards use the following mapping, and thus using this and seeing if +the system boots is often a viable option: +- Channel 0, slot 0: 0x50 +- Channel 0, slot 1: 0x51 +- Channel 1, slot 0: 0x52 +- Channel 1, slot 1: 0x53 + +BTX boards often use a reversed mapping: +- Channel 0, slot 0: 0x53 +- Channel 0, slot 1: 0x52 +- Channel 1, slot 0: 0x51 +- Channel 1, slot 1: 0x50 + +[utility]: https://codeberg.org/Riku_V/gpio-scripts diff --git a/Documentation/getting_started/porting/x86_mainboard_porting.md b/Documentation/getting_started/porting/x86_mainboard_porting.md new file mode 100644 index 0000000..70c5d3c --- /dev/null +++ b/Documentation/getting_started/porting/x86_mainboard_porting.md @@ -0,0 +1,31 @@ +# Porting x86 based boards to coreboot + +## HD Audio +The configuration for HD Audio codecs is found in the `hda_verb.c` file +for each board. This contains configs for the vendor IDs and pin widget +configs. + +The name, vendor/device ID, and subsystem ID of each codec can be found +in the files `/proc/asound/cardn/codec#m` + +The pin configs for each codec can be found in +`/sys/class/sound/cardn/hwCnDm/init_pin_configs`. The meanings of the +values in init_pin_configs can be found in the Intel High Definition +Audio Specification, Rev. 1.0a, Section 7.3.3.31: Configuration Default. + +## SuperIO +Useful utilities: superiotool + +## Devicetree +Useful utilities: +- inteltool +- lspci + +## Vendor Specific Porting Information +Refer to the appropriate page for vendor specific porting documentation + +```{toctree} +:maxdepth: 1 + +Porting Intel x86 Mainboards <intel.md> +```