Skip to content

catalog.md

Latest commit

 

History

History
136 lines (108 loc) · 6.28 KB

catalog.md

File metadata and controls

136 lines (108 loc) · 6.28 KB
Raw

Catalog Files

Catalog files are used to tell Buildroot what to build. They specify what components to build and how to combine them together. An example file is show below:

<board name="zed" platform="zynq">
    <default>
        <app name="default">
        </app>
        <handoff dir="handoff"/>
    </default>
    <image name="zynq7000ec">
        <app name="axilite">
            <dts file="axilite.dts"/>
            <bit file="axilite.bit"/>
        </app>
        <app name="axistream">
            <dts file="axistream.dts"/>
            <bit file="axistream.bit"/>
        </app>
    </image>
</board>

Catalog files are comprised of images and apps. An image is a full system image, made up of one or more apps. Each image will generate its own .zip or .img.gz file. An app is a combination of bootloader, devicetree and FPGA bitstream, and will affect the files contained within the image.

XML Format

Board Node

The board node is the top level node in the XML file. There must be exactly one instance of this node.

The board node has the following attributes:

Attribute Description
name The board name (e.g. zed, zc706, etc)
platform The platform name (e.g. zynq, socfpga)

name: The name can specify a board supported in tree (in which case the various source files supplied in tree will be available for use) or specify a completely new board. If a new board is specified, the boardInfo directory must be supplied within the default node.

platform: The platform must be one of the platforms supported in tree:

  • zynq
  • socfpga

The board node has the following sub-nodes:

Node Attributes Description
default N/A The default settings for the catalog file. Must be exactly one instance of this node
image name A description of the image to build, must be one or more instances of this node

Default Node

The default node supplies settings that apply to the entire catalog file (all images / apps).

The board node has the following sub-nodes:

Node Attributes Description
app name The default settings for all apps within the catalog; will be used unless overriden
board_dir dir The board directory to use. Will use the in-tree directory if not specified. Must be specified for boards not supported in-tree
sdcard dir The source directory to copy over contents at the root of the SD card. Will use the in-tree directory if not specified
dtsi dir A DTS include directory-- will be added to the path for compiling the DTB file. Multiple nodes can be specified
br2_config file A buildroot config file to append to generated buildroot config. Can be used to specify new values or override existing ones
kernel_config file The kernel configuration to use instead of the default in-tree defconfig
fsbl file (zynq only) The First Stage Bootloader to build for the SD Card.
fsbl dir (zynq only) The folder containing ps7_init_gpl.{c
handoff dir (socfpga only) The Quartus handoff files to use in generating the U-Boot SPL.

When locating the fsbl/handoff files, the following paths are searched (in order):

  • Relative to the catalog file, in the boot subdirectory
  • Relative to the catalog file
  • Relative to the board directory (in-tree or otherwise), in the boot subdirectory as above

Platform Notes: socfpga

The handoff folder can either be the output of Quartus (the hps_isw_handoff folder) or a folder containing two folders: "handoff" (the Quartus files) and "generated", the generated folder from the SoC EDS BSP Creator. If the former is used, buildroot will automatically create the BSP, but will require the Altera SoC EDS to be present on the build machine

Platform Notes: zynq

The fsbl tag can specify either a pre-generated FSBL or the ps7_init_gpl files generated by Vivado.

  • When using a pre-generated FSBL, the Xilinx SDK toolchain must be used to build the project, so that bootgen can be used to convert the FSBL into a boot.bin file.
  • When using the ps7_init_gpl files, the U-boot SPL will be used to generate boot.bin, and there are no toolchain restrictions.

To generate the ps7_init_gpl files in Vivado, the following commands can be used after the block design as been generated:

write_hwdef -file system.hdf
hsi::open_hw_design system.hdf
hsi::close_hw_design [hsi::current_hw_design]

Image Node(s)

Each image represents a distinct output from the tool, made up of the common settings (e.g. those specified by the board/platform/default node) and the application-specific settings. The name of the image file will be based on the name attribute of the image node.

The image node has the following sub-nodes:

Node Attributes Description
app N/A The an app to include in the image. The first listed app will be considered the default app, used to boot the image
sdcard dir The source directory to copy over contents at the root of the SD card. Will be combined with the contents specified in the default node (or the in-tree contents).
dtsi dir A DTS include directory-- will be added to the path for compiling the DTB file. Will be combined with the dtsi directories specified in the default node. Multiple nodes can be specified

App Node(s)

The app node specifies the combination of bootloader, devicetree, and FPGA bitstream to build. If values are not specified, the values from the default app node are used.

The app node has the following sub-nodes:

Node Attributes Description
dts file The DTS file to build for the application.
bit file The bitstream to build for the application.

When locating the specified files, the following paths are searched (in order):

  • Relative to the catalog file, in the per-file subdirectories
    • dts: ./dts directory
    • bit: ./boot directory
  • Relative to the catalog file
  • Relative to the board directory (in-tree or otherwise), in the per-file subdirectories as above