From bb973e02c9f3a945b11953f3e0ca18cdfb29d2c6 Mon Sep 17 00:00:00 2001 From: Aashish <145881415+aashish254@users.noreply.github.com> Date: Mon, 12 Oct 2026 05:53:20 +0545 Subject: [PATCH 1/2] docs(tl_kernels): the caller that pads these kernels is laya.fast, not base.pad_batch pad_batch has one production call site (laya/backends/compile.py:111, the compile route); laya/fast.py is the only module that imports tl_kernels, and FastLaya._forward_unlocked does its own bucketing -- bucket_rows for rows, an inlined copy of bucket_tokens' arithmetic against FastLaya.DYNAMIC_MAX_L/LONG_BUCKET for tokens. Retune pad_batch for TileLang and nothing on the TileLang route changes, so name the real caller and gate the call graph, the inlining and the duplicated constants off the AST (no tilelang import, so this runs CPU-only). --- laya/tl_kernels.py | 9 ++- tests/test_confidence.py | 141 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 146 insertions(+), 4 deletions(-) diff --git a/laya/tl_kernels.py b/laya/tl_kernels.py index fe715a938..617cfc2e8 100644 --- a/laya/tl_kernels.py +++ b/laya/tl_kernels.py @@ -2,9 +2,12 @@ GPU kernels take 16-bit activations (bf16 by default, fp16 with dtype="float16"), accumulate in fp32. Row count M is a runtime symbol so one compiled kernel serves every batch/sequence bucket: the -caller in `laya.backends.base.pad_batch` pads the batch dim to the next power of two -(`bucket_rows`, so a single question stays one row) and the sequence dim to a 16-token bucket -up to `DYNAMIC_MAX_L` and a 64-token bucket beyond (`bucket_tokens`). M is the flattened +caller, `laya.fast.FastLaya._forward_unlocked`, pads the batch dim to the next power of two +(`laya.backends.base.bucket_rows`, so a single question stays one row) and the sequence dim to a +16-token bucket up to `DYNAMIC_MAX_L` and a 64-token bucket beyond -- the policy +`laya.backends.base.bucket_tokens` implements, which `_forward_unlocked` repeats against its own +`FastLaya.DYNAMIC_MAX_L`/`LONG_BUCKET` instead of calling it. `laya.backends.base.pad_batch` is the +compile route's copy of the same policy, and that route never reaches these kernels. M is the flattened `rows * tokens`, so the multiple-of-16 comes from the token dim, not the row dim; out-of-bounds rows are predicated by TileLang's `T.ceildiv(M, bm)`, so the kernels themselves place no constraint on M. Use compile_cpu for an explicit fp32 CPU specialization; the GPU defaults are unchanged. diff --git a/tests/test_confidence.py b/tests/test_confidence.py index 50e409040..6ea751f9a 100644 --- a/tests/test_confidence.py +++ b/tests/test_confidence.py @@ -2041,9 +2041,148 @@ def test_bucket_rows_stays_a_power_of_two_below_16(): "expect 16 here" % (n, bucket_rows(n))) +# ------------------------------- and the caller it names has to be on the kernels' own route +# The attribution was the second half of the same defect. The docstring called +# `laya.backends.base.pad_batch` "the caller" of these kernels, but `pad_batch` serves the +# `backend="compile"` route: it has exactly one production call site, `laya/backends/compile.py:111`, +# and `laya/fast.py:10` is the only module in the package that imports `tl_kernels`. Those two sets +# being disjoint is what makes the sentence false, and nothing in the tree checked either one. The +# padding on the TileLang route happens in `FastLaya._forward_unlocked`, which takes its row bucket +# from `bucket_rows` (through `_bucket_n`) but *inlines* the token bucketing against its own +# `FastLaya.DYNAMIC_MAX_L`/`LONG_BUCKET` class attributes rather than calling `bucket_tokens`. So a +# maintainer who retuned `pad_batch` or `bucket_tokens` for TileLang padding changed nothing on the +# TileLang route, and no test said so. All three checks below read the call graph out of the AST -- +# no `tilelang` import, so they run on a CPU-only box where the fast path cannot execute. + +FAST_REL = "laya/fast.py" +COMPILE_REL = "laya/backends/compile.py" +_BAN_PAD_BATCH_CALLER = re.compile(r"caller(?:,| in) [`\w.]*pad_batch", re.I) + + +def _laya_trees(): + """`[(slash-relative path, parsed AST)]` for every module under `laya/`.""" + out = [] + for base, _dirs, files in os.walk(os.path.join(ROOT, "laya")): + for name in sorted(files): + if not name.endswith(".py") or "__pycache__" in base: + continue + path = os.path.join(base, name) + with open(path, encoding="utf-8") as fh: + out.append((path[len(ROOT) + 1:].replace(os.sep, "/"), ast.parse(fh.read(), filename=path))) + return out + + +def _modules_calling(trees, fname): + """Paths of the `laya/` modules containing a call node for `fname`.""" + hits = set() + for rel, tree in trees: + for node in ast.walk(tree): + func = node.func if isinstance(node, ast.Call) else None + if func is not None and ((isinstance(func, ast.Name) and func.id == fname) + or (isinstance(func, ast.Attribute) and func.attr == fname)): + hits.add(rel) + return hits + + +def _modules_importing(trees, mod): + """Paths of the `laya/` modules that import `mod`, `from . import mod` included.""" + hits = set() + for rel, tree in trees: + for node in ast.walk(tree): + if isinstance(node, ast.ImportFrom) and any(a.name == mod for a in node.names): + hits.add(rel) + elif isinstance(node, ast.Import): + if any(a.name.split(".")[-1] == mod for a in node.names): + hits.add(rel) + return hits + + +def _unparsed_function(rel, funcname): + """One function's body, `ast.unparse`d, so the check reads the code rather than its comments.""" + with open(os.path.join(ROOT, rel), encoding="utf-8") as fh: + tree = ast.parse(fh.read(), filename=rel) + for node in ast.walk(tree): + if isinstance(node, ast.FunctionDef) and node.name == funcname: + return ast.unparse(node) + raise AssertionError("%s has no function %s() -- the docstring cites a moved symbol" % (rel, funcname)) + + +def _class_constant(rel, classname, const): + """A class-level `CONST = `, read without importing the module (this one needs tilelang).""" + with open(os.path.join(ROOT, rel), encoding="utf-8") as fh: + tree = ast.parse(fh.read(), filename=rel) + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef) and node.name == classname: + for stmt in node.body: + if isinstance(stmt, ast.Assign): + for target in stmt.targets: + if isinstance(target, ast.Name) and target.id == const: + if isinstance(stmt.value, ast.Constant): + return stmt.value.value + raise AssertionError("no `%s.%s = ` in %s -- the docstring cites a moved constant" + % (classname, const, rel)) + + +def test_tl_kernels_names_a_caller_that_is_on_the_kernels_route(): + """`pad_batch` never reaches these kernels, so it cannot be the caller the docstring names.""" + trees = _laya_trees() + kernel_importers = _modules_importing(trees, "tl_kernels") + pad_batch_callers = _modules_calling(trees, "pad_batch") + assert kernel_importers == {FAST_REL}, ( + "the `laya/` modules importing `tl_kernels` are now %s; the docstring describes one caller, " + "so a second route needs its own sentence" % sorted(kernel_importers)) + assert pad_batch_callers == {COMPILE_REL}, ( + "`pad_batch` is now called from %s, not only from `%s`; if a route from there reaches " + "`tl_kernels`, the docstring's caller may genuinely be `pad_batch` again -- re-read both " + "before editing" % (sorted(pad_batch_callers), COMPILE_REL)) + assert not (kernel_importers & pad_batch_callers), ( + "`pad_batch` is on the `tl_kernels` route after all, so this ban is stale -- re-read the " + "call graph rather than deleting the sentence it caught") + doc = _tl_docstring() + assert not _BAN_PAD_BATCH_CALLER.search(doc), ( + "`laya/tl_kernels.py` again calls `laya.backends.base.pad_batch` the caller of these " + "kernels. Its one production call site is `laya/backends/compile.py:111`, and " + "`laya/fast.py:10` is the only module that imports `tl_kernels`; the padding these kernels " + "see happens in `FastLaya._forward_unlocked`.") + assert "laya.fast" in doc and "_forward_unlocked" in doc, ( + "the docstring must name the caller the call graph actually gives these kernels") + + +def test_the_fast_path_still_inlines_the_token_bucket_the_docstring_says_it_repeats(): + """`_forward_unlocked` mirrors `bucket_tokens`'s arithmetic against its own constants.""" + body = _unparsed_function(FAST_REL, "_forward_unlocked") + assert "self.DYNAMIC_MAX_L" in body and "self.LONG_BUCKET" in body, ( + "`_forward_unlocked` no longer buckets tokens against the `FastLaya` class constants, so " + "the docstring's 'repeats against its own `FastLaya.DYNAMIC_MAX_L`/`LONG_BUCKET`' is stale") + assert "bucket_tokens(" not in body, ( + "`_forward_unlocked` calls `bucket_tokens` directly now; then there is one policy rather " + "than two copies, and both the docstring and this check need re-reading") + assert "_bucket_n(" in body, ( + "the row pad no longer comes from `laya.backends.base.bucket_rows` through `_bucket_n`") + + +def test_the_two_bucket_policies_the_docstring_describes_are_still_the_same_numbers(): + """One sentence covers both routes only while the duplicated constants agree.""" + from laya.backends.base import DYNAMIC_MAX_L, LONG_BUCKET + fast_max_l = _class_constant(FAST_REL, "FastLaya", "DYNAMIC_MAX_L") + fast_long = _class_constant(FAST_REL, "FastLaya", "LONG_BUCKET") + assert (fast_max_l, fast_long) == (DYNAMIC_MAX_L, LONG_BUCKET), ( + "`FastLaya` buckets at (%s, %s) while `laya.backends.base` buckets at (%s, %s). " + "`laya/tl_kernels.py`'s docstring describes one policy for these kernels; once the two " + "copies differ it has to name both, and its `16`/`%d` numbers need re-reading." + % (fast_max_l, fast_long, DYNAMIC_MAX_L, LONG_BUCKET, LONG_BUCKET)) + doc = _tl_docstring() + assert "16-token bucket" in doc, "the docstring no longer states the small token bucket" + assert "%d-token bucket" % LONG_BUCKET in doc, ( + "the docstring no longer states the large token bucket the code uses (`%d`)" % LONG_BUCKET) + + for _fn in (test_tl_kernels_drops_the_wrong_row_claim, test_tl_kernels_names_the_real_padding_policy, - test_bucket_rows_stays_a_power_of_two_below_16): + test_bucket_rows_stays_a_power_of_two_below_16, + test_tl_kernels_names_a_caller_that_is_on_the_kernels_route, + test_the_fast_path_still_inlines_the_token_bucket_the_docstring_says_it_repeats, + test_the_two_bucket_policies_the_docstring_describes_are_still_the_same_numbers): try: _fn() except AssertionError as e: From c3b0d31261336e47189662fa4b8e00d64dbd4785 Mon Sep 17 00:00:00 2001 From: Aashish <145881415+aashish254@users.noreply.github.com> Date: Mon, 12 Oct 2026 05:55:38 +0545 Subject: [PATCH 2/2] docs(tl_kernels): tighten the route sentence, and let the row check accept a direct bucket_rows call --- laya/tl_kernels.py | 4 ++-- tests/test_confidence.py | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/laya/tl_kernels.py b/laya/tl_kernels.py index 617cfc2e8..15382effd 100644 --- a/laya/tl_kernels.py +++ b/laya/tl_kernels.py @@ -6,8 +6,8 @@ (`laya.backends.base.bucket_rows`, so a single question stays one row) and the sequence dim to a 16-token bucket up to `DYNAMIC_MAX_L` and a 64-token bucket beyond -- the policy `laya.backends.base.bucket_tokens` implements, which `_forward_unlocked` repeats against its own -`FastLaya.DYNAMIC_MAX_L`/`LONG_BUCKET` instead of calling it. `laya.backends.base.pad_batch` is the -compile route's copy of the same policy, and that route never reaches these kernels. M is the flattened +`FastLaya.DYNAMIC_MAX_L`/`LONG_BUCKET` instead of calling it. `laya.backends.base.pad_batch` applies +that policy for the compile route, which never reaches these kernels. M is the flattened `rows * tokens`, so the multiple-of-16 comes from the token dim, not the row dim; out-of-bounds rows are predicated by TileLang's `T.ceildiv(M, bm)`, so the kernels themselves place no constraint on M. Use compile_cpu for an explicit fp32 CPU specialization; the GPU defaults are unchanged. diff --git a/tests/test_confidence.py b/tests/test_confidence.py index 6ea751f9a..204ca3ecd 100644 --- a/tests/test_confidence.py +++ b/tests/test_confidence.py @@ -2157,8 +2157,9 @@ def test_the_fast_path_still_inlines_the_token_bucket_the_docstring_says_it_repe assert "bucket_tokens(" not in body, ( "`_forward_unlocked` calls `bucket_tokens` directly now; then there is one policy rather " "than two copies, and both the docstring and this check need re-reading") - assert "_bucket_n(" in body, ( - "the row pad no longer comes from `laya.backends.base.bucket_rows` through `_bucket_n`") + assert "_bucket_n(" in body or "bucket_rows(" in body, ( + "the row pad no longer comes from `laya.backends.base.bucket_rows`, through `_bucket_n` or " + "directly, so the docstring's attribution needs re-reading") def test_the_two_bucket_policies_the_docstring_describes_are_still_the_same_numbers():