sync(a5): align host_build_graph runtime with a2a3 implementation

[ChaoZheng109]

Synchronize A5 host_build_graph runtime implementation with improvements from a2a3, including cache coherence fixes, API enhancements, and documentation.

Changes:

• aicore_executor: optimize cache flush timing

  • Remove per-task global DCCI flush (performance bottleneck)
  • Clear EXIT_SIGNAL before main loop to prevent stale signals
  • Add single DCCI flush at kernel exit for cross-core visibility

• aicpu_executor: improve handshake and naming

  • Rename all_hanks -> all_handshakes for clarity
  • Add AICore register initialization after discovery
  • Update deinit signature to take Runtime parameter

• runtime.h: add kernel management and API compatibility

  • Track registered kernel func_ids for cleanup
  • Add remove_kernel_binary() host API
  • Add orch_thread_num field for API compatibility with rt2

• docs: add RUNTIME_LOGIC.md architecture documentation

  • Document core data structures and execution flow
  • Explain build/init, execution, and cleanup phases
  • Reference key implementation files

This sync ensures A5 host_build_graph matches the battle-tested a2a3 implementation for correctness and performance.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request synchronizes the A5 host_build_graph runtime implementation with the established a2a3 version. The changes primarily focus on enhancing cache coherence, improving API clarity and functionality, and providing comprehensive documentation. This ensures the A5 implementation benefits from battle-tested correctness and performance optimizations, streamlining its operation and maintainability.

Highlights

• AICore Executor Optimizations: Removed a performance-bottlenecking per-task global DCCI flush, added logic to clear the EXIT_SIGNAL before the main loop, and introduced a single DCCI flush at kernel exit for improved cross-core visibility and cache coherence.
• AICPU Executor Enhancements: Renamed internal handshake variables for clarity, added initialization of AICore registers after core discovery, and updated the deinit function signature to accept a Runtime parameter, enabling proper cache invalidation during cleanup.
• Runtime API and Kernel Management: Introduced mechanisms to track registered kernel function IDs and added a remove_kernel_binary() host API, facilitating better resource management and cleanup of kernel binaries. An orch_thread_num field was also added for API compatibility.
• New Documentation: A new documentation file, RUNTIME_LOGIC.md, was added to comprehensively describe the core data structures, build/init flow, execution flow, and cleanup phases of the host_build_graph runtime.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/a5/runtime/host_build_graph/aicore/aicore_executor.cpp
  • Removed a per-task global DCCI flush.
  • Added logic to clear EXIT_SIGNAL before the main loop.
  • Introduced a single DCCI flush at kernel exit.
• src/a5/runtime/host_build_graph/aicpu/aicpu_executor.cpp
  • Renamed all_hanks to all_handshakes for better readability.
  • Modified deinit function signature to accept a Runtime* parameter.
  • Added initialization of AICore registers after core discovery.
  • Increased MAX_IDLE_ITERATIONS and decreased WARN_INTERVAL for timeout detection.
  • Added cache invalidation for the Runtime address range during deinitialization.
• src/a5/runtime/host_build_graph/docs/RUNTIME_LOGIC.md
  • Added a new documentation file detailing the runtime logic, data structures, and execution flow.
• src/a5/runtime/host_build_graph/host/runtime_compile_info.cpp
  • Updated the platform check in get_incore_compiler from "a5" to "a2a3".
• src/a5/runtime/host_build_graph/host/runtime_maker.cpp
  • Implemented cleanup logic for registered kernel binaries during runtime validation.
• src/a5/runtime/host_build_graph/runtime/runtime.cpp
  • Initialized registered_kernel_count_ in the constructor.
• src/a5/runtime/host_build_graph/runtime/runtime.h
  • Added remove_kernel_binary function pointer to the HostApi struct.
  • Introduced orch_thread_num member for API compatibility.
  • Added registered_kernel_func_ids_ and registered_kernel_count_ members for kernel tracking.
  • Added get_registered_kernel_count, get_registered_kernel_func_id, and clear_registered_kernels methods.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces significant changes to the AICore and AICPU executors, focusing on cache coherence, inter-core communication, and runtime cleanup. Key changes include removing explicit DCCI from execute_task and adding it before kernel exit in aicore_execute, along with clearing stale exit signals. The AicpuExecutor::deinit method was updated to invalidate the Runtime cache and now accepts a Runtime* argument. Variable names like all_hanks were refactored to all_handshakes for clarity, and timeout constants MAX_IDLE_ITERATIONS and WARN_INTERVAL were adjusted. A new RUNTIME_LOGIC.md document was added to detail the system's architecture and execution flow. Additionally, the Runtime class was enhanced to track registered kernel binaries for proper cleanup, and the get_incore_compiler platform check was updated from 'a5' to 'a2a3'.

Review comments highlight several improvement opportunities: the MAX_IDLE_ITERATIONS and WARN_INTERVAL values in aicpu_executor.cpp are identified as magic numbers needing better explanation or a time-based timeout. The newly added RUNTIME_LOGIC.md documentation is noted as being out of sync with the actual register-based communication protocol used by the executors and requires an update. Finally, the set_function_bin_addr method in runtime.h has a potential bug where func_id could be added multiple times to the registered_kernel_func_ids_ array, risking overflow and double-free issues during cleanup, suggesting a check for duplicates.