Skip to content

Latest commit

 

History

History
279 lines (195 loc) · 17 KB

step2.md

File metadata and controls

279 lines (195 loc) · 17 KB
Raw

Vitis™ Platform Creation Tutorials

See Vitis™ Development Environment on xilinx.com

Step 2: Create the Vitis Software Platform

In this step, you will create an AMD Vitis™ platform running the Linux operating system. The Vitis platform relies on several essential software components that must be prepared in advance. To expedite the process, AMD offers common software images for quick evaluation, and you could leverage these common images to jump-start your project.

Please note that Device Tree Blob (DTB) files are not included in the common image package because different platforms may have unique device peripherals. You can use the createdts command to generate the device tree file tailored to your specific platform.

If you require further customization of the system image, such as modifying the kernel or root file system (rootfs), please refer to the the PetaLinux customization page customization page for detailed instructions.

Listed below are the software components necessary for this platform:

Component Conventional Path or Filename Description Provenance
Boot components in BOOT.BIN fsbl.elf First stage boot loader Generated with platform creation
Boot components in BOOT.BIN pmufw.elf Chip internal power and security related management Generated with platform creation
Boot components in BOOT.BIN bl31.elf ARM trusted firmware/ secure monitor Extracted from common image
Boot components in BOOT.BIN u-boot.elf Second stage boot loader Extracted from common image
Boot components in BOOT.BIN system.dtb Device tree information file Generated from "createdts" command
Boot components in FAT32 partition of SD card boot.scr U-boot configuration file to store in FAT32 partition of SD card Extracted from common image
Linux Software Components Image Linux kernel Image Extracted from common image
Linux Software Components rootfs.ext4 Linux file system Extracted from common image
Linux SDK sysroot Cross compile and header files Extracted from common image

Note: The Kernel Image, Linux file system, and Sysroot are not mandatory components for the platform itself. Instead, they are utilized by applications to generate the SD Card Image.

As most of the components are extracted from the common image package, we will prepare the common image first.

Prepare the Common Images

  1. Download the common image from website download page..

  2. Navigate to the WorkSpace folder that you created in step1 and place the image package in WorkSpace folder.

    cd WorkSpace
tree -L 1     # to see the directory hierarchy
.
├── xilinx-zynqmp-common-v2024.1.tar.gz
└── zcu104_custom_platform

  3. Extract the common image.

    Please follow steps below to extract the common image.

    cd WorkSpace
tar xvf xilinx-zynqmp-common-v2024.1.tar.gz -C .

You can see the xilinx-zynqmp-common-v2024.1 folder which contains some components located in the WorkSpace folder as shown below:

   tree -L 2
   ├── xilinx-zynqmp-common-v2024.1
   │   ├── bl31.elf
   │   ├── boot.scr
   │   ├── Image
   │   ├── README.txt
   │   ├── rootfs.ext4
   │   ├── rootfs.manifest
   │   ├── rootfs.tar.gz
   │   ├── sdk.sh
   │   └── u-boot.elf

From the above directory structure, you can see that the boot file, kernel image, rootfs, and SDK tool are ready. DTB and first stage boot related files are not available. Among them, the PMU (Platform Management Unit) firmware FSBL (First Stage Boot Loader) can be generated by enabling the Generate Boot artifacts option during the platform creation process. In the subsequent step, we will focus on preparing the DTB file.

Create the Device Tree File

The device tree describes the hardware components of the system. The createdts command can generate the device tree file according to the hardware configurations from the XSA file. If there are any settings unavailable in the XSA, for example, any driver nodes that do not have corresponding hardware, or if you have their own design hardware, you must add customization settings in the system-user.dtsi file.

In addition to U-Boot file, lacks default environment variables. So you must update the bootargs manually. To streamline this process, a pre-prepared system-user.dtsi file which adds pre-defined bootargs is located in the step2_pfm directory. Copy the system-user.dtsi file to the WorkSpace directory and follow these steps to generate the DTB file.

Note: Device tree knowledge is a common know-how. Please refer to AMD Device tree WIKI page or Device Tree WIKI page for more information if you are not familiar with it.

  1. First, go to Wroksapce directory and launch XSCT tool.

    cd Workspace
xsct

  2. Execute the createdts command in the XSCT console as shown below:

    createdts -hw ../zcu104_hardware_platform/zcu104_custom_platform_hw.xsa -zocl  -platform-name mydevice \
 -git-branch xlnx_rel_v2024.1 -board  zcu104-revc  -dtsi system-user.dtsi -compile

    The createdts command needs the following input values:

    • -hw: Hardware XSA file with path.
    • -platform-name: Platform name.
    • -git-branch: device tree branch.
    • -board: board name of the device. You can check the board name at /device_tree/data/kernel_dtsi.
    • -zocl: enable the zocl driver support.
    • -dtsi: Add user's device tree file support.
    • -compile: specify the option to compile the device tree.

    The following information will be displayed on the XSCT console. You can safely disregard the warning. This message confirms that you have successfully obtained the system.dtb file which is located in the <mydevice/psu_cortexa53_0/device_tree_domain/bsp> folder.

    pl.dtsi:9.21-32.4: Warning (unit_address_vs_reg): /amba_pl@0: node has a unit name, but no reg property                                                      
system-top.dts:26.9-29.4: Warning (unit_address_vs_reg): /memory: node has a reg or ranges property, but no unit name
zynqmp.dtsi:790.43-794.6: Warning (pci_device_reg): /axi/pcie@fd0e0000/legacy-interrupt-controller: missing PCI reg property
pl.dtsi:27.26-31.5: Warning (simple_bus_reg): /amba_pl@0/misc_clk_0: missing or empty reg/ranges property

    Note: createdts is a command that is executed on the XSCT console to generate device files. This command needs several inputs to generate the device tree files. Use the help command to find out about the input options. XSCT is a console tool for Vitis. You can start it by typing xsct on a Linux terminal, or you can select menu Xilinx > XSCT Console to start the XSCT tool after you launch the Vitis software platform.

    Execute the following command to exit XSCT console.

    exit

    Following the completion of this step, all the necessary components for platform creation are now prepared. In the next phase, we will proceed to attach all these components to your platform and initiate the build process.

Create a Vitis Platform

  1. Install the sysroot

    • Go to common image extracted directory <WorkSpace/xilinx-zynqmp-common-v2024.1/>.
    • Type ./sdk.sh -d <Install Target Dir> to install the PetaLinux SDK. Use the -d option to provide a full pathname to the output directory . (This is an example. . means current directory. ) and confirm.

    The environment variable LD_LIBRARY_PATH must not be set when running this command.

    Note: Sysroot is not mandatory components for the platform itself. It is the cross compile tool prepared for applications compilation.

  2. Create the Vitis platform.

    For this example, you will use the Vitis Unified IDE to create the Vitis Platform. Got to WorkSpace directory and follow steps below to create the platform.

    1. Run Vitis by typing vitis -w . in the console. -w is to specify the workspace. . means the current worksapce directory.
    2. In the Vitis Unified IDE, from menu select File > New Component > Platform to create a platform component.
    3. On the Create Platform Component setup dialog
      • Enter the component name and location. For this example, type zcu104_custom and use default location. Click Next.
      • Click Broswe button, select the XSA file generated by the Vivado. In this case, it is zcu104_custom_platform_hw.xsa.

        Note: If you want to create a platform with emulation support please click Emulation and select the emulation XSA file.

      • Set the operating system to linux.
      • Set the processor to psu_cortexa53.
      • Check the option Generate boot artifacts. Then click Next.

        Note: Enabling this option will trigger the tool to automatically generate a PMU firmware domain and an FSBL (First Stage Boot Loader) domain into the platform

      • Review the summary and click Finish.

      Note: After a few moments, the platform component will be prepared and available in the component view. Simultaneously, the platform configuration file, vitis-comp.json, will be automatically displayed in the main view. Users can access the vitis-comp.json file by expanding the Settings section under the platform component.

  3. Set up the software settings in the Platform configuration view by clicking the Linux On psu_cortexa53 domain, browse to the locations and select the directory or file needed to complete the dialog box for the following:

    • Display Name: update it as xrt

    • Bif file: Click the button to generate bif file or click Browse to select existing bif file.

      Note: The filenames in <> are placeholders in the bif file. Vitis will replace the placeholders with the relative path to platform during platform packaging. V++ packager, which runs when building the final application#, would expand it further to the full path during image packaging. Filename placeholders point to the files in boot components directory. The filenames in boot directory need to match with placeholders in BIF file. <bitstream> is a reserved keyword. V++ packager will replace it with the final system bit file.

    • Pre-Built Image Directory: Browse to xilinx-zynqmp-common-v2024.1 and click OK.

    • DTB File: Browse to mydevice/psu_cortexa53_0/device_tree_domain/bsp and select system.dtb, then click OK.

    • FAT32 Partition Directory: This directory is used to add additional file to the fat32 partition. User can set it according to your requirement.

    • QEMU Data: This Directory is used to add additional file for emulation. User can set it according tyour requirement.

    vitis_linux_config.PNG

    Note:: Qemu Args File and Pmu Args File are populated by the tool automatically. If there are additional QEMU settings, please update it accordingly.

  4. Select zcu104_custom platform component in the flow navigagor, then click the Build button to build the platform.

    missing image

    Note: The generated platform is placed in the export directory. BSP and source files are also provided for rebuilding the FSBL, if required, and are associated with the platform. The platform is ready to be used for application development.

    missing image

    Note: After compilation, users can locate the XPFM file by expanding the Output directory. This provides a logical view of the output. The actual path of platform file is under workspace/zcu104_custom/export/zcu104_custom/ directory. Users can also view the complete path of the platform file by simply hovering the mouse pointer over the XPFM file.

    Note: The Vitis Unified IDE will find the boot-related files menntioned in the software components in begin of this step and place them in the boot folder of the platform.

    If you create a Vitis application component in the same workspace as this platform component, you can find this platform available in the platform selection page in the application Creation wizard. If you want to reuse this platform in another workspace, add its path to the PLATFORM_REPO_PATHS environment variable before launching the Vitis GUI, or use the "Add" button on the platform selection page of the Vitis GUI to add its path.

    User could also use Vitis python command to create the platform component.

    Click here to see how to use Vitis python command to create a Vitis platform

    Create a python script. For example, here is the parts of platform_creation.py.

    import vitis
import argparse
import os
print("Platform generation")
parser = argparse.ArgumentParser()
parser.add_argument("--platform_name", type=str, dest="platform_name")
parser.add_argument("--xsa_path", type=str, dest="xsa_path")
parser.add_argument("--xsa-emu_path", type=str, dest="emuxsa_path")
parser.add_argument("--boot", type=str, dest="boot")
parser.add_argument("--dtb", type=str, dest="dtb")
args = parser.parse_args()
platform_name=args.platform_name
xsa_path=args.xsa_path
emuxsa_path=args.emuxsa_path
dtb=args.dtb
boot=args.boot
print('args',args)
client = vitis.create_client()
client.set_workspace(path=os.getcwd())
platform = client.create_platform_component(name = platform_name, hw =xsa_path, os = "linux",cpu = "psu_cortexa53",emulation_xsa_path = emuxsa_path )
platform = client.get_platform_component(name=platform_name)
domain = platform.get_domain(name="linux_psu_cortexa53")
status = domain.update_name(new_name="xrt")
status = domain.generate_bif() 
status = domain.add_boot_dir(path=boot)
status = domain.set_dtb(path=dtb)
status = platform.build()

    This python script is for user to create a platform. It needs the following input values.

    • name: Platform name.
    • hw: Hardware XSA file location.
    • emulation_xsa_path: Hardware emulation XSA file location.
    • boot: pre-built image path.
    • dtb: DTB file path.

    The following is the command brief explanation.

    • client.create_platform_component is used to create a platform with standalone domain or the Linux domain.
    • domain.add_boot_dir is used to set the pre-built image path.
    • domain.set_dtb is used to set the DTB file.

    You can pass the values to the script directly by replacing the variable with the actual value, or pass the value to python script.

    Here is an example of calling python script.

    vitis -s platform_creation.py --platform_name <> --xsa_path <> --xsa-emu_path <> --boot <> --dtb <>

Fast Track

Scripts are provided to create the Vitis platform component. To use these scripts, run the following steps.

  1. Run build.

    Note: Download the common image from the website download page and give its path to the following command.

    # cd to the step directory, e.g.
cd step2_pfm
make all COMMON_IMAGE_ZYNQMP=<path/to/common_image/>

  2. To clean the generated files, run the following command:

    make clean

Next Steps

In the next step, you will build some applications on this platform and test them..

Copyright © 2020–2024 Advanced Micro Devices, Inc

Terms and Conditions