Runtime Software Interface

VisualApplets
User Manual

Runtime Software Interface

VisualApplets supports different models for accessing design parameters at runtime:

Using eVA runtime environment based on HAP files
Using GenICam API based on generated GenICam XML code
Using generic, design-specific C API code generated by VisualApplets

HAP-Based eVA Runtime Interface

VisualApplets controls synthesis and implementation of the FPGA design. The resulting design is saved in a proprietary Basler file format (*.hap). This format contains the configuration bitstream for the FPGA and means for realizing a design-specific software interface.

In general, VisualApplets operators contain dynamic parameters which can be modified during runtime. The HAP file contains all necessary information for accessing design specific parameters easily.

For proper function of the runtime software on the user platform, the following requirements must be fulfilled:

The user needs access to the FPGA bitstream as he needs to do the configuration. For that purpose, the runtime interface provides the function vaRt_GetConfig().
For accessing the slave interface for the design registers, the user must implement the functions WriteReg32(), ReadReg32(), or optionally WriteReg64() and ReadReg64(). The runtime software is notified about these functions when the function vaRt_InitParams() is called.

Then the VisualApplets bitstream can be configured and the runtime software can write and read design parameters.

The register access functions must comply with following function types:

         
      typedef int ReadReg32(void* device, const uintptr_t address, uint32_t *value)
      typedef int WriteReg32(void* device, const uintptr_t address, uint32_t value)
      typedef int ReadReg64(void* device, const uintptr_t address, uint64_t *value)
      typedef int WriteReg64(void* device, const uintptr_t address, uint64_t value)

The software interface library provides additional functions for controlling the VisualApplets design. In the following table, the full set of access functions is listed:

Nr.	Function	Description
1	`vaRt_OpenHap()`	Opens the hardware applet `*.hap` and returns a pointer to the HAP structure which serves as a handle for further accesses.
2	`vaRt_CloseHap()`	Closes the hardware applet which has been opened by `vaRt_OpenHap`.
3	`vaRt_GetConfig()`	Returns a pointer to the configuration bit stream for the FPGA.
4	`vaRt_GetAppletProperty()`	Query function for applet properties like the maximum frequency of the clock net iDesignClk of the applet, information about the target platform, and version information.
5	`vaRt_GetProcessCount()`	Returns the number of processes of which the design is composed.
6	`vaRt_GetIoPortCount()`	Returns the number of used external interface ports. All kinds of interface ports are joined in a list where the position in the list is the logical number of the port. Port names and properties can be obtained by below specified functions `vaRt_GetIoPort…`.
7	`vaRt_GetIoPortName()`	Get the name of the interface port with the given logical port number.
8	`vaRt_GetIoPortProperty()`	Query I/O port properties like the name of a connected operator, the process which controls this port, and the current image format setting for this port.
9	`vaRt_GetParamCount()`	Returns the number of parameters of a design.
10	`vaRt_GetParamName()`	For a given parameter number the corresponding name is returned.
11	`vaRt_GetParamId()`	For a given parameter number the parameter ID is returned.
12	`vaRt_GetParamIdByName()`	For a given parameter name the parameter ID is returned.
13	`vaRt_GetParamProperty()`	Query parameter properties.
14	`vaRt_InitParams()`	Configure parameter interface and initialize parameters to default values.
15	`vaRt_GetParam()`	Query parameter value.
16	`vaRt_GetParamArray()`	Query array of parameters.
17	`vaRt_SetParam()`	Set parameter value.
18	`vaRt_SetParamArray()`	Set array of parameters.
19	`vaRt_SetGlobalEnable()`	Set the Master Enable signal.
20	`vaRt_SetProcessEnable()`	Activate a process of the VisualApplets design.
21	`vaRt_ResetProcess()`	Perform a reset of a VisualApplets design process.
22	`vaRt_GetErrorDescription()`	Query description for given error code.

Communicating Data

For querying information and configuring parameters, data must be exchanged through the runtime interface. In order to keep the interface functions simple but providing a type-save interface, an abstraction mechanism for data is implemented. Whenever data of different types needs to be communicated, a data structure called va_data is used, containing a reference to the data and information about the underlying data type. This data structure is created by the user but configured by dedicated functions listed below. The following table shows the data types which are handled by this method:

Data Type	Description
`VA_ENUM`	Enum entry given as 32-bit integer.
`VA_INT32`	32-bit signed integer.
`VA_UINT32`	32-bit unsigned integer.
V`A_INT64`	64-bit signed integer.
`VA_UINT64`	64-bit unsigned integer.
`VA_DOUBLE`	Floating-point value, double precision.
`VA_INT32_ARRAY`	Array of 32-bit signed integer numbers.
`VA_UINT32_ARRAY`	Array of 32-bit unsigned integer numbers.
`VA_INT64_ARRAY`	Array of 64-bit signed integer numbers.
`VA_UINT64_ARRAY`	Array of 64-bit unsigned integer numbers.
`VA_DOUBLE_ARRAY`	Array of double numbers.
`VA_STRING`	String given as `const char*`.

Configuring an earlier created va_data structure (vaData) for setting up data communication is done via the following functions:

        
      va_data* va_data_enum(va_data* vaData, int32_t *data) 
      va_data* va_data_int32(va_data* vaData, int32_t *data) 
      va_data* va_data_uint32(va_data* vaData, uint32_t *data) 
      va_data* va_data_int64(va_data* vaData, int64_t *data) 
      va_data* va_data_uint64(va_data* vaData, uint64_t *data) 
      va_data* va_data_double(va_data* vaData, double *data) 
      va_data* va_data_int32_array(va_data* vaData, int32_t *data, size_t elementCount) 
      va_data* va_data_uint32_array (va_data* vaData, uint32_t *data, size_t elementCount) 
      va_data* va_data_int64_array (va_data* vaData, int64_t *data, size_t elementCount) 
      va_data* va_data_uint64_array (va_data* vaData, uint64_t *data, size_t elementCount) 
      va_data* va_data_double_array (va_data* vaData, double *data, size_t elementCount) 
      va_data* va_data_string(va_data* vaData, char *data, size_t strSize) 
      va_data* va_data_const_string(va_data* vaData, const char **data)

For strings there are two options how strings are communicated:

Providing a char array via va_data_string(). Then queried string data will be copied to that array.
Providing a pointer to const char*. Then a pointer to an internal string representation is returned when information of type VA_STRING is queried. When you use this approach check the live time of the returned string.

Example Code:

The following example shows code for querying the design frequency for a configured design.

     
       double desFreq; 
       va_data va_desFreq; 
       va_data_double(&amp;va_desFreq,&amp;desFreq); 
         
       vaRt_GetAppletProperty(hapHandle, &quot;DesignFreq&quot;,&amp;va_desFreq);

After that, the variable desFreq will contain the requested information.

Detailed Description of Interface Functions

The following table gives a detailed description of parameters and returned values for the specified runtime access functions.

Function	`int vaRt_OpenHap (const char* hapFileName, va_hap_handle*hap)`
Parameter 1	Name of hap file which shall be opened.
Parameter 2	Return pointer for hap handle.
Description	Opens the hardware applet with the provided name and returns a pointer to the hap structure. The returned pointer is used as a handle in all other interface functions.
Return value	0 : OK <0: Error opening applet

Function

int vaRt_CloseHap (va_hap_handle handle)

Parameter 1

Hap handle from vaRt_OpenHap().

Description

Closes the VA hardware applet.

Return value

0 = OK

<0 = Error closing HAP

Function	`int vaRt_GetConfig (va_hap_handle handle, int fpgaID, char*data, size_t sizeInBytes)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	ID of the FPGA within the target platform. For single-configuration HAP files (currently the only option) this parameter may be fixed to -1. Otherwise this parameter must correspond to the (optional) FPGA ID specified in the hardware definition file used for creating the VisualApplets platform.
Parameter 3	Pointer to buffer for the configuration bitstream.
Parameter 4	Communicate the size of the configuration bitstream in bytes.
Description	Get the configuration bitstream for the FPGA design. The function has two modes of operation:
Return value	0: OK <0: Error acquiring the bitstream

Function	`int vaRt_GetAppletProperty (va_hap_handle handle, const char* propName,va_data * data)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Name of property which shall be queried.
Parameter 3	Pointer to data structure which will used for communication.
Description	Get property of the applet. Following properties may be queried: VisualAppletsVersion: Get version of VisualApplets framework used for creating this applet (type `VA_STRING`) IPCoreVersion: Get version of VA IP Core (type V`A_STRING`) AppletVersion: Get applet version (type `VA_STRING`) DesignFreq: Get frequency of design clock in MHz (type `VA_DOUBLE`) PlatformVendor: Vendor of platform (type `VA_STRING`) PlatformType: Name of hardware platform (type `VA_STRING`) PlatformID: Identification number of platform device (type `VA_STRING`) PlatformVersion: Platform device version as defined in the hardware description used for creating the applet (type `VA_STRING`) The properties are identified by one of the above strings (provided through parameter 2) and communicated via the data structure given through parameter 3. For properties of type `VA_STRING` the returned string may be overwritten by the next call of this function.
Return value	0 : OK <0 : Can’t retrieve applet property

Function	`int vaRt_GetProcessCount (va_hap_handle handle, unsigned int* count)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Return value for process count.
Description	Get the number of processes of which the design is composed.
Return value	0: OK <0 : Can’t retrieve information

Function	`int vaRt_GetIoPortCount (va_hap_handle handle, unsigned int*count)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Return value for port count.
Description	Get the number of used I/O ports of the VA IP Core. The returned number represents the size of an internally managed port list where all interface ports are registered and the position in the list is the logical number of the I/O port.
Return value	0: OK <0 : Can’t retrieve information

Function	`int vaRt_GetIoPortName (va_hap_handle handle, unsigned int index, const char** name)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Logical interface port number, which is an integer between Zero and the returned value from `vaRt_GetIoPortCount()` minus 1.
Description	Get the name of the interface port with the given logical number. When there are several ports of the same kind these ports are differentiated by a suffix _X where X is the port index (e.g. DmaRd_0).
Return value	0: OK; `*name` returns a pointer to a static buffer which holds the requested name (0-terminated). Note that the buffer may be overwritten by the next call of this function <0 : No port with given index found

Function	`int vaRt_GetIoPortProperty (va_hap_handle handle, const char* portName, const char* propName, va_data* data)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Name of I/O port.
Parameter 3	Name of property which shall be queried.
Parameter 4	Pointer to data structure which will be used for communication.
Description	Get property of the I/O port with the given name. Following properties may be queried: OperatorName: User defined name of connected operator (type `VA_STRING`). OperatorType: Operator type name of connected operator (type `VA_STRING`). Process: Logical number of process in which the connected operator works (type `VA_UINT32`). FormatID: Format ID of I/O operator (type `VA_UINT32`, only available for ports of type ImgIn or ImgOut). The properties are identified by one of the above strings (provided through parameter 3) and communicated via the data structure given through parameter 4. For properties of type `VA_STRING` the returned string may be overwritten by the next call of this function.
Return value	0: OK <0 : Can’t retrieve the requested property

Function	`int vaRt_InitParams (va_hap_handle handle, struct va_device device, ReadReg32 read32, WriteReg32 write32, ReadReg64 read64, WriteReg64 *write64)`
Parameter 1	Hap handle from `vaRt_OpenHap(`).
Parameter 2	Pointer to device handle which is provided to the low level access functions `WriteReg32()`, `ReadReg32()`, `WriteReg64`, and `ReadReg64()` for any register access.
Parameter 3	Function pointer for 32-bit register read function.
Parameter 4	Function pointer for 32-bit register write function.
Parameter 5	Function pointer for 64-bit register read function.
Parameter 6	Function pointer for 64-bit register write function.
Description	Initialize parameter interface by providing low level register access functions and associating a board interface pointer to them. The initialization procedure includes configuring initial values. Note that any other function `vaRt_Param` and the functions for controlling reset and enable may only be called after this function has been executed successfully. Regarding the register access functions following options are available:
Return value	0: Parameter interface has been initialized successfully <0 : Error during initialization

Function	`int vaRt_GetParamCount (va_hap_handle handle, unsigned int*count)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Return value for number of parameters.
Description	Get the number of parameters of the applet which can be accessed via the parameter interface. The returned number represents the size of an internally managed parameter list where all available parameters are registered and the position in the list defines the logical number of the parameter.
Return value	0: OK <0 : Can’t retrieve information

Function	`int vaRt_GetParamName (va_hap_handle handle, unsigned int index, const char** name)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Logical parameter number, which is an integer between Zero and the returned value from `vaRt_GetParamCount()` minus 1.
Parameter 3	Return pointer to name string.
Description	Get the name of the applet parameter by the given logical parameter number.
Return value	0: OK; *name returns a pointer to a static buffer which holds the parameter name (0-terminated). Note that the buffer may be overwritten by the next call of this function. <0 : Can’t retrieve information

Function	`int vaRt_GetParamId (const struct va_hap_handle* handle, unsigned int index, int* paramId)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Logical parameter number, which is an integer between zero and the returned value from `vaRt_GetParamCount()` minus 1.
Parameter 3	Return pointer for parameter ID.
Description	Get the ID of a parameter of the applet. This ID is used for accessing that parameter.
Return value	0: OK <0 : No parameter with given index found

Function	`int vaRt_GetParamIdByName (const struct va_hap_handle* handle, const char* name, int* paramId)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Name of parameter which can be one of the values provided by `vaRt_GetParamName()`.
Parameter 3	Return pointer for parameter ID.
Description	Get the ID of a parameter with the given name. This ID is used for accessing that parameter.
Return value	0: OK <0 : No parameter with given name found

Function	`int vaRt_GetParamProperty (va_hap_handle handle, int paramID, const char* propName, va_data* data)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Parameter name.
Parameter 3	Name of property which shall be queried.
Parameter 4	Pointer to data structure which will be used for communication.
Description	Query property of applet parameter. Different parameter types do have different properties. See the VA Engine specification for a list of available parameter properties. The properties are identified by a string given by parameter 3 and communicated via the data structure provided by parameter 4. For properties of type `VA_STRING` the returned string is stable at least until the parameter gets modified.
Return value	0 : OK <0 : Can’t retrieve parameter property

Function	`int vaRt_GetParam (va_hap_handle handle, int paramID, va_data * value)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Parameter ID.
Parameter 3	Pointer to data structure which will be used for communication. The associated data element will be overwritten by the acquired value.
Description	Query the applet parameter by parameter ID. The data is communicated using a data structure given by parameter 3. For querying field parameters use `vaRt_GetParamArray()`. For properties of type `VA_STRING` the returned string is stable at least until the parameter gets modified.
Return value	0: OK. <0 : Error querying the parameter.

Function	`int vaRt_GetParamArray (va_hap_handle handle, int paramID, va_data* values, size_t startIndex, size_t elementCount)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Parameter ID.
Parameter 3	Pointer to the data structure which will be used for communication. The associated data elements will be overwritten by the acquired values.
Parameter 4	Start index within the parameter field
Parameter 5	Number of elements which shall be queried
Description	Query field parameter of applet by parameter ID filling an array of data elements. The data is communicated via the data structure given by parameter 4.
Return value	0: OK. <0 : Error querying the array.

Function	`int vaRt_SetParam (va_hap_handle handle, int paramID, const va_data * value)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Parameter ID.
Parameter 3	Pointer to the data structure which will be used for submitting data to the Applet.
Description	Set applet parameter with the given name. Data is provided by a data structure (Parameter 4). For setting field parameters use v`aRt_SetParamArray()`.
Return value	0: OK. <0 : Error setting the parameter.

Function	`int vaRt_SetParamArray (va_hap_handle handle, int paramID, const va_data * values, size_t startIndex, size_t elementCount)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Parameter ID.
Parameter 3	Pointer to the data structure which will be used for submitting values to the applet.
Parameter 4	Start index within parameter field.
Parameter 5	Number of elements which shall be set.
Description	Set field parameter of applet with the given name submitting an array of data elements. The data is provided via a data structure (Parameter 3).
Return value	0: OK. <0 : Error setting the parameter field.

Function	`int vaRt_SetGlobalEnable (va_hap_handle handle, int active)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	State to which the global enable shall be set (1 or 0).
Description	Set the global enable to 1 (active=1) or 0 (active=0).
Return value	0: OK <0 : Error setting the global enable state.

Function	`int vaRt_SetProcessEnable (va_hap_handle handle, unsigned int procNr, int active)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Process number or ((unsigned int)-1) for identifying all processes at once.
Parameter 3	State to which the enable shall be set (1 or 0).
Description	Set the enable of a process (or all processes) to 1 (active=1) or 0 (active=0).
Return value	0: OK. <0 : Error setting the process enable state.

Function	`int vaRt_ResetProcess (va_hap_handle handle, unsigned int procNr)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter 2	Process number or ((unsigned int)-1) for identifying all processes at once.
Description	Reset the process with the given logical process number (or all processes). The according process reset signal(s) will be asserted and released again. The enable signal(s) of the corresponding process(es) is not touched. Use `vaRt_SetProcessEnable()` and this function for controlling the applet.
Return value	0: OK. <0 : Cannot reset the process.

Function	`const char* vaRt_GetErrorDescription (va_hap_handle handle, int errorCode)`
Parameter 1	Hap handle from `vaRt_OpenHap()`.
Parameter2	Code from `vaRt_GetLastError()`.
Description	Query error message string for given error code.
Return value	Not NULL: Error description (0-terminated c-string) NULL: No description available

Runtime Interface Based on GenICam API Version 2.0

For a given design, VisualApplets may generate GenICam XML code. When the target platform is connected via a GenICam compatible interface to the software, this option allows a seamless integration of image processing parameters into the GenICam API. There is no need for any additional software component.

If the parameter access needs to be integrated into an existing master GenICam XML file, you need to do some post processing. This is usually the case when the platform is already controlled via GenICam before embedding the VA IP core.

To integrate the parameter access into an existing master GenICam XML file:

Cut the header of the XML file generated by VisualApplets.
Copy the remaining code for the categories, variables, and registers into the master XML file.

VisualApplets may automatize this step as it is capable calling custom post processing tasks.

Runtime Interface Based on Generated API Code

For a given design, VisualApplets may generate generic C API code. The code is platform independent ANSI-C code. This approach is well suited for software integration in embedded systems (e.g., Zynq7000).

The generated code provides the following interface:

    
    #include <stdint.h> 
        
    typedef int (*write_func_t)(void* boardHandle,int address, uint64_t value, size_t sizeInBytes);
    int (*read_func_t)(void* boardHandle,int address, uint64_t *value, size_t sizeInBytes);
      
    enum VariableTypes_enum{
    
    TYPE_UNKNOWN = 0, 
    
    TYPE_INT = 1, 
    
    TYPE_FLOAT = 2, 
    
    TYPE_STRING = 3 
    
    }; 
      
    typedef enum VariableTypes_enum VariableType_t; 
      
    enum AccessMode_enum{ 
    RO, 
    WO, 
    RW 
    }; 
      
    typedef enum AccessMode_enum AccessMode_t; 
      
    int va_init(void* boardHandle, write_func_t wrFunc, read_func_t rdFunc); 
    
    int va_set_property(const char* propName, const char* propValue); 
    
    int va_get_int_value(const char* varName, int64_t *retValue); 
    
    int va_set_int_value(const char* varName, int64_t value); 
    
    int va_get_float_value(const char* varName, double *retValue); 
    
    int va_set_float_value(const char* varName, double value); 
    
    int va_get_string_value(const char* varName, const char **retValue); 
    
    int va_get_enum_value(const char* varName, const char** retValue); 
    
    int va_set_enum_value(const char* varName, const char* value); 
    
    int va_get_enum_item_count(const char* varName, int64_t *itemCount); 
    
    int va_get_enum_item_info(const char* varName, int64_t index, const char** itemName, int64_t *itemValue); 
    
    int va_query_variables_count(int32_t *retCount);     
    
    int va_query_variable_name(int32_t index, const char** retName); 
    
    int va_query_variable_type(const char* varName, VariableType_t *type); 
    
    int va_query_int_variable_properties(const char* varName, 
    
    int64_t *from, 
    
    int64_t *to, 
    
    int64_t *inc, 
    
    AccessMode_t *access); 
    
    int va_query_float_variable_properties(const char* varName, 
    
    double *from, 
    
    double *to, 
    
    double *inc, 
    
    AccessMode_t *access);

You initialize the interface by calling va_init().

The callback functions for write and read access to the register slave interface of the VA IP core are registered. The given boardHandle is stored and provided with any triggered call of these write and read functions. The set of query functions provide a baseline mechanism for implementing a generic runtime interface. For a given design the set functions and get functions provide parameter access where parameters are addressed by name. These functions perform the translation from accessing design parameters to accessing registers on the hardware via the call back functions for register access.

Prev	Level Up	Next
Content	Top	Home

Sidebar	Prev \| Level Up \| Next
Content \| Home
PDF \| Print \| Contact us

VisualApplets User Manual