This document provides a step-by-step guide for executing the Peta-Caribou image build workflow using the Peta-Manager and for one of the supported target boards. The image build process consists of six main steps :

  1. Cloning the Peta-Caribou project
  2. Creating the PetaLinux project
  3. Configuring the PetaLinux image
  4. Building the PetaLinux image
  5. Packaging the PetaLinux image
  6. Loading the PetaLinux image onto an SD card
  7. Booting the board

1. Cloning the Peta-Caribou project 

  git clone --recurse-submodules https://gitlab.cern.ch/Caribou/peta-caribou.git

2. Creating the PetaLinux project 

  ./peta-manager.py create --prj <project-name> --bsp <path-to-bsp-file>

This command initializes a PetaLinux project named <project-name> for the target board, using the specified BSP file. It also sets up the project workspace by copying all necessary recipe definitions, device tree files, and image configuration files, preparing them for further configuration.

3. Configuring the PetaLinux image 

  ./peta-manager.py configure --prj <project-name>

This step configures the PetaLinux image based on predefined settings in the corresponding configuration file. Some parameters can be modified as needed.

3.1. Updating the MAC address 

  ./peta-manager.py configure --prj <project-name> --mac <mac-address>

Use the --mac argument to specify a custom MAC address (e.g., --mac 02:0a:35:00:03:00).

3.2. (Optional) Using an custom XSA file 

  ./peta-manager.py configure --prj <project-name> --xsa <xsa-file>

The --xsa argument updates the hardware configuration using an external XSA file.

3.3. (Optional) Adding a custom Layer 

  ./peta-manager.py configure --prj <project-name> --add-recipe <layer-path>

The --add-layer adds the provided custom layer folder to the existing Caribou image layers

3.4. (Optional) Adding a custom Recipe 

  ./peta-manager.py configure --prj <project-name> --add-recipe <recipe-path>

The --add-recipe adds the provided custom recipe folder to the existing Caribou layer recipes

4. Building the PetaLinux image 

  ./peta-manager.py build --prj <project-name>

This step compiles the PetaLinux image using the bitbake utility and the Caribou-specific configuration file. The process generates the BOOT files, which will be packaged for use during the board’s boot sequence.

5. Packaging the PetaLinux image 

  ./peta-manager.py package --prj <project-name>

This command prepares the compiled PetaLinux image for deployment.

5.1. (Optional) Setting partition sizes 

  ./peta-manager.py package --prj <project-name> --boot-size <boot-size> --rootfs-size <rootfs-size>

This step modifies the boot and rootfs partition sizes in the rootfs.wks file used to package the image. Values can be provided as <N>[M/G], where N is the size and M and G corresponds to Megabyte and Gigabyte respectively. Default values are 2G for the boot partition and 10G for the rootfs partition.

6. Loading the PetaLinux image onto an SD Card 

  ./peta-manager.py load --prj <project-name> --sd <sd-device>

This step partitions the SD card, creates the necessary boot folder, and copies all required files. The --sd argument specifies the SD card device path (e.g., /dev/sda). If not provided, it defaults to /dev/sdc.

6.1. (Optional) Including an FPGA bit file 

  ./peta-manager.py load --prj <project-name> --sd <sd-device> --fpga <fpga-bitfile>

The --fpga argument specifies the path to the FPGA bitfile, which will be included in the boot partition.

7. Booting the board

Once the PetaLinux image has been written to the SD card, it can be inserted into the target board and the board can be powered on to boot. If the system boots successfully and the MAC address is registered on the local network for DHCP, the board should be accessible via SSH.