Merge branch 'jg/doc-debug' into 'main'

haijieg · haijieg · commit 9dda5debbcc8 · 2025-11-25T17:16:20.000-08:00
Add debug section to doc

See merge request dl/tileir/cutile-python!46
diff --git a/docs/source/debugging.rst b/docs/source/debugging.rst
@@ -0,0 +1,40 @@
+.. SPDX-FileCopyrightText: Copyright (c) <2025> NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+..
+.. SPDX-License-Identifier: Apache-2.0
+
+.. currentmodule:: cuda.tile
+
+Debugging
+=========
+
+Exception Types
+---------------
+
+.. autoclass:: TileSyntaxError()
+.. autoclass:: TileTypeError()
+.. autoclass:: TileValueError()
+.. autoclass:: TileCompilerExecutionError()
+.. autoclass:: TileCompilerTimeoutError()
+
+
+Environment Variables
+---------------------
+
+The following environment variables are useful when
+the above exceptions are encountered during kernel
+development.
+
+Set ``CUDA_TILE_ENABLE_CRASH_DUMP=1`` to enable dumping
+an archive including the TileIR bytecode
+for submitting a bug report on :class:`TileCompilerExecutionError`
+or class:`TileCompilerTimeoutError`.
+
+Set ``CUDA_TILE_COMPILER_TIMEOUT_SEC`` to limit the
+time the TileIR compiler `tileiras` can take.
+
+Set ``CUDA_TILE_LOGS=CUTILEIR`` to print cuTile python
+IR during compilation to stderr. This is usefule when
+debugging :class:`TileTypeError`.
+
+Set ``CUDA_TILE_TEMP_DIR`` to configure the directory
+for storing temporary files.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -44,3 +44,4 @@ latest hardware features without having to rewrite your code.
    interoperability
    performance
    operations
+   debugging
diff --git a/src/cuda/tile/__init__.py b/src/cuda/tile/__init__.py
@@ -40,7 +40,8 @@
 )
 
 from cuda.tile._exception import (
-    TileCompilerError,
+    TileCompilerExecutionError,
+    TileCompilerTimeoutError,
     TileInternalError,
     TileSyntaxError,
     TileTypeError,
@@ -169,7 +170,8 @@
     "uint32",
     "uint64",
 
-    "TileCompilerError",
+    "TileCompilerExecutionError",
+    "TileCompilerTimeoutError",
     "TileInternalError",
     "TileSyntaxError",
     "TileTypeError",
diff --git a/src/cuda/tile/_compile.py b/src/cuda/tile/_compile.py
@@ -69,11 +69,11 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
-def _get_final_ir(pyfunc, args) -> ir.Function:
+def _get_final_ir(pyfunc, args, tile_context) -> ir.Function:
     ir_ctx = ir.IRContext()
     func_ir: ir.Function = get_function_ir(pyfunc, ir_ctx, call_site=None)
     ir_args = func_ir.bind_arguments(args, get_constant_annotations(pyfunc))
-    func_ir = infer_types_pass(func_ir, ir_args, pyfunc)
+    func_ir = infer_types_pass(func_ir, ir_args, pyfunc, tile_context)
     dead_code_elimination_pass(func_ir)
 
     if not CUDA_TILE_TESTING_DISABLE_TOKEN_ORDER:
@@ -145,7 +145,7 @@ def compile_tile(pyfunc,
                  args,
                  compiler_options: CompilerOptions,
                  context: TileContext = default_tile_context) -> TileLibrary:
-    func_ir = _get_final_ir(pyfunc, args)
+    func_ir = _get_final_ir(pyfunc, args, context)
 
     if 'CUTILEIR' in context.config.log_keys:
         code = (f"==== CuTile IR for {func_ir.qualname}==== \n\n"
diff --git a/src/cuda/tile/_debug.py b/src/cuda/tile/_debug.py
@@ -2,41 +2,14 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-import logging
 import os
 
-# Comma separated string for selective debug logging
-# values are case in-sensitive
-CUDA_TILE_LOG_KEYS = {"CUTILEIR", "TILEIR"}
 
-
-def parse_cuda_tile_logs_env():
-    env = os.environ.get('CUDA_TILE_LOGS', "")
-    ret = []
-    for x in env.split(","):
-        x = x.upper().strip()
-        if len(x) == 0:
-            continue
-        if x not in CUDA_TILE_LOG_KEYS:
-            raise RuntimeError(f"Unexpected value {x} in CUDA_TILE_LOGS, "
-                               f"supported values are {CUDA_TILE_LOG_KEYS}")
-        ret.append(x)
-    return ret
-
-
-CUDA_TILE_LOGS = parse_cuda_tile_logs_env()
+# Internal environment variables for debugging
 
 CUDA_TILE_DUMP_TILEIR = os.environ.get('CUDA_TILE_DUMP_TILEIR', None)
 CUDA_TILE_DUMP_BYTECODE = os.environ.get('CUDA_TILE_DUMP_BYTECODE', None)
-CUDA_TILE_TEMP_DIR = os.environ.get('CUDA_TILE_TEMP_DIR', None)
-
-
 CUDA_TILE_TESTING_DISABLE_DIV = (
     os.environ.get("CUDA_TILE_TESTING_DISABLE_DIV", "0") == "1")
-
-
 CUDA_TILE_TESTING_DISABLE_TOKEN_ORDER = (
     os.environ.get("CUDA_TILE_TESTING_DISABLE_TOKEN_ORDER", "0") == "1")
-
-
-logger = logging.getLogger(__name__)
diff --git a/src/cuda/tile/_exception.py b/src/cuda/tile/_exception.py
@@ -94,14 +94,17 @@ def __str__(self):
 
 
 class TileSyntaxError(TileError):
+    """Exception when a python syntax not supported by cuTile is encountered."""
     pass
 
 
 class TileTypeError(TileError):
+    """Exception when an unexpected type or |data type| is encountered."""
     pass
 
 
 class TileValueError(TileError):
+    """Exception when an unexpected python value is encountered."""
     pass
 
 
@@ -167,6 +170,7 @@ def __init__(self,
 
 
 class TileCompilerExecutionError(TileCompilerError):
+    """Exception when ``tileiras`` compiler throws an error."""
     def __init__(self,
                  return_code: int,
                  stderr: str,
@@ -180,6 +184,7 @@ def __init__(self,
 
 
 class TileCompilerTimeoutError(TileCompilerError):
+    """Exception when ``tileiras`` compiler timeout limit is exceeded."""
     def __init__(self,
                  message: str,
                  compiler_flags: str,
diff --git a/src/cuda/tile/_passes/typeinfer.py b/src/cuda/tile/_passes/typeinfer.py
@@ -11,12 +11,12 @@
 from types import FunctionType
 from typing import Tuple, Any, Optional, Sequence, Callable
 
-from cuda.tile._debug import CUDA_TILE_LOGS
 from cuda.tile._exception import (
     TileTypeError,
     TileInternalError,
     ConstantNotFoundError, TileSyntaxError, Loc, TileError
 )
+from cuda.tile._cext import TileContext
 from cuda.tile._ir import ir
 from cuda.tile._ir.ir import Operation, Function, Block, Var, Argument, IRContext, TypedOperation
 from cuda.tile._ir.op_impl import op_implementations
@@ -359,12 +359,15 @@ def infer_types_in_func(context: TypingContext,
     return dataclasses.replace(func, parameters=tuple(new_params))
 
 
-def infer_types_pass(func: Function, args: Tuple[Argument, ...], pyfunc: FunctionType) -> Function:
+def infer_types_pass(func: Function,
+                     args: Tuple[Argument, ...],
+                     pyfunc: FunctionType,
+                     tile_context: TileContext) -> Function:
     context = TypingContext(func.root_block.ctx)
     try:
         return infer_types_in_func(context, func, args)
     except Exception as e:
-        if 'CUTILEIR' in CUDA_TILE_LOGS:
+        if 'CUTILEIR' in tile_context.config.log_keys:
             highlight_loc = e.loc if hasattr(e, 'loc') else None
             code = (f"====Partial CuTile IR for {func}==== \n\n"
                     f"{func.to_string(highlight_loc=highlight_loc)}\n\n")
diff --git a/test/test_dce.py b/test/test_dce.py
@@ -8,11 +8,12 @@
 from cuda.tile._ir.ops import Loop, Continue, Break
 from cuda.tile._ir import ir
 from cuda.tile._compile import _get_final_ir
+from cuda.tile._cext import default_tile_context
 
 
 def get_ir(func) -> ir.Function:
     x = torch.zeros(10, device="cuda")
-    ir = _get_final_ir(func, (x,))
+    ir = _get_final_ir(func, (x,), default_tile_context)
     print(ir)
     return ir
 
