[psiddh]

Document the version-1 hf_static I/O contract

Document HF's per-step tensor interface separately from the fixed-shape adaptation: token IDs, masks, positions and full K/V caches in; logits and those caches updated in place out. Fixed prefill/decode methods and the padding/counter protocol replace variable-length forward because HTP needs static shapes.

The contract covers metadata, absolute counters, optional returned state and runner responsibilities. The Qualcomm guide describes only hf_static and uses its dedicated CLI, with no contract selector. It preserves float-cache, guarded local-transformers-hook and CPU-only sliding-evidence boundaries. No zero-copy Python host API or measured device performance is claimed.

Review the contract, Qualcomm guide and toctree. Documentation-only. Quantized caches, sha and full-length sliding mode are excluded; inspection, adopt/fork/evict hooks remain follow-ups.

Files

docs/source/backends-qualcomm.md
docs/source/index.md
docs/source/llm-hf-static-io-contract.md

Test Plan

Commit bee5bb8fbcc1d03999046db7854d5a60af826086 on 892e50425f5a3e90ff8d3c8802fdfb31f8599518. Validated locally with Python 3.12, pinned Torch/TorchAO, the local transformers exporter branch and QAIRT SDK 2.48.

['flock', '/data/users/sidart/qnnflow/gh_prs/model-export.lock', '/data/users/sidart/qnnflow/gh_prs/venv-rebase312/bin/python', '-c', 'import torch,pytest,sys;torch.ops.load_library("/data/users/sidart/qnnflow/gh_prs/build-rebase-native-exir-test/libexir_test.so");raise SystemExit(pytest.main(sys.argv[1:]))', '-q', '-rs', 'backends/qualcomm/tests/test_hf_static.py', 'extension/llm/export/test/test_hf_static.py', 'extension/llm/io_contracts/test/test_hf_static.py', 'exir/tests/test_partitioner_transform_passes.py', 'backends/qualcomm/tests/test_output_order.py', 'backends/qualcomm/tests/test_partitioner_options.py', '--junitxml=/data/users/sidart/qnnflow/gh_prs/logs/split-pr08-python-1.xml']
97 passed, 55 subtests passed in 348.61s (0:05:48)

['flock', '/data/users/sidart/qnnflow/gh_prs/model-export.lock', '/data/users/sidart/qnnflow/gh_prs/venv-rebase312/bin/python', '-c', 'import torch,pytest,sys;torch.ops.load_library("/data/users/sidart/qnnflow/gh_prs/build-rebase-native-exir-test/libexir_test.so");raise SystemExit(pytest.main(sys.argv[1:]))', '-q', '-rs', 'backends/qualcomm/tests/test_passes.py', '--junitxml=/data/users/sidart/qnnflow/gh_prs/logs/split-pr08-python-2.xml']
56 passed, 70 subtests passed in 42.90s

['flock', '/data/users/sidart/qnnflow/gh_prs/model-export.lock', '/data/users/sidart/qnnflow/gh_prs/venv-rebase312/bin/python', '-c', 'import torch,pytest,sys;torch.ops.load_library("/data/users/sidart/qnnflow/gh_prs/build-rebase-native-exir-test/libexir_test.so");raise SystemExit(pytest.main(sys.argv[1:]))', '-q', '-rs', 'backends/qualcomm/tests/test_import_side_effects.py', '--junitxml=/data/users/sidart/qnnflow/gh_prs/logs/split-pr08-python-3.xml']
59 passed in 5.85s

['flock', '/data/users/sidart/qnnflow/gh_prs/model-export.lock', '/data/users/sidart/qnnflow/gh_prs/venv-rebase312/bin/python', '-c', 'import torch,pytest,sys;torch.ops.load_library("/data/users/sidart/qnnflow/gh_prs/build-rebase-native-exir-test/libexir_test.so");raise SystemExit(pytest.main(sys.argv[1:]))', '-q', '-rs', 'backends/qualcomm/tests/rework/passes/test_lpbq_linear_routing.py', '--junitxml=/data/users/sidart/qnnflow/gh_prs/logs/split-pr08-python-4.xml']
7 passed in 3.26s

223 runner + 7 QNN host tests passed; 2 existing runner skips; 0 failures.

cmake --build /data/users/sidart/qnnflow/gh_prs/build-split-native-top-final -j4 --target test_runner
ctest --test-dir /data/users/sidart/qnnflow/gh_prs/build-split-native-top-final -R "^test_runner$" --output-on-failure -V

The two existing runner skips are TextDecoderRunnerTest.LoadUsesMethodName and StepWithAllModels.

Pinned lint: 25 Python files clean under ufmt/flake8; 19 C++ files clean under clang-format 18.1.3; whitespace checks pass. Focused Sphinx/MyST HTML build with -W: 2 pages, no warnings. All series-owned final files and added lines have an empty forbidden-pattern grep. Independent source review found no blocking issues.

No device/physical rpcmem, two-target FCB, real-model export or full QNN device-suite result is claimed. Buck could not start because the local launcher requires a missing .buck2. The base already contains #23563 and #23183; neither is a separate prerequisite commit here.

Related PRs (review in order)

1. Partitioner: run backend-contributed edge transform passes #24566 Partitioner: run backend-contributed edge transform passes
2. Export: avoid reused lifted-constant names #24567 Export: avoid reused lifted-constant names
3. LLM runner: select I/O contracts and accept custom buffer allocators #24568 LLM runner: select I/O contracts and accept custom buffer allocators
4. QNN: construct partitioners from options and allocate LLM I/O in rpcmem #24569 QNN: construct partitioners from options and allocate LLM I/O in rpcmem
5. QNN: bind delegate outputs in exported program order #24570 QNN: bind delegate outputs in exported program order
6. Export hf_static float-cache programs and register their Python runner #24571 Export hf_static float-cache programs and register their Python runner
7. LLM runner: validate and drive hf_static float-cache programs #24572 LLM runner: validate and drive hf_static float-cache programs
8. Document the version-1 hf_static I/O contract #24573 Document the version-1 hf_static I/O contract

Each PR includes the commits of the ones above it; review only its own top commit.

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/24573

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 1 New Failure, 1 Unrelated Failure, 2 Unclassified Failures

As of commit d24a6af with merge base 765e973 ():

NEW FAILURE - The following job has failed:

• pull / test-qnn-buck-build-linux / linux-job (gh)
  RuntimeError: Command bash /__w/_temp/exec_script failed with exit code 3

UNCLASSIFIED FAILURES - DrCI could not classify the following jobs because the workflow did not run on the merge base. The failures may be pre-existing on trunk or introduced by this PR:

• Core AI / backend-tester (operators, coreai_w8a8) / test-coreai_w8a8-operators (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
  AssertionError: 24 tests failed; at most 23 allowed
• pull / test-arm-backend-docgen / linux-job (gh) (this job did not run on the merge base, so DrCI cannot tell whether the failure is pre-existing)
  RuntimeError: Command bash /__w/_temp/exec_script failed with exit code 1

BROKEN TRUNK - The following job failed but were present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

• pull / unittest / linux / linux-job (gh) (trunk failure)
  examples/models/muse-glimmer/tests/test_cuda_sequence_export_inputs.py::SequenceExportInputsTest::test_small_logits_example_preserves_token_and_embedding_capacity

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[github-actions]

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.