Pyxrt: modernize to make hw_context first-class

[thomthehound]

Problem:

pyxrt has lagged far behind the ongoing modernization of the codebase. This patch updates it to prefer hw_context and fleshes-out implementation of that path. A compatibility shim for downstream callers still using device.load_xclbin(...) is introduced with a run-time deprecation warning.

Bug / issue and how it was discovered:

Compile-time deprecation warnings for load_xclbin were introduced by #9651 and a breakage in Windows was discovered while testing #9623. The warnings were suppressed without corrective action in #9669. Those are all distal issues.

The issue at hand is that the underlying API-gap has not been addressed and pyxrt is still on a dying code path. (Incidentally, issue #9557 is also functionally addressed by this fix).

How the problem was solved, alternative solutions (if any) and why they were rejected:

The primary pyxrt path was moved to hw_context:

• add hw_context constructors for xclbin objects and xclbin paths
• expose hw_context::access_mode, cfg_param_type, add_config(), and related accessors
• add bo(hw_context, ...) bindings
• update pyxrt.pyi and binding docstrings to match the modern codebase

For compatibility, device.load_xclbin(...) is retained via C-binding shim. The shim is intentionally cordoned off so it can be removed later. It retains existing functionality.

Rejected alternatives:

• continue suppressing the deprecation warnings without change
  Rejected because this hides the problem, makes it more difficult to fix in the future, and leaves the Python bindings obsolete.

• remove device.load_xclbin(...) from Python entirely
  Rejected due to possibility of unforeseen consequences.

Risks (if any) associated with the changes in the commit:

Python.

What has been tested and how, additional testing if necessary:

Tested locally on Windows with a custom test harness (available upon request) and an mlir-aie-generated xclbin.

• XRT builds cleanly all they way through pyxrt, even without the warning suppression from Build fix on windows after https://github.com/Xilinx/XRT/pull/9651 merge #9669.
• hw_context can be constructed from both xclbin objects and xclbin paths
• kernels can be opened through hw_context
• BO allocation through hw_context works with a kernel-derived memory group

On the signed Windows runtime used for testing, the deprecated load_xclbin compatibility shim can be exercised but terminates with the expected failure at load_axlf. That is a 'success' in this case, but cannot be counted as fully "end-to-end".

Updates to the following tests should be scheduled (and can be committed upon request):

• 00_hello
• 02_simple
• 04_swizzle
• 22_verify
• 23_bandwidth

To clarify, the tests should still function, but they will no longer function if the current deprecation direction is executed to obsolescence.

Documentation impact (if any)

Docstrings and comments in pyxrt.pyi were cleaned up, docstrings concerning hw_context were added, and deprecation of load_xclbin(...) was made clear in the code. Pyxrt itself still lacks documentation (#9581).

[xrt-pr-bot]

⚠️ Authorization Failed

@thomthehound is not a repository collaborator.

To proceed:

• XRT Admins: Add the build label to authorize this PR build
• OR Add @thomthehound as a repository collaborator

[chvamshi-xilinx]

@thomthehound , Please resolve the conflicts.

[thomthehound]

@thomthehound , Please resolve the conflicts.

Done. Thank you for your time.

[github-actions]

clang-tidy made some suggestions