[PAL] Add NPU device support for FlagCX Ascend communicator

[Joiin0392]

PR Category

PAL (Portable Abstraction Layer)

PR Types

Bug Fixes, New Features

PR Description

The FlagCX Ascend adaptor was added in commit #196 (2025-07-22) but has never been CI-tested or successfully built end-to-end. Four bugs prevent libflagcx.so from building and the torch plugin from working on Ascend 910B NPU:

1. makefiles/ascend.mk — Missing PLATFORM_EXTRA_SRCS

Commit #522 (2026-07-30) introduced the device_api/ refactor but only updated nvidia.mk. All non-NVIDIA .mk files (including ascend.mk) have empty PLATFORM_EXTRA_SRCS, causing undefined symbol: devApiBackend when loading libflagcx.so.

Fix: Add default_dev_api_backend.cc to PLATFORM_EXTRA_SRCS.

2. backend_flagcx.hpp — Wrong device name "cann" → "npu"

The Ascend adaptor sets devName = "cann", but torch_npu registers the device type as "npu" via PrivateUse1 (from v2.5.1 through v2.11.0). torch.device("cann") is not recognized by PyTorch, causing RuntimeError: Expected one of cpu, cuda, ..., privateuseone device type.

Fix: Change devName from "cann" to "npu".

3. _build_config.py — Missing CANN include path

The Ascend adaptor config only adds torch_npu's include directory, but not the CANN toolkit's include path (containing hccl.h and other essential headers). Additionally, torch_npu 2.11.0 bundles newer ACL headers (with types like aclmdlRITask) that are incompatible with CANN 8.5.1, causing compile errors.

Fix: Prepend ASCEND_HOME_PATH/$ARCH-linux/include to include_dirs before torch_npu's bundled headers. The code auto-detects architecture (x86_64-linux or aarch64-linux).

4. flagcx_wrapper.py — NPU Stream attribute access

adaptor_stream_copy() accesses old_stream.cuda_stream directly, but NPU Stream objects have npu_stream (not cuda_stream), causing AttributeError: 'Stream' object has no attribute 'cuda_stream'.

Fix: Use getattr chain: musa_stream → npu_stream → cuda_stream → 0.

Additionally, _find_default_library() now checks the installed flagcx package directory for libflagcx.so (before falling back to source tree), enabling the industry-standard pattern where .so files ship inside the Python package (like torch/torch_npu).

Testing

Environment: Ascend 910B2C x86_64 / CANN 8.5.1 / torch_npu 2.11.0

# Build
cd FlagCX
FLAGCX_ADAPTOR=ascend make
cd plugin/torch && pip install --no-build-isolation .

# Verify
python3 -c "import flagcx; print('flagcx OK')"
python3 -c "from plugin.interservice.flagcx_wrapper import FLAGCXLibrary; print('wrapper OK')"
python3 -c "import torch; print(torch.distributed.is_backend_available('flagcx'))"
# → True

Tested end-to-end with vllm-plugin-FL on Qwen3.6-35B-A3B (4-card TP=4):

• backend=flagcx (HCCL, not NCCL)
• communicator=CommunicatorFL
• Correct inference output

[CLAassistant]

All committers have signed the CLA.