NI TClk High Level Functions - ni/grpc-device GitHub Wiki
High-Level Functions
- niTClk_ConfigureForHomogeneousTriggers
- niTClk_Synchronize
- niTClk_Initiate
- niTClk_WaitUntilDone
- niTClk_GetExtendedErrorInfo
niTClk_ConfigureForHomogeneousTriggers
ViStatus niTClk_ConfigureForHomogeneousTriggers (ViUInt32 sessionCount, ViSession sessions []);
Purpose
Configures the attributes commonly required for the TClk synchronization of device sessions with homogeneous triggers in a single PXI chassis or a single PC.
Use the niTClk_ConfigureForHomogeneousTriggers function to configure attributes for the Reference Clocks, Start Triggers, Reference Triggers, Script Triggers, and Pause Triggers.
If the niTClk_ConfigureForHomogeneousTriggers function cannot perform all the steps required for the given sessions, it returns an error. If the niTClk_ConfigureForHomogeneousTriggers function returns an error, use the instrument driver functions and attributes, along with the following NI-TClk attributes, for signal routing.
- NITCLK_ATTR_START_TRIGGER_MASTER_SESSION
- NITCLK_ATTR_REF_TRIGGER_MASTER_SESSION
- NITCLK_ATTR_SCRIPT_TRIGGER_MASTER_SESSION
- NITCLK_ATTR_PAUSE_TRIGGER_MASTER_SESSION
The niTClk_ConfigureForHomogeneousTriggers function affects the following clocks and triggers:
Reference Clocks
The niTClk_ConfigureForHomogeneousTriggers function configures the reference clocks if they are needed. Specifically, if you use the internal sample clocks or internal Sample Clock timebases, and the Reference Clock Source is either not configured—or set to None (no trigger configured), the niTClk_ConfigureForHomogeneousTriggers function configures the following:
Start Triggers
If the Start Trigger is set to None (no trigger configured) for all sessions, the sessions are configured to share the Start Trigger. The Start Trigger is shared by:
If the Start Triggers are None for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures the sessions to share the Start Trigger from the one excepted session. The Start Trigger is shared by:
If the Start Triggers are configured for all sessions, the niTClk_ConfigureForHomogeneousTriggers function does not affect the Start Triggers. Start Triggers are considered to be configured for all sessions if one of the following conditions is true:
Reference Triggers
For sessions that support Reference Triggers, if the Reference Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Reference Triggers. The Reference Triggers are shared by:
If the Reference Triggers are configured for all sessions that support Reference Triggers, the niTClk_ConfigureForHomogeneousTriggers function does not affect the Reference Triggers. Reference Triggers are configured for all sessions if one of the following conditions is true:
Reference Trigger Holdoffs
Acquisition sessions may be configured with the Reference Trigger. For acquisition sessions, when the Reference Trigger is shared, niTClk_ConfigureForHomogeneousTriggers configures the holdoff attributes (which are instrument driver specific) on the Reference Trigger master session so that the session does not recognize the Reference Trigger before the other sessions are ready. This condition is only relevant when the Sample Clock rates, Sample Clock timebase rates, sample counts, holdoffs, and/or any delays for the acquisitions are different.
When the Sample Clock rates, Sample Clock timebase rates, and/or the sample counts are different in acquisition sessions sharing the Reference Trigger, you must also set the holdoff attributes for the Reference Trigger master, using the instrument driver.
Script Triggers
For sessions that support Script Triggers, if the Script Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Script Triggers. The Script Triggers are shared by:
If the Script Triggers are configured for all sessions that support Script Triggers, niTClk_ConfigureForHomogeneousTriggers does not affect Script Triggers. Script Triggers are configured for all sessions if one of the following conditions is true:
Pause Triggers
For sessions that support Pause Triggers, if the Pause Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Pause Triggers. The Pause Triggers are shared by:
If the Pause Triggers are configured for all generation sessions that support Pause Triggers, niTClk_ConfigureForHomogeneousTriggers does not affect Pause Triggers. Pause Triggers are configured for all sessions if one of the following conditions is true:
Parameters
| Input |
|---|
| Name | Type | Description |
|---|---|---|
| sessionCount | ViUInt32 | Specifies the number of elements in the sessions array. |
| sessions | ViSession [] | Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference. |
Return Value
The status code returned by the function.
- A value of 0 indicates success.
- A negative value indicates an error.
- A value greater than 0 indicates a warning.
Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.
niTClk_Synchronize
ViStatus niTClk_Synchronize (ViUInt32 sessionCount, ViSession sessions [], ViReal64 minTime);
Purpose
Synchronizes the TClk signals on the given sessions. After the niTClk_Synchronize function executes, the TClk signals from all the sessions are synchronized.
Note Before using the niTClk_Synchronize function, verify that your system is configured, as described in the PXI Trigger Lines and RTSI Lines topic.
Parameters
| Input |
|---|
| Name | Type | Description |
|---|---|---|
| sessionCount | ViUInt32 | Specifies the number of elements in the sessions array. |
| sessions | ViSession [] | Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference. |
| minTime | ViReal64 | Specifies the minimum TClk period, in seconds. Valid values are 0.0 s to 0.050 s (50 ms), inclusive. The minimum period for a single chassis/PC is 200 ns. If the specified value is less than 200 ns, NI-TClk automatically coerces the minimum TClk period to 200 ns. For multichassis synchronization, adjust this value to account for the propagation delays through the various devices and cables. |
Return Value
The status code returned by the function.
- A value of 0 indicates success.
- A negative value indicates an error.
- A value greater than 0 indicates a warning.
Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.
niTClk_Initiate
Specific Function
ViStatus niTClk_Initiate (ViUInt32 sessionCount, ViSession sessions []);
Purpose
Initiates the acquisition and/or generation sessions that you specify. This function also processes any special requirements that are needed for the synchronization.
For example, the session that exports the TClk-synchronized Start Trigger is not initiated until after the niTClk_Initiate function initiates all the sessions that import the TClk-synchronized Start Trigger.
Parameters
| Input |
|---|
| Name | Type | Description |
|---|---|---|
| sessionCount | ViUInt32 | Specifies the number of elements in the sessions array. |
| sessions | ViSession [] | Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference. |
Return Value
The status code returned by the function.
- A value of 0 indicates success.
- A negative value indicates an error.
- A value greater than 0 indicates a warning.
Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.
niTClk_WaitUntilDone
ViStatus niTClk_WaitUntilDone (ViUInt32 sessionCount, ViSession sessions [], ViReal64 timeout);
Purpose
Waits until the acquisitions and/or generations corresponding to the sessions are done, or until the function returns a timeout error.
niTClk_WaitUntilDone is a blocking function that periodically checks the operation status. This function returns control to the calling program, if the operation completes successfully, or if an error occurs (including a timeout error).
This function is most useful for finite data operations that you want to complete within a certain time.
Parameters
| Input |
|---|
| Name | Type | Description |
|---|---|---|
| sessionCount | ViUInt32 | Specifies the number of elements in the sessions array. |
| sessions | ViSession [] | Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference. |
| timeout | ViReal64 | Specifies the amount of time, in seconds, that the niTClk_WaitUntilDone function waits, for the sessions to complete. If the timeout parameter is exceeded, the niTClk_WaitUntilDone function returns an error. |
Return Value
The status code returned by the function.
- A value of 0 indicates success.
- A negative value indicates an error.
- A value greater than 0 indicates a warning.
Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.
niTClk_GetExtendedErrorInfo
Specific Function
ViStatus niTClk_GetExtendedErrorInfo (ViChar errorString [], ViUInt32 errorStringSize);
Purpose
Reports extended error information for the most recent NI-TClk function that returned an error.
To determine the function that returned an error, use the return values of the individual functions. After the niTClk_GetExtendedErrorInfo function reports an errorString, this function does not report an empty string again.
Parameters
| Input |
|---|
| Name | Type | Description |
|---|---|---|
| errorString | ViChar [] | Extended error description. If errorString is NULL, then the string is not large enough to hold the entire error description. In this case, niTClk_GetExtendedErrorInfo returns the size of the full error string, which can be used with niTClk_GetExtendedErrorInfo to retrieve the full error string. |
| errorStringSize | ViUInt32 | Size of errorString. If errorStringSize is 0, then it is not large enough to hold the entire error description. In this case, niTClk_GetExtendedErrorInfo returns the size of the full error string, which can be used with niTClk_GetExtendedErrorInfo to retrieve the full error string. |
Return Value
The status code returned by the function.
- A value of 0 indicates success.
- A negative value indicates an error.
- A value greater than 0 indicates a warning.
Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.