VisualApplets
User Manual

To actually generate (build) the hardware applets, VisualApplets uses a whole tool chain that works in the background.

For each hardware platform, VisualApplets provides a default build setup that is optimized for the specific hardware platform.

Based on the hardware platform you selected for your design in the design settings, the according default setup for build is proposed by VisualApplets. This setup cannot be changed by the user, but can be replaced by a user-defined setup.

	You have to replace the default build setup by own settings if ...
	You create designs for a microEnable 5 (ironman and marathon) or LightBridge platform. You work with Xilinx Vivado. You work with a Xilinx ISE version higher than 9.2.

Recommended Xilinx Tools

See Which Xilinx Toolchain and Version for Which Frame Grabber Platform for detailed information about which Xilinx tool is required to build applets for which hardware platform. mE5 marathon and LightBridge: Although applet build for mE5 marathon and LightBridge is possible with ISE 14.7, Basler recommends to use Xilinx Vivado since applet build (synthesis) with Vivado is much faster for these platforms.

Defining Build Settings

Using one Parameter Set as Active Configuration

Each time the program performs the build steps, a certain set of build parameters will be used.

There are several sets of build parameters that come with VisualApplets. You can add additional sets.

For building an applet, one of these sets has to be specified as the “Active configuration”. This configuration will be used and the tool chain will be controlled accordingly.

All setting information is stored in the file “SynthesizeSettings.xml” at your local installation.

Activated and Current Parameter Set

To open the Build Settings dialog, click Settings → Build Settings. The Dialog opens. The activated parameter set displayed: The activated parameter set is indicated by a green tick in the left-hand panel of the Build Settings dialog. The activated parameter set is used for build. The activated parameter set stays activated even if you select another parameter set to be displayed. (To display a parameter set, click on its name in the left-hand panel of the Build Settings dialog. The selected parameter set will be displayed in the right-hand panel of the Build Settings dialog.) The parameter set displayed you can edit, copy, save, or delete (see below). In the following, we will refer to the parameter set displayed as the "current parameter set".

Defining New Parameter Sets

The set of parameters itself consists of parameters for starting the external applications (Xilinx tools) that perform certain steps of the workflow, and of parameters for controlling these tools. You can define a certain set to be the default configuration (for starting a build of the current design) by checking “Active configuration”, and you can add a comment to describe the purpose of this specific set.

1. To open the Build Settings dialog, click menu Settings → Build Settings.

   The Dialog opens. The activated parameter set is displayed.

   	Before Adding the First Alternative Parameter Set
   	As long as no additional parameter set for the target hardware of your design has been created, the default build settings are displayed. You cannot make any changes to these default settings, therefore, all input fields are deactivated. You also cannot uncheck “Active configuration” as there is no alternative to the default yet.

2. Click Add to create a new set of parameters.

   You will be asked for hardware platform information. You can specify here which parameter set you want to load as a basis for creating your own parameter set. In most cases, it is quite sensible to select here the target hardware of your design.

   

   Figure 143. Selection of Hardware Platform

   
   

3. Click OK.

   Now, you can edit the first fields.

Figure 144. Build Settings Window

4. Name: Give a name to your new set of properties for identification. This name will show up in the configuration dialog and in the build protocols.

5. Active configuration: If you want to use this set of parameters when building your applet, check the box Active Configuration.

   	Active Configuration
   	The set of parameters you define as Active configuration will be used as often as you execute a build. When you change the hardware platform you selected as target hardware platform of the design: Define new build settings for this new platform.

6. Precondition Check: In default mode, the Precondition Check is activated. The Precondition Check verifies that the FPGA type on the target hardware of your design is supported by your Xilinx tool chain. In addition, in all designs for mE5 or LightBridge platforms: When this check box is activated, the information in operator AppletProperties is updated at each build, namely the fields BuildTime and AppletUid. Therefore, after a build has been completed, the design is in "unsaved" mode, since the parameter values in the operator AppletProperties have been changed during build.

   	Avoiding the Update of AppletProperties
   	Under specific circumstances you might not want to update the AppletProperties operator by a build. In this case, simply de-activate the check box Preconditions Check.

7. Xilinx ISE/Xilinx Vivado: Select the Xilinx tool chain you are going to use. Vivado is supported by all marathon and LightBridge platforms. If Vivado is not supported by the target hardware of the open design, this is stated directly in the GUI:

   

   Figure 145. Vivado Supported by Target Hardware Design

   
   
   

   Figure 146. Vivado not Supported by Target Hardware Design

   
   

8. Build Environment:

   • When using a newer Xilinx tool (i.e., when developing with Xilinx Vivado or with Xilinx ISE in a version higher than 9.2):

     • De-activate the “Use system environment” checkbox, and

     • from your file system, select the Xilinx settings batch file that sets the environment to launch the external tools.

     Please follow the Xilinx documentation to make the best choice.

     You find the batch file in the Xilinx installation folder:

     • ISE: \Xilinx\14.7\ISE_DS\settings64.bat.

     • Vivado: \Xilinx\Vivado\2020.2\settings64.bat.

     Basler recommends to use the 64-bit Windows operating system when developing applets for microEnable 5 platforms. Make sure you select the batch file that matches the operating system you are using, e.g., "settings64.bat" which is the file for the 64-bit Windows OP.

   • If you use an older Xilinx ISE version (version 9.2 or older) and all environment variables are set at the operating system, activate the “Use system environment” checkbox.

9. Build Flow: Activate all options under Build Flow. Normally, all steps should be activated.

   Basler recommends to set the system under Multi place and route to 20 iterations.

   Keep the Command Mode at Use platform default value.

10. Applet Generation: Activate Applet Generation.

11. Comment: Enter a comment that describes the set of parameters you just created. The entries you make here have no effect on the actual build process.

12. Click the OK button.

Example: When developing for microEnable 5 or LightBridge, the following parameter values need to be set:

Figure 147. Parameter Set Example: Developing for microEnable 5 or LightBridge

Disabling Build Flow Steps

Per default, all build flow steps (translation, mapping, ...) are activated: Figure 148. Defaut: All Build Flow Steps Activated With the Expert license or the VisualApplets 4 license you can de-select individual steps. However, the build steps depend on each other. They are listed in the order of their dependence: Translation is the first step that can always be executed. Mapping can only be executed if the step Translation has been executed before. Place and route can only be executed if the step Mapping has been executed before, and so on. Figure 149. Subsequent Build Steps Deactivated However, a previous step doesn't need to be executed within the same build run. It might as well have been executed in an earlier build run. As long as the files (trace files) that have been generated during an earlier build run are still available, it is possible to deactivate steps that come earlier in the "Build Flow" list and to activate steps that come later in the list. To keep trace files of earlier build runs: Go to menu Settings → System Settings → Global Build. Under Build Trace Files, activate Keep build trace files. Deactivate Compress build trace files. Figure 150. Keeping Build Files of the Individual Build Steps If you keep the build trace files, and you have carried out all previous build flow steps once before, you can also activate only subsequent steps, e.g.: Figure 151. Keeping Build Files of the Individual Build Steps

Command Mode Options

With the Expert license or the VisualApplets 4 license you can change the Command Mode. To change the Command Mode, go to Command Mode at the right upper corner of the Build Flow area. Figure 152. Command Mode Options In the list, you have three different options: Use platform default value (Default) Append to platform default value Overwrite platform default value ---------- Use platform default value (Default): If you keep or select this option, VisualApplets displays the default values recommended for the hardware platform you specified as target platform for the open design. VisualApplets also uses these default values when running the Xilinx tools (i.e., when the actual applet is build (synthesized) out of the open design). Since default sets cannot be modified, it is not possible to edit the Arguments fields in the Use platform default value mode. Figure 153. Command Mode "Use platform default value" Append to platform default value: If you select this option, you can add information for the Mapping and Place and route tools to the basic arguments provided by VisualApplets. During build, VisualApplets adds the parameters you defined in the Arguments fields to the platform default values when calling the tool. This setting is for experienced users only. Figure 154. Command Mode "Append to platform default value" Overwrite platform default value: If you select this option, VisualApplets displays the default arguments for Mapping and Place and route for the target hardware platform you selected directly after creating the new applet set. You can define (overwrite) the Mapping and Place and route arguments stated here. VisualApplets now uses only the parameters you specify in these Arguments fields when calling the tools. This setting is for experienced users only. Figure 155. Command Mode "Overwrite platform default value"

Re-Using Parameter Sets

In the Build Settings window, you have some options for handling parameter sets:

Figure 156. Handling Options

Clicking on

• Add creates a new parameter set which you can modify as you want (based on the hardware platform you select).

• Copy copies the parameters of the current set, creates a new set and pastes the parameters of the copied set into the new set.

• Import allows to import a certain set of parameters into the current installation of VisualApplets.

• Export selected saves the current parameter set to a file. The file can be used for transporting the data to a different PC or installation or for backup reasons. A dialog is displayed where you can specify a file name and location.

• Delete deletes the current set of parameters.

Experienced users only: Creating *.hap Files for Different Operating Systems Using the Same Build (mE 5 ironman, mE5 marathon and LightBridge)

For mE 5 ironman, mE5 marathon and LightBridge, the checkbox Precondition Check offers a specific function:

• If Precondition Check is activated, at each start of synthesis (build) the entries for BuildTime and AppletUid are updated. If you want to start a complete build (from netlist generation through to applet generation) you need to activate Precondition Check. Otherwise, later on (when using the applet on the frame grabber) the loaded applet cannot be reliably validated by the runtime environment.

• Specific option: If you have already completely built an applet, but decide you need another *.hap file for another target operating system: You can build a new OS-specific hap file out of the complete build to make your design usable on other target operating systems (i.e., for another target runtime). Proceed as follows:

  1. In menu Settings, select System Settings.

  2. In the window that opens, select category Global Build.

  3. Here, under Build Trace Files, activate the option Keep build trace files and specify a path.

  4. Go to menu Settings, menu item Build Settings.

  5. Deactivate option Precondition Check.

  6. Deactivate all other options under Xilinx Build Flow.

  7. Activate Applet Generation.

  8. Under Defaults, activate Active Configuration.

  9. Start the build of the OS specific *.hap file.

  Especially with complex designs, this option allows you to save time.

In VisualApplets, multiple build settings can be created in the in the Build Settings dialog which are stored in the application.

In the Build Hardware Applets dialog under Xilinx configuration, you can select one of the build settings you defined in the in the Build Settings dialog. The Build configuration you select here will be used for the build you are going to start. Default value is the configuration you specified as Active configuration in the Build Settings dialog.

Figure 157. Selecting the Build Configuration for Applet Build

In the same Build Hardware Applets dialog, you can specify the required target runtimes. By default, the target runtime of the design file is selected. (See 'Target Runtime') However, sometimes the applet will be used on multiple target runtimes. In this case, multiple target runtimes can be selected as can be seen in the next figure. VisualAppelts will generate a HAP file for all selected target runtimes.

Figure 158. Target Runtime Selection during Applet Build

For the target runtime you defined the design file, the output file is located in the specified directory as described above. The file name of this output file is the same as the name of the *.va design file, only with the *.hap extention. The file is copied into the Framegrabber SDK installation, if the Framegrabber SDK is installed.

All additional output files: VisualApplets will add target runtime information to the file name of all additional output files, like “_Linux_AMD64”, “_Linux_IA32”, etc. These additional HAP files will NOT be copied into the Framegrabber SDK installation directory.

	Repacking the *.hap File for Other Target Runtimes at a Later Stage
	You can easily create a new *.hap file for an additional target runtime at a later stage without starting the whole build process again. This may save you a lot of time as the repacking only takes some minuts. For details on how to repack a *.hap File for additional target runtimes, see section 'Repacking the *.hap File for Other Operating Systems at a Later Stage'.

The platforms imaFlex CXP-12 Quad and imaFlex CXP-12 Penta have one additional build setting: Netlist synthesis engine.

Figure 159. Build Setting for imaFlex CXP-12 Quad and imaFlex CXP-12 Penta

This setting has an effect on the build velocity and device ressources.

Standard:

Enhanced:

Basler recommends to use always the Enhanced netlist synthesis engine.

The build process will always execute design rules checks level 1 and level 2. If one of the fails, the build process is aborted. Check 'Design Rules Check' for more information on the design rules checks.

Moreover, the build process can cause several further errors. The most likely errors is a resource overmap or timing error. If an applet contains to much logic elements, the XILINX tools cannot map all required elements to the physically available elements. In the case of a resource overmap, your design has to be optimized to fit into the FPGA.

In case of a timing error, the XILINX tools cannot route all signals within the allowed constraints. This mostly happens if almost all logic resources are used. The design has to be optimized to use less resources in this case. Designs which have a timing error can still be completed. Keep in mind that a hardware applet which did not meet timing might not work correct. It might result in time-outs, failing data or other unexpected behaviors if used. Therefore, the use of a non-timing matched applet should only be used with care and is at the user's own risk. If the required resources of your design are far less than 100% and you still get timing errors, contact the Basler Support.

Other errors can be caused by an incorrect XILINX installation or disk volume access permissions.

Note that the build process might require some hours to be completed.

The usage and run of a hardware applet file (HAP) is described in the Framegrabber SDK documentation. The SDK generator of VisualApplets can help with the first steps of running an applet. See 'Framegrabber SDK' for more information.

microDisplay is part of the Framegrabber SDK. It is a tool for first tests of the generated applets. If the Framegrabber SDK is installed, microDisplay can directly be opened from VisualApplets by clicking on Build → microDisplay ( F5 ). Alternatively, you can also use the icon microDisplay from the Build icon bar.

You can create additional *.hap files out of an already existing *.hap file. This is especially helpful if you want to use an applet on additional operating systems you did not specify before the first build.

You do not need to start the whole build process again. This saves you a lot of time. The repacking only takes some minutes. Only the operating system specific parts of the original *.hap file are replaced by VisualApplets during the repacking process.

	Pre-Conditions
	To repack an existing *.hap file for a new operating system, you must use the same VisualApplets version that was used to build the original applet (VA 2.2 or higher). Otherwise, you will get an according error message.

To create additional *.hap files for additional operating systems: