How to Integrate a MicroBlaze ELF Binary

Goal: Build a MicroBlaze C/C++ application, compile it to an ELF binary, and embed it into the Vivado bitstream.

Note

The ruckus MicroBlaze flow auto-detects whether Vitis (Vivado 2019.2+) or the legacy Xilinx SDK (Vivado 2019.1 and older) is available. The same make elf command works with both tools. This guide focuses on the Vitis path; the SDK path is functionally equivalent.

Prerequisites

  • A Vivado installation with MicroBlaze support

  • Vitis (Vivado 2019.2+) or Xilinx SDK (Vivado 2019.1) available on PATH

  • A completed Vivado block design with a MicroBlaze processor instance named by EMBED_PROC (default: microblaze_0)

  • C/C++ source directory set via VITIS_SRC_PATH in the project Makefile

Makefile Setup

Add these lines to your project Makefile before the include line:

export EMBED_PROC     = microblaze_0
export VITIS_SRC_PATH = $(PROJ_DIR)/firmware/src

include $(TOP_DIR)/submodules/ruckus/system_vivado.mk

Steps

  1. Open the Vitis/SDK IDE to develop your C/C++ application:

    make vitis    # opens Vitis IDE (if vitis binary detected on PATH)
# or
make sdk      # opens Xilinx SDK (if only xsdk is available)

    The IDE workspace is created at $(OUT_DIR)/$(PROJECT).vitis. Use the IDE to write and debug your C/C++ application before building the ELF.

  2. Build the ELF and embed it into the bitstream:

    make elf

    The make elf target automatically:

    • Opens the existing Vivado project

    • Exports the hardware platform (.xsa)

    • Creates a Vitis application project (app_0) scoped to $(EMBED_PROC)

    • Builds the ELF (app_0/Release/app_0.elf)

    • Adds the ELF to Vivado sources, scoped to the MicroBlaze instance

    • Resets impl_1 and reruns write_bitstream to embed the ELF

    • Calls CreateFpgaBit to produce the final artifact

Custom Hook

If $(VIVADO_DIR)/vitis.tcl exists in your project’s vivado/ directory, the entire Vitis project creation and build is replaced by that custom script. Use this for non-standard BSP configurations or multi-processor designs.

Key Variables

Variable

Default

Description

EMBED_PROC

microblaze_0

MicroBlaze processor instance name as it appears in the block design. Must match exactly.

VITIS_SRC_PATH

(user-set)

Path to the C/C++ source directory for the application. Required before running make elf.

VITIS_LIB

$(MODULES)/surf/xilinx/general/sdk/common

BSP library include paths. Override to add custom BSP libraries to the build.

Troubleshooting

“vitis: command not found”

Source the Vitis settings script before running the build:

source /path/to/Vitis/settings64.sh
“processor not found in block design”

Verify that EMBED_PROC matches the processor instance name exactly as it appears in the Vivado block design. Open the block design in Vivado and check the cell name.

“xsct: command not found”

xsct ships with Vitis. If it is missing, verify that the full Vitis installation (not just Vivado) is installed and that its settings64.sh is sourced. The xsct binary is in the Vitis bin/ directory, not the Vivado bin/ directory.