Creating a Bare-metal System - 2023.2 English

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

Document ID
Release Date
2023.2 English
Building a bare-metal system requires a deviation from the standard System project flow previously described. The branch in the process occurs after the Linking the System step, with the bare-metal system requiring a new process branching after the generating the .xsa file from the v++ --link command. The specific steps required are detailed below.
  1. Create a bare-metal fixed platform from the .xsa produced by the linking process for the hardware build target. Because the xilinx_vck190_base_202310_1 base platform does not have a bare-metal domain, you must create a custom platform with one.

    1. Select the File > New Component > Platform command in the Vitis unified IDE. This opens the Create Platform Component wizard as shown.

    2. Specify a Component name and click Next to proceed. This displays the Flow page of the wizard where you select Hardware Design and specify the binary_container_1.xsa from the System project to create the new platform.

    3. After you select the XSA, the Vitis IDE reads the file, determines the Operating system and Processor for the domain defined by the XSA, and populates it in the dialog box.

    4. Click Next to go to the Summary page and click Finish to create the platform project.
      Tip: The bare-metal platform is valid for either hardware emulation or hardware builds depending on the fixed-XSA selected for the platform.
    5. Click the Build command to build the newly created platform. A copy of the completed platform is written to the export folder of the project, and shows in the Explorer view for the project.

      As shown in the following figure, the exported platform has the platform.xpfm meta-data file, as well as the ./hw and ./sw folders for the different elements of the platform.

    The Vitis unified IDE automatically adds the new platform to your platform repository making it available to use in projects. You can also add the file location to your $PLATFORM_REPO_PATHS environment variable to make the platform available to the command-line tools as well as the Vitis unified IDE.

    Important: The bare-metal platform will be only used for building the bare-metal PS application and is not used any other places in the flow.
  2. Create a new embedded software Application component.
    1. Select the File > New Component > Application command in the Vitis IDE. This opens the New Application Project wizard.
    2. Specify a Component name and click Next.
    3. Select the baremetal-platform you created in the last step, and click Next to proceed.
    4. Review the Domain page and click Next to proceed.
    5. Review the Summary page and click Finish to create the Application component.
    6. Add the source files and build the application as described in Creating an Application Component. The source code for the PS application must be written specifically for the bare-metal project using the provided drivers for accessing the hadware system. For AI Engine designs you must also add the bare-metal AI Engine control file (aie_control.cpp), which is created by the aiecompiler command, and can be found in the ./Work/ps/c_rts folder.

    7. Edit the UserConfig.cmake file of the Application component located in the Settings folder in the Vitis Components Explorer. This step is only if you have AIE. Edit the Include paths under Directories to include the following:

    8. After updating the UserConfig.cmake file you can build the Application component.

  3. Package the System project with the new PS application added to the SD card files.
    1. With the ELF file produced for the bare-metal PS application, you are ready to package the System project and Application component for the bare-metal platform. You must run the package process to generate the final bootable image (PDI), and write the SD card content for booting the device and running the application, as described in Packaging the System.
    2. Add the following to the Packaging config as described in Defining the Package Configuration:
      Note: To enable debugging for both the AI Engine component and the bare-metal PS application, do not add the --package.ps_elf option. To debug only the AI Engine component, then add the option as described.
    3. After updating the package.cfg file, run the Build Package command on the System project.

      This adds the ELF file you created in Step 2 above for the bare-metal Application component, assigns it to a processor core (--package.ps_elf), and packages the System project files and boot system. In the original Linux-based System project, you added a PS application into the system project to build and debug as part of the system. Here you are building the PS application as part of a separate bare-metal project and adding it as a boot file to the package process in the original System project. This results in a System project build for the platform hardware, and a PS application that runs in the baremetal domain.

Now that you have built the bare-metal system, you can continue to run or debug the application as described in Bare-Metal Debug from the Vitis Unified IDE.
Important: You cannot debug the hardware emulation build for bare-metal projects in the Vitis unified IDE.