Add external JIT mixed dispatch and include paths

[ChaoWao]

Summary

• add optional dual-AIV dispatch for mixed pl.jit.extern kernels
• preserve signature-only external kernels through vector splitting and all-external codegen
• resolve ordered include_dirs relative to the extern stub and forward them to CCEC
• fingerprint sources, reachable headers, launch metadata, and target identity in the external binary cache

Testing

• 60 passed across focused codegen, IR, JIT, backend, and runtime unit tests
• ruff check and ruff format --check
• pyright (0 errors)
• downstream Qwen3 CCEC attention passed B1 and true-B16 a2a3 hardware validation

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds dual_aiv_dispatch support for mixed external kernels, preserves external declarations during IR splitting, fingerprints recursive source dependencies for caching, avoids external sidecar binaries, emits manifests for all-external graphs, and updates documentation and tests.

Changes

External kernel source hashing and caching

Layer / File(s)	Summary
Source fingerprinting and kernel caching python/pypto/_external_source.py, python/pypto/jit/decorator.py, python/pypto/runtime/device_runner.py, tests/ut/runtime/test_external_kernel_cache.py	External source digests include resolved includes, file bytes, metadata, compiler inputs, and platform details. External compilation bypasses adjacent sidecars and uses content-addressed cache files.

Dual-AIV dispatch propagation

Layer / File(s)	Summary
Dual-AIV dispatch propagation python/pypto/jit/decorator.py, python/pypto/jit/specializer.py, src/ir/transforms/split_vector_kernel_pass.cpp, src/codegen/orchestration/orchestration_codegen.cpp, docs/en/dev/language/01-external-kernels.md, docs/zh-cn/dev/language/01-external-kernels.md, tests/ut/jit/test_extern_kernel.py, tests/ut/ir/transforms/test_split_vector_kernel.py	Mixed external kernels accept and propagate dual_aiv_dispatch, while IR splitting preserves signature-only external bodies and dispatch attributes. Documentation and tests cover validation, hashing, and AIV sub-block behavior.

External manifest emission

Layer / File(s)	Summary
External kernel manifest emission python/pypto/backend/pto_backend.py, tests/ut/codegen/test_external_kernel.py	Generated kernel configuration marks external entries and is emitted when an orchestration graph contains only external kernels, including when PTOAS generation is skipped.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UserCode
  participant ExternDecorator
  participant Specializer
  participant SplitVectorKernel
  participant PTOBackend
  participant DeviceRunner

  UserCode->>ExternDecorator: declare mixed external kernel
  ExternDecorator->>Specializer: pass dual_aiv_dispatch
  Specializer->>SplitVectorKernel: emit external AIV attributes
  SplitVectorKernel->>PTOBackend: preserve external declarations
  PTOBackend->>DeviceRunner: provide external kernel configuration
  DeviceRunner->>DeviceRunner: hash sources and compile or load cache

Loading

Possibly related PRs

• hw-native-sys/pypto#1955: Updates the same external-kernel decorator, specialization, and backend plumbing extended here.

Suggested labels: enhancement

Poem

A bunny hops where AIV lanes gleam,
Two little launches race through the stream.
Headers are hashed, stale sidecars flee,
Manifests bloom by the kernel tree.
“Split by your sub-block!” the rabbit cheers,
While cached binaries hop between gears.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.59% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly reflects the main changes: external JIT mixed dispatch and include path handling.
Description check	✅ Passed	The description is directly related to the changeset and summarizes the key implementation and testing updates.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request introduces support for dual AIV dispatch (dual_aiv_dispatch=True) in mixed external kernels, updating the JIT compiler, IR transforms, codegen, and runtime to handle this option. It also implements a content-addressed caching mechanism for external CCEC binaries by hashing source files and their include closures. The review feedback highlights a critical issue where hashing absolute paths (such as pto_isa_root, include_dirs, and resolved source/include paths) in the cache fingerprint makes the compiled kernel cache non-relocatable across different environments or CI/CD runners, and suggests using relative paths or omitting absolute paths from the digest.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

🧹 Nitpick comments (1)

docs/en/dev/language/01-external-kernels.md (1)

112-121: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document the @pl.program equivalent for dual dispatch.

This option is shown only for @pl.jit.extern. For direct @pl.function(external_source=...) users, add a short example or cross-reference showing attrs={"dual_aiv_dispatch": True} on the AIV member, as exercised by tests/ut/ir/transforms/test_split_vector_kernel.py.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/en/dev/language/01-external-kernels.md` around lines 112 - 121, Document
the direct `@pl.function`(external_source=...) equivalent for dual dispatch
alongside the existing `@pl.jit.extern` guidance. Add a concise example or
cross-reference showing attrs={"dual_aiv_dispatch": True} on the AIV member,
matching the usage covered by test_split_vector_kernel.py.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/en/dev/language/01-external-kernels.md`:
- Around line 112-121: Document the direct `@pl.function`(external_source=...)
equivalent for dual dispatch alongside the existing `@pl.jit.extern` guidance. Add
a concise example or cross-reference showing attrs={"dual_aiv_dispatch": True}
on the AIV member, matching the usage covered by test_split_vector_kernel.py.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a35a7d92-a9e0-4844-82c1-2fbfe8a27fee

📥 Commits

Reviewing files that changed from the base of the PR and between 8ebddcb and a2c8f80.

📒 Files selected for processing (13)

• docs/en/dev/language/01-external-kernels.md
• docs/zh-cn/dev/language/01-external-kernels.md
• python/pypto/_external_source.py
• python/pypto/backend/pto_backend.py
• python/pypto/jit/decorator.py
• python/pypto/jit/specializer.py
• python/pypto/runtime/device_runner.py
• src/codegen/orchestration/orchestration_codegen.cpp
• src/ir/transforms/split_vector_kernel_pass.cpp
• tests/ut/codegen/test_external_kernel.py
• tests/ut/ir/transforms/test_split_vector_kernel.py
• tests/ut/jit/test_extern_kernel.py
• tests/ut/runtime/test_external_kernel_cache.py

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2c8f80e53

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[ChaoWao]

Addressed the automated review follow-ups in a5bad6c: cache digests no longer contain machine-specific absolute paths and now have a relocation regression; the new test has the required direct pytest entrypoint; and the docs show the direct @pl.function attribute form.