Edit the Platform DSA

Copy the Base Platform

The first step is to locate the platform specific files for one of the SDSoC base platforms. The files are provided as a part of the SDSoC software installation, and can generally be found at the following location: <SDx_Install_Dir>/platforms. For instance, the files for the ZCU102 platform can be found at <SDx_Install_Dir>/platforms/zcu102.

TIP: It is a good idea to copy the platform folder to make sure you are editing the copy, and not the original platform from your software installation. Though perhaps your file permissions would prevent you from modifying the installation files directly.

Open the Platform DSA

The DSA file for the platform can be can be found in the ./hw folder of the platform. For example, the DSA file for the ZCU102 platform is found at zcu102/hw/zcu102.dsa.

In your copy of the platform, open the DSA in the Vivado Design Suite using the following process.
  1. Launch the Vivado Design Suite:
    source <SDx_Install_Dir>/settings64.csh
    vivado & 
  2. From within the Vivado IDE, open the DSA by using the following command from the Tcl Console:
    open_dsa <path_to_dsa>/zcu102.dsa

A new project is created in your current working directory, and the block design is opened in the Vivado IP Integrator. The block design inside the DSA file has the name from the original platform you are editing. At this point, you should rename the block design to match the name of the new platform you are creating.

Use the File > Save Block Design As command from the main menu to rename the block design.

TIP: When you use the Save Block Design As command, the new block design is added to the current project.

Remove Original Block Design

To remove the original block design, and its wrapper from the project, open the Sources window, and expand the wrapper to show original block design inside. Select both the wrapper and the block design. Right-click and select the Remove File from Project command.

Figure: Remove File from Project

This removes the HDL wrapper and the original block design from the project. In the Remove Sources dialog box that opens, you can select the Also delete the project local file/directory from disk checkbox to completely delete the files. This should leave the new block design in the project, and you are ready to move to the next step of changing the target part for the project.

TIP: Removing the HDL wrapper opens the Invalid Top Module dialog box as there is no top-level design module for the project. Select the Ignore and continue with invalid top module option, and click OK.

Change the Project Part

At this point you can edit the project settings to change the target part for the project. Select the Settings command under the Project Manager menu in the Flow Navigator window. The Settings dialog box will open displaying the current Project device as shown below.

Figure: General Page of the Settings Dialog Box

Select the Browse button for the Project device field to open the Select Device dialog box. From this dialog box you can select a board or part for the project. Select the Parts tab at the top of the Select Device dialog box to list the available parts as shown below. The displayed parts can be filtered by Category, Family, Package, etc. You can also use the Search field to filter the displayed parts by a specific search string.

Select a new Project part for your design, for example the xczu9eg-ffvb1156-2-i device.

Figure: Select Device

As soon as you change the project settings from a board flow to a part-based flow, all of the IP in the design will go stale, be locked, and require an upgrade. This is indicated by the yellow banner at the top of the block design. At the very least, the change of the target part in the project has made the current customization of the IP in the design out-of-date. For this reason the IP is locked, and must be updated to re-target the new part in the design.

TIP: There may be other reasons, such as major or minor revisions, that the IP may be locked and need to be updated.

Figure: Locked IP Banner

Click the Report IP Status link in the banner. This opens the IP Status report. Select all of the IP in the report and click the Upgrade Selected command.

After the IP in the design are upgraded, the Generate Output Products dialog box is displayed. Select Generate. This starts the generation of the necessary HDL files for the IP contained within the block design. Wait for the generation of the output products to finish. The Design Runs window displays the status of the Out-of-Context module runs.

Edit Platform Properties

The block design needs platform properties to be defined, as explained in Declaring Platform (PFM) Interfaces and Properties. Review that topic for a complete discussion of what needs to be done.

Begin editing the platform properties by selecting Window > Platform Interfaces from the Vivado menu bar and clicking on the Enable platform interfaces link. This displays any existing platform properties that you may need to update.

TIP: The platform properties defined in the original block design may be inherited in the new block design you created using the Save Block Design As command. You will need to set the platform properties again to insure they properly define your platform.

In the Platform Interface window, select the top-level Platform, as shown in the following figure. Selecting the top-level Platform in the Platform Interfaces window, opens the Platform Properties window, also shown in the following figure.

Figure: Select the Top-Level Platform

Notice the Platform Properties window displays the Name, Vendor, Board, and Version properties, which you can edit as needed to define your custom platform. Edit the Vendor field to specify your company name, or appropriate name as the Vendor of this platform.

IMPORTANT: You must edit at least one field in the Platform Properties window to have the properties written to the current project, which is required for the DSA.
After editing the Platform Properties, you should see commands similar to the following commands written to the Tcl Console window:
set_property pfm.name my_platform [get_files ...]
set_property dsa.name "my_platform" [current_project]
set_property dsa.vendor "xilinx.com" [current_project]
set_property dsa.board_id "lib" [current_project]

In the Platform Interfaces window, check the Clocking properties, the Interface properties, and the Interrupt properties as defined in Configuring Platform Interface Properties.

With the platform properties defined, you can validate the block design by running validation. This can be done by typing the following command in the Tcl console:

validate_bd_design -include_pfm -force

Write the Platform DSA

In this step, you will create an HDL wrapper for the block design, generate a bitstream for the design (after synthesis and implementation), export the hardware description file, and write the DSA file for use by SDSoC.

In the Sources window, create a new HDL wrapper by right-clicking on the block design and selecting Create HDL Wrapper. In the Create HDL Wrapper dialog box, select the Let Vivado manage wrapper and auto-update option, and click OK.

After the wrapper is created, right-click the wrapper in the Sources window, and select the Set as Top command to specify this as the top-level of your platform design.

In the Flow Navigator, select Generate Bitstream. The Vivado tool notifies you that there are no implementation results, and asks if you want to run synthesis and implementation. Click Yes to proceed. Click OK to launch the runs.

With the bitstream generated for the platform, use the File > Export > Export Hardware command to write the hardware description file for the project. Select Include bitstream when prompted in the Export Hardware dialog box.

You are now ready to generate the new platform DSA, to replace the original DSA file you opened at the start of this process. In the Tcl Console, use the following commands to write and validate the DSA:
write_dsa -force -include_bit <path_to_platform>/my_platform.dsa
validate_dsa my_platform.dsa

With the platform DSA file exported, you are now ready to import the DSA into a new platform project, and define the software platform elements as described in the next section.

Migrating Platforms to 2019.1 and Later

The platform structure and process for creating platforms has changed starting 2017.4, notably in the three following areas:

  • SDSoC Tcl commands have been replaced with Vivado properties requiring you to update the project and rerun the write_dsa command, as described in Mapping SDSoC Tcl Commands to Vivado Properties.
  • IP Caching is enabled for hardware platforms, which reduces the time to compile the hardware accelerated functions. You must set the dsa.ip_cache_dir property, re-synthesize the Vivado project to populate the cache, and regenerate the DSA file.
  • The SDx IDE now supports directly creating an SDSoC platform project. Regenerating an SDSoC platform will now be done as described in Creating SDSoC Platforms.

Mapping SDSoC Tcl Commands to Vivado Properties

The Tcl commands used in prior releases to set the platform and interface properties in the SDSoC platform have been replaced with a set of properties that can be defined directly in the Vivado Design Suite project. This requires reconfiguring the platform and interface properties for each platform to migrate it to the 2017.4 release before you can move to a more current version.

The following table shows the mapping of sdsoc:: Tcl commands to the PFM properties required in 2017.4 and beyond.

Table 1. Mandatory Properties: Pre-2017.4 and Post 2017.4
Purpose Pre 2017.4 Post 2017.4
Declare the hardware platform sdsoc::create_pfm PFM_NAME
Define the DSA Vendor Not required PFM_NAME
Define the hardware platform name sdsoc::pfm_name PFM_NAME
Define a brief description of the platform sdsoc::pfm_description Defined in the SDSoC platform project.
Declare the platform clock ports sdsoc::pfm_clock PFM.CLOCK
Declare the platform AXI bus interfaces sdsoc::pfm_axi_port PFM.AXI_PORT
Declare the platform AXI4-Stream bus interfaces sdsoc::pfm_axis_port PFM.AXIS_PORT
Declare the available platform interrupts sdsoc::pfm_irq PFM.IRQ
Generate the hardware platform DSA. sdsoc::generate_hw_pfm Replaced by the write_dsa Tcl command.