執行階段軟體介面

VisualApplets 支援在執行時存取設計參數的各種模式：

使用基於 HAP 檔案的 eVA 執行環境
使用基於生成的GenICam XML 程式碼所建構的GenICam API
使用由VisualApplets

基於 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()`	開啟硬體小程式 `*.hap` 並傳回指向 HAP 結構體的指標，該指標將作為後續存取的句柄。
2	`vaRt_CloseHap()`	關閉由 `vaRt_OpenHap`.
3	`vaRt_GetConfig()`	回傳指向 FPGA 配置位元流的指標。
4	`vaRt_GetAppletProperty()`	用於查詢小程式屬性的查詢功能，例如時鐘小程式中的iDesignClk網路、目標平台相關資訊，以及版本資訊。
5	`vaRt_GetProcessCount()`	回傳構成該設計的程序數量。
6	`vaRt_GetIoPortCount()`	回傳已使用的外部介面埠數量。所有類型的介面埠均彙整至一個清單中，其中在清單中的位置即為該埠的邏輯編號。可透過下方指定的函式取得埠名稱及屬性 `vaRt_GetIoPort…`.
7	`vaRt_GetIoPortName()`	取得對應於指定邏輯埠號的介面埠名稱。
8	`vaRt_GetIoPortProperty()`	查詢 I/O 埠的屬性，例如已連接運算子的名稱、控制此埠的程序，以及此埠的當前影像格式設定。
9	`vaRt_GetParamCount()`	回傳設計的參數數量。
10	`vaRt_GetParamName()`	針對給定的參數編號，會回傳對應的名稱。
11	`vaRt_GetParamId()`	針對給定的參數編號，會回傳對應的參數 ID。
12	`vaRt_GetParamIdByName()`	針對給定的參數名稱，會回傳該參數的 ID。
13	`vaRt_GetParamProperty()`	查詢參數的屬性。
14	`vaRt_InitParams()`	設定參數介面，並將參數初始化為預設值。
15	`vaRt_GetParam()`	查詢參數值。
16	`vaRt_GetParamArray()`	查詢參數陣列。
17	`vaRt_SetParam()`	設定參數值。
18	`vaRt_SetParamArray()`	設定一組參數。
19	`vaRt_SetGlobalEnable()`	設定主控制啟用訊號。
20	`vaRt_SetProcessEnable()`	啟動VisualApplets 設計中的某個流程。
21	`vaRt_ResetProcess()`	重置VisualApplets 設計流程。
22	`vaRt_GetErrorDescription()`	針對指定錯誤代碼的查詢說明。

資料通訊

在查詢資訊及設定參數時，資料必須透過執行時介面進行交換。為了使介面功能保持簡單，同時提供型別安全的介面，因此實作了資料的抽象化機制。每當需要傳遞不同型別的資料時，便會使用一種稱為 va_data 會使用，其中包含對資料的引用以及關於底層資料型別的資訊。此資料結構由使用者建立，但由下列專用函式進行配置。下表列出了此方法所支援的資料型別：

Data Type	描述
`VA_ENUM`	以 32 位元整數形式提供的枚舉項目。
`VA_INT32`	32 位元有符整數。
`VA_UINT32`	32 位元無符號整數。
V`A_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`	由 double 型號數組成的陣列。
`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(&amp;va_desFreq,&amp;desFreq); 
         
       vaRt_GetAppletProperty(hapHandle, &quot;DesignFreq&quot;,&amp;va_desFreq);

之後，該變數 desFreq 將包含您所要求的資訊。

Detailed Description of Interface Functions

下表詳細說明了指定之執行時存取函式的參數與回傳值。

功能	`int vaRt_OpenHap (const char* hapFileName, va_hap_handle*hap)`
參數 1	要開啟的 hap 檔案名稱。
Parameter 2	Hap 句柄的回傳指標。
描述	開啟名稱與參數相符的硬體小程式，並回傳指向 hap 結構體的指標。該回傳的指標在所有其他介面函式中皆用作處理器。
回傳值	0 : 好 <0: Error opening applet

功能

int vaRt_CloseHap (va_hap_handle handle)

參數 1

哈普手柄來自 vaRt_OpenHap().

描述

關閉 VA 硬體小程式。

回傳值

0 = 正常

<0 = Error closing HAP

功能	`int vaRt_GetConfig (va_hap_handle handle, int fpgaID, char*data, size_t sizeInBytes)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	目標平台中 FPGA 的識別碼。對於單一配置的 HAP 檔案（目前為唯一選項），此參數可固定為 -1。否則，此參數必須與用於建立VisualApplets 平台的硬體定義檔案中指定的（可選）FPGA 識別碼相符。
Parameter 3	指向配置位元流緩衝區的指標。
參數 4	請以位元組為單位，說明配置位元流的大小。
描述	取得 FPGA 設計的配置位元流。此函式有兩種運作模式：
回傳值	0：好 <0: Error acquiring the bitstream

功能	`int vaRt_GetAppletProperty (va_hap_handle handle, const char* propName,va_data * data)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	要查詢的屬性名稱。
Parameter 3	指向將用於通訊之資料結構的指標。
描述	取得 Applet 的屬性。可查詢以下屬性： VisualAppletsVersion: 取得用於建立此小程式的VisualApplets 框架版本（輸入 `VA_STRING`) IPCoreVersion: 取得 VA IP 核心的版本（類型 V`A_STRING`) AppletVersion: 取得小程式版本（輸入 `VA_STRING`) DesignFreq: 取得設計時鐘的頻率（單位為 MHz）（輸入 `VA_DOUBLE`) 平台供應商: 平台供應商（類型 `VA_STRING`) 平台類型: 硬體平台名稱（類型 `VA_STRING`) PlatformID: 平台裝置的識別編號（類型 `VA_STRING`) 平台版本: 如用於建立小程式的硬體描述中所定義的平台裝置版本（類型 `VA_STRING`) 這些屬性透過上述其中一個字串（透過參數 2 提供）進行識別，並透過參數 3 所提供的資料結構進行傳遞。對於類型為 `VA_STRING` 該回傳的字串可能會被下次呼叫此函式時所覆寫。
回傳值	0：確定 <0 : Can’t retrieve applet property

功能	`int vaRt_GetProcessCount (va_hap_handle handle, unsigned int* count)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	表示進程數的回傳值。
描述	取得構成該設計的程序數量。
回傳值	0：OK <0 : Can’t retrieve information

功能	`int vaRt_GetIoPortCount (va_hap_handle handle, unsigned int*count)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	埠數的回傳值。
描述	取得 VA IP 核心已使用的 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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	邏輯介面埠號，即介於 0 與由 `vaRt_GetIoPortCount()` 減 1。
描述	取得具有指定邏輯號碼的介面埠名稱。當存在多個同類埠時，這些埠會透過後綴 _X 來區分，其中 X 代表埠索引（例如 DmaRd_0）。
回傳值	0：好； `*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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	I/O 埠的名稱。
Parameter 3	要查詢的屬性名稱。
參數 4	指向將用於通訊之資料結構的指標。
描述	取得指定名稱的 I/O 埠之屬性。可查詢的屬性如下：：操作員名稱: 已連線運算子的使用者自訂名稱（類型 `VA_STRING`)。運算子類型: 已連接運算子的運算子類型名稱（類型 `VA_STRING`)。 Process: 連線運算子運作的程序的邏輯編號（類型 `VA_UINT32`)。格式識別碼: I/O 運算子的格式識別碼（類型 `VA_UINT32`, 僅適用於類型為 ImgIn 或我mgOut)。這些屬性透過上述其中一個字串（透過參數 3 提供）來識別，並透過參數 4 所提供的資料結構進行傳遞。對於類型為 `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	哈普手柄來自 `vaRt_OpenHap(`)。
Parameter 2	指向裝置處理程式的指標，該處理程式會提供給低階存取函式 `WriteReg32()`, `ReadReg32()`, `WriteReg64`, 以及 `ReadReg64()` 對於任何寄存器存取。
Parameter 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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數數量的回傳值。
描述	取得可透過參數介面存取的 Applet 參數數量。回傳的數字代表內部所管理的參數清單大小，該清單中註冊了所有可用的參數，而清單中的位置則定義了該參數的邏輯編號。
回傳值	0：OK <0 : Can’t retrieve information

功能	`int vaRt_GetParamName (va_hap_handle handle, unsigned int index, const char** name)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	邏輯參數編號，即介於零與由所傳回的值之間的整數 `vaRt_GetParamCount()` 減 1。
Parameter 3	傳回指向名稱字串的指標。
描述	根據給定的邏輯參數編號，取得 Applet 參數的名稱。
回傳值	0：OK；*name 會傳回一個靜態緩衝區的指標，該緩衝區存放參數 name（以 0 結尾）。請注意，此緩衝區可能會被下次呼叫此函式時所覆寫。 <0 : Can’t retrieve information

功能	`int vaRt_GetParamId (const struct va_hap_handle* handle, unsigned int index, int* paramId)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	邏輯參數編號，即介於零與由 `vaRt_GetParamCount()` 減 1。
Parameter 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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數名稱，其值可為以下所列值之一： `vaRt_GetParamName()`.
Parameter 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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數名稱。
Parameter 3	要查詢的屬性名稱。
參數 4	指向將用於通訊之資料結構的指標。
描述	查詢 Applet 參數的屬性。不同的參數類型確實具有不同的屬性。有關可用參數屬性的清單，請參閱 VA Engine 規格。這些屬性由參數 3 提供的字串進行識別，並透過參數 4 提供的資料結構進行傳遞。對於類型為 `VA_STRING` 回傳的字串至少在參數被修改之前，其值是穩定的。
回傳值	0：確定 <0 : Can’t retrieve parameter property

功能	`int vaRt_GetParam (va_hap_handle handle, int paramID, va_data * value)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數 ID。
Parameter 3	指向將用於通訊之資料結構的指標。該相關資料元素將被讀取到的值覆寫。
描述	根據參數 ID 查詢小程式參數。資料是透過由參數 3 指定的資料結構進行傳輸。若要查詢欄位參數，請使用 `vaRt_GetParamArray()`. 對於類型為 `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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數 ID。
Parameter 3	指向將用於通訊之資料結構的指標。相關的資料元素將被擷取的值所覆寫。
參數 4	在參數欄位內設定起始索引
參數 5	應查詢的元素數量
描述	透過參數 ID 查詢小程式的查詢欄位參數，並填入一個由資料元素組成的陣列。資料是透過參數 4 所指定的資料結構進行傳輸的。
回傳值	0：好的。 <0 : Error querying the array.

功能	`int vaRt_SetParam (va_hap_handle handle, int paramID, const va_data * value)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數 ID。
Parameter 3	指向將用於將資料提交至 Applet 的資料結構的指標。
描述	設定指定名稱的 Applet 參數。資料由一個資料結構提供（參數 4）。若要設定欄位參數，請使用 v`aRt_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	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	參數 ID。
Parameter 3	指向將用於將值傳送至小程式的資料結構的指標。
參數 4	在參數欄位中設定起始索引。
參數 5	應設定的元素數量。
描述	透過提交一個由資料元素組成的陣列，設定指定名稱的小程式之欄位參數。資料是透過資料結構（參數 3）提供的。
回傳值	0：好的。 <0 : Error setting the parameter field.

功能	`int vaRt_SetGlobalEnable (va_hap_handle handle, int active)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	應將全域啟用設定為的狀態（1 或 0）。
描述	將全域啟用設定設為 1（啟用=1）或 0（啟用=0）。
回傳值	0：OK <0 : Error setting the global enable state.

功能	`int vaRt_SetProcessEnable (va_hap_handle handle, unsigned int procNr, int active)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	進程編號，或 ((unsigned int)-1)，用以一次識別所有進程。
Parameter 3	應設定為啟用狀態的值（1 或 0）。
描述	將某個程序（或所有程序）的啟用狀態設定為 1（活躍=1）或 0 （活躍=0）。
回傳值	0：好的。 <0 : Error setting the process enable state.

功能	`int vaRt_ResetProcess (va_hap_handle handle, unsigned int procNr)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
Parameter 2	進程編號，或 ((unsigned int)-1)，用以一次識別所有進程。
描述	重置指定邏輯進程號的進程（或所有進程）。相應的進程重置訊號將被拉高，隨後再次釋放。對應進程的使能訊號則不予干預。請使用 `vaRt_SetProcessEnable()` 以及這個用來控制小程式的函式。
回傳值	0：好的。 <0 : Cannot reset the process.

功能	`const char* vaRt_GetErrorDescription (va_hap_handle handle, int errorCode)`
參數 1	哈普手柄來自 `vaRt_OpenHap()`.
參數2	程式碼來源： `vaRt_GetLastError()`.
描述	查詢指定錯誤代碼對應的錯誤訊息字串。
回傳值	非 NULL：錯誤說明（以 0 結尾的 C 字串） NULL：無說明

基於 GenICam API 2.0 版本的執行階段介面

針對特定設計，VisualApplets 可能會產生GenICam XML 程式碼。當目標平台透過與GenICam 相容的介面連接到軟體時，此選項可讓影像處理參數無縫整合至GenICam API 中。無需任何額外的軟體元件。

若需將參數存取功能整合至現有的主檔案GenICam XML 中，則需進行一些後處理。通常在將 VA IP 核心嵌入之前，若平台已透過GenICam 進行控制，便會出現這種情況。

若要將參數存取功能整合至現有的主檔案GenICam XML 中：

刪除由VisualApplets 生成的XML 檔案的標頭。
將類別、變數及登錄檔的其餘程式碼複製到主 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 會被儲存，並在每次觸發這些寫入與讀取函式時提供。這組查詢函式提供了一種實作通用執行時介面的基礎機制。對於給定的設計，這組寫入函式與讀取函式可提供參數存取功能，其中參數是透過名稱來定位的。這些函式會透過用於存取登錄檔的回呼函式，將對設計參數的存取轉換為對硬體上登錄檔的存取。

上一頁	上一層	下一頁
內容	頂端	首頁

側邊欄	上一頁 \| 上一層 \| 下一頁
內容 \| 首頁
PDF \| 列印 \| 聯絡我們

VisualApplets 使用者手冊