System Design Example using Scalar Engine and Adaptable Engine

This chapter guides you through building a system based on Versal® devices using available tools and supported software blocks. This chapter demonstrates how to use the Vivado® tool to create an embedded design using PL AXI GPIO and PL AXI UART. It also describes how to configure and build the Linux operating system for an Arm® Cortex™-A72 core-based APU on a Versal ACAP device.

Examples using the PetaLinux tool are provided in this chapter.

Design Example: Using AXI GPIO

The Linux application uses a PL-based AXI GPIO interface to monitor the DIP switch of the board and accordingly control the LEDs on the board. The LED application can run on both the VMK180 and the VCK190 boards.

The RPU application uses the PL-based AXI UART lite to print the debug messages on the AXI UART console instead of using the PS UART console. The PL UART application can run on both the VMK180 and VCK190 boards.

Configuring Hardware

The first step in this design is to configure the PS and PL sections. You can do this using the Vivado IP integrator. Start with adding the required IPs from the Vivado IP catalog and then connect the components to blocks in the PS subsystem. To configure the hardware, follow these steps:

Note

If the Vivado Design Suite is open already, jump to step 3.

1. Open the Vivado project you created in Versal ACAP CIPS and NoC (DDR) IP Core Configuration.

   C:/edt/edt_versal/edt_versal.xpr

2. In the Flow Navigator, under IP Integrator, click Open Block Design.

   

3. Right-click the block diagram and select Add IP.

Connecting IP Blocks to Create a Complete System

To connect IP blocks to create a system, follow these steps.

1. Double-click the Versal ACAP CIPS IP core.

2. Click PS-PMC→ PL-PS Interfaces.

   

3. Enable the M_AXI_FPD interface and set the Number of PL Resets to 1, as shown in the previous figure.

4. Click Clocking, and then click on the Output Clocks tab.

5. Expand PMC Domain Clocks. Then expand PL Fabric Clocks. Configure the PL0_REF_CLK to 300 MHz as shown in the following figure:

   

6. Click Finish and OK to complete the configuration and return to the block diagram.

Adding and Configuring IP Addresses

To add and configure IP addresses, follow these steps.

1. Right-click the block diagram and select Add IP from the IP catalog.

2. Search for AXI GPIO and double-click the AXI GPIO IP to add it to your design.

3. Add another instance of the AXI GPIO IP into the design.

4. Search for AXI Uartlite in the IP catalog and add it into the design.

5. Click Run Connection Automation in the Block Design view.

   

   The Run Connection Automation dialog box opens.

6. In the Run Connection Automation dialog box, select the All Automation check box.

   

   This checks the automation for all the ports of the AXI GPIO IP.

7. Click GPIO of axi_gpio_0 and set the Select Board Part Interface to Custom as shown below.

   

8. Make the same setting for the GPIO of axi_gpio_1.

9. Click S_AXI of axi_gpio_0. Set the configurations as shown in the following figure:

   

10. Make the same setting for S_AXI of axi_gpio_1.

11. Click S_AXI of axi_uartlite_0. Set the configurations as shown in the following figure:

    

12. This configuration sets the following connections:

    • Connects the S_AXI of AXI_GPIO and AXI Uartlite to M_AXI_FPD of CIPS with SmartConnect as a bridge IP between CIPS and AXI GPIO IPs.

    • Enables the processor system reset IP.

    • Connects the pl0_ref_clk to the processor system reset, AXI GPIO, and the SmartConnect IP clocks.

    • Connects the reset of the SmartConnect and AXI GPIO to the peripheral_aresetn of the processor system reset IP.

13. Click UART of axi_uartlite_0. Set the configurations as shown in the following figure:

    

14. Click OK.

15. Click Run Connection Automation in the block design window and select the All Automation check box.

16. Click ext_reset_in and configure the setting as shown below.

    

    This connects the ext_reset_in of the processor system reset IP to the pl_resetn of the CIPS.

17. Click OK.

18. Disconnect the aresetn of SmartConnect IP from peripheral_aresetn of processor system reset IP.

19. Connect the aresetn of SmartConnect IP to interconnect_aresetn of processor system reset IP.

    

20. Double-click the axi_gpio_0 IP to open it.

21. Go to the IP Configuration tab and configure the settings as shown in the following figure.

    

22. Make the same setting for axi_gpio_1.

23. Add four more instances of Slice IP.

24. Delete the external pins of the AXI GPIO IP and expand the interfaces.

25. Connect the output pin gpio_io_0 of axi_gpio_0 to slice 0 and slice 1.

26. Similarly, connect the output pin gpio_io_0 of axi_gpio_1 to slice 2 and slice 3.

27. Make the output of Slice IP as External.

28. Configure each Slice IP as shown below.

    

29. Double-click axi_uartlite_0 to open the IP.

30. In the Board tab, set Board interface as shown below:

    

31. Go to the IP Configuration tab and configure the settings as shown in the following figure.

    

32. Add Clock Wizard IP. Double-click to open the IP.

33. Go to Clocking Features tab and set the configuration as shown below:

    

34. Make sure the Source option in Input Clock Information is set to Global buffer.

35. Go to Output clocks tab and configure as follows:

    

36. Right-click pl0_ref_clk of CIPS and click Disconnect Pin.

37. Connect the pl0_ref_clk from CIPS to input clk_in1 of the Clocking wizard.

38. Connect the output of clocking wizard to slowest_sync_clock of Processor System Reset IP.

    This will help in avoiding timing failure.

The overall block design is shown in the following figure:

Validating the Design and Generating the Output

To validate the design and to generate the output product, follow these steps:

1. Return to the block design view and save your block design (press Ctrl+S).

2. Right-click in the white space of the Block Diagram view and select Validate Design. Alternatively, you can press the F6 key. A message dialog box opens as shown below.

   The Vivado tool will prompt you to map the IPs in the design to an address. Click Yes.

   

   Note

   The number of address segments may vary depending on the number of memory mapped IPs in the design.

   Once the validation is complete, A message dialog box opens as shown below:

   

3. Click OK to close the message.

4. Click the Sources window.

   1. Expand Constraints.

   2. Right-click on constrs_1-> ADD Sources.

      The Add Sources window opens.

   3. Choose Add or Create Constraints option and click Next.

   4. Choose the .xdc file to be added.

      Note

      The constraints file is provided as part of the package in the pl_gpio_uart/constrs folder.

   5. Click Finish.

5. Click Hierarchy.

6. In the Sources window, under Design Sources, expand edt_versal_wrapper.

7. Right-click the top-level block design, edt_versal_i : edt_versal (edt_versal.bd), and select Generate Output Products.

   

8. Click Generate.

9. When the Generate Output Products process completes, click OK.

10. In the Sources window, click the IP Sources view. Here, you can see the output products that you just generated, as shown in the following figure.

    

Synthesizing, Implementing, and Generating the Device Image

Follow these steps to generate a device image for the design.

1. Go to Flow Navigator→ Program and Debug, click Generate Device Image and click OK.

2. A No Implementation Results Available menu appears. Click Yes.

3. A Launch Run menu appears. Click OK.

   When the Device Image Generation completes, the Device Image Generation Completed dialog box opens.

4. Click Cancel to close the window.

5. Export hardware after you generate the Device Image.

Note

The following steps are optional and you can skip these and go to the Exporting Hardware section. These steps provide the detailed flow for generating the device image by running synthesis and implementation before generating device image. If you need to understand the flow for generating the device image, follow the steps provided below.

1. Go to Flow Navigator→ Synthesis and click Run Synthesis.

   

2. If Vivado prompts you to save your project before launching synthesis, click Save.

   While synthesis is running, a status bar is displayed in the upper right-hand window. This status bar spools for various reasons throughout the design process. The status bar signifies that a process is working in the background. When synthesis is complete, the Synthesis Completed dialog box opens.

3. Select Run Implementation and click OK.

   When implementation completes, the Implementation Completed dialog box opens.

4. Select Generate Device Image and click OK.

   When Device Image Generation completes, the Device Image Generation Completed dialog box opens.

5. Click Cancel to close the window.

   Export hardware, after you generate Device Image.

Exporting Hardware

1. From the Vivado main menu, select File→ Export → Export Hardware. The Export Hardware dialog box opens.

2. Choose Include bitstream and click Next.

3. Provide a name for your exported file (or use the default provided) and choose the location. Click Next.

   A warning message appears if a hardware module has already been exported. Click Yes to overwrite the existing XSA file, if the overwrite message is displayed.

4. Click Finish.

Example Project: FreeRTOS AXI UARTLITE Application Project with RPU

This section explains how to configure and build the FreeRTOS application for an Arm Cortex-R5F core based RPU on a Versal device.

The following steps demonstrate the procedure to create a FreeRTOS Application from Arm Cortex-R5F:

1. Start the Vitis™ IDE and create a new workspace, for example, c:/edt/freertos.

2. Select File→ New → Application Project. The Creating a New Application Project wizard opens. If this is the first time that you have launched the Vitis IDE, you can select Create Application Project on the Welcome screen as shown in the following figure.

   

   Note

   Optionally, you can check the box next to Skip welcome page next time to skip seeing the welcome page every time.

3. There are four components of an application project in the Vitis IDE: a target platform, a system project, a domain and a template. To create a new application project in the Vitis IDE, follow these steps:

   1. A target platform is composed of a base hardware design and the meta-data used in attaching accelerators to declared interfaces. Choose a platform or create a platform project from the XSA that you exported from the Vivado Design Suite.

   2. 2. Put the application project in a system project, and associate it with a processor.

   3. 1. The domain defines the processor and operating system used for running the host program on the target platform.

   4. 1. Choose a template for the application, to quick start development. Use the following information to make your selections in the wizard screens.

      Table 9: Wizard Information

      Wizard Screen	System Properties	Setting or Command to Use
      Platform	Create a new platform from hardware (XSA)	Click Browse to add your XSA file
      	Platform Name	vck190_platform
      Application Project Detail	Application project name	freertos_gpio_test
      	Select a system project	+Create New
      	System project name	freertos_gpio_test_system
      	Processor	versal_cips _0_pspmc_0_psv_cortexr5_0
      Dom	Select a domain	+Create New
      	Name	The default name assigned
      	Display Name	The default name assigned
      	Operating System	freertos10_xilinx
      	Processor	versal_cips _0_pspmc_0_psv_cortexr5_0
      Templates	Available	Freertos Hello
      	Templates	world

   The Vitis software platform creates the board support package for the Platform project (vck190_platform) and the system project (freertos_gpio_test_system) containing an application project named freertos_gpio_test under the Explorer view after performing the preceding steps.

4. Right-click the freertos_hello_world.c file under src/ and delete the freertos_hello_world.c file. Copy the freertos source code files from the FreeRTOS project path, <design-package>/ch5_system_design_example_source__files/rpu/ to the src/ direcrtory.

5. Configure the Vitis IDE to enable AXI UARTLITE for RPU application debug console under the FreeRTOS Board Support Package.

   Navigate to platform.spr under vck190_platform project, and then select Modify BSP settings under Board support package, and modify stdin and stdout to axi_uarlite_0 by pressing <Y> option as shown in the figure.

   

6. Click <OK> to save the above configuration and exit the configuration wizard.

7. Right-click freertos_gpio_test_system and select Build Project. Alternatively, you can click .

   For building the Linux images and incorporating the FreeRTOS elf into the image, see Example Project: Creating Linux Images Using PetaLinux.

8. On PL AXI UART Serial Console, RPU debug logs will be printed as below:

   Gpio Initialization started
   Counter 0
   Counter 1
   Counter 2
   Counter 3
   Counter 4
   Counter 5
   

Example Project: Creating Linux Images Using PetaLinux

This section explains how to configure and build the Linux operating system for an Arm Cortex-A72 core-based APU on a Versal device. You can use the PetaLinux tool with the board-specific BSP to configure and build Linux images.

This example needs a Linux host machine. Refer to the PetaLinux Tools Documentation Reference Guide UG1144 for information on dependencies and installation procedure for the PetaLinux tool.

Important

This example uses the VCK190 PetaLinux BSP to create a PetaLinux project. Ensure that you have downloaded the respective BSP for PetaLinux (VCK190/VMK180).

• If you are using the VCK190 ES1 board, download the xilinx-vck190-es1-v2021.2-final.bsp file from here.

• If you are using the VCK190 production board, download the xilinx-vck190-v2021.2-final.bsp file from here.

• If you are using the VMK180 ES1 board, download the VMK180 PetaLinux 2021.12 BSP (xilinx-vmk180-es1-v2021.2-final.bsp) from here.

• If you are using the VMK180 Production board, download the VMK180 PetaLinux 2021.2 BSP (xilinx-vmk180-v2021.2-final.bsp) from here.

1. Copy the respective board’s PetaLinux BSP to the current directory.

2. Set up the PetaLinux environment

   $ source <petalinux-tools-path>/settings.csh
   

3. Create a PetaLinux project using the following command.

   $ petalinux-create -t project -s xilinx-vck190-vxxyy.z-final.bsp -n led_example
   

   Note

   For VMK180 board, use xilinx-vmk180-vxxyy.z-final.bsp after the -s option in the command.

4. Change to the PetaLinux project directory using the following command.

   $cd led_example
   

5. Copy the hardware platform project XSA to the Linux host machine.

   Note

   For the VMK180 board, use the XSA file that you generated in the Design Example: Using AXI GPIO.

6. Reconfigure the BSP using the following commands.

   $ petalinux-config --get-hw-description=<path till the directory containing the respective xsa file>
   

   This command opens the PetaLinux Configuration window. For this example, no need to change anything in this window.

7. Click <Save> to save the above configuration and then <Exit> to exit the configuration wizard.

8. Create a Linux application named gpiotest within the PetaLinux project using the following command.

   $petalinux-create -t apps --template install --name gpiotest --enable
   

9. Copy application files from <design-package>/<vck190 or vmk180>/linux/bootimages to the project using the following commands.

   $cp <design-package>/ch5_system_design_example_source__files/apu/gpiotest_app/gpiotest/files/* <plnxproj-root>/project-spec/meta-user/recipes-apps/gpiotest/files/
   $cp <design-package>/ch5_system_design_example_source__files/apu/gpiotest_app/gpiotest.bb <plnx-proj-root>/project-spec/meta-user/recipes-apps/gpiotest/gpiotest.bb
   $cp <design-package>/ch5_system_design_example_source__files/apu/device_tree/system-user.dtsi <plnx-proj-root>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
   

10. Enable GPIO support within kernel configuration.

    $petalinux-config -c kernel
    

    Note

    This command opens the kernel configuration wizard for the PetaLinux project.

11. Navigate to Device drivers→ GPIO Support and enable it by pressing the <Y> key. Press Enter and enable the Debug GPIO calls and /sys/class/gpio/...(sysfs interface) entries by pressing the <Y> key as shown in the following figure.

    

12. Navigate to Memory mapped GPIO drivers and enable Xilinx GPIO support and Xilinx Zynq GPIO support by pressing <Y> key as shown in the following figure.

    

13. Click <Save> to save the above configuration and then <Exit> option to exit the configuration wizard.

14. Configure ROOTFS to disable the AIE, STDC++, and TCL options to reduce the rootfs size to fit into both SD and OSPI/QSPI Flash partitions.

    petalinux-config -c rootfs
    

15. Navigate to User Packages and disable aie-notebooks, openamp-demo-notebooks, packagegroup-petalinux-jupyter, pm-notebooks, python3-ipywidgets support by pressing <Y> key as shown in the following figure.

    

16. Navigate to Filesystem Packages → misc → gcc-runtime and disable libstdc++ support by pressing <Y> key as shown in the following figure.

    

17. Navigate to Filesystem Packages → devel → tcltk → tcl and disable tcl support by pressing <Y> key as shown in the following figure.

    

18. Click <Save> to save the above configuration and then click <Exit> to exit the configuration wizard.

19. OSPI and eMMC boot modes will work only on VCK190/VMK180 REVB Production boards.

20. For OSPI build, copy the below code to PLNX project bsp file <plnxproj-root>/project-spec/meta-user/conf/petalinuxbsp.conf.

    VCK190 Production board:
    YAML_DT_BOARD_FLAGS_vck190 = "{BOARD versal-vck190-reva-x-ebm-03-reva}"
    
    VMK180 Production board:
    YAML_DT_BOARD_FLAGS_vmk180 = "{BOARD versal-vmk180-reva-x-ebm-03-reva}"
    

21. For eMMC build, copy the below code to PLNX project bsp file <plnxproj-root>/project-spec/meta-user/conf/petalinuxbsp.conf.

    VCK190 Production board:
    YAML_DT_BOARD_FLAGS_vck190 = "{BOARD versal-vck190-reva-x-ebm-02-reva}"
    
    VMK180 Production board:
    YAML_DT_BOARD_FLAGS_vmk180 = "{BOARD versal-vmk180-reva-x-ebm-02-reva}"
    

22. Build the Linux images using the following command.

    $ petalinux-build
    

Combining FreeRTOS and APU Images using a BIF File

1. Open the XSCT console in your Vitis IDE workspace.

2. Navigate to the images/linux directory of your PetaLinux project:

   $ cd <petalinux-project>/images/linux/
   

3. Freertos elf file is supported only for QSPI/SD boot images. Copy the freertos_gpio_test.elf from <design-package>/vck190/freertos/bootimages/freertos_gpio_test.elf to the images/linux directory.

   $ cp <design-package>/vck190/ready_to_test/qspi_images/freertos/freertos_gpio_test.elf .
   

4. Copy the bootgen.bif file from <design-package>/ to the images/linux directory.

   $ cp <design-package>/vck190/ready_to_test/qspi_images/linux/bootgen.bif .
   

5. Run the following command to create BOOT.BIN.

   $ bootgen -image bootgen.bif -arch versal -o BOOT.BIN -w
   

   This creates a BOOT.BIN image file in the <petalinux-project>/images/linux/ directory.

Note

To run the images using SD boot mode, see Boot Sequence for SD-Boot Mode.