Main Content

Author a Xilinx Zynq Linux Image for a Custom Zynq Board by Using MathWorks Buildroot

This example shows how to create a Zynq® Linux® image for starting a Zynq® custom board with the Linux® operating system in a Zynq® workflow by using MathWorks® buildroot system.


You create a Zynq® Linux® Image for a Digilent™ Zybo Z7-10 Zynq® development board for the custom reference design in the HDL workflow advisor. This example uses a Zybo Z7-10 board. You can build a Linux® image for other Zynq® platforms by using the MathWorks® build system.


  • Mathworks build system - Buildroot

  • Linux® operating system

  • Xilinx® Vivado® Design Suite, the supported version listed in the HDL Coder™ documentation

  • Digilent® Zybo Z7-10 Zynq® development board with the accessory kit

Zynq Configuration

The Zynq® boot process involves the processor system (PS), loading and executing Zynq® boot image which consists of a First stage bootloader (FSBL), a bitstream to configure the programmable logic (PL), and user applications.

Boot Process

Stage 0

After the board is switched ON or the Zynq® processor is reset. BootROM, a read-only code executes from (CPU0) one of the processor from processing system (PS). Based on the boot mode pin settings (JP5) in Zybo Z7-10 from available boot mode options, such as QSPI Flash, NAND Flash, SD Card, it copies the BootROM to on-chip memory (OCM). It executes the BootROM. Post-execution, the BootROM transfers execution to FSBL in the OCM.

Stage 1

The FSBL enables by configuring PS components, such as DDR memory controller and I/O components and looks for the bitstream file in the boot device. The FSBL loads application binaries and data files into memory until the complete image has been read from the boot device then FSBL initializes the external RAM and loads the second stage bootloader or stand alone application.

Stage 2

The user application loaded in the previous stage will be executed like U-Boot. It runs in CPU0 to initialize and setup the environment in which OS will boot. Initialization includes configuring the memory management unit.

Stage 3

The bootloader then fetches the kernal image and boots the embedded Linux operating system. In case of Linux, the OS detects and enables the second processor core CPU1, configures and activates the MMU and data caches and performs other actions to make a complete system available to applications.

Mathworks Build System

Mathworks Buildroot is a tool you use to generate embedded Linux® systems through cross-compilation. The MathWorks® build system wraps Buildroot in pre and post-processing scripts to automate the generation of system images for various platforms. The build system is based on scripts that take as input the target board, platform or image description file and output a complete system image, including bootloaders, kernel, and user space. This repository hosts the buildroot framework that creates the Altera® SoC and Xilinx® Zynq® platform SD Card images for use with MathWorks® tools.

Build a Zynq Linux image by Using the Mathworks Build System

1. Setup Cross compiler

Set up the cross compiler by Installing the Linaro ARM toolchain on your Linux machine using the following command. Below command works in Debian® 10 Linux Machines.

>> sudo apt-get install gcc-arm-linux-gnueabihf

2. Sync MathWorks Buildroot from Git Hub

Get the buildroot from the git clone GitHub - MathWorks Buildroot by using the latest release tag.

>> git checkout mathworks_zynq_R22.1.0

The release tags are labeled as mathworks_zynq_R2x.y.z, where the "R2x" denotes the year of the MATLAB release and "y" denotes the 'a' or 'b' release. The "z" is used for updates to the image within a particular MATLAB release. For example, the tag "R22.1.0" is interpreted as MATLAB R2022a where "R22" represents R2022 and "1.0" is for release 'a'. If there will be any updates to the image within the R2022a release, the versions would be "R22.1.1", "R22.1.2", etc.

After syncing the Mathworks buildroot, build the image by using the following files. Navigate to the file folder and place the required files in it. This image shows the folder hierarchy and contents inside it that you use for building the Linux image for a specific board (ZyboZ7).


Required files for Building Zynq Linux Image

  • Exported Handoff files

  • Device Tree Source file

  • Zynq Defconfig file

Handoff Files

The settings applied in Zynq processing system IP such as address mapping of memory and peripherals, are exported from the Xilinx Vivado project. Bitstream file, system hardware project file (.hdf) are exported after custom reference design creation. For more information, see the Create and Export a Custom Reference Design by Using Xilinx Vivado section in Define Custom Board and Reference Design for Zynq Workflow. Export the hardware platform from the vivado block design project and unzip the .xsa file to get ps7_init_gpl.c, ps7_init_gpl.h and place these files into handoff folder in the zyboz7 buildroot directory as shown in the below image.

Device Tree Source

Device tree is a data structure that describes the hardware which is readable by an operating system like Linux so that it doesn't need to hard code any details of the machine. A device tree source (DTS) file contains plain text data that describes a list of nodes,properties and child nodes for platform identification, run-time configuration like bootargs. DTS files are compiled using device tree compiler into device tree blob (DTB) which is a binary file that the hardware uses during the boot process.

This code is the sample code of the Zybo Z7-10 Device tree source file.

#include "zynq-7000.dtsi"
#include <dt-bindings/gpio/gpio.h>

/ {
    model = "Digilent Zybo Z7 board";
    compatible = "digilent,zynq-zybo-z7", "xlnx,zynq-7000";

    aliases {
        ethernet0 = &gem0;
        serial0 = &uart1;

    memory@0 {
        device_type = "memory";
        reg = <0x0 0x40000000>;

    chosen {
        bootargs = "";
        stdout-path = "serial0:115200n8";

    gpio-leds {
        compatible = "gpio-leds";

        ld4 {
            label = "zynq-zybo-z7:green:ld4";
            gpios = <&gpio0 7 GPIO_ACTIVE_HIGH>;

    usb_phy0: phy0 {
        #phy-cells = <0>;
        compatible = "usb-nop-xceiv";
        reset-gpios = <&gpio0 46 GPIO_ACTIVE_LOW>;

&clkc {
    ps-clk-frequency = <33333333>;

&gem0 {
    status = "okay";
    phy-mode = "rgmii-id";
    phy-handle = <&ethernet_phy>;

    ethernet_phy: ethernet-phy@0 {
        reg = <0>;
        device_type = "ethernet-phy";

&sdhci0 {
    status = "okay";

&uart1 {
    status = "okay";

&usb0 {
    status = "okay";
    dr_mode = "host";
    usb-phy = <&usb_phy0>;

3. Zynq Defconfig

The platform defconfig contains the Linux kconfig settings required to properly configure the kernel build. This file is the zynq_zybo_z7_defconfig file used for building the Z7-10 Image.


# Zybo Options




Build Script

Using the following build script we can initiate the linux SD image build for the specific board.

>> -c board/mathworks/zynq/boards/zyboz7/catalog.xml

Otherwise use this command to provide the different toolchain path manually to build.

>> ./ -p zynq -b zyboz7 --brconfig BR2_TOOLCHAIN_EXTERNAL_PATH='/opt/ARM_CortexA/LinaroToolchain/6.3.1-2017.02/Linux/aarch32'

List of files after build

After a build, these files are in the output folder /buildroot/output/zybo_linux_linaro/images/ as a zip file. Unzip the files into the SD card and insert the SD card on Zybo Z7-10 board. To learn more about board connections, see Define Custom Board and Reference Design for Zynq Workflow.


This example shows step by step process of building a Linux image by using the Mathworks Buildroot system. You can build a Linux image for other Zynq platforms by using the MathWorks build system. Using this example you can create Xilinx Zynq Linux image for the custom Zynq boards by including the required files in the Mathworks buildroot folder and setting up the linaro cross-compiler.