运行时软件接口

VisualApplets 支持在运行时访问设计参数的不同模型：

  • 使用基于 HAP 文件的 eVA 运行环境

  • 使用基于生成的 GenICam XML 代码的 GenICam API

  • 使用由 VisualApplets 生成的通用、设计特定的 C API 代码

基于 HAP 的 eVA 运行时接口

VisualApplets 控制 FPGA 设计的综合与实现。生成的设计以专有的 Basler 文件格式（*.hap）保存。该格式包含用于 FPGA 的配置比特流以及实现设计特定软件接口的方法。

通常，VisualApplets 运算符包含可在运行时修改的动态参数。HAP 文件包含用于轻松访问设计特定参数所需的所有信息。

为确保运行软件在用户平台上正常运行，必须满足以下要求：

  • 用户需要访问 FPGA 比特流，因为其需要进行配置。为此，运行接口提供了以下函数： vaRt_GetConfig().

  • 为了访问设计寄存器的从接口，用户必须实现以下函数： WriteReg32(), ReadReg32()或可选地 WriteReg64() 和 ReadReg64()。当函数 vaRt_InitParams() 被调用。

随后，可以配置 VisualApplets 比特流，并且运行软件可以写入和读取设计参数。

寄存器访问函数必须符合以下函数类型： 

         
      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)

软件接口库提供了用于控制 VisualApplets 设计的其他函数。下表列出了完整的访问函数集：

序号

功能

描述

1

vaRt_OpenHap()

打开硬件 applet *.hap 并返回指向 HAP 结构的指针，该结构用作进一步访问的句柄。

2

vaRt_CloseHap()

关闭已被以下项打开的硬件 applet： vaRt_OpenHap.

3

vaRt_GetConfig()

返回指向 FPGA 配置比特流的指针。

4

vaRt_GetAppletProperty()

用于查询 applet Property 的查询函数，例如 applet 时钟网络 iDesignClk 的最大频率、目标平台信息以及版本信息。

5

vaRt_GetProcessCount()

返回构成该设计的进程数。

6

vaRt_GetIoPortCount()

返回所使用的外部接口端口数。所有类型的接口端口都汇集在一个列表中，其中列表中的位置即为端口的逻辑编号。可以通过下面指定的函数获取端口名称和 Property： vaRt_GetIoPort….

7

vaRt_GetIoPortName()

获取具有给定逻辑端口号的接口端口的名称。

8

vaRt_GetIoPortProperty()

查询 I/O 端口 Property，例如连接的运算符的名称、控制此端口的进程以及此端口的当前图像格式设置。

9

vaRt_GetParamCount()

返回设计的参数数量。

10

vaRt_GetParamName()

根据给定的参数编号，返回相应的名称。

11

vaRt_GetParamId()

根据给定的参数编号，返回参数 ID。

12

vaRt_GetParamIdByName()

根据给定的参数名称，返回参数 ID。

13

vaRt_GetParamProperty()

查询 Property。

14

vaRt_InitParams()

配置参数接口并将参数初始化为默认值。

15

vaRt_GetParam()

查询 Property 值。

16

vaRt_GetParamArray()

查询参数数组。

17

vaRt_SetParam()

设置 Property 值。

18

vaRt_SetParamArray()

设置参数数组。

19

vaRt_SetGlobalEnable()

设置 Master Enable 信号。

20

vaRt_SetProcessEnable()

激活 VisualApplets 设计的一个处理过程。

21

vaRt_ResetProcess()

执行 VisualApplets 设计处理过程的重置。

22

vaRt_GetErrorDescription()

查询给定错误代码的描述。

数据通信

为了查询信息和配置参数，必须通过运行时接口交换数据。为了保持接口函数简洁同时又提供类型安全的接口，实现了一种数据抽象机制。每当需要传输不同类型的数据时，就会使用一种名为 va_data 的数据结构，其中包含对数据的引用以及底层数据类型的信息。该数据结构由用户创建，但通过以下列出的专用函数进行配置。下表显示了此方法处理的数据类型：

数据类型

描述

VA_ENUM

以 32 位整数形式给出的 Enum 条目。

VA_INT32

32 位有符号整数。

VA_UINT32

32 位无符号整数。

VA_INT64

64 位有符号整数。

VA_UINT64

64 位无符号整数。

VA_DOUBLE

双精度浮点值。

VA_INT32_ARRAY

32 位有符号整数数组。

VA_UINT32_ARRAY

32 位无符号整数数组。

VA_INT64_ARRAY

64 位有符号整数数组。

VA_UINT64_ARRAY

64 位无符号整数数组。

VA_DOUBLE_ARRAY

双精度浮点数数组。

VA_STRING

给定的字符串为 const char*.

配置先前创建的 va_data 用于设置数据通信的结构体 (vaData) 通过以下函数完成： 

        
      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)

对于字符串，有两种字符串通信方式：

  • 通过以下方式提供 char 数组 va_data_string()。然后，查询到的字符串数据将被复制到该数组中。

  • 提供指向以下内容的指针 const char*。随后，当查询类型为 VA_STRING 的信息时，将返回指向内部字符串表示形式的指针。使用此方法时，请检查返回字符串的生存期。

示例代码：

以下示例显示了查询已配置设计的设计频率的代码。 

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

在此之后，变量 desFreq 将包含请求的信息。

接口函数详细说明

下表详细说明了指定运行时访问函数的参数和返回值。

功能

int vaRt_OpenHap (const char* hapFileName, va_hap_handle*hap)

参数 1

应打开的 hap 文件的名称。

参数 2

hap 句柄的返回指针。

描述

打开具有指定名称的硬件 applet 并返回指向 hap 结构体的指针。

返回的指针在所有其他接口函数中用作句柄。

返回值

0 :  OK

<0: Error opening applet

功能

int vaRt_CloseHap (va_hap_handle handle)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

描述

关闭 VA 硬件 applet。

返回值

0 = 正常

<0 = Error closing HAP

功能

int vaRt_GetConfig (va_hap_handle handle, int fpgaID, char**data, size_t *sizeInBytes)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

目标平台中 FPGA 的 ID。对于单配置 HAP 文件（目前唯一的选项），此参数可以固定为 -1。否则，此参数必须与用于创建 VisualApplets 平台的硬件定义文件中指定的（可选）FPGA ID 相对应。

参数 3

指向配置比特流缓冲区的指针。

参数 4

以字节为单位传递配置比特流的大小。

描述

获取 FPGA 设计的配置比特流。该函数有两种工作模式：

返回值

0：正常

<0:  Error acquiring the bitstream

功能

int vaRt_GetAppletProperty (va_hap_handle handle, const char* propName,va_data * data)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

要查询的 Property 名称。

参数 3

指向将用于通信的数据结构的指针。

描述

获取 applet 的 Property。可以查询以下 Property：

  • VisualAppletsVersion：获取用于创建此 applet 的 VisualApplets 框架的版本（类型 VA_STRING)

  • IPCoreVersion：获取 VA IP Core 的版本（类型 VA_STRING)

  • AppletVersion：获取 applet 版本（类型 VA_STRING)

  • DesignFreq：获取设计时钟频率，单位为 MHz（类型 VA_DOUBLE)

  • PlatformVendor：平台供应商（类型 VA_STRING)

  • PlatformType：硬件平台名称（类型 VA_STRING)

  • PlatformID: 平台设备的识别号（类型 VA_STRING)

  • PlatformVersion: 用于创建小程序的硬件描述中定义的平台设备版本（类型 VA_STRING)

属性由上述字符串之一标识（通过参数 2 提供），并通过通过参数 3 给出的数据结构进行通信。对于以下类型的属性 VA_STRING 返回的字符串可能会被此函数的下一次调用覆盖。

返回值

0：确定

<0 : Can’t retrieve applet property

功能

int vaRt_GetProcessCount (va_hap_handle handle, unsigned int* count)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

进程数的返回值。

描述

获取设计所组成的进程数。

返回值

0: OK

<0 : Can’t retrieve information

功能

int vaRt_GetIoPortCount (va_hap_handle handle, unsigned int*count)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

端口数的返回值。

描述

获取 VA IP Core 已使用的 I/O 端口数量。返回的数字代表内部管理的端口列表的大小，所有接口端口均在该列表中注册，列表中的位置即为 I/O 端口的逻辑编号。

返回值

0: OK

<0 : Can’t retrieve information

 

功能

int vaRt_GetIoPortName (va_hap_handle handle, unsigned int index, const char** name)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

逻辑接口端口号，其为介于零与 vaRt_GetIoPortCount() 减 1 之间的整数。

描述

获取具有给定逻辑编号的接口端口的名称。当有多个同类端口时，这些端口通过后缀 _X 进行区分，其中 X 是端口索引（例如 DmaRd_0）。

返回值

0: OK； *name 返回一个指向静态缓冲区的指针，该缓冲区保存请求的名称（以 0 结尾）。注意，该缓冲区可能会被此函数的下一次调用覆盖

<0 : No port with given index found

功能

int vaRt_GetIoPortProperty (va_hap_handle handle, const char* portName, const char* propName, va_data* data)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

I/O 端口的名称。

参数 3

要查询的 Property 名称。

参数 4

指向将用于通信的数据结构的指针。

描述

获取具有给定名称的 I/O 端口的属性。可以查询以下属性：

  • OperatorName: 连接操作员的用户定义名称（类型 VA_STRING）。

  • OperatorType: 连接操作员的操作员类型名称（类型 VA_STRING）。

  • 处理: 连接操作员所在的进程的逻辑编号（类型 VA_UINT32）。

  • FormatID: I/O operator 的 Format ID（类型 VA_UINT32，仅适用于以下类型的端口： ImgIn 或 ImgOut）。

Property 由上述字符串之一标识（通过参数 3 提供），并经由参数 4 给出的数据结构进行通信。对于以下类型的 Property： VA_STRING 返回的字符串可能会被此函数的下一次调用覆盖。

返回值

0: OK

<0 : Can’t retrieve the requested property

 

功能

int vaRt_InitParams (va_hap_handle handle, struct va_device *device, ReadReg32 *read32, WriteReg32 *write32, ReadReg64 *read64, WriteReg64 *write64)

参数 1

来自的 Hap 句柄 vaRt_OpenHap(）。

参数 2

指向提供给底层访问函数的设备句柄的指针 WriteReg32(), ReadReg32(), WriteReg64，以及 ReadReg64() 用于任何寄存器访问。

参数 3

32 位寄存器读取函数的函数指针。

参数 4

32 位寄存器写入函数的函数指针。

参数 5

64 位寄存器读取函数的函数指针。

参数 6

64 位寄存器写入函数的函数指针。

描述

通过提供底层寄存器访问函数并将板卡接口指针与之关联来初始化参数接口。初始化过程包括配置初始值。请注意，任何其他函数 vaRt_*Param* 以及用于控制重置和使能的函数只能在此函数成功执行后调用。

关于寄存器访问函数，提供以下选项：

返回值

0：参数接口初始化成功

<0 : Error during initialization

 

功能

int vaRt_GetParamCount (va_hap_handle handle, unsigned int*count)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数数量的返回值。

描述

获取可通过参数接口访问的 Applet 参数的数量。返回的数量表示内部管理的参数列表的大小，该列表注册了所有可用参数，并且列表中定义的位置即为参数的逻辑编号。

返回值

0: OK

<0 : Can’t retrieve information

 

功能

int vaRt_GetParamName (va_hap_handle handle, unsigned int index, const char** name)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

逻辑参数编号，它是介于 0 与来自以下各项的返回值之间的整数： vaRt_GetParamCount() 减 1 之间的整数。

参数 3

返回指向名称字符串的指针。

描述

根据给定的逻辑参数编号获取 Applet 参数的名称。

返回值

0：确定；*name 返回一个指向静态缓冲区的指针，该缓冲区包含参数名称（以 0 结尾）。请注意，该缓冲区可能会被此函数的下一次调用覆盖。

<0  : Can’t retrieve information

 

功能

int vaRt_GetParamId (const struct va_hap_handle* handle, unsigned int index, int* paramId)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

逻辑参数编号，是一个介于 0 和返回值之间的整数，返回值来自 vaRt_GetParamCount() 减 1 之间的整数。

参数 3

用于参数 ID 的返回指针。

描述

获取 applet 的参数 ID。该 ID 用于访问该参数。

返回值

0: OK

<0 : No parameter with given index found

 

功能

int vaRt_GetParamIdByName (const struct va_hap_handle* handle, const char* name, int* paramId)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数名称，可以是以下各项提供的值之一 vaRt_GetParamName().

参数 3

用于参数 ID 的返回指针。

描述

通过给定的名称获取参数的 ID。该 ID 用于访问该参数。

返回值

0: OK

<0 : No parameter with given name found

 

功能

int vaRt_GetParamProperty (va_hap_handle handle, int paramID, const char* propName, va_data* data)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数名称。

参数 3

要查询的 Property 名称。

参数 4

指向将用于通信的数据结构的指针。

描述

查询 applet 参数的 Property。不同的参数类型具有不同的 Property。有关可用参数 Property 的列表，请参见 VA Engine 规范。Property 由参数 3 给出的字符串标识，并通过参数 4 提供的通信数据结构进行传输。对于以下类型的 Property VA_STRING 返回的字符串至少在参数修改之前保持稳定。

返回值

0：确定

<0 : Can’t retrieve parameter property

 

功能

int vaRt_GetParam (va_hap_handle handle, int paramID, va_data * value)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数 ID。

参数 3

指向将用于通信的数据结构的指针。关联的数据元素将被获取的值覆盖。

描述

通过参数 ID 查询 applet 参数。数据使用参数 3 给定的数据结构进行传输。若要查询数组参数，请使用 vaRt_GetParamArray()。对于以下类型的 Property VA_STRING 返回的字符串至少在参数修改之前保持稳定。

返回值

0：正常。

<0 : Error querying the parameter.

 

功能

int vaRt_GetParamArray (va_hap_handle handle, int paramID, va_data* values, size_t startIndex, size_t elementCount)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数 ID。

参数 3

指向将用于通信的数据结构的指针。关联的数据元素将被获取的值覆盖。

参数 4

参数数组内的起始索引

参数 5

要查询的元素数量

描述

通过参数 ID 查询 applet 的数组参数，并填充数据元素数组。数据通过参数 4 给定的数据结构进行传输。

返回值

0：正常。

<0 : Error querying the array.

 

功能

int vaRt_SetParam (va_hap_handle handle, int paramID, const va_data * value)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数 ID。

参数 3

指向将用于向 Applet 提交数据的数据结构的指针。

描述

使用给定的名称设置 applet 参数。数据由数据结构（参数 4）提供。若要设置数组参数，请使用 vaRt_SetParamArray().

返回值

0：正常。

<0 : Error setting the parameter.

 

功能

int vaRt_SetParamArray (va_hap_handle handle, int paramID, const va_data * values, size_t startIndex, size_t elementCount)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

参数 ID。

参数 3

指向将用于向 applet 提交值的数据结构的指针。

参数 4

参数数组内的起始索引。

参数 5

要设置的元素数量。

描述

使用给定的名称设置 applet 的数组参数，并提交数据元素数组。数据通过数据结构（参数 3）提供。

返回值

0：正常。

<0 : Error setting the parameter field.

 

功能

int vaRt_SetGlobalEnable (va_hap_handle handle, int active)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

全局使能应设置到的状态（1 或 0）。

描述

将全局启用设置为 1（active=1）或 0（active=0）。

返回值

0: OK

<0 : Error setting the global enable state.

 

功能

int vaRt_SetProcessEnable (va_hap_handle handle, unsigned int procNr, int active)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

进程号，或用于同时标识所有进程的 ((unsigned int)-1)。

参数 3

启用应设置到的状态（1 或 0）。

描述

将某个进程（或所有进程）的启用设置为 1（active=1）或 0 （active=0）。

返回值

0：正常。

<0 : Error setting the process enable state.

 

功能

int vaRt_ResetProcess (va_hap_handle handle, unsigned  int procNr)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

参数 2

进程号，或用于同时标识所有进程的 ((unsigned int)-1)。

描述

使用指定的逻辑进程号重置该进程（或所有进程）。 将断言并再次释放相应的进程重置信号。 对应进程的启用信号不会被触及。使用 vaRt_SetProcessEnable() 及此函数来控制该 applet。

返回值

0：正常。

<0 : Cannot reset the process.

 

功能

const char* vaRt_GetErrorDescription (va_hap_handle handle, int errorCode)

参数 1

来自的 Hap 句柄 vaRt_OpenHap().

Parameter2

代码来自 vaRt_GetLastError().

描述

查询给定错误代码的错误消息字符串。

返回值

非 NULL：错误描述（以 0 结尾的 c-string）

NULL：无可用描述

基于 GenICam API 2.0 版本的运行时接口

对于给定的设计，VisualApplets 可以生成 GenICam XML 代码。当目标平台 通过兼容 GenICam 的接口连接到软件时，此选项允许将图像处理参数无缝 集成到 GenICam API 中。无需任何 额外的软件组件。

如果需要将参数访问集成到现有的主 GenICam XML 文件中， 则需要进行一些后处理。在嵌入 VA IP 核之前平台 已经通过 GenICam 进行控制时，通常会出现这种情况。

要将参数访问集成到现有的主 GenICam XML 文件中，请执行以下操作：

  1. 剪切由 VisualApplets 生成的 XML 文件的标头。

  2. 将用于类别、变量和寄存器的剩余代码复制到主 XML 文件中。

VisualApplets 可以自动执行此步骤，因为它能够调用自定义后处理任务。

基于生成的 API 代码的运行时接口

对于给定的设计， VisualApplets 可以生成通用的 C API 代码。该代码是平台无关的 ANSI-C 代码。这种方法非常适合嵌入式系统（例如 Zynq7000）中的软件集成。

生成的代码提供以下接口： 

    
    #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);

您可以通过调用来初始化接口 va_init().

VA IP 核寄存器从接口的读写访问回调函数已注册。 boardHandle 存储的信息会在每次触发这些读写函数调用时提供。查询函数集为实现通用运行时接口提供了一个基本机制。对于给定的设计，设置函数和获取函数提供参数访问，其中参数按名称寻址。这些函数执行从访问设计参数到访问硬件寄存器的转换，并通过寄存器访问回调函数来实现。

 

  上一页     上一层     下一步  
内容 顶部 主页