Genicam gentl standard ver1.5 (3) Chapter 4

4. Configuration and signal

From system module to data flow module , Each module supports GenTL Port to configure the internal settings of the module , And send a signal to the caller GenTL consumer . For buffer modules ,GenTL Ports are optional .

of C Detailed description of functional interfaces and data types , Please refer to the first 6 Chapter software interface . The module to be accessed must be instantiated before configuring the module or registering the event . This is done through module enumeration , Just like No 3 Chapter module enumeration and instantiation

4.1 To configure Configuration

To configure the module and access specific settings based on transport layer technology , It is necessary to use a device that conforms to GenApi Of XML Description of the GenTL port . The concerns of module specific functions are ： enumeration 、 Instantiation 、 Configuration and basic information retrieval . Configuration is through virtual register mapping and this register mapping GenApi XML Describe the completed .

about GenApi Reference implemented IPort Interface ,TLI Port functions have been released . One GenApi IPort A read / write function is required to read or write data blocks from the associated device . About GenTL Producer function access , Each module does

by GenAPi Devices in implementation , By implementing virtual register mapping . When some registers are written or read , Implementation dependent operations are performed in the specified module . therefore , The abstraction of camera configuration has also been transferred to GenTL On the producer side .

The memory layout of the virtual register map does not specify , Therefore, from GenTL The producer's implementation determines . Therefore, a specific set of mandatory functions must be implemented , This will be in the 7 Chapter GenTL Standard feature naming conventions for （GenTL SFNC） In detail .

C The port functions of the interface include GCReadPort Functions and GCWritePort function , Can be used to implement GenApi Realized IPort object . These functions behave like IPort Read and write functions .

Register access through port functions is always byte aligned . If the supporting technology does not allow byte aligned access ,GenTL The producer must imitate this feature by ：1. The number of bytes read exceeds the number of bytes requested , And only return the requested number of bytes ;2. Read port register mapping / modify / Write access .

4.1.1 modular Modules

In addition to the buffer module , Every GenTL All modules must support TLI Port function of . The buffer module can support these functions . To access the register of the module . for example , Call... On the module handle GCReadPort and GCWritePort function , for instance , In the system module TL_HANDLE On .GenApi XML Description documents and GenApiGenICam The module is used to use GenApi Access the virtual register mapping feature in the module .

Include the corresponding GenICam XML Describe the location of URL It can be by calling C Interface GCGetNumPortRls and GCGetPortURLInfo Function to retrieve . of GenTL Additional information about the actual port implementation in the producer , Please see use GCGetPortInfo retrieval . This information includes, for example, port byte order or allowed access （ read / Write 、 read-only …）. The two modules are special in the way they handle port access , It will be described in the following chapters .

4.1.1.1 Device modules

In the device module , Two ports are available ：

 First , The port function can be associated with the... That allows access to the device DEV_HANDLE Handle to use the module's internal functions .

 secondly ,GenTL Consumers can call DevGetPort Function to get the... Of the remote device PORT_HANDLE.

These two ports are for GenTL For producers , Must be realized .

4.1.1.2 Buffer module

For buffers , The implementation of port functions is not mandatory . Check whether there is implementation , You can call GCGetPortInfo function , for example PORT_INFO_MODULE command . If there is no implementation of the function , The return value of the function must be GC_ERR_NOT_IMPLEMENTED.

4.1.2 XML describe

To use similar GenApi Feature access , The last thing missing is XML Description contains to retrieve XML A list of possible locations can be called GCGetNumPortURLs Functions and GCGetPortURLInfo function . Similar to URL Three possible positions are defined in the symbol of （ of URL The definition of , see also RFC 3986）：

 Module register mapping （ Suggest GenTL Producers use ）

 Local directory

 Supplier website

need GenTL Consumers to achieve “ Module register mapping ” and “ Local directory ”. Downloading from the supplier's website is optional .

Supported formats include ：

 Uncompressed XML Description file

 Compression of the XML Description file . The compression method used is DEFLATE And in accordance with the RFC 1951 The description in .

4.1.2.1 Module register mapping （ recommend ）

URL The format is “local:[///]filename.extension;address;length[?SchemaVersion=x.x.x]” instructions XML The description file is located in the module's virtual register map . This square bracket is optional .“x.x.x” Stands for quoted XML Of SchemaVersion Conform to the version format :” Main version . Small version . Sub version ”. If you omit SchemaVersion, be URL To quote SchemaVersion 1.0.0 Of XML References to . This option is only available with older functions GCGetPortURL Use it together . For the current implementation GCGetPortURLInfo Function to get a specific XML Of documents SchemaVersion. Optionally , It can be omitted “//”behind“local:” In order to GigE Vision local Compatible with the overall arrangement if XML The description is stored in the local register map , By calling GCReadPort function .

Italicized input must be replaced with actual value , As shown in the table below ：

entry point	describe
local	instructions XML The description file is located in the module's virtual register map .
filename	Information file name . It is recommended that the supplier 、 model / The device and version information is placed in the file name , Separate it with an underline . for example ： First edition “tlguru_system_rev1” GenTL Manufacturer company tlguru System module file for
extension	Indicates the file type . The allowed types are  “xml”, For uncompressed xml Description file .  “zip”, For compression XML Description file .
address	The starting address of the file in the virtual register map . it Must be expressed in hexadecimal , Without prefix
length	The length of the file （ byte ）. Must be expressed in hexadecimal form without prefix .
SchemaVersion	Refer to the XML Compliant version . The format of this version is ： Major.minor.subminor. This only involves outdated GCGetPortURL function , Because the old mechanism has no other purpose XML File reports SchemaVersion Methods . For new GCGetPortURLInfo function It shall be through information retrieval SchemaVersion command .

A complete local URL It seems to have the following format ：

local:tlguru_system_rev1.xml;F0F00000;3BF?SchemaVersion=1.0.0

The information file name of this file is “tlguru_system_rev1.xml”, Located in the virtual register mapping slave address 0xF0F00000（C

Style notation ） Start , The length is 0x3BF byte .GenTL There are no further restrictions on memory alignment in modules （ Byte alignment ）. If the platform or transport layer technology requires some memory alignment , GenTL Producers need to consider this factor in their implementation .

4.1.2.2 Local directory

In the following two formats URL：

1. “file:///filepath.extension[？SchemaVersion=1.0.0]” or
2. “file:filename.extension[？SchemaVersion=1.0.0]”

Indicates that a file exists in a certain location and is running GenTL On the consumer's machine . This symbol follows URL Definition , Such as RFC 3986 For local files . Italicized input must be replaced with actual value .

for instance ：

file:///C|program%20files/genicam/xml/genapi/tlguru/tlguru_system_rev.xml？

SchemaVersion=1.0.0

This will apply to English Microsoft Windows Uncompressed on the operating system XML File system C Driver .

You can choose to omit “file：” hinder “//”, In order to GigE Visually compatible symbols . This symbol does not specify the exact location . For example, the graphical user interface can be used to determine the location using the file dialog box . In order to conform to certain Windows Mark , It is also allowed to take “：” The drive letter for . It is recommended that the supplier 、 Model or device and version information is placed in underlined names in the file . for example ：tlguru_system_rev1, be used for GenTL Manufacturer company TLGuru System module file for .

Supported extensions include ：

“xml”, For uncompressed xml Description file

“zip“, be used for zip Compression of the xml Description file

4.1.2.3 Supplier website （ Optional ）

A format such as “http://host/path/filename.extension[？SchemaVersion=1.0.0]“ Of URL,

It means that the supplier's web download XML Describe where the document is located . This symbol follows http agreement RFC 3986 Medium URL Definition . Italicized input must be replaced with actual value , for example ,http://www.tlguru.org/xml/tlguru_system_rev1.xml , This will apply to TLGuru On the company website xml Uncompressed found in subdirectories XML file . It is recommended that the supplier 、 The model or equipment and version information is placed in the file name , Separate it with an underline . for example ：tlguru_system_rev1, be used for GenTL Manufacturer company TLGuru System module file for .

Supported extensions include ：

“xml”, For uncompressed xml Description file

“zip“, be used for zip Compression of the xml Description file

4.1.3 Example

The following example shows how to get the port module xmls.

{

 // Retrieve the number of available URLs

 GCGetNumPortURLs( hModule, NumURLs );

 for( i=0; i<NumURLs; i++ )

 {

 URLSize = 0;

 GCGetPortURLInfo( hModule, i, URL_INFO_URL, 0, 0, &URLSize );

 // Retrieve an string buffer to store the URL

 GCGetPortURLInfo( hModule, i, URL_INFO_URL, 0, pURL, &URLSize );

 if ( ParseURLLocation( pURL ) == local )

 {

 // Retrieve the address within the module register map from the URL

 Addr = ParseURLLocalAddress( pURL );

 Length = ParseURLLocalLength( pURL );

 // Retrieve an XMLBuffer to store the XML with the size Length

 …

 // Load xml from local register map into memory

 GCReadPort( hModule, Addr, XMLBuffer, Length );

 }

 }

}

4.2  The signal Signaling

Signals are used to notify... In the form of asynchronous events GenTL consumer . Usually all communications are made by GenTL Consumer initiated .GenTL Consumers can get information about specific GenTL Notification of producer actions . This mechanism is the observer mode , One call GenTL Our consumers are observers , and GenTL The producer is the object being observed .

The main reason for choosing the event object method instead of the callback function is the thread priority problem . The callback function that signals the arrival of a new buffer is usually executed in the thread context of the collection engine . therefore , All processing functions in this callback are also completed with their priority . If no other precautions are taken , So as long as the callback function is processing , The engine will be blocked .

for instance , If you use an event object - based method , The collection engine only needs to prepare the necessary data , Then through the previously registered event object , Signal that data is available .GenTL The consumer can decide in which thread context to use the priority of data processing . therefore , The processing of events and the occurrence of signals are decoupled , Not related to each other .

4.2.1 Event object event object

Event objects allow calls to GenTL The user sends an asynchronous signal . Event objects have two states ： Signaled or Unsignalized .EventGetData Function block calling thread , Until a user-defined timeout occurs 、 Signal or... To an event object GenTL Consumer ends waiting .

If you're calling EventGetData Function before , The event object has signaled , Function will return immediately , And transmit the data associated with the signaling event .

Not every event type can be registered in every module , Not every module needs to implement every possible event type . If the module for an event is not listed , It is not necessary to implement in this module .

The maximum size of data transmitted by an event is defined in the event description , Can pass EventGetInfo Function to obtain . The actual size is determined by EventGetData The function returns , This function retrieves the data associated with the event .

There is no mandatory event type . If GenTL The event type... Is not implemented in the producer GCRegisterEvent Should return GC_ERR_NOT_IMPLEMENTED. If the event type is GenTL The producer module implements , It is recommended to register an event object for this event type .

The following table describes the event types .

surface 4-2 modular - Event type

Event type	modular	describe
Error	All	GenTL The consumer can receive an error in the asynchronous module . These are not due to mistakes C Interface or GenApi Function call function access in . They have their own error reports . for example , This event is applicable to collecting data in the collection engine of the data flow module
New Buffer	Data Stream	In the collection engine , New data exists in the buffer . If you implement a new buffer event It must be registered on the data flow module . Notification call after registration GenTL Consumer about each new buffer in the data stream . If EventFlush Function call , Then the output buffer queue is discarded . If one DSFlushQueue Events that are called to all event queues will also be deleted . Please use BUFFER_INFO_IS_QUEUED Command to query the queue status of the buffer .
Feature Invalidate	Local Device	This event calls... To GenTL The consumer sends the following signals ：GenTL The producer driver changed the mapping of the registered remote device , If this value is in GenApi Implementation in cache , The cache must be invalidated . This is especially useful for remote devices GenTL The producer may change some information GenTL Consumers will also use it . For local modules, the implementation knows which functions cannot be cached . Using this mechanism means that the user must ensure that all end node dependencies are invalid , To update GenApi cache . The function name provided may not be SFNC Standardization . If you pass SFNC Functions are overwritten , Should be used by GenTL What the producer has provided is correct SFNC name . If the function name provided is located in GenTL Consumer's selector , Traverse all selector values , And invalidate all nodes on which all provided functions and their selector values depend .
Feature Change	Local Device	This event is directed to GenTL The consumer communicates the following message ：GenApi The function must be set to a specific value . This is currently only used with “TLParamsLocked” Standard functions . Only GenTL Producer Know that flow related functions must be locked . This event indicates a lock “1” Or unlock the function “0”. Future use cases may be added when appropriate . Specifies the value of the feature through its IValue Interface , So set the string information . No error reports complete . If the function is not set or an error occurs , No action was performed , And it won't inform GenTL producer .
Remote Device Event	Local Device	This event is related to the call GenTL Consumer communications , Think GenApi An understandable event occurs , Started by remote device . Event is passed along with this event ID And optional data can be put into GenApi Adapter , Then disable all relevant nodes . This event was previously known as a function device event , But renamed , To synchronize enumeration of event types with .
Module Event	All	This event is related to the call GenTL Consumer communications , Think GenApi An understandable event occurs , from GenTL The producer module starts , This event has been registered in advance . event ID And the data delivered with this event （ Optional ） Put in GenApi Adapter , Then fail all relevant nodes .

4.2.2 Event object queue Event Object Queue

The event data queue is the core of the signal . This is thread safe queue holding event type specific data . Operations on this queue must be locked in some way , For example, through mutual exclusion , When one of the event functions is accessing it or a module specific thread is accessing it . therefore ,GenTL The producer implementation must ensure that the access time to the queue is as short as possible . perhaps , Lockless queues can be used to support dequeue operations from multiple threads .

As long as the event data queue is not empty , The status of the event object will be notified .

Each event data queue must have its own lock （ If there is ）, To protect the state of each instance and achieve the necessary parallelism . Both read and write operations must be locked . Two event data retrieval operations and event object signal state processing EventGetData A function must be an atomic function . in other words , If locks are used, the event data queue must be maintained on these two operations . There is also the operation of placing data in the queue , The state handling of an event object must be atomic .

4.2.3 Event handling Event Handling

The handling of event objects is always the same , Independent of event type . The cause of the signal and the signal data depend, of course, on the type of event . The complete state processing is performed by GenTL Producer driven completion .GenTL Consumers can call EventKill Function to terminate the wait EventGetData A single instance of an operation . This means that if there are multiple threads waiting for an event ,EventKill Function terminates only one wait operation , Other threads will continue to execute .

4.2.3.1 register Registration

In the GenTL Before the consumer notifies the event , The event object must be registered . After the module instance is created during enumeration , have access to GCRegisterEvent Function to create an event object . This function returns a that uniquely identifies the registered event object EVENT_HANDLE Handle . have access to EventGetInfo Function to get information about registered events . Only one event must be registered by module and event type . If an event object is registered twice in the same module ,GCRegisterEvent The function must return an error GC_ERR_RESOURCE_IN_USE.

To unregister an event object , Must call GCUnregisterEvent function . If the module to be given has been closed , All registered events on it will be automatically unregistered . When the event object logs out , Events in the event queue are automatically discarded . When the event object has passed GCUnregisterEvent Cancellation , Pending wait operations , Yes EventGetData Will be called with GC_ERR_ABORT End .

obtain EVENT_HANDLE After handle ,GenTL The consumer can wait for the event object to call EventGetData Function to signal . Together with event delivery , Event objects can carry data . When EventGetData After successful call , This data is copied to GenTL Consumer provided buffer .

4.2.3.2 Notification and data retrieval

If the event object is signaled , Then the data will be put into the event data queue at a certain point in time . You can call EventGetData Function to retrieve actual data . As long as there is only one listener thread , This function always returns the stored data , If no data is available , Then it returns the event waiting to be notified with the provided timeout . If multiple listener threads display only the event data returned by one of them , Other returns are waiting until a timeout occurs , To send out EventKill, Or until the next event data becomes available .

If the EventKill, Only one pair will be returned EventGetData Call to GC_ERR_ABORT, Even without EventGetData Call waiting , Called EventKill. And return GC_ERR_ABORT Is higher than sending events from the queue , Even if there is one or more events in the queue , Prepare to call EventGetData Pass it on to the user . Calling EventKill after , call EventGetData Will return GC_ERR_ABORT. under these circumstances , No events will be removed from the queue , No data is passed to GenTL consumer . Counter EVENT_NUM_FIRED Not subject to EventKill Impact of call .

If by calling GCUnregisterEvent Unregister event objects , Its previous state will be lost . This also applies to previous studies on EventKill Function call . After re registering , stay EventGetData On this port by calling GCRegisterEvent The event that occurs will be called again EventKill Before , Will not return GC_ERR_ABORT.

When using this function to read data , Data will be deleted from the queue . after GenTL Producer implementation , Check whether the event data queue is empty . If more data is available , The event object remains in signal state , Next call EventGetData The next queue entry will be passed . otherwise , The event object will be reset to a non signaled state . adopt EventGetData Delivered

The maximum size of the buffer can be by using EventGetInfo Functional EVENT_SIZE_MAX The query .GenTL Consumers must not perform data size queries , Because a call with NULL Of EventGetData The buffer pointer will delete data from the queue , Without passing data . In this case, the event will be counted , As if it will be triggered and the data will be discarded .

The exact type of data depends on the event type and GenTL Producer implementation . Data is copied to GenTL Consumer allocated user buffer . have access to EventGetDataInfo Function to query the contents of the event data . The maximum size of the buffer to be filled is defined by the event type , You can use the delivered buffer EVENT_INFO_DATA_SIZE_ MAX. This information can be used EventGetInfo The function finds .

1. Follow these steps to handle the event ：
2. Corresponding GenTL Register on the module DeviceEvent.
3. Maximum buffer size required for query .
4. Allocate buffer to receive event data .
5. Wait for events and data . The data structure in the provided buffer is not defined , It depends on GenTL producer . The only exception is to provide a new buffer event with a defined internal structure .
6. Use EventGetDataInfo Extract data from buffer . This step is not necessary , When GenTL Producers know through EventGetData When passing the contents of the buffer , For example, in the case of a new buffer event .

 ... 

1. The cancellation of the event .
2. Release buffer .

As mentioned above , adopt EventGetData The contents of the retrieved buffer are GenTL The producer specifically implements , have access to EventGetDataInfo Function to parse it . The only exception to this is the new buffer event , It will return EVENT_NEW_BUFFER_DATA structure . Many events for device events （Event_REMOTE_Device）,GenTL The producer must provide two types of information about each event , So that we can “ Connect ” Node mapping to remote devices ：

1. event ID： adopt EventGetDataInfo（Event_DATA_ID） Inquire about .ID A string representation passed as hexadecimal , For example, without leading “0x” Of “CF51”. You can also use EventGetDataInfo Query directly in digital form ID（EVENT_DATA_NUMID）.
2. Event data ： Contains the （ Optional ） Buffer for data . It must correspond to the addressable data in the remote device node map , Must be with nodemap The address of the event port 0 Corresponding . for example , about GigE Vision Equipment as per convention , This is the whole thing EVENTDATA Data packets , No, 8 Bytes GVCP header .

Besides , For module events （EVENT_MODULE）,GenTL The producer must provide two types of information about each event , To connect it to the module's node mapping ：

1. event ID： adopt EventGetDataInfo（Event_DATA_ID） Inquire about .ID A string representation passed as hexadecimal , For example, without leading “0x” Of “CF51”. You can also use EventGetDataInfo Query directly in digital form ID（EVENT_DATA_NUMID）.

Event data ： Contains the （ Optional ） Buffer for data . It must correspond to the addressable data in the module node mapping buffer . Must be with nodemap The address of the event port 0 Corresponding , Be similar to EVENT_REMOTE_DEVICE I am working . Be careful ： To improve interoperability , It is recommended that for “ standard ” Event data format , adopt EventGetData The passed buffer can be directly fed to the corresponding standard GenApi Event adapter buffer . for example , In regard to GigE Vision, It will be the whole EVENTDATA package , Including Baotou . If you no longer need the event data in the queue , Can be associated by calling EVENT_HANDLE Upper EventFlush function . Query buffer GenTL Consumers can use info Command invocation DSGetBufferInfo Buffer information queued . A signal that occurs without registering the corresponding event object GCRegisterEvent Automatically discarded .

A single event notification contains an event and its data . hypothesis , One GigE vision Device events are sent through the message channel , With multiple events in a package ID, It will inevitably lead to multiple GenTL Producer Events . Every GenTL The producer will provide a GigE Vision EventID.

4.2.4 Example Example

The following code snippet demonstrates how to register a new buffer event :

{

 GCRegisterEvent(hDS, EVENT_NEW_BUFFER, hNewBufferEvent);

 CreateThread ( AcqFunction );

}

4.2.4.1 Data collection thread function AcqFunction

{

 while( !EndRun )

 {

 EventGetData( hNewBufferEvent, EventData );

 if ( successful )

 {

 // Do something with the new buffer

 }

 }

}