SIGN IN SIGN UP

DOCS: Document UCX backend initialization options (#2050)

## What?

Documents the UCX plugin's initialization options and the generic
mechanism for
overriding backend init parameters.

- `docs/BackendGuide.md`: new `#### UCX backend initialization options`
under
"Create transfer backends", where parameter passing is already
described. Adds
the option table for `ucx_error_handling_mode` (default `peer`,
alternative
`none`), then explains the lane-selection consequence and the tradeoff
of
  each value.
- `docs/python_api.md`: new `## Backend initialization parameters`
section with
the `get_plugin_params` -> override -> `create_backend` snippet,
cross-linked
  to the backend guide.

Documentation only. No functional change.

## Why?

`ucx_error_handling_mode` is exposed through
`getPluginParams`/`get_plugin_params`
but was undocumented, and its effect is easy to misread as "error
reporting only".
It also affects UCP transport lane selection: NIXL sets
`ep_params.err_mode` from
this option, and UCP only selects lanes whose transport advertises peer
failure
support. A transport that does not advertise it is excluded from `peer`
endpoints
even when it is available and faster.

ROCm IPC is the concrete case. `rocm_ipc` in UCX 1.22 reports
`error handling: none`, so it is not selected for NIXL's default `peer`
endpoints.
This is a contributing factor to the transport-selection behavior
reported in
#2039, where large ROCm VRAM RMA falls back to `software emulation |
tcp/bond0`
instead of `rocm_ipc`.

The docs deliberately do not present `none` as the fix. It restores lane
eligibility but disables the peer failure detection NIXL relies on to
move an
endpoint to its failed state and report `NIXL_ERR_REMOTE_DISCONNECT`, so
it
trades remote failure visibility for transport availability. The
guidance is to
fix lane eligibility in the transport where remote failure reporting is
needed.

Related: #2039


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Added guidance for configuring UCX backend initialization parameters
through C++ and Python APIs.
* Documented how to retrieve defaults, override settings, and create the
backend.
* Explained `ucx_error_handling_mode` options, including their effects
on transport selection and remote failure reporting.
* Added references to supported UCX configuration options and clarified
behavior for peer and disabled error-handling modes.
* Clarified how error-handling settings influence available transport
lanes and failure notifications.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Yaser Afshar <yaser.afshar@intel.com>
Y
Yaser Afshar committed
b8bbfdb62a22dc4d1aab61d2b8db8ead17730fb7
Parent: eb26be2
Committed by GitHub <noreply@github.com> on 8/13/2026, 2:52:34 PM