Martin L Roth has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/87185?usp=email )
Change subject: Documentation: Add information about the site-local directory ......................................................................
Documentation: Add information about the site-local directory
This adds a document about coreboot's site-local directory along with how and when to use it.
Change-Id: Ida176aa460be7673bad219f958f741dd68a8aa62 Signed-off-by: Martin Roth gaumless@gmail.com --- M Documentation/getting_started/index.md A Documentation/getting_started/site-local.md 2 files changed, 463 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/85/87185/1
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 7180c96..91bd714 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -10,5 +10,6 @@ Writing Documentation <writing_documentation.md> Setting up GPIOs <gpio.md> Adding devices to a device tree <devicetree.md> +Using the site-local directory <site-local.md> Frequently Asked Questions <faq.md> ``` diff --git a/Documentation/getting_started/site-local.md b/Documentation/getting_started/site-local.md new file mode 100644 index 0000000..497939e --- /dev/null +++ b/Documentation/getting_started/site-local.md @@ -0,0 +1,462 @@ +# Using the site-local Directory in coreboot + +## Overview + +The `site-local` directory is a powerful mechanism in coreboot that +allows developers to maintain local modifications, configurations, and +binary blobs separate from the main coreboot repository. This +separation ensures that your local changes never conflict with upstream +updates and can be versioned independently. + +## Purpose and Benefits + +- **Local Customization**: Store board-specific configurations and + modifications +- **Binary Blobs**: Keep non-redistributable files (like firmware + blobs) outside the main repository +- **Independent Versioning**: Version your local additions separately + from coreboot +- **Clean Separation**: Avoid conflicts with upstream changes +- **Build Integration**: Seamlessly integrate local additions into the + build process +- **Override default values**: Set custom Kconfig or Makefile values, + overriding the general coreboot codebase + +## Getting Started + +### Directory Structure + +Create a `site-local` directory at the top level of your coreboot +repository: + +``` +coreboot/ +├── src/ +├── util/ +├── ... +└── site-local/ <-- Your local additions go here +``` + +### Key Files + +The following files in your `site-local` directory are recognized by +coreboot's build system and parsed very early in the process to allow +default values to be set, overriding values that might be set +elsewhere in the coreboot tree. + +1. **`site-local/Kconfig`**: Integrated early in the configuration + process, allowing you to set custom defaults +2. **`site-local/Makefile.mk`**: Integrated into the build system for + custom build rules + +## Integration Methods + +### 1. Using Symbolic Links + +The most common approach for integrating local additions is using +symbolic links. This allows you to maintain a parallel directory +structure in `site-local` that mirrors coreboot's structure. + +#### Steps: + +1. Create your directory structure within `site-local` that mirrors + coreboot's structure +2. Add a `symlink.txt` file at the root of each directory you want to + link +3. In each `symlink.txt`, specify the path (relative to coreboot root) + where it should be linked +4. Run `make symlink` to create the symbolic links + +#### Example: + +``` +coreboot/ +├── src/ +│ └── soc/ +│ └── test-soc-from-site-local -> ../../site-local/src/soc/test-soc-from-site-local/ +└── site-local/ + ├── Kconfig + ├── Makefile.mk + └── src/ + └── soc/ + └── test-soc-from-site-local/ + ├── chip.h + ├── soc.c + └── symlink.txt <-- Contains "src/soc/test-soc-from-site-local" +``` + +To keep symlinks updated automatically, add this to your +`site-local/Makefile.mk`: + +``` +site-local-target:: symlink +``` + +### 2. Direct Integration via Kconfig + +Your `site-local/Kconfig` file is included early in coreboot's +configuration process, allowing you to: + +- Set custom default configurations +- Override upstream defaults +- Define new configuration options + +### 3. Build System Integration + +The `site-local/Makefile.mk` file is included in the build system, +allowing you to: + +- Add files to CBFS +- Define custom build targets +- Modify build behavior for specific boards + +## Common Use Cases + +### 1. Adding Binary Blobs to CBFS + +For non-redistributable files like firmware blobs or option ROMs: + +```makefile +# In site-local/Makefile.mk +cbfs-files-$(CONFIG_BOARD_VENDOR_BOARDNAME) += firmware.bin +firmware.bin-file := path/to/firmware.bin +firmware.bin-type := raw +``` + +### 2. Board-Specific Binary Files + +Store board-specific binary files in your `site-local` directory: + +```makefile +# Example from real configs +CONFIG_IFD_BIN_PATH="site-local/descriptor.bin" +CONFIG_ME_BIN_PATH="site-local/me.bin" +CONFIG_GBE_BIN_PATH="site-local/gbe.bin" +``` + +### 3. Custom Payloads + +Specify custom payloads for your builds: + +```makefile +CONFIG_PAYLOAD_FILE="site-local/custom/linuxboot_payload" +``` + +### 4. FSP Binaries + +Store and reference Intel FSP binaries: + +```makefile +CONFIG_FSP_T_FILE="site-local/board/Server_T.fd" +CONFIG_FSP_M_FILE="site-local/board/Server_M.fd" +CONFIG_FSP_S_FILE="site-local/board/Server_S.fd" +``` + +### 5. CPU Microcode Updates + +Include CPU microcode updates: + +```makefile +CONFIG_CPU_UCODE_BINARIES="site-local/board/microcode.bin" +``` + +## Example: Developing a New SoC Out-of-Tree + +One of the most powerful use cases for `site-local` is developing a new +SoC implementation out-of-tree before it's ready to be made public. +This allows you to: + +- Keep proprietary or under-NDA code separate until it can be properly + open-sourced +- Develop and test in the context of the full coreboot tree +- Collaborate with a team on the SoC without affecting the public + codebase +- Gradually transition from private to public as code is cleared for + release + +### Directory Structure for a New SoC + +Here's a comprehensive example of how to structure your `site-local` +directory for developing a new SoC (in this example, a fictional +"newvendor/newtarget" SoC): + +``` +coreboot/ +└── site-local/ + ├── Kconfig # Global Kconfig overrides + ├── Makefile.mk # Global Makefile overrides + └── src/ + ├── soc/ + │ └── newvendor/ # New vendor directory + │ ├── common/ # Common code for vendor SoCs + │ │ ├── include/ + │ │ │ └── soc/ + │ │ │ └── common_definitions.h + │ │ ├── Kconfig + │ │ ├── Makefile.mk + │ │ ├── common_init.c + │ │ └── symlink.txt # Contains "src/soc/newvendor/common" + │ │ + │ └── newtarget/ # Specific SoC implementation + │ ├── include/ + │ │ └── soc/ + │ │ ├── addressmap.h + │ │ ├── gpio.h + │ │ └── soc_api.h + │ ├── chip.h + │ ├── Kconfig + │ ├── Makefile.mk + │ ├── romstage.c + │ ├── ramstage.c + │ ├── gpio.c + │ ├── soc.c + │ ├── memory.c + │ ├── uart.c + │ └── symlink.txt # Contains "src/soc/newvendor/newtarget" + │ + └── mainboard/ + └── newvendor/ # Reference mainboard for the new SoC + └── devboard/ # Development board for the SoC + ├── devicetree.cb + ├── Kconfig + ├── Makefile.mk + ├── board.c + ├── romstage.c + ├── gpio.c + └── symlink.txt # Contains "src/mainboard/newvendor/devboard" +``` + +### Key Files for SoC Implementation + +Let's look at the content of some key files in this structure: + +#### 1. SOC Kconfig (`site-local/src/soc/newvendor/newtarget/Kconfig`) + +```kconfig +config SOC_NEWVENDOR_NEWTARGET + bool + help + NewVendor NewTarget SoC support + +if SOC_NEWVENDOR_NEWTARGET + +config SOC_SPECIFIC_OPTIONS + def_bool y + select ARCH_BOOTBLOCK_ARM64 + select ARCH_RAMSTAGE_ARM64 + select ARCH_ROMSTAGE_ARM64 + select ARCH_VERSTAGE_ARM64 + select ARM64_USE_ARM_TRUSTED_FIRMWARE + select HAVE_UART_SPECIAL + select COMMON_CBFS_SPI_WRAPPER + select SOC_NEWVENDOR_COMMON # For common vendor code + +config VBOOT + bool + default y if VBOOT_SLOTS_RW_AB + +config UART_FOR_CONSOLE + int + default 0 + +endif # SOC_NEWVENDOR_NEWTARGET +``` + +#### 2. SOC Makefile (`site-local/src/soc/newvendor/newtarget/Makefile.mk`) + +```makefile +bootblock-y += bootblock.c +bootblock-y += uart.c +bootblock-y += gpio.c + +romstage-y += romstage.c +romstage-y += memory.c +romstage-y += uart.c +romstage-y += gpio.c + +ramstage-y += soc.c +ramstage-y += uart.c +ramstage-y += gpio.c + +CPPFLAGS_common += -Isrc/soc/newvendor/newtarget/include +CPPFLAGS_common += -Isrc/soc/newvendor/common/include + +# Include any vendor-specific binary blobs that can't be open-sourced yet +BL31_MAKEARGS += PLAT=newtarget + +# Include private bootloader files for this SoC +cbfs-files-y += scp.bin +scp.bin-file := site-local/blobs/newvendor/newtarget/scp.bin +scp.bin-type := raw +scp.bin-position := 0x20000 +``` + +#### 3. Global site-local Kconfig (`site-local/Kconfig`) + +```kconfig +# Include our custom SoC in the mainboard selection process +source "src/soc/newvendor/*/Kconfig" + +# Override build options for development +config COMPILER_GCC + default y + +config ALLOW_MANUAL_FIRMWARE_BLOB_SELECTION + default y + +# Add custom firmware verification options +config CUSTOM_FIRMWARE_VERIFICATION + bool "Use custom firmware verification" + default n + help + Enable custom firmware verification process for NDA-covered + components +``` + +#### 4. Global site-local Makefile (`site-local/Makefile.mk`) + +```makefile +# Always run the symlink target to keep links updated +site-local-target:: symlink + +# Add a custom build step for the new SoC +prebuild-y += $(if $(CONFIG_SOC_NEWVENDOR_NEWTARGET), site-local-newtarget-prepare) + +# Define custom build step +site-local-newtarget-prepare: + @echo "Preparing NewTarget build environment..." + $(MAKE) -C site-local/tools/newtarget +``` + +#### 5. Mainboard Kconfig (`site-local/src/mainboard/newvendor/devboard/Kconfig`) + +```kconfig +if BOARD_NEWVENDOR_DEVBOARD + +config BOARD_SPECIFIC_OPTIONS + def_bool y + select SOC_NEWVENDOR_NEWTARGET + select BOARD_ROMSIZE_KB_16384 + select MAINBOARD_HAS_CHROMEOS + select COMMON_CBFS_SPI_WRAPPER + select DRIVERS_I2C_GENERIC + select DRIVERS_USB_ACPI + +config MAINBOARD_DIR + string + default "newvendor/devboard" + +config MAINBOARD_PART_NUMBER + string + default "NewVendor Development Board" + +config MAINBOARD_VENDOR + string + default "NewVendor" + +config MAX_CPUS + int + default 8 + +endif # BOARD_NEWVENDOR_DEVBOARD +``` + +### Integration with coreboot + +1. First, set up the symlinks: + +```bash +cd coreboot +make symlink +``` + +This will create symbolic links from your `site-local` SoC +implementation into the main coreboot directory structure. + +2. Configure coreboot to use your new board: + +```bash +make menuconfig +``` + +Select: +- Mainboard → Mainboard vendor → NewVendor +- Mainboard → Mainboard model → NewVendor Development Board + +3. Build coreboot with your new SoC: + +```bash +make +``` + +### Transition to Upstream + +When your SoC implementation is ready to be made public: + +1. Move the code from `site-local` to the appropriate locations in the + main coreboot tree +2. Remove the symlinks +3. Test to ensure everything still works +4. Commit the code to the main coreboot repository + +This approach allows for a seamless transition from private to public +development. + +## Useful Commands + +- `make symlink`: Create symbolic links from `site-local` into the + coreboot tree +- `make clean-symlink`: Remove symbolic links created by `make symlink` +- `make cleanall-symlink`: Remove all symbolic links in the coreboot + tree + +## Best Practices + +1. **Version Control**: Consider keeping your `site-local` directory in + a separate git repository +2. **Git Submodules**: You can add your `site-local` repo as a git + submodule to your coreboot checkout +3. **Documentation**: Document your local additions within your + `site-local` directory +4. **Organization**: Mirror coreboot's directory structure for clarity +5. **Minimal Changes**: Keep local modifications minimal to ease future + updates + +## Important Notes + +- The `site-local` directory is intentionally excluded from coreboot's + `.gitignore` +- coreboot's lint checks will fail if you try to commit the + `site-local` directory to the main repository +- It's recommended to keep `site-local` in a separate repository and + pull it in as needed + +## Example: Complete `site-local` Setup + +Here's a complete example of a `site-local` setup for a custom board: + +``` +coreboot/ +└── site-local/ + ├── Kconfig # Custom Kconfig options + ├── Makefile.mk # Build system integration + ├── blobs/ # Binary blobs directory + │ ├── board1/ + │ │ ├── descriptor.bin + │ │ └── me.bin + │ └── board2/ + │ └── microcode.bin + └── src/ # Custom source code + └── mainboard/ + └── vendor/ + └── custom_board/ + ├── devicetree.cb + ├── Kconfig + ├── Makefile.mk + └── symlink.txt # Contains "src/mainboard/vendor/custom_board" +``` + +By leveraging the `site-local` mechanism effectively, you can maintain a +clean separation between upstream coreboot and your local +customizations, making it easier to update to new coreboot versions +while preserving your specific modifications. \ No newline at end of file