【Source of Change】

• Requirement
• Issue/Ticket
• Community issue
• Refactoring / Optimization
• Documentation update

This PR introduces a common architecture for managing PrivateUse1 activity profiler backends in torch_npu.

The purpose is to decouple PrivateUse1 profiler registration and session management from the existing MSPTI implementation, provide a common foundation for multiple profiler backends, and extend the NPU-specific experimental configuration mechanism.

The existing MSPTI profiling behavior is preserved. ACLprof support is introduced as a nonfunctional backend stub for future implementation.

【Modification】

The following changes are included:

1. Common profiler abstraction

Introduced NPUActivityProfiler as the common abstraction for PrivateUse1 profiler backends.

2. PrivateUse1 profiler plugin

Added NPUActivityProfilerPlugin as the backend-neutral plugin registered through:

REGISTER_PRIVATEUSE1_PROFILER

3. Backend factory

Added NPUActivityProfilerFactory to select the profiler backend for each profiling session.

Backend selection behavior:

default / empty config -> MSPTI
backend=mspti          -> MSPTI
backend=aclprof        -> ACLprof stub
invalid backend        -> MSPTI fallback

Backend selection remains explicit.

The additional profiler_level and export_type parameters do not implicitly select ACLprof.

4. Profiler session manager

Added PrivateUse1ProfilerManager as the libkineto::IActivityProfilerSession implementation responsible for delegating profiler lifecycle and trace-processing operations to the selected backend.

The resulting architecture is:

REGISTER_PRIVATEUSE1_PROFILER
    -> NPUActivityProfilerPlugin
    -> NPUActivityProfilerFactory
    -> MSPTI / ACLprof
    -> PrivateUse1ProfilerManager
    -> libkineto::IActivityProfilerSession

5. MSPTI backend integration

Refactored MsptiActivityProfiler to inherit from the common NPUActivityProfiler interface.

Existing MSPTI activity collection, callbacks, buffer handling, draining, conversion, correlation, and metadata processing are not modified by this PR.

6. ACLprof backend stub

Added an ACLprof backend stub to establish the architectural boundary for future ACLprof implementation.

The stub supports the profiler lifecycle but does not collect or convert ACLprof activities.

Current behavior:

start()        -> RECORDING
stop()         -> PROCESSING
processTrace() -> completes without device activities

When trace processing is requested, the stub emits:

ACLprof activity collection is not implemented yet

Functional ACLprof collection and export are intentionally excluded from this PR.

7. Extended NPU experimental configuration

Extended _NPUExperimentalConfig to support three optional parameters:

• backend
• profiler_level
• export_type

The existing backend-only configuration remains compatible.

Example:

from torch_npu.profiler import _NPUExperimentalConfig
from torch_npu.profiler.experimental_config import ProfilerLevel, ExportType

npu_config = _NPUExperimentalConfig(
    backend="aclprof",
    profiler_level=ProfilerLevel.Level1,
    export_type=ExportType.Db,
)

experimental_config = torch.profiler._ExperimentalConfig(
    custom_profiler_config=str(npu_config)
)

The serialized configuration is:

{"backend":"aclprof","profiler_level":"Level1","export_type":["db"]}

The configuration implementation provides:

1. Backward-compatible JSON serialization.
2. Deterministic export-type normalization.
3. Validation of supported profiler levels and export types.
4. Scalar and nonempty list support for export types.
5. Python-to-C++ configuration propagation through custom_profiler_config.
6. Per-session configuration ownership and isolation.
7. Compatibility handling for different PyTorch experimental-configuration representations.

Backend selection depends exclusively on backend.

The default backend remains MSPTI, even when profiler_level or export_type is provided without an explicit backend.

The additional configuration values are validated, parsed, and retained by the selected profiler instance. They are not applied to ACLprof collection or export in this PR.

8. Extended test coverage

Added and extended C++ and Python tests covering:

• Backend selection and fallback.
• Plugin-to-manager creation.
• Manager lifecycle and trace delegation.
• Independent sequential ACLprof stub sessions.
• NPU experimental configuration serialization.
• Profiler-level validation.
• Export-type validation and normalization.
• Backward compatibility of backend-only configuration.
• Standard PyTorch custom_profiler_config compatibility.
• Configuration ownership and session isolation.
• Invalid configuration handling.
• Pickle round-trip compatibility.
• Lazy serialization-state fallback behavior.

9. Scope limitation

This PR provides the PrivateUse1 profiler management architecture and configuration infrastructure only.

It does not implement functional ACLprof activity collection, device activity conversion, database export, or report generation.

【Documentation Changes】

No user-facing documentation changes.

This PR introduces internal profiler architecture and extends an experimental configuration helper. Functional ACLprof usage documentation is deferred until the corresponding backend implementation is available.

【Interface Changes】

No changes to stable customer-facing APIs or cross-repository interfaces are introduced.

The internal PrivateUse1 profiler architecture is extended, and the experimental Python helper _NPUExperimentalConfig now accepts optional profiler_level and export_type parameters in addition to backend.

The configuration is transferred through the existing PyTorch custom_profiler_config mechanism.

Existing backend-only configuration remains compatible:

_NPUExperimentalConfig(backend="aclprof")

The default backend remains MSPTI. ACLprof selection requires an explicit backend="aclprof".

【Functional Verification】

Linux / Ascend hardware integration

Integration validation was performed using:

PyTorch:  2.14.0.dev20260719+cpu
torch_npu: 2.14.0.dev20260719+gita58699e
CANN:     9.1.0
Platform: Linux aarch64 / Ascend NPU

The test uses the standard torch.profiler.profile() API with CPU and NPU activities, scheduled profiling, prof.step(), and a CPU trace callback.

Four configuration scenarios were executed:

All four scenarios completed without runtime errors.

The following behavior was observed:

• Profiler start and stop operations completed successfully.
• The scheduled trace callback executed successfully.
• Each scenario produced 15 CPU trace events, including 3 tagged events.
• The ACLprof scenario invoked AclprofActivityProfiler::processTrace(), confirmed by the expected stub warning.
• MSPTI scenarios completed without the ACLprof stub warning.
• Invalid profiler-level and export-type inputs were rejected as expected.

Verification limitations

The integration test confirms runtime execution of the ACLprof stub through the standard PyTorch profiling API.

MSPTI scenarios completed successfully, but runtime backend selection was not independently instrumented in those scenarios. Backend selection behavior is additionally covered by C++ unit tests.

No device activities were present in the collected traces. Therefore, full MSPTI hardware activity-collection regression is not claimed by these results.

The runtime test also does not directly inspect retained configuration values inside the C++ backend; parsing and retention are verified separately by C++ and bridge tests.

Functional ACLprof collection and DB export are outside the scope of this PR.

【CheckList】

• Code comments and error/warning logging are provided where required
• Return values, object lifetime, and null cases introduced by this change have been considered
• PR title uses the appropriate type prefix (refactor)
• Focused Python and C++ tests pass
• Ascend runtime configuration integration tests pass
• PR cumulative changed-line count is within 1,000 lines
• PR CI pipeline passes and all required code checks complete successfully