Applications

Creating a Standalone Application Project

You can create a C or C++ standalone application project by using the New Application Project wizard.

To create a project:

  1. Click File > New > Application Project. The New Application Project wizard appears.
    Note: This is equivalent to clicking on File > New > Project to open the New Project wizard, selecting Xilinx > Application Project, and clicking Next.

    This will show you the page that guide you to create the application project.

  2. Click Next to open the platform view.
  3. Choose a platform for your project.
    • You can either use a pre-supplied platform (from Xilinx or another vendor), or a previously created custom platform.
    • You can create one automatically from an exported Vivado hardware project (XSA).

    Click Next to proceed.

  4. Provide the name of the application project (user choice), the name of the system project (user choice), and the target processor for the application. The tool automatically creates a system project with the given name, but you can add the application to existing system projects. Click Next to proceed to the Domain page.

  5. Provide the name of the domain (user choice), select the Operating System as standalone, and also select the architecture. The tool automatically creates a domain for the target processor. Additionally, you can use existing domains in the platform. Click Next to proceed to the Templates page.

    The software platform provides useful sample applications listed in the Templates page that you can use to create your project. The Description box displays a brief description of the selected sample application. When you use a sample application for your project, the Vitis software platform creates the required source and header files and linker script.

  6. Select the desired template. If you want to create a blank project, select Empty Application.

    You can then add C files to the project, after the project is created.

  7. Click Finish to create your application project and the domain (if it does not exist).

Creating a Linux Application Project

You can create a C or C++ Linux application project by using the New Application Project wizard.

To create a project:

  1. Click File > New > Application Project. The New Application Project wizard appears.

    This will show you the page that guide you to create the application project.

  2. Click Next to open the platform view.
  3. Choose a platform for your project.
    • You can either use a pre-supplied platform (from Xilinx or another vendor), or a previously created custom platform.
    • You can create one automatically from an exported Vivado hardware project (XSA).

    Click Next to proceed.

  4. Select the Platform that has a Linux domain and click Next.
    Note: If the Linux domain is not present in the platform, add it as shown in the following steps:
    1. After selecting the platform, click Next.
    2. On the system project page, select Show all the processors in the hardware specification option, and then select the Linux processor which is displayed in the list and click Next.
  5. Provide the name of the application project of your choice and select Next.

    This displays the list of domains present in the platform. Optional: You can choose the sysroot, the root file system, and the kernel image path.



  6. Click Next to proceed to the Templates page.

    The software platform provides useful sample applications listed in the Templates page that you can use to create your project. The Description box displays a brief description of the selected sample application. When you use a sample application for your project, the Vitis software platform creates the required source and header files and linker script.

  7. Select the desired template. To create a blank project, select Empty Application.

    You can then add C files to the project after the project is created.

  8. Click Finish to create your application project and board support package (if it does not exist).

Building Projects

The first step in developing a software application is to create a board support package to be used by the application. Then, you can create an application project.

When you build an executable for this application, Vitis automatically performs the following actions. Configuration options can also be provided for these steps.

  1. The Vitis software platform builds the board support package. This is sometimes called a platform.
  2. The Vitis software platform compiles the application software using a platform-specific gcc/g++ compiler.
  3. The object files from the application and the board support package are linked together to form the final executable. This step is performed by a linker which takes as input a set of object files and a linker script that specifies where object files should be placed in memory.

The following sections provide an overview of concepts involved in building applications.

Build Configurations

Software developers typically build different versions of executables, with different settings used to build those executables. For example, an application that is built for debugging uses a certain set of options (such as compiler flags and macro definitions), while the same application is built with a different set of options for eventual release to customers. The Vitis software platform makes it easier to maintain these different profiles using the concept of build configurations.

A build configuration is a named collection of build tools options. The set of options in a given build configuration causes the build tools to generate a final binary with specific characteristics. When the wizard completes its process, it generates launch configurations with names that follow the pattern <projectname>, where <projectname> represents the name of the project.

Each build configuration can customize:

  • Compiler settings: debug and optimization levels
  • Macros passed for compilation
  • Linker settings

By default, the Vitis software platform provides two build configurations, as listed in the following table:

Table 1. Build Configurations
Configuration Type Compiler Flags
Debug -O0 -g
Release -O2

Changing the Build Configuration

Use the Tool Settings properties view to customize the tools and tool options used in your build configuration. Follow these steps to change build settings:

  1. Select the project for which you want to modify the build settings in the Project Explorer view.
  2. Select Project > Properties. The Properties for <project> view appears. The left panel of the view has a properties list. This list shows the build properties that apply to the current project.
  3. Expand the C/C++ Build property.
  4. Select Settings.
  5. Use the Configuration list to select the configuration that needs to be modified.
  6. Click the Tool Settings view.
  7. Select the tool and change the settings as per your requirement.
  8. Click Apply to save the settings.
  9. When you finish updating the tools and their settings, click OK to save and close the Properties for <project> view.

Adding Symbols or Definitions

Definitions and symbols are tokenized and processed as if they have appeared during a preprocessor translation phase in a #define directive. You can add or remove symbols in the Vitis IDE with the following steps:
  1. Right-click your application project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Under gcc compiler, select Symbols.
  3. Click the Add... () button to add symbols, or the Delete () button to remove existing symbols.

Adding Libraries and Library Paths

You can add libraries and library paths for Application projects. If you have a custom library to link against, you should specify the library path and the library name to the linker.

To set properties for your Application project:

  1. Right-click your Application project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Expand the target linker section and select the libraries to which you want to add the custom library path and library name.

Specifying the Linker Options

You can specify the linker options for Application projects. Any other linker flags not covered in the Tool Settings can be specified here.

To set properties for your project:

  1. Right-click your managed make project and select C/C++ Build Settings. Alternatively, select Properties and navigate to C/C++ Build > Settings.
  2. Under the Tool Settings view, expand the target linker section.
  3. Select Miscellaneous.
  4. Specify linker options in the Linker Flags field by clicking the Add button. Options can be deleted using the Delete button, or modified using the Edit button.

Specifying Debug and Optimization Compiler Flags

Based on the build configuration selected, the Vitis software platform assigns a default optimization level and debug flags for compilation. You can change the default value for your project.

To set properties for your project:

  1. Right-click your managed make project.
  2. Select Properties. Alternatively, to set properties for a specific source file in your project, right-click a source file within your standard make project and select Properties to open the properties page.
  3. Expand the list under C/C++ Build.
  4. Click on Settings.
  5. Under the Tool Settings view, expand the gcc compiler list.
  6. Select Optimization to change the optimization level and Debugging to change the debugging level.

Specifying Miscellaneous Compiler Flags

You can specify any other compiler flags not covered in the Tool Settings for program compilation.

To set properties for your project:

  1. Right-click your managed make project and select Properties. Alternatively, to set properties for a specific source file in your project, right-click a source file within your standard make project and select Properties.
  2. Click C/C++ Build to expand the list and click on Settings.
  3. In the Tool Settings view, expand the gcc compiler list.
  4. Select Miscellaneous.
  5. In the Other flags field, specify compiler flags.

Restoring Build Configuration

Follow these steps to restore the build properties to have a factory-default configuration, or to revert to a last-known working build configuration:

  1. Select the project for which you want to modify the build settings in the Project Explorer view.
  2. Select Project > Properties. The Properties for <project> view appears. The left panel of the view has a properties list. This list shows the build properties that apply to the current project.
  3. Click the Restore Defaults button.
  4. When you finish restoring the build settings, click OK to save and close the Properties for <project> view.

Makefiles

Compilation of source files into object files is controlled using Makefiles. With the Vitis software platform, there are two possible options for Makefiles:

Managed Make
For managed make projects, the Vitis software platform automatically creates Makefiles. Makefiles created by the Vitis software platform typically compile the sources into object files, and finally link the different object files into an executable. In most cases, managed make eliminates the job of writing Makefiles. This is the suggested option.
Standard Make
If you want ultimate control over the compilation process, use standard make projects. In this case, you must manually write a Makefile with steps to compile and link an application. Using the standard make flow hides a number of dependencies from the Vitis software platform. You must follow manual steps for other tasks such as debugging or running the application from within the Vitis software platform. Therefore, the standard make flow is not recommended for general use.

Linker Scripts

The application executable building process can be divided into compiling and linking. Linking is performed by a linker that accepts linker command language files called linker scripts. The primary purpose of a linker script is to describe the memory layout of the target machine, and specify where each section of the program should be placed in memory.

Note: Only standalone applications need linker script. Linux OS helps managing the memory allocation, and thus it does not need a linker script.

The Vitis software platform provides a linker script generator to simplify the task of creating a linker script for GCC. The linker script generator GUI examines the target hardware platform and determines the available memory sections. The only action required by you is to assign the different code and data sections in the ELF file to different memory regions.

Note:
  • For multi-processor systems, each processor runs a different ELF file, and each ELF file requires its own linker script. Ensure that the two ELF files do not overlap in memory.
  • The default linker always points to the DDR address available in memory. If you are creating an application under a given hardware/domain project, the memory will overlap for the applications.

Generating a Linker Script for an Application

To generate a linker script for an application, do the following:

  1. Select the application project in the Project Navigator view.
  2. Right-click Generate Linker Script. Alternatively, you can click Xilinx > Generate Linker Script. The left side of the page is read-only, except for the Output Script name and project build settings in the Modify project build settings as follows field. This region shows all the available memory areas for the design. You have two choices of how to allocate memory: using the Basic view or the Advanced view. Both perform the same tasks; however, the Basic view is less granular and treats all types of data as “data” and all types of instructions as “code”. This is often sufficient to accomplish most tasks. Use the Advanced view for precise allocation of software blocks into various types of memory.
  3. Click OK.

    If there are errors, they must be corrected before you can build your application with the new linker script.

    Note: If the linker script already exists, a message view appears, asking if you want to overwrite the file. Click OK to overwrite the file or Cancel to cancel the overwrite.

    The Vitis software platform automatically adds the linker script to the linker settings for a managed make project based on the options selected in Modify project build settings as follows.

Basic Page

Configure the following sections of the Linker Script Generator page Basic view. Placing these key sections into the appropriate memory region can improve performance. Use the drop-down menu next to the code, data, and heap or stack sections to select the region and type of memory that you want these blocks to reside in.

Code Sections
This is used to store the executable code (instructions). Typically DDR memory is used for this task. Sometimes interrupt handlers or frequently used functions are built into separate sections and can be mapped to lower latency memory such as BRAM or OCM.
Data Sections
Place initialized and uninitialized data in this region. Often DDR memory is used; however, if the data size requirements are small, OCM or BRAM can be used to improve performance.
Heap and Stack
Heap is accessed through dynamic memory allocation calls such as malloc(). These sections are typically left in DDR unless they are known to be small, in which case they can be placed in OCM or BRAM. If the stack is lightly used, no significant performance loss will occur if left in DDR.
Heap Size
Specify the heap size. Even if a programmer does not use dynamic memory allocation explicitly, there are some functions that use the heap such as printf(). It is a good idea to allocate a few KB for such functions, as a precaution.
Stack Size
Specify the stack size. Remember that the stack size grows down in memory and could overrun the heap without warning. Make certain that you allocate enough memory, especially if you use recursive functions or deep hierarchies.


Advanced Page

If you require more control over the definition of memory sections and assignments to them, use the LinkerScript Generator page Advanced view.

Code Section Assignments
Typically there is only one code section, .text, unless you specifically created other code sections. All the code sections appear in this region.
Data Sections Assignments
The compilers automatically generate a number of different types of data sections including read-only data (.rodata), initialized data (.data), and uninitialized data (.bss).
Heap and Stack Section Assignments
Use this area to map the heap and stack onto memory and define their sizes.
Heap Size
Specify the heap size. Even if a programmer does not use dynamic memory allocation explicitly, there are some functions that use the heap such as printf(). It is a good idea to allocate a few KB for such functions, as a precaution.
Stack Size
Specify the stack size. Remember that the stack size grows down in memory and could overrun the heap without warning. Make certain that you allocate enough memory, especially if you use recursive functions or deep hierarchies.


Manually Adding the Linker Script

If you want to manually add the linker script for a managed make flow, do the following:

  1. Right-click your managed make project and select C/C++ Build Settings.
  2. Click the linker corresponding to your target processor, for example ARM v8 gcc linker.
  3. Select Linker Script to add the linker script.
  4. For standard make projects, add the linker script manually to your Makefile linker options.

Modifying a Linker Script

When you generate a linker script, there are multiple ways in which you can update it.
  1. Open the linker script using a text editor, and directly edit the linker script. Right-click on the linker script and select Open With > Text Editor.
  2. Regenerate the linker script with different settings using the linker script generator.
  3. Use the linker script editor to make modifications. To do this, double-click on the linker script. The custom linker script editor displays relevant sections of the linker script.

The linker script editor provides the following functionality.

Table 2. Linker Script Editor Functionality

Name

Function
Available Memory Regions This section lists the memory regions specified in the linker script. You can add a new region by clicking on the Add button to the right. You can modify the name, base address and size of each defined memory region.
Stack and Heap Sizes This section displays the sizes of the stack and heap sections. Simply edit the value in the text box to update the sizes for these sections.
Section to Memory Region Mapping This section provides a way to change the assigned memory region for any section defined in the linker script. To change the assigned memory region, simply click on the memory region to bring a drop down menu from which an alternative memory region can be selected.

Changing a Referenced Domain

You can re-target an application project to a different platform. The Vitis™ software platform lists all the applicable system configurations available in the re-targeted platform. You must select the right domain from the available domains of a selected system configuration. To change the referenced domain, follow these steps:
IMPORTANT: The new platform should have domain(s) matching the current domain.
  1. Double-click on <project name>.prj in the Explorer view.
  2. Click the ellipses (…) beside the Domain field in the Application Project Settings to see the available configurations in the platform.

  3. Select the domain to re-target.

Creating a Library Project

You can create a managed make library project by using the New Library Project wizard.

To create a library project:

  1. Click File > New > Library Project.
  2. Click Next. The New Library Project wizard appears.

    This will show you the page that guide you to create the application project.

  3. Click Next to open the platform view.
  4. Choose a platform for your project.
    • You can either use a pre-supplied platform (from Xilinx or another vendor), or a previously created custom platform.
    • You can create one automatically from an exported Vivado hardware project (XSA).

    Click Next to proceed.



  5. Provide the name of the library project (user choice) and choose either shared or static as the library type.
    Table 3. Library Project Creation Flags
    Processor Toolchain Standalone Linux
    Static Library Static Library Shared Library
    Extra Compiler Flags Archiver Flags Extra Linker Flags Extra Compiler Flags Archiver Flags Extra Compiler Flags Extra Linker Flags
    A9 Linaro "-mcpu=cortex-A9 -mfpu=vfpv3 -mfloat-abi=hard" None None "--static" None "-fPIC" "-shared"
    A9 Code Sourcery None None None "--static" None "-fPIC" "-shared"
    A53 Linaro None None None "--static" None "-fPIC" "-shared"
    A53-32 Bit Linaro "-march=armv7-a" None None "--static" None "-fPIC" "-shared"
    R5 Linaro "-mcpu=cortex-r5" None None NA NA NA NA
    MicroBlaze Xilinx "-mcpu=v9.5 -mlittle-endian -mno-xl-soft-mul -mxl-barrel-shift -mxl-pattern-compare" "-mlittle-endian" None "--static" None "-fPIC" "-shared"
    A72 Linaro "-mcpu=cortex-a72" None None NA NA NA NA
  6. Select the target processor. The tool automatically creates the system project. You can change name of the system project. Click Next.
  7. Select the Operating system based on your choice. Click on Next.

    The template list appears.

  8. Choose Empty application and click on Finish.

User Makefile Flow

The Vitis IDE supports the import of a user Makefile. See the following steps for details.
  1. Create an empty project for the platform.
  2. Import the sources and Makefile(s) of the command line application. To import sources, follow these steps:
    1. Right-click on the application and select Import sources.
    2. Select the source directory path and the required files required.
    3. Click OK.
  3. Right-click the project, and select C/C++ Build Settings.
  4. Deselect the Generate Makefiles automatically checkbox. In the Build directory field, enter the directory where you imported the Makefile.
  5. The default build command is make. You can customize this build command by deselecting the Use default build command checkbox and then entering your custom build command in the text entry field.
  6. Select the Behavior view. Update the build, incremental build, and clean commands as required.
  7. Click Apply and Close.

Creating a User Application Template

The Vitis software platform and XSCT support creation of user-defined application templates using the repository functionality. To create a standalone or Linux application template:

  1. A great way to start creating an user-defined application template is to look at an existing template for the directory structure and files that needs to be defined along with the source files.
    1. Sample standalone OS application template files are available at <Vitis software platform installation directory>\data\embeddedsw\lib\sw_apps\lwip_echo_server.
    2. Sample Linux OS application template files are available at <Vitis software platform installation directory>\data\embeddedsw\lib\sw_apps_linux\linux_hello_world .
    3. Observe the folder name. Also note that the file names are the same as the application template names, excluding the file extensions.
    4. Decide on your application template name and OS.
    5. Create an application Tcl file. The Tcl file name should be same as the application template name.
    6. Add the following functions to the Tcl file:
      1. swapp_get_name: This function returns the application template name. The return value should be same as the application template name.
        proc swapp_get_name {} {
    return "lwIP Echo Server";
}
      2. swapp_get_description: This function returns the description of the application template in the Vitis IDE. You can customize the description according to the application details.
        proc swapp_get_description {} {    
return "The lwIP Echo Server application provides a simple demonstration of 
how to use the light-weight IP stack (lwIP). This application sets up the board 
to use IP address 192.168.1.10, with MAC address 00:0a:35:00:01:02. The server listens 
for input at port 7 and simply echoes back whatever data is sent to that port."
}
      3. swapp_is_supported_sw: This function checks for the required software libraries for the application project. For example, the lwip_echo_server application template requires the lwip library in the domain.

      4. swapp_is_supported_hw: This function checks if the application is supported for a particular design or not. For example, lwip is not supported for MicroBlaze™ processors.

      5. swapp_get_linker_constraints: This function is used to generate the linker script. If this function returns lscript no, the linkerscript is copied from the application template. For example, the FSBL application does not generate a linker script. There exists a default linker script in the src folder that is used to create an application.
        proc swapp_get_linker_constraints {} {    
    # don't generate a linker script. fsbl has its own linker script
    return "lscript no";
}
      6. swapp_get_supported_processors: This function checks the supported processors for the application template. For example, the linux_hello_world project supports the ps7_cortexa9, psu_cortexa53, and microblaze processors.
        proc swapp_get_supported_processors {} {
    return "ps7_cortexa9 psu_cortexa53 microblaze";
}
      7. proc swap_get_supported_os: This function checks the OS supported by the application template.
        proc swapp_get_supported_os {} {
    return "linux";
}
  2. Create an application MSS file to provide specific driver libraries to the application template. The MSS file name should be similar to the application template name.
  3. Provide the OS and LIBRARY parameter details.

  4. Copy the newly created TCL and MSS files to the data folder.
  5. Create your source source files and save them in the src folder. Copy the lscript.ld file to the src folder, if required.
  6. Move the data and src folders to a newly created folder. For example:
    • For standalone application templates, create a folder sw_apps and move the data and src folders to the newly created folder. The Vitis software platform considers the applications created in the sw_apps folder as standalone applications.
    • For Linux application templates, create a folder sw_apps_linux and move the data and src folders to the newly created folder. The Vitis software platform considers the applications created in the sw_apps_linux folder as Linux applications.

Accessing User Application Templates

You can access the user template applications in the Vitis IDE or using the XSCT. To access the user application templates:

  1. Using the Vitis IDE:
    1. Launch the Vitis IDE.
    2. Select Xilinx > Repositories > Add.
    3. Select the repository folder, from the page that appears.
      Note: For standalone applications, the parent folder that contains the applications should be sw_apps. Example: C:\temp\repo\sw_apps\custom_app_name. For Linux applications, the parent folder that contains the applications should be sw_apps_linux. Example: C:\temp\repo\sw_apps_linux\custom_app_name.
    4. Select File > New > Application Project. The New Project wizard page appears.
    5. Click Next.
    6. Select your platform or create a new platform from the hardware (xsa).
    7. Provide the name of the application project and select the target processor. Click Next.

      The domain page appears.

    8. Choose the desired operating and processor type to match with the user application template.
    9. Select the user application template from the Available Templates list and click Finish to create an application based on the selected user application template.
  2. Using XSCT:
    1. Execute the following commands at the XSCT prompt: 
      setws {c:\temp\workspace}
repo –set {C:\temp\repo}app create -name custom_app -hw zc702 -os standalone -proc ps7_cortexa9_0 -template {custom_app_name}
app build -name custom_app