This is an automated email from the ASF dual-hosted git repository.
tqchen pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/dev by this push:
new 5511c6c add runtime support section (#14)
5511c6c is described below
commit 5511c6c3d04aabe37613e2126321ae3ed154a195
Author: Yaoyao Ding <[email protected]>
AuthorDate: Sun Sep 14 21:04:25 2025 -0400
add runtime support section (#14)
---
docs/_static/custom.css | 5 ++++
docs/conf.py | 4 +++
docs/guides/compiler_integration.md | 52 +++++++++++++++++++++++++++++++++++++
tests/lint/check_file_type.py | 1 +
4 files changed, 62 insertions(+)
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
new file mode 100644
index 0000000..6277c6d
--- /dev/null
+++ b/docs/_static/custom.css
@@ -0,0 +1,5 @@
+/* Avoid the uncessary scrollbar on the primiary sidebar
+ See: https://github.com/executablebooks/sphinx-book-theme/issues/732 */
+#rtd-footer-container {
+ margin: 0px !important;
+}
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index f86f9bd..8a1c5b3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -225,3 +225,7 @@ html_context = {
"github_version": "main",
"conf_py_path": "/docs/",
}
+
+html_static_path = ['_static']
+
+html_css_files = ['custom.css']
diff --git a/docs/guides/compiler_integration.md
b/docs/guides/compiler_integration.md
index 96f5b2f..0eaf1ff 100644
--- a/docs/guides/compiler_integration.md
+++ b/docs/guides/compiler_integration.md
@@ -103,6 +103,58 @@ This approach provides a unified mechanism to call into
any libraries and other
that expose kernels following the FFI convention, enabling seamless
interoperability
with various kernel DSLs and libraries.
+
+## Runtime and State Management for Compilers
+
+While TVM FFI provides a standard ABI for compiler-generated kernels, many
compilers and domain-specific languages
+(DSLs) require their own **runtime** to manage states like dynamic shapes,
workspace memory, or other
+application-specific data. This runtime can be a separate shared library
accessible to all kernels from a specific
+compiler.
+
+### Recommended Approach for State Management
+
+The recommended approach for managing compiler-specific state is to define the
state within a **separate shared library**.
+This library exposes its functionality by registering functions as global
`tvm::ffi::Function`s.
+
+Here's a breakdown of the process:
+
+1. **Define a Global State**: Create a class or structure to hold your
compiler's runtime state. A simple singleton pattern is often used for this.
+2. **Register Global Functions**: Use the `TVM_FFI_STATIC_INIT_BLOCK()` macro
to register a global function that returns a pointer to your state. For example:
+ ```c++
+ class GlobalState {
+ ... // your state variables here
+ public:
+ GlobalState* Global() {
+ static auto *inst = new GlobalState();
+ return inst;
+ }
+ };
+ TVM_FFI_STATIC_INIT_BLOCK() {
+ using refl = tvm::ffi::reflection;
+ refl.GlobalDef().def("mylang.get_global_state", []()-> void*{ return
GlobalState::Global()});
+ // other runtime APIs can be registered here
+ }
+ ```
+ This method allows both C++ and Python to access the runtime state through
a consistent API.
+3. **Access State from Kernels**: Within your compiler-generated kernels, you
can use
+ `GetGlobalRequired("mylang.get_global_state")` in C++ or the C equivalent
+ `TVMFFIGetGlobalFunction("mylang.get_global_state", ...)` to get the
function and then call it to retrieve the state
+ pointer.
+
+### Distributing the Runtime
+
+For a user to use a kernel from your compiler, they must have access to your
runtime library. The preferred method is to
+package the runtime shared library (e.g., `libmylang_runtime.so`) as part of a
Python or C++ package. Users must install
+and import this package before loading any kernels compiled by your system.
+This approach ensures the state is shared among different kernels.
+
+### Common vs. Custom State
+
+It's important to distinguish between compiler-specific state and **common
state** managed by TVM FFI. TVM FFI handles
+common states like **streams** and **memory allocators** through environment
functions (e.g., `TVMFFIEnvGetStream`),
+allowing kernels to access these without managing their own. However, for any
unique state required by your compiler,
+the global function registration approach is the most suitable method.
+
## Advanced: Custom Modules
While the standard dynamic library module is sufficient for many use cases,
diff --git a/tests/lint/check_file_type.py b/tests/lint/check_file_type.py
index f5ab2b9..b44d5f1 100644
--- a/tests/lint/check_file_type.py
+++ b/tests/lint/check_file_type.py
@@ -61,6 +61,7 @@ ALLOW_EXTENSION = {
"txt",
"md",
"rst",
+ "css",
# sgx
"edl",
"lds",
