HOME
| OPENMP API Specification: Version 5.1 November 2020

4.6.2  Entry Points in the OMPT Device Tracing Interface

The runtime entry points with type signatures of the types that are specified in this section enable a tool to trace activities on a device.

4.6.2.1 ompt_get_device_num_procs_t

Summary The ompt_get_device_num_procs_t type is the type signature of the ompt_get_device_num_procs runtime entry point, which returns the number of processors currently available to the execution environment on the specified device.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_get_device_num_procs_t) ( 
  ompt_device_t *device 
);  

SVG-Viewer needed.

Description The ompt_get_device_num_procs runtime entry point, which has type signature ompt_get_device_num_procs_t, returns the number of processors that are available on the device at the time the routine is called. This value may change between the time that it is determined and the time that it is read in the calling context due to system actions outside the control of the OpenMP implementation.

Description of Arguments The device argument is a pointer to an opaque object that represents the target device instance. The pointer to the device instance object is used by functions in the device tracing interface to identify the device being addressed.

Cross References

4.6.2.2 ompt_get_device_time_t

Summary The ompt_get_device_time_t type is the type signature of the ompt_get_device_time runtime entry point, which returns the current time on the specified device.

Format

SVG-Viewer needed.

 

 
typedef ompt_device_time_t (*ompt_get_device_time_t) ( 
  ompt_device_t *device 
);  

SVG-Viewer needed.

Description Host and target devices are typically distinct and run independently. If host and target devices are different hardware components, they may use different clock generators. For this reason, a common time base for ordering host-side and device-side events may not be available.

The ompt_get_device_time runtime entry point, which has type signature ompt_get_device_time_t, returns the current time on the specified device. A tool can use this information to align time stamps from different devices.

Description of Arguments The device argument is a pointer to an opaque object that represents the target device instance. The pointer to the device instance object is used by functions in the device tracing interface to identify the device being addressed.

Cross References

4.6.2.3 ompt_translate_time_t

Summary The ompt_translate_time_t type is the type signature of the ompt_translate_time runtime entry point, which translates a time value that is obtained from the specified device to a corresponding time value on the host device.

Format

SVG-Viewer needed.

 

 
typedef double (*ompt_translate_time_t) ( 
  ompt_device_t *device, 
  ompt_device_time_t time 
);  

SVG-Viewer needed.

Description The ompt_translate_time runtime entry point, which has type signature ompt_translate_time_t, translates a time value obtained from the specified device to a corresponding time value on the host device. The returned value for the host time has the same meaning as the value returned from omp_get_wtime.

SVG-Viewer needed.

Note – The accuracy of time translations may degrade, if they are not performed promptly after a device time value is received and if either the host or device vary their clock speeds. Prompt translation of device times to host times is recommended.

SVG-Viewer needed.

Description of Arguments The device argument is a pointer to an opaque object that represents the target device instance. The pointer to the device instance object is used by functions in the device tracing interface to identify the device being addressed.

The time argument is a time from the specified device.

Cross References

4.6.2.4 ompt_set_trace_ompt_t

Summary The ompt_set_trace_ompt_t type is the type signature of the ompt_set_trace_ompt runtime entry point, which enables or disables the recording of trace records for one or more types of OMPT events.

Format

SVG-Viewer needed.

 

 
typedef ompt_set_result_t (*ompt_set_trace_ompt_t) ( 
  ompt_device_t *device, 
  unsigned int enable, 
  unsigned int etype 
);  

SVG-Viewer needed.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

The etype argument indicates the events to which the invocation of ompt_set_trace_ompt applies. If the value of etype is 0 then the invocation applies to all events. If etype is positive then it applies to the event in ompt_callbacks_t that matches that value.

The enable argument indicates whether tracing should be enabled or disabled for the event or events that the etype argument specifies. A positive value for enable indicates that recording should be enabled; a value of 0 for enable indicates that recording should be disabled.

Restrictions Restrictions on the ompt_set_trace_ompt runtime entry point are as follows:

Cross References

4.6.2.5 ompt_set_trace_native_t

Summary The ompt_set_trace_native_t type is the type signature of the ompt_set_trace_native runtime entry point, which enables or disables the recording of native trace records for a device.

Format

SVG-Viewer needed.

 

 
typedef ompt_set_result_t (*ompt_set_trace_native_t) ( 
  ompt_device_t *device, 
  int enable, 
  int flags 
);  

SVG-Viewer needed.

Description This interface is designed for use by a tool that cannot directly use native control functions for the device. If a tool can directly use the native control functions then it can invoke native control functions directly using pointers that the lookup function associated with the device provides and that are described in the documentation string that is provided to the device initializer callback.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

The enable argument indicates whether this invocation should enable or disable recording of events.

The flags argument specifies the kinds of native device monitoring to enable or to disable. Each kind of monitoring is specified by a flag bit. Flags can be composed by using logical or to combine enumeration values from type ompt_native_mon_flag_t.

To start, to pause, to flush, or to stop tracing for a specific target device associated with device, a tool invokes the ompt_start_trace, ompt_pause_trace, ompt_flush_trace, or ompt_stop_trace runtime entry point for the device.

Restrictions Restrictions on the ompt_set_trace_native runtime entry point are as follows:

Cross References

4.6.2.6 ompt_start_trace_t

Summary The ompt_start_trace_t type is the type signature of the ompt_start_trace runtime entry point, which starts tracing of activity on a specific device.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_start_trace_t) ( 
  ompt_device_t *device, 
  ompt_callback_buffer_request_t request, 
  ompt_callback_buffer_complete_t complete 
);  

SVG-Viewer needed.

Description A device’s ompt_start_trace runtime entry point, which has type signature ompt_start_trace_t, initiates tracing on the device. Under normal operating conditions, every event buffer provided to a device by a tool callback is returned to the tool before the OpenMP runtime shuts down. If an exceptional condition terminates execution of an OpenMP program, the OpenMP runtime may not return buffers provided to the device.

An invocation of ompt_start_trace returns 1 if the command succeeds and 0 otherwise.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

The request argument specifies a tool callback that supplies a buffer in which a device can deposit events.

The complete argument specifies a tool callback that is invoked by the OpenMP implementation to empty a buffer that contains event records.

Cross References

4.6.2.7 ompt_pause_trace_t

Summary The ompt_pause_trace_t type is the type signature of the ompt_pause_trace runtime entry point, which pauses or restarts activity tracing on a specific device.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_pause_trace_t) ( 
  ompt_device_t *device, 
  int begin_pause 
);  

SVG-Viewer needed.

Description A device’s ompt_pause_trace runtime entry point, which has type signature ompt_pause_trace_t, pauses or resumes tracing on a device. An invocation of ompt_pause_trace returns 1 if the command succeeds and 0 otherwise. Redundant pause or resume commands are idempotent and will return the same value as the prior command.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

The begin_pause argument indicates whether to pause or to resume tracing. To resume tracing, zero should be supplied for begin_pause; To pause tracing, any other value should be supplied.

Cross References

4.6.2.8 ompt_flush_trace_t

Summary The ompt_flush_trace_t type is the type signature of the ompt_flush_trace runtime entry point, which causes all pending trace records for the specified device to be delivered.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_flush_trace_t) ( 
  ompt_device_t *device 
);  

SVG-Viewer needed.

Description A device’s ompt_flush_trace runtime entry point, which has type signature ompt_flush_trace_t, causes the OpenMP implementation to issue a sequence of zero or more buffer completion callbacks to deliver all trace records that have been collected prior to the flush. An invocation of ompt_flush_trace returns 1 if the command succeeds and 0 otherwise.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

Cross References

4.6.2.9 ompt_stop_trace_t

Summary The ompt_stop_trace_t type is the type signature of the ompt_stop_trace runtime entry point, which stops tracing for a device.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_stop_trace_t) ( 
  ompt_device_t *device 
);  

SVG-Viewer needed.

Description A device’s ompt_stop_trace runtime entry point, which has type signature ompt_stop_trace_t, halts tracing on the device and requests that any pending trace records are flushed. An invocation of ompt_stop_trace returns 1 if the command succeeds and 0 otherwise.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

Cross References

4.6.2.10 ompt_advance_buffer_cursor_t

Summary The ompt_advance_buffer_cursor_t type is the type signature of the ompt_advance_buffer_cursor runtime entry point, which advances a trace buffer cursor to the next record.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_advance_buffer_cursor_t) ( 
  ompt_device_t *device, 
  ompt_buffer_t *buffer, 
  size_t size, 
  ompt_buffer_cursor_t current, 
  ompt_buffer_cursor_t *next 
);  

SVG-Viewer needed.

Description A device’s ompt_advance_buffer_cursor runtime entry point, which has type signature ompt_advance_buffer_cursor_t, advances a trace buffer pointer to the next trace record. An invocation of ompt_advance_buffer_cursor returns true if the advance is successful and the next position in the buffer is valid.

Description of Arguments The device argument points to an opaque object that represents the target device instance. Functions in the device tracing interface use this pointer to identify the device that is being addressed.

The buffer argument indicates a trace buffer that is associated with the cursors.

The argument size indicates the size of buffer in bytes.

The current argument is an opaque buffer cursor.

The next argument returns the next value of an opaque buffer cursor.

Cross References

4.6.2.11 ompt_get_record_type_t

Summary The ompt_get_record_type_t type is the type signature of the ompt_get_record_type runtime entry point, which inspects the type of a trace record.

Format

SVG-Viewer needed.

 

 
typedef ompt_record_t (*ompt_get_record_type_t) ( 
  ompt_buffer_t *buffer, 
  ompt_buffer_cursor_t current 
);  

SVG-Viewer needed.

Description Trace records for a device may be in one of two forms: native record format, which may be device-specific, or OMPT record format, in which each trace record corresponds to an OpenMP event and most fields in the record structure are the arguments that would be passed to the OMPT callback for the event.

A device’s ompt_get_record_type runtime entry point, which has type signature ompt_get_record_type_t, inspects the type of a trace record and indicates whether the record at the current position in the trace buffer is an OMPT record, a native record, or an invalid record. An invalid record type is returned if the cursor is out of bounds.

Description of Arguments The buffer argument indicates a trace buffer.

The current argument is an opaque buffer cursor.

Cross References

4.6.2.12 ompt_get_record_ompt_t

Summary The ompt_get_record_ompt_t type is the type signature of the ompt_get_record_ompt runtime entry point, which obtains a pointer to an OMPT trace record from a trace buffer associated with a device.

Format

SVG-Viewer needed.

 

 
typedef ompt_record_ompt_t *(*ompt_get_record_ompt_t) ( 
  ompt_buffer_t *buffer, 
  ompt_buffer_cursor_t current 
);  

SVG-Viewer needed.

Description A device’s ompt_get_record_ompt runtime entry point, which has type signature ompt_get_record_ompt_t, returns a pointer that may point to a record in the trace buffer, or it may point to a record in thread local storage in which the information extracted from a record was assembled. The information available for an event depends upon its type.

The return value of the ompt_record_ompt_t type includes a field of a union type that can represent information for any OMPT event record type. Another call to the runtime entry point may overwrite the contents of the fields in a record returned by a prior invocation.

Description of Arguments The buffer argument indicates a trace buffer.

The current argument is an opaque buffer cursor.

Cross References

4.6.2.13 ompt_get_record_native_t

Summary The ompt_get_record_native_t type is the type signature of the ompt_get_record_native runtime entry point, which obtains a pointer to a native trace record from a trace buffer associated with a device.

Format

SVG-Viewer needed.

 

 
typedef void *(*ompt_get_record_native_t) ( 
  ompt_buffer_t *buffer, 
  ompt_buffer_cursor_t current, 
  ompt_id_t *host_op_id 
);  

SVG-Viewer needed.

Description A device’s ompt_get_record_native runtime entry point, which has type signature ompt_get_record_native_t, returns a pointer that may point may point into the specified trace buffer, or into thread local storage in which the information extracted from a trace record was assembled. The information available for a native event depends upon its type. If the function returns a non-null result, it will also set the object to which host_op_id points to a host-side identifier for the operation that is associated with the record. A subsequent call to ompt_get_record_native may overwrite the contents of the fields in a record returned by a prior invocation.

Description of Arguments The buffer argument indicates a trace buffer.

The current argument is an opaque buffer cursor.

The host_op_id argument is a pointer to an identifier that is returned by the function. The entry point sets the identifier to which host_op_id points to the value of a host-side identifier for an operation on a target device that was created when the operation was initiated by the host.

Cross References

4.6.2.14 ompt_get_record_abstract_t

Summary The ompt_get_record_abstract_t type is the type signature of the ompt_get_record_abstract runtime entry point, which summarizes the context of a native (device-specific) trace record.

Format

SVG-Viewer needed.

 

 
typedef ompt_record_abstract_t *(*ompt_get_record_abstract_t) ( 
  void *native_record 
);  

SVG-Viewer needed.

Description An OpenMP implementation may execute on a device that logs trace records in a native (device-specific) format that a tool cannot interpret directly. The ompt_get_record_abstract runtime entry point of a device, which has type signature ompt_get_record_abstract_t, translates a native trace record into a standard form.

Description of Arguments The native_record argument is a pointer to a native trace record.

Cross References