Building a Bare-metal AI Engine in the Vitis IDE - 2021.2 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
UG1076
Release Date
2021-12-17
Version
2021.2 English
Building a bare-metal system requires a deviation from the standard application flow previously described. The branch in the process occurs at the Configuring the HW-Link Project step, with the bare-metal system requiring an addition to that step and then following a new process. The specific steps required are detailed below.
  1. For bare-metal systems you must follow the process described in Configuring the HW-Link Project with the added step of enabling the Export Hardware (XSA) option for Emulation-HW and Hardware builds. This triggers the creation of a fixed-XSA file used for building a bare-metal platform using data found in the AI Engine graph and PL regions of the design.
    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.
    After enabling this option, build the emulation or hardware build as usual. The fixed-XSA file will be written to the output folder for the build.

  2. Create a bare-metal platform. Building bare-metal applications requires a platform with a bare-metal domain. Because the xilinx_vck190_base_202120_1 base platform does not have one, you must create a custom platform with a bare-metal domain using the fixed-XSA file exported during the build process described above.
    1. Select the File > New > Platform Project command in the Vitis IDE. This opens the New Platform Project wizard as shown.

    2. Specify a Platform project name and click Next to proceed. This displays the Platform page of the wizard where you specify an XSA to create the new platform. Use the binary_container_1.xsa exported from the HW_Link project as described in Step 1.

    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. 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.
    4. Click the Build command to build the 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 IDE automatically adds the new platform to your platform repository making it available to use in new projects. You can also add the file location to your $PLATFORM_REPO_PATHS environment variable. This makes the platform accessible to the Vitis IDE, or allows you to specify the platform in command-lines by referring to the platform name rather than the whole path.

    Important: The generated platform will be used only for building the bare-metal PS application and is not used any other places in the flow.
  3. Create a new PS application project.
    1. Select the File > New > Application Project command in the Vitis IDE. This opens the New Application Project wizard.
    2. Click Next to skip past the first page, and display the Platform page as shown.
    3. Select the baremetal_platform you created in the last step, and click Next to proceed.

    4. Provide an Application project name and click Next.
    5. Review the Domain page and click Next to proceed.
    6. On the Templates page, select Empty Application and click Finish to create the project. The project is opened in the Vitis IDE.
    7. Add the source code for the PS application, main.cpp, platform.cpp, and associated files written specifically for the bare-metal project. Select the project in the Explorer view, expand the folders, right-click the src folder, and click the Import Sources command () to open the dialog box shown in the following figure. Select the files to add and click Finish.

    8. 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. Select the src folder again, and click the Import Sources icon () to open the dialog box and add the aie_control.cpp file to the project.
    9. Finally, you must add to the Include paths for your project. Right-click the bare-metal application project and select C/C++ Build Settings as shown.

      This selection opens the Build Settings dialog box, as shown in the following figure. Select the Directories option as shown, and select the Add command () to add the new include paths. You will need to add an entry for the source files for your original AI Engine graph application. This is the src folder for the project described in Creating the AI Engine Graph Project and Top-Level System Project. This should point to a folder containing your AI Engine graph source files. Click Apply and Close to finish defining the include path.



      With the updated Include path, select the Build () icon to build your project. When the build completes, you should see the ELF file for your bare-metal application.



  4. Package the system.
    1. With the ELF file produced for the PS application, you are ready to build the system-level project, and package the system 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. See Packaging for more information.
    2. In the system project created that was created when you set up your AI Engine graph project as discussed in Creating the AI Engine Graph Project and Top-Level System Project, add the following to the Packaging options field:
      --package.ps_elf ../../baremetal_app/Debug/baremetal_app.elf,a72-0
      Note: For debugging both the AI Engine graph, together with the bare-metal PS application, you should not add the --package option specified in the previous example. If you want to debug only the AI Engine graph, then you need to add the option as described.
    3. For the hardware build of the bare-metal application system project you need to specify an XCLBIN file for the project in the Packaging options field as shown in the following figure.
      Tip: You can copy or reference the required file from the top-level system project, which is the source of the fixed-XSA described in Step 1.
    4. Now build () the top-level system project.

      This adds the ELF file you created in the bare-metal application project, assigns it to a processor core, and builds the system project. See the --package option in the Vitis Compiler Command in the Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393) for more information.

      Note: In the Linux system, 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 for the package process in your top-level system.
Now that you have built the bare-metal system, you can continue to run or debug the application.
Important: You cannot debug the hardware emulation build for bare-metal projects in the Vitis IDE.