Run Baremetal Software Emulation - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English

To step back from creating acceleration applications for platform verification, you can run emulation of baremetal host applications to test the hardware inside the platform. This lets you quickly test the embedded platform against the drivers required to access elements of the hardware through the baremetal application. This can help platform developers validate platform peripheral features and custom IP in the platform with simple applications. This validation requires you to convert the extensible platform to a fixed version for baremetal software development. This validation does not need Linux software components.

To create a fixed form of the extensible platform use the following steps.

Export a Fixed-XSA from the Extensible Hardware Platform
As described in Platform Types, there are two general types of platforms: extensible platforms and fixed platforms. Fixed platforms support embedded software development, and do not let you modify the PL kernels or the target platform defined by the device binary. However, the AI Engine flow does let you modify and recompile the graph application on a fixed platform.

A fixed-version of the hardware platform (.xsa) can be generated during the linking process of the Vitis compiler (v++) when building an Application Project as described in Building the Device Binary.

In the Vitis IDE, the fixed-XSA can be generated by enabling the Export hardware (XSA) check box in the Hardware Link Project Settings view. For the command-line flow, the feature must be enabled by adding the following option to a configuration file used during the v++ --link command:

The Vitis compiler exports a fixed hardware specification containing elements of the target platform with any acceleration kernels and the AI Engine graph fixed into the hardware. The fixed-XSA provides a BSP for the system design that you can use for developing embedded software applications.

Important: The fixed-XSA matches the specified build target of the Vitis compiler. So a hardware emulation capable fixed-XSA is generated from the hw_emu build target, and a hardware capable fixed-XSA is generated from the hw build target.
Generate a Baremetal Platform
  1. The fixed-XSA can be used to create or generate a baremetal fixed-version of an embedded processor platform, that can be used to validate the platform. Open the Vitis IDE and select File > New > Platform Project. This opens the New Platform Project wizard.
  2. Specify the Platform project name and click Next. This opens the Platform page as shown in the figure below.
  3. In this dialog box you can define the platform by specifying the name of the XSA File, selecting the Operating system, Processor domain, and Generate boot components for the platform.

    Select standalone for Operating system, specify the Processor, and Architecture to define the domain. Enable Generate boot components as shown above, and click Finish to generate the baremetal embedded platform.

    When the platform is complete, you should see it added to your repository of available platforms. You will use it to create a baremetal application project as described next.

Validate the Baremetal Platform with an Application Project
With the baremetal platform built, you can use a simple application running on the Arm processor to validate the platform. This approach lets you quickly exercise various features of the platform from compiled ELF files.
  1. In the Vitis IDE, select File > New > Application Project. This opens the New Application Project wizard.

    On the Platform page, select the baremetal platform you created in the prior step, and click Next to continue.

  2. The New Application Project wizard presents the Application Project Details page next. Specify the Project name and the System project name, and click Next to continue.
  3. The Domain page displays the domain information for the selected platform. Click Next to proceed.
  4. The Templates page displays a list of Embedded software development templates for the selected platform. Select the Hello World template, or another simple application, or select the Empty Application to let you specify your own source files, and click Finish to create the application project.
  5. With the baremetal application project in support of the baremetal platform, you are now ready to begin validation. You can use the baremetal platform with the same build target that the fixed-XSA was created from:
    • If the fixed-XSA was generated from a hardware emulation build (v++ --link -t hw_emu), it can be used for Emulation-HW builds in the baremetal application project.
    • If the fixed-XSA was generated from a hardware build (v++ --link -t hw), it can be used for Hardware builds in the baremetal application project.
    In the System Project Settings window, specify the Active build configuration that is compatible with the fixed-XSA of the baremetal platform, as shown below.
    Tip: You might also need to specify an .xclbin file for the baremetal application project in the Packaging options field as shown in the figure below. This is necessary for the hardware build, and you can copy the .xclbin file from the source project of the fixed-XSA into your baremetal Application Project.
  6. For the Emulation-HW build configuration, you can run the application in the QEMU environment and see the application interacting with the fixed-platform to validate the system. To run the emulation build, select the Launch HW Emulator command from the Assistant view, or the main toolbar menu. QEMU is launched through the TCF agent and in the Emulation Console view you can observe the transcript of QEMU booting and the PS application running.
    Important: Remember to set the heap/stack size to 2MB in the lscript.ld file, or a "Terminate" error will be displayed.
    Tip: You can also select the Debug As command to launch the interactive debug environment in the Vitis IDE.