Driver Functions and Attribute Model
The IVI Foundation requires that each IVI-C instrument driver contain the following additional inherent functions:
- Prefix_init
- Prefix_InitWithOptions
- Prefix_SetAttribute<type>
- Prefix_GetAttribute<type>
- Prefix_GetNextCoercionRecord
- Prefix_LockSession
- PrefixDisable
- PrefixResetWithDefaults
- Prefix_UnlockSession
- Prefix_GetError
- Prefix_ClearError
The following functions are recommended to implement in IVI drivers:
- Prefix_GetNextInterchangeWarning
- Prefix_GetNextCoercionRecord
- Prefix_CheckAttribute<type>
- Prefix_ReadInstrData (Message-based instruments only)
- Prefix_WriteInstrData (Message-based instruments only)
Refer to the LabWindows/CVI Help for a description of all functions that the VXIplug&play and IVI specifications require.
VXIplug&play drivers also contain high-level functions that encapsulate multiple instrument interactions. The drivers usually group high-level functions into categories such as configuration functions and measurement functions. A configuration function modifies one or more settings on the instrument. A measurement function reads the data from the instrument. Drivers often contain application-level functions, which call one or more configuration functions and a measurement function.
IVI drivers contain the same types of high-level functions. A key difference between IVI and non IVI drivers is how they implement the high-level functions. Non IVI drivers use direct instrument I/O to query and modify instrument settings. IVI drivers query and modify instrument settings through attributes. Thus, a high-level function in an IVI driver might consist of a set of calls to IVI Engine functions such as Ivi_GetAttributeViInt32, Ivi_SetAttributeViInt32, and Ivi_SetAttributeViReal64. The IVI Engine provides the mechanism for the management of instrument driver attributes.
Types of Attributes
Some attributes are common to all IVI instrument drivers. These attributes are called inherent attributes. The specification for an instrument class defines attributes that are common among all instruments of one type. These attributes are called class-defined attributes. A specific instrument driver defines attributes that are specific to a particular instrument model or family of models. These attributes are called instrument specific attributes. Each specific instrument driver API exports the inherent IVI attributes and most or all of its instrument specific attributes. A specific instrument driver that complies with a standard class definition also exports the class-defined attributes.
An instrument driver can use attributes for more than modeling instrument states. For instance, the driver can use attributes to represent values that the driver recalculates dynamically each time the user queries its value. The driver also can use attributes to maintain internal data attached to each IVI session the user creates. Instrument driver developers can choose whether to export such attributes to the user. Attributes that drivers export to users are called public attributes. Attributes that drivers use only internally are called private or hidden attributes.
The instrument driver must assign one of the following VISA data types to each attribute: ViInt32, ViInt64, ViReal64, ViString, ViBoolean, ViSession, or ViAddr. Only hidden attributes can be of type ViAddr.
Refer to the Inherent IVI Attributes section for detailed descriptions of each inherent attribute.
Get/Set/Check Functions
When a high-level function in an instrument driver queries or modifies the current setting of an attribute, it does so by calling one of the Ivi_GetAttribute or Ivi_SetAttribute functions. The IVI Engine contains seven Ivi_GetAttribute functions and seven Ivi_SetAttribute functions, one for each possible attribute data type. These are called typesafe functions.
The IVI Engine also exports seven typesafe Ivi_CheckAttribute functions. Instrument drivers can call these functions to verify that a particular value is valid for an attribute.
 |
Note The IVI_Get/Set/CheckAttributeViInt64 functions are needed only if your driver supports ViInt64 attributes. |
Instrument drivers export Prefix_GetAttribute, Prefix_SetAttribute, and Prefix_CheckAttribute functions for each of the data types that instrument driver public attributes can have. Exporting these functions for each data type allows users to bypass the high-level functions in instrument drivers and directly query and modify the values of instrument attributes. The Prefix_GetAttribute, Prefix_SetAttribute, and Prefix_CheckAttribute functions are merely wrappers around calls to the Ivi_GetAttribute, Ivi_SetAttribute, and Ivi_CheckAttribute functions.
Each Ivi_Get/Set/CheckAttribute function has an optionFlags parameter. The Prefix_Get/Set/CheckAttribute functions that instrument drivers export do not have this parameter. They always pass the IVI_VAL_DIRECT_USER_CALL flag to the Ivi_Get/Set/CheckAttribute function. For more information on the optionFlags parameter, refer to the function descriptions for the Ivi_Get/Set/CheckAttribute functions in the LabWindows/CVI Help.
The LabWindows/CVI Help contains one consolidated function description for all the Ivi_GetAttribute functions, except Ivi_GetAttributeViString, one consolidated function description for all the Ivi_SetAttribute functions, and one consolidated function description for all the Ivi_CheckAttribute functions. The function descriptions contain detailed information on the purpose of each function and the functions parameters.
Callbacks
The IVI Engine contains a sophisticated attribute state caching mechanism. Each specific instrument driver, on the other hand, can obtain settings from the instrument, validate new settings, and send new settings to the instrument. Thus, a function call to set or get an attribute value executes code, both in the IVI Engine and in the specific instrument driver.
The most efficient way to partition this work is through a callback mechanism. The specific instrument driver can query and modify instrument attribute values into a set of callback functions for each attribute. The driver installs the callbacks for each attribute by passing the addresses of the callback functions to the IVI Engine. Besides enabling state caching, this scheme also allows the IVI Engine to play an important role in implementing the range checking, status checking, and simulation options in instrument drivers.
All function calls to get or set an attribute value first go through the IVI Engine. The IVI Engine uses this opportunity to determine whether state caching, range checking, and simulation are enabled. It also determines whether the cached value of the attribute is valid, that is, whether the attribute reflects the current state of the instrument. Depending on these factors, the IVI Engine invokes one or more callback functions. After the callbacks return, the IVI Engine can take additional actions such as storing a new value in the cache.
The IVI Engine allows an instrument driver to install six callback functions for each attribute: read, write, check, coerce, compare, and range table. Refer to the Attribute Callback Functions section for a description of the six attribute callbacks.
The IVI Engine also allows an instrument driver to install two callback functions that are global to an entire IVI session: an operation complete callback and a check status callback. Refer to the Session Callback Functions section for a description of the session callbacks.
The instrument driver developer chooses which callbacks to install. The IVI Engine does not require any callbacks.