General Description ¶
Interface Overview¶
The Profiling module provides the msPTI C interface to collect performance data of each module.
For details about the functions and usage examples of the msPTI API, see msPTI Tool.
Header file path: ${INSTALL_DIR}/include/mspti.
Library file path: ${INSTALL_DIR}/lib64/libmspti.so.
Replace ${INSTALL_DIR} with the path for storing the files after the CANN Toolkit is installed. For example, if the installation is performed by the root user, the path is /usr/local/Ascend/cann.
Interface List¶
APIs are listed below.
Table 1 Activity APIs
| Interface | Description |
|---|---|
| Function type | Function Description |
| msptiActivityRegisterCallbacks | Registers callback functions with MSPTI for activity buffer processing. |
| msptiActivityEnable | Profiles data of a specified activity type. |
| msptiActivityDisable | Stops profiling activity records of a specified type. |
| msptiActivityGetNextRecord | Obtains the activity record data from the activity buffer in sequence. |
| msptiActivityFlushAll | Subscribers manually flush the data recorded in the activity buffer. |
| msptiActivityFlushPeriod | Sets the execution period of flushing. |
| msptiActivityPushExternalCorrelationId | Pushes an external correlation ID for the calling thread. |
| msptiActivityPopExternalCorrelationId | Pops the external correlation ID for the calling thread. |
| msptiActivityEnableMarkerDomain | Enables the profiling for a specific domain. |
| msptiActivityDisableMarkerDomain | Disables the profiling for a specific domain. |
| Typedef type | Description |
| msptiBuffersCallbackRequestFunc | Registers the callback function with MSPTI to allocate the storage space of the activity buffer. |
| msptiBuffersCallbackCompleteFunc | Registers the callback function with MSPTI to release the data in the activity buffer. |
| Enumeration type | Enumeration description |
| msptiActivityKind | All activity types supported by MSPTI. |
| msptiActivityFlag | Activity record flag. |
| msptiActivitySourceKind | Activity data source. |
| msptiActivityMemoryOperationType | Enumeration of memory operation types. |
| msptiActivityMemoryKind | Enumeration of memory types. |
| msptiActivityMemcpyKind | Enumeration of memory copy types. |
| msptiExternalCorrelationKind | Supported types of external APIs that can be correlated. |
| msptiCommunicationDataType | Data type of the communication operator. |
| Data structure type | Data Structure Description |
| msptiActivity | Basic struct of an activity record. |
| msptiActivityApi | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_API. |
| msptiActivityHccl | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_HCCL. |
| msptiActivityKernel | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_KERNEL. |
| msptiActivityMarker | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_MARKER. |
| msptiActivityMemory | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_MEMORY. |
| msptiActivityMemset | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_MEMSET. |
| msptiActivityMemcpy | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_MEMCPY. |
| msptiActivityExternalCorrelation | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_EXTERNAL_CORRELATION. |
| msptiActivityCommunication | Struct corresponding to the activity record type MSPTI_ACTIVITY_KIND_COMMUNICATION. |
| Union type | Union Description |
| msptiObjectId | Identifies the process ID, thread ID, device ID, and stream ID of the marker. |
Activity record: NPU profiling record, which is represented by a struct, such as msptiActivityApi or msptiActivityMarker.
Activity buffer: Buffers activity record data and transfers one or more activity records from MSPTI to the client. You need to provide an empty activity buffer based on service requirements to ensure that no activity record is missing.
Table 2 Callback APIs
| API | Description |
|---|---|
| Function type | Function Description |
| msptiSubscribe | Registers callback functions with MSPTI. |
| msptiUnsubscribe | Deregisters the current subscriber from MSPTI. |
| msptiEnableCallback | Enables or disables callbacks for subscribers of specific domain and CallbackId. |
| msptiEnableDomain | Enables or disables all callbacks for subscribers of specific domain. |
| Typedef type | Description |
| msptiCallbackFunc | Callback function type. |
| msptiCallbackId | ID of the callback tracing function. |
| msptiSubscriberHandle | Handle to the subscriber. |
| Enumeration type | Enumeration description |
| msptiCallbackDomain | Callback point of an API function or CANN driver activity. |
| msptiApiCallbackSite | Callback point in an API call, for example, the start and end of the callback. |
| msptiCallbackIdRuntime | Index definition of the runtime API function. |
| msptiCallbackIdHccl | Brief definition of the communication API function index. |
| Data structure type | Data Structure Description |
| msptiCallbackData | Data to be passed to the callback function. |
Table 3 Result codes
| API | Description |
|---|---|
| Enumeration type | Enumeration description |
| msptiResult | Error and result code returned by MSPTI. |