HOME
| OPENMP API Specification: Version 5.1 November 2020

4.5.2  Event Callback Signatures and Trace Records

This section describes the signatures of tool callback functions that an OMPT tool may register and that are called during runtime of an OpenMP program. An implementation may also provide a trace of events per device. Along with the callbacks, the following defines standard trace records. For the trace records, tool data arguments are replaced by an ID, which must be initialized by the OpenMP implementation. Each of parallel_id, task_id, and thread_id must be unique per target region. Tool implementations of callbacks are not required to be async signal safe.

Cross References

4.5.2.1 ompt_callback_thread_begin_t

Summary The ompt_callback_thread_begin_t type is used for callbacks that are dispatched when native threads are created.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_thread_begin_t) ( 
  ompt_thread_t thread_type, 
  ompt_data_t *thread_data 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_thread_begin_t { 
  ompt_thread_t thread_type; 
} ompt_record_thread_begin_t;  

SVG-Viewer needed.

Description of Arguments The thread_type argument indicates the type of the new thread: initial, worker, or other. The binding of the thread_data argument is the new thread.

Cross References

4.5.2.2 ompt_callback_thread_end_t

Summary The ompt_callback_thread_end_t type is used for callbacks that are dispatched when native threads are destroyed.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_thread_end_t) ( 
  ompt_data_t *thread_data 
);  

SVG-Viewer needed.

Description of Arguments The binding of the thread_data argument is the thread that will be destroyed.

Cross References

4.5.2.3 ompt_callback_parallel_begin_t

Summary The ompt_callback_parallel_begin_t type is used for callbacks that are dispatched when a parallel or teams region starts.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_parallel_begin_t) ( 
  ompt_data_t *encountering_task_data, 
  const ompt_frame_t *encountering_task_frame, 
  ompt_data_t *parallel_data, 
  unsigned int requested_parallelism, 
  int flags, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_parallel_begin_t { 
  ompt_id_t encountering_task_id; 
  ompt_id_t parallel_id; 
  unsigned int requested_parallelism; 
  int flags; 
  const void *codeptr_ra; 
} ompt_record_parallel_begin_t;  

SVG-Viewer needed.

Description of Arguments The binding of the encountering_task_data argument is the encountering task.

The encountering_task_frame argument points to the frame object that is associated with the encountering task. Accessing the frame object after the callback returned can cause a data race.

The binding of the parallel_data argument is the parallel or teams region that is beginning.

The requested_parallelism argument indicates the number of threads or teams that the user requested.

The flags argument indicates whether the code for the region is inlined into the application or invoked by the runtime and also whether the region is a parallel or teams region. Valid values for flags are a disjunction of elements in the enum ompt_parallel_flag_t.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_parallel_begin_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.4 ompt_callback_parallel_end_t

Summary The ompt_callback_parallel_end_t type is used for callbacks that are dispatched when a parallel or teams region ends.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_parallel_end_t) ( 
  ompt_data_t *parallel_data, 
  ompt_data_t *encountering_task_data, 
  int flags, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_parallel_end_t { 
  ompt_id_t parallel_id; 
  ompt_id_t encountering_task_id; 
  int flags; 
  const void *codeptr_ra; 
} ompt_record_parallel_end_t;  

SVG-Viewer needed.

Description of Arguments The binding of the parallel_data argument is the parallel or teams region that is ending.

The binding of the encountering_task_data argument is the encountering task.

The flags argument indicates whether the execution of the region is inlined into the application or invoked by the runtime and also whether it is a parallel or teams region. Values for flags are a disjunction of elements in the enum ompt_parallel_flag_t.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_parallel_end_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.5 ompt_callback_work_t

Summary The ompt_callback_work_t type is used for callbacks that are dispatched when worksharing regions, loop-related regions, taskloop regions and scope regions begin and end.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_work_t) ( 
  ompt_work_t wstype, 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *parallel_data, 
  ompt_data_t *task_data, 
  uint64_t count, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_work_t { 
  ompt_work_t wstype; 
  ompt_scope_endpoint_t endpoint; 
  ompt_id_t parallel_id; 
  ompt_id_t task_id; 
  uint64_t count; 
  const void *codeptr_ra; 
} ompt_record_work_t;  

SVG-Viewer needed.

Description of Arguments The wstype argument indicates the kind of region.

The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The binding of the parallel_data argument is the current parallel region.

The binding of the task_data argument is the current task.

The count argument is a measure of the quantity of work involved in the construct. For a worksharing-loop or taskloop construct, count represents the number of iterations in the iteration space, which may be the result of collapsing several associated loops. For a sections construct, count represents the number of sections. For a workshare construct, count represents the units of work, as defined by the workshare construct. For a single or scope construct, count is always 1. When the endpoint argument signals the end of a scope, a count value of 0 indicates that the actual count value is not available.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_work_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.6 ompt_callback_dispatch_t

Summary The ompt_callback_dispatch_t type is used for callbacks that are dispatched when a thread begins to execute a section or loop iteration.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_dispatch_t) ( 
  ompt_data_t *parallel_data, 
  ompt_data_t *task_data, 
  ompt_dispatch_t kind, 
  ompt_data_t instance 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_dispatch_t { 
  ompt_id_t parallel_id; 
  ompt_id_t task_id; 
  ompt_dispatch_t kind; 
  ompt_data_t instance; 
} ompt_record_dispatch_t;  

SVG-Viewer needed.

Description of Arguments The binding of the parallel_data argument is the current parallel region.

The binding of the task_data argument is the implicit task that executes the structured block of the parallel region.

The kind argument indicates whether a loop iteration or a section is being dispatched.

For a loop iteration, the instance.value argument contains the logical iteration number. For a structured block in the sections construct, instance.ptr contains a code address that identifies the structured block. In cases where a runtime routine implements the structured block associated with this callback, instance.ptr contains the return address of the call to the runtime routine. In cases where the implementation of the structured block is inlined, instance.ptr contains the return address of the invocation of this callback.

Cross References

4.5.2.7 ompt_callback_task_create_t

Summary The ompt_callback_task_create_t type is used for callbacks that are dispatched when task regions are generated.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_task_create_t) ( 
  ompt_data_t *encountering_task_data, 
  const ompt_frame_t *encountering_task_frame, 
  ompt_data_t *new_task_data, 
  int flags, 
  int has_dependences, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_task_create_t { 
  ompt_id_t encountering_task_id; 
  ompt_id_t new_task_id; 
  int flags; 
  int has_dependences; 
  const void *codeptr_ra; 
} ompt_record_task_create_t;  

SVG-Viewer needed.

Description of Arguments The binding of the encountering_task_data argument is the encountering task.

The encountering_task_frame argument points to the frame object associated with the encountering task. Accessing the frame object after the callback returned can cause a data race.

The binding of the new_task_data argument is the generated task.

The flags argument indicates the kind of task (explicit or target) that is generated. Values for flags are a disjunction of elements in the ompt_task_flag_t enumeration type.

The has_dependences argument is true if the generated task has dependences and false otherwise.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_task_create_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.8 ompt_callback_dependences_t

Summary The ompt_callback_dependences_t type is used for callbacks that are related to dependences and that are dispatched when new tasks are generated and when ordered constructs are encountered.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_dependences_t) ( 
  ompt_data_t *task_data, 
  const ompt_dependence_t *deps, 
  int ndeps 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_dependences_t { 
  ompt_id_t task_id; 
  ompt_dependence_t dep; 
  int ndeps; 
} ompt_record_dependences_t;  

SVG-Viewer needed.

Description of Arguments The binding of the task_data argument is the generated task for a depend clause on a task construct, the target task for a depend clause on a target construct respectively depend object in an asynchronous runtime routine, or the encountering implicit task for a depend clause of the ordered construct.

The deps argument lists dependences of the new task or the dependence vector of the ordered construct. Dependences denoted with dependency objects are described in terms of their dependency semantics.

The ndeps argument specifies the length of the list passed by the deps argument. The memory for deps is owned by the caller; the tool cannot rely on the data after the callback returns.

The performance monitor interface for tracing activity on target devices provides one record per dependence.

Cross References

4.5.2.9 ompt_callback_task_dependence_t

Summary The ompt_callback_task_dependence_t type is used for callbacks that are dispatched when unfulfilled task dependences are encountered.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_task_dependence_t) ( 
  ompt_data_t *src_task_data, 
  ompt_data_t *sink_task_data 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_task_dependence_t { 
  ompt_id_t src_task_id; 
  ompt_id_t sink_task_id; 
} ompt_record_task_dependence_t;  

SVG-Viewer needed.

Description of Arguments The binding of the src_task_data argument is a running task with an outgoing dependence.

The binding of the sink_task_data argument is a task with an unsatisfied incoming dependence.

Cross References

4.5.2.10 ompt_callback_task_schedule_t

Summary The ompt_callback_task_schedule_t type is used for callbacks that are dispatched when task scheduling decisions are made.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_task_schedule_t) ( 
  ompt_data_t *prior_task_data, 
  ompt_task_status_t prior_task_status, 
  ompt_data_t *next_task_data 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_task_schedule_t { 
  ompt_id_t prior_task_id; 
  ompt_task_status_t prior_task_status; 
  ompt_id_t next_task_id; 
} ompt_record_task_schedule_t;  

SVG-Viewer needed.

Description of Arguments The prior_task_status argument indicates the status of the task that arrived at a task scheduling point.

The binding of the prior_task_data argument is the task that arrived at the scheduling point.

The binding of the next_task_data argument is the task that is resumed at the scheduling point. This argument is NULL if the callback is dispatched for a task-fulfill event or if the callback signals completion of a taskwait construct.

Cross References

4.5.2.11 ompt_callback_implicit_task_t

Summary The ompt_callback_implicit_task_t type is used for callbacks that are dispatched when initial tasks and implicit tasks are generated and completed.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_implicit_task_t) ( 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *parallel_data, 
  ompt_data_t *task_data, 
  unsigned int actual_parallelism, 
  unsigned int index, 
  int flags 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_implicit_task_t { 
  ompt_scope_endpoint_t endpoint; 
  ompt_id_t parallel_id; 
  ompt_id_t task_id; 
  unsigned int actual_parallelism; 
  unsigned int index; 
  int flags; 
} ompt_record_implicit_task_t;  

SVG-Viewer needed.

Description of Arguments The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The binding of the parallel_data argument is the current parallel or teams region. For the implicit-task-end and the initial-task-end events, this argument is NULL.

The binding of the task_data argument is the implicit task that executes the structured block of the parallel or teams region.

The actual_parallelism argument indicates the number of threads in the parallel region or the number of teams in the teams region. For initial tasks, that are not closely nested in a teams construct, this argument is 1. For the implicit-task-end and the initial-task-end events, this argument is 0.

The index argument indicates the thread number or team number of the calling thread, within the team or league that is executing the parallel or teams region to which the implicit task region binds. For initial tasks, that are not created by a teams construct, this argument is 1.

The flags argument indicates the kind of task (initial or implicit).

Cross References

4.5.2.12 ompt_callback_masked_t

Summary The ompt_callback_masked_t type is used for callbacks that are dispatched when masked regions start and end.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_masked_t) ( 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *parallel_data, 
  ompt_data_t *task_data, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_masked_t { 
  ompt_scope_endpoint_t endpoint; 
  ompt_id_t parallel_id; 
  ompt_id_t task_id; 
  const void *codeptr_ra; 
} ompt_record_masked_t;  

SVG-Viewer needed.

Description of Arguments The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The binding of the parallel_data argument is the current parallel region.

The binding of the task_data argument is the encountering task.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_masked_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.13 ompt_callback_sync_region_t

Summary The ompt_callback_sync_region_t type is used for callbacks that are dispatched when barrier regions, taskwait regions, and taskgroup regions begin and end and when waiting begins and ends for them as well as for when reductions are performed.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_sync_region_t) ( 
  ompt_sync_region_t kind, 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *parallel_data, 
  ompt_data_t *task_data, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_sync_region_t { 
  ompt_sync_region_t kind; 
  ompt_scope_endpoint_t endpoint; 
  ompt_id_t parallel_id; 
  ompt_id_t task_id; 
  const void *codeptr_ra; 
} ompt_record_sync_region_t;  

SVG-Viewer needed.

Description of Arguments The kind argument indicates the kind of synchronization.

The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The binding of the parallel_data argument is the current parallel region. For the barrier-end event at the end of a parallel region this argument is NULL.

The binding of the task_data argument is the current task.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_sync_region_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.14 ompt_callback_mutex_acquire_t

Summary The ompt_callback_mutex_acquire_t type is used for callbacks that are dispatched when locks are initialized, acquired and tested and when critical regions, atomic regions, and ordered regions are begun.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_mutex_acquire_t) ( 
  ompt_mutex_t kind, 
  unsigned int hint, 
  unsigned int impl, 
  ompt_wait_id_t wait_id, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_mutex_acquire_t { 
  ompt_mutex_t kind; 
  unsigned int hint; 
  unsigned int impl; 
  ompt_wait_id_t wait_id; 
  const void *codeptr_ra; 
} ompt_record_mutex_acquire_t;  

SVG-Viewer needed.

Description of Arguments The kind argument indicates the kind of mutual exclusion event.

The hint argument indicates the hint that was provided when initializing an implementation of mutual exclusion. If no hint is available when a thread initiates acquisition of mutual exclusion, the runtime may supply omp_sync_hint_none as the value for hint.

The impl argument indicates the mechanism chosen by the runtime to implement the mutual exclusion.

The wait_id argument indicates the object being awaited.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_mutex_acquire_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.15 ompt_callback_mutex_t

Summary The ompt_callback_mutex_t type is used for callbacks that indicate important synchronization events.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_mutex_t) ( 
  ompt_mutex_t kind, 
  ompt_wait_id_t wait_id, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_mutex_t { 
  ompt_mutex_t kind; 
  ompt_wait_id_t wait_id; 
  const void *codeptr_ra; 
} ompt_record_mutex_t;  

SVG-Viewer needed.

Description of Arguments The kind argument indicates the kind of mutual exclusion event.

The wait_id argument indicates the object being awaited.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_mutex_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.16 ompt_callback_nest_lock_t

Summary The ompt_callback_nest_lock_t type is used for callbacks that indicate that a thread that owns a nested lock has performed an action related to the lock but has not relinquished ownership of it.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_nest_lock_t) ( 
  ompt_scope_endpoint_t endpoint, 
  ompt_wait_id_t wait_id, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_nest_lock_t { 
  ompt_scope_endpoint_t endpoint; 
  ompt_wait_id_t wait_id; 
  const void *codeptr_ra; 
} ompt_record_nest_lock_t;  

SVG-Viewer needed.

Description of Arguments The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The wait_id argument indicates the object being awaited.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_nest_lock_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.17 ompt_callback_flush_t

Summary The ompt_callback_flush_t type is used for callbacks that are dispatched when flush constructs are encountered.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_flush_t) ( 
  ompt_data_t *thread_data, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_flush_t { 
  const void *codeptr_ra; 
} ompt_record_flush_t;  

SVG-Viewer needed.

Description of Arguments The binding of the thread_data argument is the executing thread.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_flush_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.18 ompt_callback_cancel_t

Summary The ompt_callback_cancel_t type is used for callbacks that are dispatched for cancellation, cancel and discarded-task events.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_cancel_t) ( 
  ompt_data_t *task_data, 
  int flags, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_cancel_t { 
  ompt_id_t task_id; 
  int flags; 
  const void *codeptr_ra; 
} ompt_record_cancel_t;  

SVG-Viewer needed.

Description of Arguments The binding of the task_data argument is the task that encounters a cancel construct, a cancellation point construct, or a construct defined as having an implicit cancellation point.

The flags argument, defined by the ompt_cancel_flag_t enumeration type, indicates whether cancellation is activated by the current task, or detected as being activated by another task. The construct that is being canceled is also described in the flags argument. When several constructs are detected as being concurrently canceled, each corresponding bit in the argument will be set.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_cancel_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References

4.5.2.19 ompt_callback_device_initialize_t

Summary The ompt_callback_device_initialize_t type is used for callbacks that initialize device tracing interfaces.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_device_initialize_t) ( 
  int device_num, 
  const char *type, 
  ompt_device_t *device, 
  ompt_function_lookup_t lookup, 
  const char *documentation 
);  

SVG-Viewer needed.

Description Registration of a callback with type signature ompt_callback_device_initialize_t for the ompt_callback_device_initialize event enables asynchronous collection of a trace for a device. The OpenMP implementation invokes this callback after OpenMP is initialized for the device but before execution of any OpenMP construct is started on the device.

Description of Arguments The device_num argument identifies the logical device that is being initialized.

The type argument is a character string that indicates the type of the device. A device type string is a semicolon-separated character string that includes at a minimum the vendor and model name of the device. These names may be followed by a semicolon-separated sequence of properties that describe the hardware or software of the device.

The device argument is a pointer 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 lookup argument points to a runtime callback that a tool must use to obtain pointers to runtime entry points in the device’s OMPT tracing interface. If a device does not support tracing then lookup is NULL.

The documentation argument is a string that describes how to use any device-specific runtime entry points that can be obtained through the lookup argument. This documentation string may be a pointer to external documentation, or it may be inline descriptions that include names and type signatures for any device-specific interfaces that are available through the lookup argument along with descriptions of how to use these interface functions to control monitoring and analysis of device traces.

Constraints on Arguments The type and documentation arguments must be immutable strings that are defined for the lifetime of program execution.

Effect A device initializer must fulfill several duties. First, the type argument should be used to determine if any special knowledge about the hardware and/or software of a device is employed. Second, the lookup argument should be used to look up pointers to runtime entry points in the OMPT tracing interface for the device. Finally, these runtime entry points should be used to set up tracing for the device.

Initialization of tracing for a target device is described in Section 4.2.5.

Cross References

4.5.2.20 ompt_callback_device_finalize_t

Summary The ompt_callback_device_initialize_t type is used for callbacks that finalize device tracing interfaces.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_device_finalize_t) ( 
  int device_num 
);  

SVG-Viewer needed.

Description of Arguments The device_num argument identifies the logical device that is being finalized.

Description A registered callback with type signature ompt_callback_device_finalize_t is dispatched for a device immediately prior to finalizing the device. Prior to dispatching a finalization callback for a device on which tracing is active, the OpenMP implementation stops tracing on the device and synchronously flushes all trace records for the device that have not yet been reported. These trace records are flushed through one or more buffer completion callbacks with type signature ompt_callback_buffer_complete_t as needed prior to the dispatch of the callback with type signature ompt_callback_device_finalize_t.

Cross References

4.5.2.21 ompt_callback_device_load_t

Summary The ompt_callback_device_load_t type is used for callbacks that the OpenMP runtime invokes to indicate that it has just loaded code onto the specified device.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_device_load_t) ( 
  int device_num, 
  const char *filename, 
  int64_t offset_in_file, 
  void *vma_in_file, 
  size_t bytes, 
  void *host_addr, 
  void *device_addr, 
  uint64_t module_id 
);  

SVG-Viewer needed.

Description of Arguments The device_num argument specifies the device.

The filename argument indicates the name of a file in which the device code can be found. A NULL filename indicates that the code is not available in a file in the file system.

The offset_in_file argument indicates an offset into filename at which the code can be found. A value of -1 indicates that no offset is provided.

ompt_addr_none is defined as a pointer with the value ~0.

The vma_in_file argument indicates a virtual address in filename at which the code can be found. A value of ompt_addr_none indicates that a virtual address in the file is not available.

The bytes argument indicates the size of the device code object in bytes.

The host_addr argument indicates the address at which a copy of the device code is available in host memory. A value of ompt_addr_none indicates that a host code address is not available.

The device_addr argument indicates the address at which the device code has been loaded in device memory. A value of ompt_addr_none indicates that a device code address is not available.

The module_id argument is an identifier that is associated with the device code object.

Cross References

4.5.2.22 ompt_callback_device_unload_t

Summary The ompt_callback_device_unload_t type is used for callbacks that the OpenMP runtime invokes to indicate that it is about to unload code from the specified device.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_device_unload_t) ( 
  int device_num, 
  uint64_t module_id 
);  

SVG-Viewer needed.

Description of Arguments The device_num argument specifies the device.

The module_id argument is an identifier that is associated with the device code object.

Cross References

4.5.2.23 ompt_callback_buffer_request_t

Summary The ompt_callback_buffer_request_t type is used for callbacks that are dispatched when a buffer to store event records for a device is requested.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_buffer_request_t) ( 
  int device_num, 
  ompt_buffer_t **buffer, 
  size_t *bytes 
);  

SVG-Viewer needed.

Description A callback with type signature ompt_callback_buffer_request_t requests a buffer to store trace records for the specified device. A buffer request callback may set *bytes to 0 if it does not provide a buffer. If a callback sets *bytes to 0, further recording of events for the device is disabled until the next invocation of ompt_start_trace. This action causes the device to drop future trace records until recording is restarted.

Description of Arguments The device_num argument specifies the device.

The *buffer argument points to a buffer where device events may be recorded. The *bytes argument indicates the length of that buffer.

Cross References

4.5.2.24 ompt_callback_buffer_complete_t

Summary The ompt_callback_buffer_complete_t type is used for callbacks that are dispatched when devices will not record any more trace records in an event buffer and all records written to the buffer are valid.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_buffer_complete_t) ( 
  int device_num, 
  ompt_buffer_t *buffer, 
  size_t bytes, 
  ompt_buffer_cursor_t begin, 
  int buffer_owned 
);  

SVG-Viewer needed.

Description A callback with type signature ompt_callback_buffer_complete_t provides a buffer that contains trace records for the specified device. Typically, a tool will iterate through the records in the buffer and process them.

The OpenMP implementation makes these callbacks on a thread that is not an OpenMP primary or worker thread.

The callee may not delete the buffer if the buffer_owned argument is 0.

The buffer completion callback is not required to be async signal safe.

Description of Arguments The device_num argument indicates the device for which the buffer contains events.

The buffer argument is the address of a buffer that was previously allocated by a buffer request callback.

The bytes argument indicates the full size of the buffer.

The begin argument is an opaque cursor that indicates the position of the beginning of the first record in the buffer.

The buffer_owned argument is 1 if the data to which the buffer points can be deleted by the callback and 0 otherwise. If multiple devices accumulate trace events into a single buffer, this callback may be invoked with a pointer to one or more trace records in a shared buffer with buffer_owned = 0. In this case, the callback may not delete the buffer.

Cross References

4.5.2.25 ompt_callback_target_data_op_emi_t and
ompt_callback_target_data_op_t

Summary Theompt_callback_target_data_op_emi_t and ompt_callback_target_data_op_t types are used for callbacks that are dispatched when a thread maps data to a device.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_target_data_op_emi_t) ( 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *target_task_data, 
  ompt_data_t *target_data, 
  ompt_id_t *host_op_id, 
  ompt_target_data_op_t optype, 
  void *src_addr, 
  int src_device_num, 
  void *dest_addr, 
  int dest_device_num, 
  size_t bytes, 
  const void *codeptr_ra 
);  
 
typedef void (*ompt_callback_target_data_op_t) ( 
  ompt_id_t target_id, 
  ompt_id_t host_op_id, 
  ompt_target_data_op_t optype, 
  void *src_addr, 
  int src_device_num, 
  void *dest_addr, 
  int dest_device_num, 
  size_t bytes, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_target_data_op_t { 
  ompt_id_t host_op_id; 
  ompt_target_data_op_t optype; 
  void *src_addr; 
  int src_device_num; 
  void *dest_addr; 
  int dest_device_num; 
  size_t bytes; 
  ompt_device_time_t end_time; 
  const void *codeptr_ra; 
} ompt_record_target_data_op_t;  

SVG-Viewer needed.

Description A thread dispatches a registered ompt_callback_target_data_op_emi or ompt_callback_target_data_op callback when device memory is allocated or freed, as well as when data is copied to or from a device.

SVG-Viewer needed.

Note – An OpenMP implementation may aggregate program variables and data operations upon them. For instance, an OpenMP implementation may synthesize a composite to represent multiple scalars and then allocate, free, or copy this composite as a whole rather than performing data operations on each scalar individually. Thus, callbacks may not be dispatched as separate data operations on each variable.

SVG-Viewer needed.

Description of Arguments The endpoint argument indicates that the callback signals the beginning or end of a scope.

The binding of the target_task_data argument is the target task region.

The binding of the target_data argument is the target region.

The host_op_id argument points to a tool controlled integer value, which identifies a data operation on a target device.

The optype argument indicates the kind of data operation.

The src_addr argument indicates the data address before the operation, where applicable.

The src_device_num argument indicates the source device number for the data operation, where applicable.

The dest_addr argument indicates the data address after the operation.

The dest_device_num argument indicates the destination device number for the data operation.

Whether in some operations src_addr or dest_addr may point to an intermediate buffer is implementation defined.

The bytes argument indicates the size of data.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_target_data_op_emi_t or ompt_callback_target_data_op_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Restrictions Restrictions to the ompt_callback_target_data_op_emi and ompt_callback_target_data_op callbacks are as follows:

Cross References

4.5.2.26 ompt_callback_target_emi_t and
ompt_callback_target_t

Summary The ompt_callback_target_emi_t and ompt_callback_target_t types are used for callbacks that are dispatched when a thread begins to execute a device construct.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_target_emi_t) ( 
  ompt_target_t kind, 
  ompt_scope_endpoint_t endpoint, 
  int device_num, 
  ompt_data_t *task_data, 
  ompt_data_t *target_task_data, 
  ompt_data_t *target_data, 
  const void *codeptr_ra 
);  
 
typedef void (*ompt_callback_target_t) ( 
  ompt_target_t kind, 
  ompt_scope_endpoint_t endpoint, 
  int device_num, 
  ompt_data_t *task_data, 
  ompt_id_t target_id, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_target_t { 
  ompt_target_t kind; 
  ompt_scope_endpoint_t endpoint; 
  int device_num; 
  ompt_id_t task_id; 
  ompt_id_t target_id; 
  const void *codeptr_ra; 
} ompt_record_target_t;  

SVG-Viewer needed.

Description of Arguments The kind argument indicates the kind of target region.

The endpoint argument indicates that the callback signals the beginning of a scope or the end of a scope.

The device_num argument indicates the device number of the device that will execute the target region.

The binding of the task_data argument is the generating task.

The binding of the target_task_data argument is the target region.

The binding of the target_data argument is the target region.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_target_emi_t or ompt_callback_target_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Restrictions Restrictions to the ompt_callback_target_emi and ompt_callback_target callbacks are as follows:

Cross References

4.5.2.27 ompt_callback_target_map_emi_t and
ompt_callback_target_map_t

Summary The ompt_callback_target_map_emi_t and ompt_callback_target_map_t types are used for callbacks that are dispatched to indicate data mapping relationships.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_target_map_emi_t) ( 
  ompt_data_t *target_data, 
  unsigned int nitems, 
  void **host_addr, 
  void **device_addr, 
  size_t *bytes, 
  unsigned int *mapping_flags, 
  const void *codeptr_ra 
);  
 
typedef void (*ompt_callback_target_map_t) ( 
  ompt_id_t target_id, 
  unsigned int nitems, 
  void **host_addr, 
  void **device_addr, 
  size_t *bytes, 
  unsigned int *mapping_flags, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_target_map_t { 
  ompt_id_t target_id; 
  unsigned int nitems; 
  void **host_addr; 
  void **device_addr; 
  size_t *bytes; 
  unsigned int *mapping_flags; 
  const void *codeptr_ra; 
} ompt_record_target_map_t;  

SVG-Viewer needed.

Description An instance of a target, target data, target enter data, or target exit data construct may contain one or more map clauses. An OpenMP implementation may report the set of mappings associated with map clauses for a construct with a single ompt_callback_target_map_emi or ompt_callback_target_map callback to report the effect of all mappings or multiple ompt_callback_target_map_emi or ompt_callback_target_map callbacks with each reporting a subset of the mappings. Furthermore, an OpenMP implementation may omit mappings that it determines are unnecessary. If an OpenMP implementation issues multiple ompt_callback_target_map_emi or ompt_callback_target_map callbacks, these callbacks may be interleaved with ompt_callback_target_data_op_emi or ompt_callback_target_data_op callbacks used to report data operations associated with the mappings.

Description of Arguments The binding of the target_data argument is the target region.

The nitems argument indicates the number of data mappings that this callback reports.

The host_addr argument indicates an array of host data addresses.

The device_addr argument indicates an array of device data addresses.

The bytes argument indicates an array of sizes of data.

The mapping_flags argument indicates the kind of data mapping. Flags for a mapping include one or more values specified by the ompt_target_map_flag_t type.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_target_map_t or ompt_callback_target_map_emi_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Restrictions Restrictions to the ompt_callback_target_data_map_emi and ompt_callback_target_data_map callbacks are as follows:

Cross References

4.5.2.28 ompt_callback_target_submit_emi_t and
ompt_callback_target_submit_t

Summary The ompt_callback_target_submit_emi_t and ompt_callback_target_submit_t types are used for callbacks that are dispatched before and after the host initiates creation of an initial task on a device.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_target_submit_emi_t) ( 
  ompt_scope_endpoint_t endpoint, 
  ompt_data_t *target_data, 
  ompt_id_t *host_op_id, 
  unsigned int requested_num_teams 
);  
 
typedef void (*ompt_callback_target_submit_t) ( 
  ompt_id_t target_id, 
  ompt_id_t host_op_id, 
  unsigned int requested_num_teams 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_target_kernel_t { 
  ompt_id_t host_op_id; 
  unsigned int requested_num_teams; 
  unsigned int granted_num_teams; 
  ompt_device_time_t end_time; 
} ompt_record_target_kernel_t;  

SVG-Viewer needed.

Description A thread dispatches a registered ompt_callback_target_submit_emi or ompt_callback_target_submit callback on the host before and after a target task initiates creation of an initial task on a device.

Description of Arguments The endpoint argument indicates that the callback signals the beginning or end of a scope.

The binding of the target_data argument is the target region.

The host_op_id argument points to a tool controlled integer value, which identifies an initial task on a target device.

The requested_num_teams argument is the number of teams that the host requested to execute the kernel. The actual number of teams that execute the kernel may be smaller and generally will not be known until the kernel begins to execute on the device.

If ompt_set_trace_ompt has configured the device to trace kernel execution then the device will log a ompt_record_target_kernel_t record in a trace. The fields in the record are as follows:

Restrictions Restrictions to the ompt_callback_target_submit_emi and ompt_callback_target_submit callbacks are as follows:

Cross References

4.5.2.29 ompt_callback_control_tool_t

Summary The ompt_callback_control_tool_t type is used for callbacks that dispatch tool-control events.

Format

SVG-Viewer needed.

 

 
typedef int (*ompt_callback_control_tool_t) ( 
  uint64_t command, 
  uint64_t modifier, 
  void *arg, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_control_tool_t { 
  uint64_t command; 
  uint64_t modifier; 
  const void *codeptr_ra; 
} ompt_record_control_tool_t;  

SVG-Viewer needed.

Description Callbacks with type signature ompt_callback_control_tool_t may return any non-negative value, which will be returned to the application as the return value of the omp_control_tool call that triggered the callback.

Description of Arguments The command argument passes a command from an application to a tool. Standard values for command are defined by omp_control_tool_t in Section 3.14.

The modifier argument passes a command modifier from an application to a tool.

The command and modifier arguments may have tool-specific values. Tools must ignore command values that they are not designed to handle.

The arg argument is a void pointer that enables a tool and an application to exchange arbitrary state. The arg argument may be NULL.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_control_tool_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Constraints on Arguments Tool-specific values for command must be 64.

Cross References

4.5.2.30 ompt_callback_error_t

Summary The ompt_callback_error_t type is used for callbacks that dispatch runtime-error events.

Format

SVG-Viewer needed.

 

 
typedef void (*ompt_callback_error_t) ( 
  ompt_severity_t severity, 
  const char *message, 
  size_t length, 
  const void *codeptr_ra 
);  

SVG-Viewer needed.

Trace Record

SVG-Viewer needed.

 

 
typedef struct ompt_record_error_t { 
  ompt_severity_t severity; 
  const char *message; 
  size_t length; 
  const void *codeptr_ra; 
} ompt_record_error_t;  

SVG-Viewer needed.

Description A thread dispatches a registered ompt_callback_error_t callback when an error directive is encountered for which the at(execution) clause is specified.

Description of Arguments The severity argument passes the specified severity level.

The message argument passes the string from the message clause.

The length argument provides the length of the string.

The codeptr_ra argument relates the implementation of an OpenMP region to its source code. If a runtime routine implements the region associated with a callback that has type signature ompt_callback_error_t then codeptr_ra contains the return address of the call to that runtime routine. If the implementation of the region is inlined then codeptr_ra contains the return address of the invocation of the callback. If attribution to source code is impossible or inappropriate, codeptr_ra may be NULL.

Cross References