Module 05: Bare-Metal PS Host Application - 2024.1 English - XD100

Difference between main_partial.cpp and main_full.cpp

There are two main files: main_partial.cpp and main_full.cpp. The only difference between them is that the main_partial.cpp file runs through 10 complex data samples (TDATA) for each kernel. The main_partial.cpp file is created to run through hardware emulation in a timely manner. In Module 06, you will run the main_partial.elf file for hardware emulation.

The main_full.cpp file runs through the full set of data. For the dlbf_data kernels, main_full.cpp runs through NITER=4 and BLOCK_SIZE=384 for a total of 1536 64-bit data packets (TDATA). For the dlbf_coeffs kernels, main_full.cpp runs through NITER=4 and BLOCK_SIZE=256 for a total of 1024 64-bit data packets (TDATA). In Module 06, you will run the main_full.elf file on the hardware run on the VCK190 board.

Generating the Platform

Building bare-metal applications requires a bare-metal domain in the platform. In Module 01, you created a custom platform with a bare-metal domain. In Module 04, you built on top of your custom platform and added PL kernels (and subsequently their PS drivers) to the design. The first step of building the bare-metal PS host application is to use the XSA generated during the link process to create a new software platform using the following command.

generate-platform.sh -name vck190_baremetal             \
                     -hw  ../../Module_04_AI_Engine_and_PL_Integration/build/rev1/hw/beamforming.rev1.hw.xsa \
                     -domain ai_engine:aie_runtime      \
                     -domain psv_cortexa72_0:standalone \
                     -out-dir build

The options are explained in the AI Engine Documentation: Building a Bare-Metal System.

Compiling the PS Application Source Code

You now need to compile your PS host application (main_partial.cpp or main_full.cpp) and the additional source code your PS host applications need. The source code is stored in the baremetal_src/ folder. This bare-metal PS host application only controls the PL kernels, so you do not need to compile the aie_control.cpp file in this design.

Compile the main_partial.cpp file using the following command:

aarch64-none-elf-g++ -c -Wall -O0 -g -mcpu=cortex-a72 -MMD -MP \
                     -I=build/vck190_baremetal/psv_cortexa72_0/standalone_domain/bsp/psv_cortexa72_0/include  \  
                     -o build/main_partial.o main_partial.cpp

In this step, you need to include the BSP include files from the generated platform. This command creates a build/main_partial.o object. The same options are used when compiling the main_full.cpp file.

Next, compile the helper source code stored in the baremetal_src/*.cpp files. Below is an example of how to compile the dlbf_din.cpp file. The rest of the baremetal_src/*.cpp files are compiled the same way.

aarch64-none-elf-g++ -c -Wall -O0 -g -mcpu=cortex-a72 -MMD -MP \
                     -I=build/vck190_baremetal/psv_cortexa72_0/standalone_domain/bsp/psv_cortexa72_0/include \   
                     -o build/dlbf_din.o baremetal_src/dlbf_din.cpp

This step creates a build/*.o object for each file in the baremetal_src/*.cpp.

Linking the PS Application Source Code

Lastly, link the PS application object (main_partial.o) with the baremetal_src object files:

aarch64-none-elf-g++ build/main_partial.o \
                     build/dlbf_cin.o       \
                     build/dlbf_din.o       \
                     build/dlbf_gold0.o     \
                     build/ulbf_cin.o       \
                     build/ulbf_din.o       \
                     build/ulbf_gold0.o     \
                     build/utils.o          \
                     build/utils_dlbf.o     \
                     build/utils_ulbf.o     \
                     -Wl, -T -Wl,./lscript.ld -mcpu=cortex-a72 -Wl,     \
                     --start-group,-lxil,-lgcc,-lc,-lstdc++,--end-group \
                     -L build/vck190_baremetal/psv_cortexa72_0/standalone_domain/bsp/psv_cortexa72_0/lib \
                     -o build/main_partial_ps.elf

During this step, the board support package (BSP) libxil.a is required. It is linked by including the BSP library from the generated platform. This command creates the bare-metal executable (main_partial.elf). The main_full.elf file is created in the same way.

Main Function

Open the main_partial.cpp source code and review the main function. It calls two functions: test_dlbf and test_ulbf. If either of them returns 0, the test has failed. If both of them return 1, the test has passed. The test_ulbf function is structured in the same way as the test_dlbf function.

test_dlbf/test_ulbf Functions

This section details the test_dlbf function (it is left to you to review the test_ulbf function). The diagram below shows the execution flow of the test_dlbf and test_ulbf functions.

Reset

The first thing the test_dlbf function does is call the dlbf_reset function (defined in the utils_dlbf.cpp file). This function resets the dlbf_data, dlbf_coeff, and dlbf_slave PL kernels. This is done by asserting and deasserting the DLBF_DATA_REG_OFFSET_RESET register using the Xil_Out32 function. The Xil_Out32 function is part of the AMD Hardware Abstraction Layer API in the standalone library. This API is used throughout this PS host application. See the OS and Libraries Document Collection (UG643) for the full API documentation.

Configuration

The test_dlbf function calls the dlbf_data_config_ips, dlbf_coeffs_config_ips, and dlbf_slave_config_ips functions. The functions configure the BLOCK_SIZE, NITER, and ROLLOVER_ADDR registers.

Check RAM

The dlbf_data_check_ram and dlbf_coeffs_check_ram functions are called. These functions are optional, but they are useful for debugging. In Module 03, the BRAMs in the dlbf_data and dlbf_coeffs PL kernels were initialized to input data stored in *_hex.mem data files. These check_ram functions ensure that the dlbf_data and dlbf_coeffs RAMs have been initialized to the correct values. The golden input data is stored in the dlbf_din.cpp and dlbf_coeffs.cpp files.

Start

The dlbf_start function is called. This function asserts the GO register bit for the dlbf_data and dlbf_coeffs PL kernels to start the PL traffic to the AI Engine.

Wait for Done: Inputs

The dlbf_data_wait_for_done is called continuously in a while loop. This function reads the MASTER_DONE register on each dlbf_data PL kernel. When all four data masters in the dlbf_data PL kernels have a status of DONE, the function returns a 1’b, which breaks the while loop. The while loop only calls the function 100 times maximum, and times out if the dlbf_data kernels are not done by then.

After the dlbf_data kernels are done sending their data to the AI Engine, wait for the dlbf_coeffs to send their data to the AI Engine. If the dlbf_data or dlbf_coeffs kernels time out, the test fails.

Wait for Done: Outputs

Wait for the dlbf_slave kernels to finish receiving output data from the AI Engine. The dlbf_slaves are done when NITER*BLOCKSIZE number of 32-bit complex data samples (TDATA) are received from the AI Engine. If the dlbf_slaves time out, the test fails.

Verify Output

If the dlbf_slave does not time out, the test_dlbf function calls the dlbf_slave_read_and_verify function. This function compares the data in the dlbf_slave to the golden output data in the dlbf_gold0.cpp file. If there are any mismatches, the test fails. If all the output data matches the golden output data, then the test_dlbf passes and returns a 1’b to the main function.

Support

GitHub issues will be used for tracking requests and bugs. For questions go to forums.xilinx.com.

_{Copyright © 2020–2024 Advanced Micro Devices, Inc}

^{Terms and Conditions}