Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/34632 )
Change subject: Documentation: Add guidelines for new mainboard ports ......................................................................
Documentation: Add guidelines for new mainboard ports
This is WIP and partly copied from https://www.coreboot.org/Motherboard_Porting_Guide
It also list what should be documented for new mainboard ports.
Change-Id: I134dbf2341696ba0dd33c3d52bf787b8eaabbdab Signed-off-by: Patrick Rudolph siro@das-labor.org --- M Documentation/getting_started/index.md A Documentation/getting_started/new_mainboard_ports.md M Documentation/getting_started/writing_documentation.md 3 files changed, 95 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/32/34632/1
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 52d873e..7821ee1 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -7,3 +7,4 @@ * [Gerrit Guidelines](gerrit_guidelines.md) * [Documentation License](license.md) * [Writing Documentation](writing_documentation.md) +* [Adding new mainboards](new_mainboard_ports.md) diff --git a/Documentation/getting_started/new_mainboard_ports.md b/Documentation/getting_started/new_mainboard_ports.md new file mode 100644 index 0000000..cb7cd9b --- /dev/null +++ b/Documentation/getting_started/new_mainboard_ports.md @@ -0,0 +1,91 @@ +# Adding new mainboards + +Mainboard code is placed under `src/mainboards`. It glues the HW components +together by selecting appropiate northbridge, southbridge, on-board HW and +drivers. + +It provides the devicetree.cb, configures GPIOs, audio codecs, a static ACPI +board desciption and allows the romstage code to retrieve the SPD for +DRAM training. + +## Starting a new port from scratch + +1. Identify your platform + Try to find out as much as possible about the current hardware. + Dump information with existing tools: + * lspci + * lsusb + * superiotool + * inteltool + * ectool + * dmidecode + * acpidump + + Have a look at the mainboard schematics to see how those components are + connected. +2. Find a similar existing board + It a good idea to find a similar board and use it as reference. You should + then provide a proper GPIO configuration and devicetree.cb. +3. Find a similar SuperIo or BMC + To debug coreboot you should get the serial console working first. If your + board has a SuperIO or BMC try to find a compatible one. + Some boards have UART hardware on the SoC, makeing external components + obsolete. +4. Start with a minimal bootable configuration. That is: + * serial is working + * SPD reading/DRAM is working + * A payload that is able to boot an operating system +5. Be able to recover from a bad flash. You should use external flashing as + it's likely that you will brick your platform on the first attempts. + Make sure to backup the original firmware (if any). + +## Code submission + +Here's a checklist for new mainboard ports: + +1. Try to not duplicate code, use variants scheme instead. +2. Split changes logical into top level directories: + `src/mainboard` , `src/northbridge`, `src/ec`, ... +3. Provide good documentation, see point 4 +4. In the commit message describe as much as possible or point to the + documentation, satisfying the following questions: + * Where's the flash IC located? + * Can you flash incircuit? + * Are there pinheaders for flashing? + * Is the flash hardware write-protected? + * Which flash IC is usually equipped? + * If the board features an BMC, can it be used for developing and + debugging? + * What was tested and is working? + * What was tested and isn't working? + * What wasn't tested (due to lack of testing equipment)? + * Are blobs necessary? + * How can the board be debugged? + * Are there serial, EHCI debug, xHCI debug or BMC connections? + * Does it have a SuperIO? + + In addition please descibe: + * How to retrieve blobs, like dumping them from vendor firmware + + See [Writing Documentation] for more details. + +5. What you should **not** document: + * Steps or instructions how to flash the board + * Steps or instructions how to use a specific application for flashing + * Please do not provide pictures of the whole board or it's backplate + connectors +6. Recommand a flashing method as descibed in [Flashing tutorial] +7. If you are working at/for a hardware vendor, please provide free board + schematics as well. +8. Provide a picture of the flash IC or flash connector. + * The picture should be less than 800pc in width and compressed with + 70% compression to reduce size. + * You must own the Copyright + * Try to cut of uninteresting parts of the image, like tables, cables, ... + +Once done submit your board to Gerrit. Please follow the [Gerrit Guidelines] as +well. + +[Writing Documentation]: writing_documentation.md +[Flashing tutorial]: ../flash_tutorial/index.md +[Gerrit Guidelines]: gerrit_guidelines.md diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md index fb942a4..0b820fc 100644 --- a/Documentation/getting_started/writing_documentation.md +++ b/Documentation/getting_started/writing_documentation.md @@ -49,6 +49,8 @@ the current theme doesn't allow bigger images. 12. Shouldn't cover implementation details; for details, the code is the reference. +13. New mainboard ports should also add documentation. See + [Adding new mainboards] for more details.
## Referencing markdown documents
@@ -122,3 +124,4 @@ [Markdown Guide]: https://www.markdownguide.org/ [Gerrit Guidelines]: gerrit_guidelines.md [review.coreboot.org]: https://review.coreboot.org +[Adding new mainboards]: new_mainboard_ports.md