docs: 新增 Host API 参考并按源码生成英文稿-catlass-AtomGit

Mpython/tla_dsl/README.md+3-1

	@@ -8,7 +8,9 @@ CATLASS DSL 是 CATLASS 的 Python 前端。它在 AscendNPU-IR 的基础上构
8		8
9	- [环境准备](docs/zh/dsl_development/build_guide/index.md)：环境要求及安装入口。	9	- [环境准备](docs/zh/dsl_development/build_guide/index.md)：环境要求及安装入口。
10	- [编译与测试](docs/zh/dsl_development/build_guide/index.md)：构建、pytest、lit 和端到端用例。	10	- [编译与测试](docs/zh/dsl_development/build_guide/index.md)：构建、pytest、lit 和端到端用例。
11	-- [API 文档](docs/zh/api/generate_api_docs.md)：生成并预览 API 文档。	11	+- [Host API 参考](docs/zh/api/host_api_reference.md)：Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。
		12	+- [Kernel API 参考](docs/zh/api/kernel_api_reference.md)：Kernel 侧 Core API。
		13	+- [API 文档生成](docs/zh/api/generate_api_docs.md)：从源码 docstring 重新生成英文 API 参考。
12	- [AscendNPU-IR 构建](docs/zh/dsl_development/build_guide/ascend_npu_ir.md)：手动构建AscendNPU-IR。	14	- [AscendNPU-IR 构建](docs/zh/dsl_development/build_guide/ascend_npu_ir.md)：手动构建AscendNPU-IR。
13	- [手动 CMake 构建](docs/zh/dsl_development/advanced/manual_cmake_build.md)：直接配置 `csrc/mlir` 的进阶用法。	15	- [手动 CMake 构建](docs/zh/dsl_development/advanced/manual_cmake_build.md)：直接配置 `csrc/mlir` 的进阶用法。
14		16

Mpython/tla_dsl/catlass/base_dsl/compiler.py+34-0文件内容审核中，请稍后刷新重试

Mpython/tla_dsl/catlass/base_dsl/jit_executor.py+37-0

	@@ -103,6 +103,43 @@ class TlaJitExecutor:
103	args: Sequence[Any] \| None = None,	103	args: Sequence[Any] \| None = None,
104	**kwargs: Any,	104	**kwargs: Any,
105	) -> TlaExecutionResult:	105	) -> TlaExecutionResult:
		106	+ """Directory: Compile and Launch / Launch
		107	+ Description:
		108	+ Launch a compiled kernel on the NPU after `tla.compile`, passing runtime
		109	+ kernel arguments and launch options (for example `block_num`, `stream`).
		110	+
		111	+ Parameters:
		112	+ - `launch_args` (`Any`): Positional runtime kernel arguments matching
		113	+ the `@tla.kernel` signature (bound Host tensors, scalars, or
		114	+ `@dataclass` instances). Mutually exclusive with `args=`.
		115	+ - `block_num` (`int \| None`): Number of blocks to launch. Optional;
		116	+ default `1`. Must be an `int` when provided.
		117	+ - `args` (`Sequence[Any] \| None`): Explicit runtime argument sequence.
		118	+ Optional; default `None`. Cannot be combined with non-empty
		119	+ `*launch_args`.
		120	+ - `stream` (`Any`, via `**kwargs`): Optional ACL stream handle (often
		121	+ an `int`). When omitted, uses `torch.npu.current_stream` if available;
		122	+ otherwise set `stream=` explicitly or `CATLASS_DSL_NPU_DEVICE`.
		123	+
		124	+ Constraints:
		125	+ - `artifact(...)` and `.launch(...)` share the same runtime rules.
		126	+ - `*launch_args` and `args=` must not both be non-empty
		127	+ (`TlaUnsupportedAbiError`).
		128	+ - Launch args must be bound NPU buffers for tensors (`from_dlpack`);
		129	+ `make_fake_tensor` samples are for compile only.
		130	+ - `block_num` must be an `int` (default `1`).
		131	+
		132	+ Example:
		133	+ ```python
		134	+ artifact = tla.compile(vadd, tx, ty, options="--npu-arch 3510")
		135	+ artifact(tx, ty, block_num=1)
		136	+ # same as:
		137	+ artifact.launch(tx, ty, block_num=1)
		138	+ # or pass args explicitly:
		139	+ artifact.launch(args=(tx, ty), block_num=1)
		140	+ ```
		141	+
		142	+ """
106	from ..execution import (	143	from ..execution import (
107	TlaRuntimeUnavailableError,	144	TlaRuntimeUnavailableError,
108	TlaUnsupportedAbiError,	145	TlaUnsupportedAbiError,

Mpython/tla_dsl/catlass/base_dsl/typing.py+6-1

	@@ -1158,7 +1158,12 @@ class Float8E5M2(
1158		1158
1159		1159
1160	class Constexpr(Generic[_T]):	1160	class Constexpr(Generic[_T]):
1161	- """Type marker for compile-time-only frontend parameters."""	1161	+ """Annotation marker for compile-time-only kernel / dataclass fields.
		1162	+
		1163	+ Written as ``tla.Constexpr[T]``. Semantics live in the Python syntax guide
		1164	+ and the ``kernel`` / ``dataclass`` Host API type tables — not a callable
		1165	+ Host entry.
		1166	+ """
1162		1167
1163	@classmethod	1168	@classmethod
1164	def is_constexpr_annotation(cls, annotation: Any) -> bool:	1169	def is_constexpr_annotation(cls, annotation: Any) -> bool:

Mpython/tla_dsl/catlass/catlass_dsl/tla.py+75-3

	@@ -18,10 +18,20 @@ if TYPE_CHECKING:
18		18
19		19
20	class KernelLauncher:	20	class KernelLauncher:
21	- """Runtime launch wrapper for ``@tla.kernel`` functions.	21	+ """Runtime launch wrapper returned when a ``@tla.kernel`` function is called.
22		22
23	- Collects launch args / options, triggers host-side ``compile_kernel`` when	23	+ Typical usage::
24	- needed, then calls ``execute_kernel``.	24	+
		25	+ launcher = my_kernel(tx, ty, options="--npu-arch 3510")
		26	+ launcher(block_num=1) # or launcher.launch(block_num=1)
		27	+
		28	+ The first call returns this object without launching. Compilation happens
		29	+ when the launcher is constructed with launch args (or the kernel has no
		30	+ parameters), or on ``.launch`` when there is no cached artifact or runtime
		31	+ options changed; otherwise ``.launch`` reuses the cached artifact. To
		32	+ compile once and launch repeatedly with compile and launch separated, use
		33	+ ``tla.compile`` and the returned executor.
		34	+ See Host API reference (Compile and Launch).
25	"""	35	"""
26		36
27	def __init__(	37	def __init__(
	@@ -70,6 +80,68 @@ class KernelLauncher:
70	args: Sequence[Any] \| None = None,	80	args: Sequence[Any] \| None = None,
71	**kwargs: Any,	81	**kwargs: Any,
72	) -> TlaExecutionResult:	82	) -> TlaExecutionResult:
		83	+ """Directory: Compile and Launch / Launch
		84	+ Description:
		85	+ Launch a `@tla.kernel` on the NPU. Obtain this object by calling the
		86	+ decorated kernel (`launcher = my_kernel(*tensors, options=...)`); that
		87	+ call does not launch. Then call `launcher.launch(...)` or invoke the
		88	+ launcher (`launcher(block_num=...)`, equivalent to
		89	+ `.launch(args=..., **kwargs)`). Compiles when there is no cached artifact
		90	+ or runtime options changed; reuses the cached artifact when runtime
		91	+ options are unchanged. To compile once and launch repeatedly with compile
		92	+ and launch separated, use `tla.compile` and the returned
		93	+ `TlaJitExecutor`.
		94	+
		95	+ Parameters:
		96	+ - `block_num` (`int \| None`): Number of blocks to launch. Optional;
		97	+ default `1` (also taken from kwargs stored when the launcher was
		98	+ constructed). Must be an `int` when provided.
		99	+ - `type_args` (`Sequence[Any] \| None`): Compile-time type samples.
		100	+ Optional; inferred from `args` / constructor launch args when omitted.
		101	+ - `args` (`Sequence[Any] \| None`): Explicit runtime argument sequence.
		102	+ Optional. Cannot be combined with launch args already stored on the
		103	+ launcher from the first call (`my_kernel(*tensors)`).
		104	+ - `stream` (`Any`, via `**kwargs`): Optional ACL stream handle (often
		105	+ an `int`). When omitted, uses `torch.npu.current_stream` if available;
		106	+ otherwise set `stream=` explicitly or `CATLASS_DSL_NPU_DEVICE`.
		107	+ - `options` (`str`, via `**kwargs`): Public chip name, e.g.
		108	+ `options="--npu-arch 3510"`. May be set on the first call or here;
		109	+ kwargs from this call override values stored when the launcher was
		110	+ constructed.
		111	+
		112	+ Constraints:
		113	+ - Calling `@tla.kernel` returns `KernelLauncher` and does not launch.
		114	+ This method (or calling the launcher) compiles when there is no cached
		115	+ artifact or runtime options changed, then launches; it does not
		116	+ recompile when runtime options are unchanged and a cached artifact
		117	+ exists.
		118	+ - When the first call already passed tensors (`my_kernel(tx, ty)`), pass
		119	+ only launch kwargs such as `block_num` on the second call / `.launch`.
		120	+ - Repeated `.launch` on the same launcher reuses the cached artifact
		121	+ when runtime options are unchanged. Use `tla.compile` when compile and
		122	+ launch must be separated explicitly.
		123	+ - `args=` must not be set if the launcher already holds launch args
		124	+ (`TlaUnsupportedAbiError`).
		125	+ - Launch args must be bound NPU buffers for tensors (`from_dlpack`);
		126	+ `make_fake_tensor` samples are for compile / type samples only.
		127	+ - `block_num` must be an `int` (default `1`).
		128	+
		129	+ Example:
		130	+ ```python
		131	+ @tla.kernel
		132	+ def vadd(src: tla.Tensor, dst: tla.Tensor) -> None:
		133	+ with tla.vector():
		134	+ tla.copy(src, dst)
		135	+
		136	+ vadd(tx, ty, options="--npu-arch 3510")(block_num=1)
		137	+ # or:
		138	+ launcher = vadd(tx, ty, options="--npu-arch 3510")
		139	+ launcher.launch(block_num=1)
		140	+ # or pass args on .launch when the first call had none:
		141	+ vadd(options="--npu-arch 3510").launch(args=(tx, ty), block_num=1)
		142	+ ```
		143	+
		144	+ """
73	launch_kwargs = {self._launch_kwargs, kwargs}	145	launch_kwargs = {self._launch_kwargs, kwargs}
74	if block_num is not None:	146	if block_num is not None:
75	launch_kwargs["block_num"] = block_num	147	launch_kwargs["block_num"] = block_num

Mpython/tla_dsl/catlass/core_api.py+10-3

	@@ -5074,6 +5074,11 @@ def range_constexpr(
5074	Constraints:	5074	Constraints:
5075	- Must be called inside a `@tla.kernel`-decorated kernel function.	5075	- Must be called inside a `@tla.kernel`-decorated kernel function.
5076	- Bounds and step must be compile-time constants for unrollable loops.	5076	- Bounds and step must be compile-time constants for unrollable loops.
		5077	+ - Bounds may come from compile-time Numeric values (for example via
		5078	+ `tla.as_numeric(...)`).
		5079	+ - Emits `DSLOptimizationWarning` when the loop has 64 or more
		5080	+ iterations; expansion continues. Prefer `tla.range(...)` for large
		5081	+ counted loops.
5077		5082
5078	Example:	5083	Example:
5079	```python	5084	```python
	@@ -5226,6 +5231,8 @@ def mmad(
5226	Constraints:	5231	Constraints:
5227	- Must be called inside a `@tla.kernel`-decorated kernel function.	5232	- Must be called inside a `@tla.kernel`-decorated kernel function.
5228	- Must be called inside `tla.cube()`; `acc`/`lhs`/`rhs` must be matching L0 tiles.	5233	- Must be called inside `tla.cube()`; `acc`/`lhs`/`rhs` must be matching L0 tiles.
		5234	+ - Supported element-type routes include `f16`/`bf16`/`f32` pairs and any
		5235	+ `f8e4m3fn` / `f8e5m2` operand pairing, all accumulating into fp32 on L0C.
5229	- `init_c` accepts only a Python `bool` or an `i1` SSA value.	5236	- `init_c` accepts only a Python `bool` or an `i1` SSA value.
5230	- Unknown keyword arguments are not accepted; passing any raises an error.	5237	- Unknown keyword arguments are not accepted; passing any raises an error.
5231		5238
	@@ -7432,9 +7439,9 @@ Parameters:
7432	- `sync_threads()`: Barrier across threads of the enclosing SIMT	7439	- `sync_threads()`: Barrier across threads of the enclosing SIMT
7433	`tla.vec.func` (only inside `mode="simt"`).	7440	`tla.vec.func` (only inside `mode="simt"`).
7434	- `get_capacity_in_bytes(mem_scope)`: Byte capacity of an on-chip memory	7441	- `get_capacity_in_bytes(mem_scope)`: Byte capacity of an on-chip memory
7435	- space for the compile target. Takes a `tla.arch` memory-scope token (`L1` /	7442	+ space for the compile target. Takes a `tla.AddressSpace` token
7436	- `L0A` / `L0B` / `L0C` / `UB`). Returns a plain `int`;	7443	+ (`tla.AddressSpace.l1` / `l0a` / `l0b` / `l0c` / `ub`). Returns a plain
7437	- valid on host and inside a kernel (folds to a constant).	7444	+ `int`; valid on host and inside a kernel (folds to a constant).
7438		7445
7439	Constraints:	7446	Constraints:
7440	- Layout tags / pipe identifiers / memory-scope tokens are ordinary attributes	7447	- Layout tags / pipe identifiers / memory-scope tokens are ordinary attributes

Mpython/tla_dsl/catlass/dsl.py+92-3文件内容审核中，请稍后刷新重试

Mpython/tla_dsl/catlass/execution_lowering.py+45-4

	@@ -771,11 +771,52 @@ _DATACLASS_DEFAULT_ONLY_PARAMS: tuple[tuple[str, object], ...] = (
771		771
772		772
773	def _validate_dataclass_kernel_arg(instance: Any) -> None:	773	def _validate_dataclass_kernel_arg(instance: Any) -> None:
774	- """Reject dataclasses whose stdlib options were customized beyond frozen/kw_only.	774	+ """Directory: Decorators
		775	+ Description:
		776	+ Pack Host-side kernel arguments with the Python stdlib `@dataclass`.
		777	+ Instances created on the Host can be passed to `tla.compile` / launch;
		778	+ fields may also be constructed inside a kernel.
		779	+
		780	+ Parameters:
		781	+ - `frozen` (`bool`): If `True`, instances are immutable. Default
		782	+ `False`.
		783	+ - `kw_only` (`bool`): If `True`, fields must be passed by keyword.
		784	+ Default `False`.
		785	+
		786	+ Constraints:
		787	+ - For kernel arguments, only `frozen` / `kw_only` may be set; other
		788	+ stdlib options such as `slots=True` or `init=False` raise at compile
		789	+ time.
		790	+ - Supported field types:
		791	+
		792	+ \| Kind \| Types \| Constraints \|
		793	+ \| --- \| --- \| --- \|
		794	+ \| Tensor \| `tla.Tensor` \| No dynamic-GM; use a static tensor field or a top-level tensor argument \|
		795	+ \| Python scalars \| `bool` / `int` / `float` \| — \|
		796	+ \| `tla` scalars \| `Bool`, `Int8/16/32/64`, `UInt8/16/32/64`, `Float16/32`, `BFloat16` \| — \|
		797	+ \| Compile-time \| `tla.Constexpr[...]` \| Not in kernel ABI / IR; read-only inside the kernel \|
		798	+
		799	+ Example:
		800	+ ```python
		801	+ from dataclasses import dataclass
		802	+ import catlass.tla as tla
		803	+
		804	+ @dataclass(frozen=True, kw_only=True)
		805	+ class TilingData:
		806	+ TILE_M: tla.Constexpr[int]
		807	+ tiling_int: int
		808	+ out: tla.Tensor
		809	+
		810	+ @tla.kernel
		811	+ def struct_arg_kernel(tiling: TilingData) -> None:
		812	+ # TILE_M is a compile-time constant; tiling_int is a runtime scalar.
		813	+ ...
		814	+
		815	+ tiling = TilingData(TILE_M=128, tiling_int=64, out=tout)
		816	+ artifact = tla.compile(struct_arg_kernel, tiling, options="--npu-arch 3510")
		817	+ artifact(tiling, block_num=1)
		818	+ ```
775		819
776	- The TLA frontend unpacks dataclass fields as kernel arguments and assumes the
777	- default dataclass semantics; options such as ``slots=True`` or ``init=False``
778	- would silently diverge from that, so they are rejected at compile time.
779	"""	820	"""
780	cls = type(instance)	821	cls = type(instance)
781	params = getattr(cls, "__dataclass_params__", None)	822	params = getattr(cls, "__dataclass_params__", None)

Mpython/tla_dsl/catlass/tla/runtime.py+127-53

	@@ -272,14 +272,33 @@ class _Tensor(TensorABC):
272	raise RuntimeError("Tensor buffer is not bound; use from_dlpack first.")	272	raise RuntimeError("Tensor buffer is not bound; use from_dlpack first.")
273		273
274	def mark_layout_dynamic(self, leading_dim: int \| None = None) -> "_Tensor":	274	def mark_layout_dynamic(self, leading_dim: int \| None = None) -> "_Tensor":
275	- """Mark shape/stride layout metadata dynamic.	275	+ """Directory: Host Tensor / Dynamic Layout
		276	+ Description:
		277	+ Mark every shape mode dynamic so one compiled artifact can run at
		278	+ different extents. Strides become dynamic except the leading dimension
		279	+ (stride stays `1`). Broadcast strides of `0` are kept. Matching
		280	+ `origin_shape` leaves become dynamic so the compile type no longer
		281	+ depends on concrete DLPack extents.
		282	+
		283	+ Parameters:
		284	+ - `leading_dim` (`int \| None`): Index of the unit-stride (leading)
		285	+ dimension. Optional; default `None` (inferred from `layout_tag` or
		286	+ compact stride order).
		287	+
		288	+ Constraints:
		289	+ - In-place; returns `self` (chainable).
		290	+ - All `coord` leaves must be `0`; sliced views are rejected.
		291	+ - `leading_dim` must have stride `1`.
		292	+ - For NZFamily layouts, each two-leaf physical shape group maps to one
		293	+ logical `origin_shape` axis.
		294	+
		295	+ Example:
		296	+ ```python
		297	+ ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
		298	+ ta = ta.mark_layout_dynamic()
		299	+ artifact = tla.compile(my_kernel, ta, options="--npu-arch 3510")
		300	+ ```
276		301
277	- All shape modes become dynamic. Strides become dynamic except the leading
278	- dimension, which keeps stride ``1``. Broadcast strides of ``0`` are
279	- preserved. Matching ``origin_shape`` leaves become dynamic as well so the
280	- compile type no longer depends on concrete DLPack extents. For NZFamily
281	- layouts, each two-leaf physical shape group maps to one logical
282	- ``origin_shape`` axis.
283	"""	302	"""
284	# Dynamic GM ABI hard-codes root coord/offset 0 (same rule as	303	# Dynamic GM ABI hard-codes root coord/offset 0 (same rule as
285	# TlaLowerFuncPass::validateKernelTensorArg).	304	# TlaLowerFuncPass::validateKernelTensorArg).
	@@ -329,15 +348,32 @@ class _Tensor(TensorABC):
329	mode: int,	348	mode: int,
330	stride_order: tuple[int, ...] \| None = None,	349	stride_order: tuple[int, ...] \| None = None,
331	) -> "_Tensor":	350	) -> "_Tensor":
332	- """Mark one compact shape mode dynamic.	351	+ """Directory: Host Tensor / Dynamic Layout
		352	+ Description:
		353	+ Mark one compact shape mode dynamic. Strides of modes major to `mode`
		354	+ (whose compact stride product includes that extent) become dynamic as
		355	+ well. Matching `origin_shape` leaves are marked so the compile type does
		356	+ not depend on the concrete size.
333		357
334	- Propagates dynamic extents to strides of modes that are major to ``mode``	358	+ Parameters:
335	- (their stride is a product that includes the marked extent).	359	+ - `mode` (`int`): Flattened shape-leaf index to mark dynamic
		360	+ (0-based). Required.
		361	+ - `stride_order` (`tuple[int, ...] \| None`): Compact stride order
		362	+ (outer → inner). Optional; inferred from current strides when omitted.
		363	+
		364	+ Constraints:
		365	+ - In-place; returns `self`.
		366	+ - All `coord` leaves must be `0`.
		367	+ - `stride_order` must be a permutation of `range(rank)`.
		368	+ - For NZFamily layouts, physical modes 0/1 map to logical M and modes
		369	+ 2/3 map to logical N.
		370	+
		371	+ Example:
		372	+ ```python
		373	+ ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
		374	+ ta = ta.mark_compact_shape_dynamic(mode=0)
		375	+ ```
336		376
337	- Matching ``origin_shape`` leaves become dynamic with the shape modes so
338	- the compile type stays independent of concrete problem sizes. For
339	- NZFamily layouts, physical modes 0/1 map to logical M and modes 2/3 map
340	- to logical N.
341	"""	377	"""
342	coord_leaves = _flat_layout_leaves(self.coord, allow_dynamic=True)	378	coord_leaves = _flat_layout_leaves(self.coord, allow_dynamic=True)
343	if any(leaf is None for leaf in coord_leaves) or not all(	379	if any(leaf is None for leaf in coord_leaves) or not all(
	@@ -595,39 +631,52 @@ def from_dlpack(
595	stream: int \| None = -1,	631	stream: int \| None = -1,
596	element_type: type \| None = None,	632	element_type: type \| None = None,
597	) -> _Tensor:	633	) -> _Tensor:
598	- """Convert a DLPack object to a TLA runtime tensor (zero-copy).	634	+ """Directory: Host Tensor / Binding
		635	+ Description:
		636	+ Bind a DLPack NPU tensor to a TLA Host tensor (zero-copy). The returned
		637	+ object shares the device buffer of `tensor_dlpack`.
599		638
600	- ``tensor_dlpack`` must export an Ascend/NPU tensor (e.g. ``torch_npu``). CPU /	639	+ Parameters:
601	- NumPy buffers are not supported. ``layout_tag`` must be a ``tla.arch`` layout tag	640	+ - `tensor_dlpack` (`object`): Object implementing `__dlpack__()`. Must
602	- (e.g. ``tla.arch.ColumnMajor``).	641	+ be an Ascend/NPU buffer (e.g. `torch_npu`). CPU / NumPy are rejected.
		642	+ Required.
		643	+ - `layout_tag` (`tla.arch.*`): Layout tag such as `tla.arch.RowMajor`,
		644	+ `tla.arch.ColumnMajor`, `tla.arch.zN`. Required.
		645	+ - `origin_shape` (`tuple \| int \| None`): Logical origin as a Python int
		646	+ tree. Optional; derived from the DLPack physical shape and `layout_tag`
		647	+ when omitted. Not a Kernel `tla.make_shape`.
		648	+ - `assumed_align` (`int \| None`): Reserved; currently unused.
		649	+ - `stream` (`int \| None`): Passed to `__dlpack__(stream=...)`. Default
		650	+ `-1` (no stream sync). `None` omits the `stream` argument.
		651	+ - `element_type` (`type \| None`): Optional override for the element
		652	+ type inferred from DLPack. Default `None` keeps the DLPack type.
		653	+ Use when DLPack cannot express the real type (e.g. fp8): pass
		654	+ `tla.Float8E4M3FN` / `Float8E5M2`. Must have the same per-element
		655	+ bit width as the exported buffer.
603		656
604	- When ``origin_shape`` is omitted, logical ``origin_shape`` is derived from the	657	+ Constraints:
605	- DLPack physical shape/strides and ``layout_tag``. For dense 2-D buffers the	658	+ - Ownership follows the DLPack consumer contract: the capsule is consumed
606	- physical storage must match ``basic_matmul`` preparation: ``tensor.contiguous()``	659	+ and its deleter runs when the returned tensor is destroyed. A reference
607	- for ``RowMajor``, or ``tensor.permute(1, 0).contiguous()`` for ``ColumnMajor``	660	+ to `tensor_dlpack` is also retained, so a temporary source such as
608	- (row-major physical on the permuted shape). When ``origin_shape`` is provided	661	+ `from_dlpack(x.contiguous().to(device), ...)` is safe.
609	- it is used directly and DLPack stride derivation is skipped. Shape / stride metadata	662	+ - A capsule is single-use; passing an already-consumed capsule raises
610	- come from the logical origin and ``layout_tag`` via layout remap, not from raw	663	+ `RuntimeTensorError`. Call `from_dlpack` again for another binding.
611	- DLPack fields. Use :meth:`_Tensor.mark_layout_dynamic` /	664	+ - 2-D `RowMajor` requires `tensor.contiguous()`. 2-D `ColumnMajor`
612	- :meth:`_Tensor.mark_compact_shape_dynamic` when dynamic layout metadata is required.	665	+ requires `tensor.permute(1, 0).contiguous()`. A mismatch raises
		666	+ `RuntimeTensorError`. Providing `origin_shape` skips that check.
		667	+ - Default layout is static. Call `mark_layout_dynamic` /
		668	+ `mark_compact_shape_dynamic` for dynamic extents.
		669	+ - When `element_type` is set, its per-element bit width must match the
		670	+ exported DLPack buffer.
613		671
614	- Ownership follows the DLPack consumer contract: the exported capsule is consumed	672	+ Example:
615	- (renamed to ``used_dltensor``) and its ``DLManagedTensor`` deleter is called when	673	+ ```python
616	- the returned tensor is destroyed, so the allocation lives exactly as long as the	674	+ tx = from_dlpack(x.contiguous(), layout_tag=tla.arch.RowMajor)
617	- tensor pointing at it. A reference to ``tensor_dlpack`` is retained as well, which	675	+ ty = from_dlpack(
618	- covers producers whose deleter is a no-op. A temporary source such as	676	+ y.permute(1, 0).contiguous(),
619	- ``tla.from_dlpack(x.contiguous().to(device), ...)`` is therefore safe.	677	+ layout_tag=tla.arch.ColumnMajor,
620	-	678	+ )
621	- Because the capsule is consumed, it cannot be handed to a second consumer: a	679	+ ```
622	- capsule is single-use, and passing an already-consumed one raises
623	- :class:`RuntimeTensorError`. Call ``__dlpack__()`` again (or ``from_dlpack``
624	- again on the same producer) for another binding.
625	-
626	- ``element_type`` overrides the element type derived from the DLPack dtype,
627	- for formats DLPack cannot describe. The override must have the same storage
628	- width as the exported dtype, so shape and stride derivation is unaffected.
629	- torch cannot export fp8 over DLPack at all, so an fp8 buffer is handed over
630	- as its ``int8`` view plus ``element_type=tla.Float8E4M3FN`` / ``Float8E5M2``.
631	"""	680	"""
632	from ..base_dsl.runtime.dlpack_types import DLDataTypeCode	681	from ..base_dsl.runtime.dlpack_types import DLDataTypeCode
633	from ..base_dsl.typing import (	682	from ..base_dsl.typing import (
	@@ -817,18 +866,43 @@ def make_fake_tensor(
817	coord: Iterable[Any] \| None = None,	866	coord: Iterable[Any] \| None = None,
818	assumed_align: int \| None = None,	867	assumed_align: int \| None = None,
819	) -> _Tensor:	868	) -> _Tensor:
820	- """Create a metadata-only Host fake tensor (no device buffer).	869	+ """Directory: Host Tensor / Binding
		870	+ Description:
		871	+ Build a metadata-only Host tensor with no device buffer (`data_ptr == 0`).
		872	+ Use this as a `tla.compile` type sample when no NPU is needed. Bind real
		873	+ buffers with `from_dlpack`.
821		874
822	- Always unbound: ``data_ptr`` is forced to ``0`` and the tensor is not	875	+ Parameters:
823	- externally bound. Use :func:`from_dlpack` for real NPU buffers.	876	+ - `dtype`: Element type such as `tla.Float16` / `tla.Float32`. Required.
		877	+ - `shape` (`int \| tuple`): Logical shape tree (nested tuples for zN
		878	+ physical layouts). Required.
		879	+ - `stride` (`int \| tuple`): Stride tree; structure must match `shape`.
		880	+ Required.
		881	+ - `layout_tag`: `tla.arch` tag. Optional; default `tla.arch.RowMajor`.
		882	+ - `addrspace`: Address space. Optional; default `AddressSpace.gm`.
		883	+ - `origin_shape` (`int \| tuple \| None`): Logical origin. Optional;
		884	+ defaults to `shape`.
		885	+ - `coord` (`int \| tuple \| None`): Coordinate tree. Optional; derived
		886	+ from the layout when omitted (typically zeros).
		887	+ - `assumed_align` (`int \| None`): Reserved; currently unused.
824		888
825	- Positional arguments are ``(dtype, shape, stride)``. ``layout_tag`` defaults	889	+ Constraints:
826	- to ``tla.arch.RowMajor``. Explicit ``shape`` / ``stride`` are kept as given	890	+ - `shape` / `stride` / `origin_shape` / `coord` are Python int trees,
827	- (no layout remap). ``origin_shape`` defaults to ``shape`` when omitted.	891	+ not Kernel `tla.make_shape` / `tla.make_stride` / `tla.make_coord`.
		892	+ - Always unbound; cannot be launched until replaced by `from_dlpack`.
		893	+ - Explicit `shape` / `stride` are kept as given (no layout remap).
828		894
829	- Opens an internal capture session so callers only use this helper.	895	+ Example:
830	- Host args are int / nested-int trees (not Kernel ``make_shape`` /	896	+ ```python
831	- ``make_coord`` / ``make_stride``).	897	+ fa = make_fake_tensor(tla.Float16, (128, 64), (64, 1))
		898	+ fzn = make_fake_tensor(
		899	+ tla.Float16,
		900	+ ((16, 2), (16, 4)),
		901	+ ((16, 256), (1, 512)),
		902	+ layout_tag=tla.arch.zN,
		903	+ origin_shape=(32, 64),
		904	+ )
		905	+ ```
832	"""	906	"""
833	from ..runtime import _eager_capture	907	from ..runtime import _eager_capture
834		908

Apython/tla_dsl/docs/en/api/host_api_reference.md+632-0

@@ -0,0 +1,632 @@
	1	+<!--
	2	+This file is generated by python/tla_dsl/tools/generate_host_api_reference.py.
	3	+Do not edit manually. Update Host docstrings in catlass/dsl.py,
	4	+catlass/base_dsl/compiler.py, catlass/base_dsl/jit_executor.py,
	5	+catlass/catlass_dsl/tla.py, catlass/execution_lowering.py,
	6	+and catlass/tla/runtime.py.
	7	+-->
	8	+
	9	+# TLA DSL Host API Reference
	10	+
	11	+This document describes the TLA DSL Host-side APIs (typically imported as `import catlass.tla as tla`). It covers the `@tla.kernel` decorator, Host `@dataclass` packing, `tla.compile` / `KernelLauncher` launch, and Host tensors. Environment variables are in `docs/zh/kernel_development/core_concepts/env_vars.md`. Kernel-side ops live in `docs/en/api/kernel_api_reference.md`.
	12	+
	13	+Interface descriptions and examples come from each API's source docstring (`Directory:` plus `Description:` / `Parameters:` / `Constraints:` / `Example:`).
	14	+
	15	+These APIs are called from Python Host scripts, outside a `@tla.kernel` function body.
	16	+
	17	+---
	18	+
	19	+## Table of Contents
	20	+
	21	+- [1. Decorators](#1-decorators)
	22	+- [2. Compile and Launch](#2-compile-and-launch)
	23	+ - [2.1 Compile](#21-compile)
	24	+ - [2.2 Launch](#22-launch)
	25	+ - [2.3 Inspect](#23-inspect)
	26	+- [3. Host Tensor](#3-host-tensor)
	27	+ - [3.1 Binding](#31-binding)
	28	+ - [3.2 Dynamic Layout](#32-dynamic-layout)
	29	+
	30	+---
	31	+
	32	+## 1. Decorators
	33	+
	34	+Host-side `@tla.kernel` entry, plus Host `@dataclass` packing. The decorated kernel body is not executed on the Host.
	35	+
	36	+### `kernel`
	37	+
	38	+Source: [`catlass.dsl.kernel`](../../../catlass/dsl.py#L305)
	39	+
	40	+Description:
	41	+
	42	+Mark a Python function as a TLA kernel entry. The function body is not
	43	+executed on the Host. Returns a `TlaJitFunction`. Calling that object
	44	+returns a `KernelLauncher` without launching; call the launcher or
	45	+`.launch(...)` to compile and run.
	46	+
	47	+Prototype:
	48	+
	49	+```python
	50	+tla.kernel(fn: Callable[..., Any] \| None = None, *, auto_sync: str \| None = None) -> TlaJitFunction \| Callable[[Callable[..., Any]], TlaJitFunction]
	51	+```
	52	+
	53	+Parameters:
	54	+
	55	+- `fn` (`Callable[..., Any] \| None`): The function being decorated.
	56	+ Use `@tla.kernel` or `@tla.kernel(auto_sync=...)`; call `tla.kernel(fn)`
	57	+ only when decorator syntax is unavailable.
	58	+- `auto_sync` (`str \| None`): Optional. `"v0"` inserts automatic local
	59	+ mutexes. Default `None` (synchronization stays explicit).
	60	+
	61	+Constraints:
	62	+
	63	+- The decorated function must not be defined with Python `async def`.
	64	+- `auto_sync` must be `"v0"` or `None`.
	65	+- Kernel parameter types:
	66	+
	67	+ \| Kind \| Types \|
	68	+ \| --- \| --- \|
	69	+ \| Tensor \| `tla.Tensor` \|
	70	+ \| Python scalars \| `bool` / `int` / `float` \|
	71	+ \| `tla` scalars \| `Bool`, `Int8/16/32/64`, `UInt8/16/32/64`, `Float16/32`, `BFloat16` \|
	72	+ \| Compile-time \| `tla.Constexpr[...]` \|
	73	+ \| Struct \| `@dataclass` whose fields are among the above \|
	74	+
	75	+Example:
	76	+
	77	+```python
	78	+@tla.kernel
	79	+def vadd(src: tla.Tensor, dst: tla.Tensor) -> None:
	80	+ with tla.vector():
	81	+ tla.copy(src, dst)
	82	+
	83	+@tla.kernel(auto_sync="v0")
	84	+def vadd_auto(src: tla.Tensor, dst: tla.Tensor) -> None:
	85	+ with tla.vector():
	86	+ tla.copy(src, dst)
	87	+
	88	+vadd(tx, ty, options="--npu-arch 3510")(block_num=1)
	89	+```
	90	+
	91	+---
	92	+
	93	+### `dataclass`
	94	+
	95	+Source: [`dataclasses.dataclass`](../../../catlass/execution_lowering.py#L773)
	96	+
	97	+Description:
	98	+
	99	+Pack Host-side kernel arguments with the Python stdlib `@dataclass`.
	100	+Instances created on the Host can be passed to `tla.compile` / launch;
	101	+fields may also be constructed inside a kernel.
	102	+
	103	+Prototype:
	104	+
	105	+```python
	106	+dataclasses.dataclass(cls: type, *, frozen: bool = False, kw_only: bool = False) -> type
	107	+```
	108	+
	109	+Parameters:
	110	+
	111	+- `frozen` (`bool`): If `True`, instances are immutable. Default
	112	+ `False`.
	113	+- `kw_only` (`bool`): If `True`, fields must be passed by keyword.
	114	+ Default `False`.
	115	+
	116	+Constraints:
	117	+
	118	+- For kernel arguments, only `frozen` / `kw_only` may be set; other
	119	+ stdlib options such as `slots=True` or `init=False` raise at compile
	120	+ time.
	121	+- Supported field types:
	122	+
	123	+ \| Kind \| Types \| Constraints \|
	124	+ \| --- \| --- \| --- \|
	125	+ \| Tensor \| `tla.Tensor` \| No dynamic-GM; use a static tensor field or a top-level tensor argument \|
	126	+ \| Python scalars \| `bool` / `int` / `float` \| — \|
	127	+ \| `tla` scalars \| `Bool`, `Int8/16/32/64`, `UInt8/16/32/64`, `Float16/32`, `BFloat16` \| — \|
	128	+ \| Compile-time \| `tla.Constexpr[...]` \| Not in kernel ABI / IR; read-only inside the kernel \|
	129	+
	130	+Example:
	131	+
	132	+```python
	133	+from dataclasses import dataclass
	134	+import catlass.tla as tla
	135	+
	136	+@dataclass(frozen=True, kw_only=True)
	137	+class TilingData:
	138	+ TILE_M: tla.Constexpr[int]
	139	+ tiling_int: int
	140	+ out: tla.Tensor
	141	+
	142	+@tla.kernel
	143	+def struct_arg_kernel(tiling: TilingData) -> None:
	144	+ # TILE_M is a compile-time constant; tiling_int is a runtime scalar.
	145	+ ...
	146	+
	147	+tiling = TilingData(TILE_M=128, tiling_int=64, out=tout)
	148	+artifact = tla.compile(struct_arg_kernel, tiling, options="--npu-arch 3510")
	149	+artifact(tiling, block_num=1)
	150	+```
	151	+
	152	+---
	153	+
	154	+## 2. Compile and Launch
	155	+
	156	+Compile a decorated kernel and launch it on the NPU. Use `tla.compile` then `artifact(...)` / `.launch(...)` when the same binary is launched repeatedly; call `@tla.kernel` to get a `KernelLauncher` for one-off or few launches. Cache / arch / IR-dump knobs that are not function arguments are in `docs/zh/kernel_development/core_concepts/env_vars.md`.
	157	+
	158	+### 2.1 Compile
	159	+
	160	+Build a device binary. Primary entry: `tla.compile`. `TlaJitFunction.compile` is a lower-level helper on the decorated function.
	161	+
	162	+#### `compile`
	163	+
	164	+Source: [`catlass.base_dsl.compiler.CompileCallable.__call__`](../../../catlass/base_dsl/compiler.py#L46)
	165	+
	166	+Description:
	167	+
	168	+Compile a `@tla.kernel` function and return a callable executor wrapping
	169	+the `TlaKernelArtifact`. This is the public `tla.compile` entry. Call the
	170	+returned executor to launch (`artifact(*tensors, block_num=...)`). Use
	171	+this path when you compile once and launch the same binary repeatedly.
	172	+
	173	+Prototype:
	174	+
	175	+```python
	176	+tla.compile(func: Any, args: Any, *kwargs: Any) -> TlaJitExecutor
	177	+```
	178	+
	179	+Parameters:
	180	+
	181	+- `func` (`TlaJitFunction`): Decorated `@tla.kernel` function. Required.
	182	+- `args` (`Any`): Host tensors / scalars / `@dataclass` instances used
	183	+ as compile type samples (e.g. `from_dlpack` or `make_fake_tensor`
	184	+ results).
	185	+- `kwargs`: Host compile kwargs. Pass `options="--npu-arch 3510"` to
	186	+ select the public chip name. Cache / IR dump / force-recompile use
	187	+ `CATLASS_DSL_*` environment variables.
	188	+
	189	+Constraints:
	190	+
	191	+- `func` must be a `@tla.kernel` `TlaJitFunction`.
	192	+- `args` are compile-time type samples; they need not be bound NPU
	193	+ buffers (`make_fake_tensor` is valid).
	194	+- Pass the public chip name with `options="--npu-arch 3510"`;
	195	+ unsupported tokens raise at compile time.
	196	+- Launch kwargs such as `block_num` / `stream` belong on the returned
	197	+ executor (`artifact(...)` / `TlaJitExecutor.launch`), not on
	198	+ `tla.compile`.
	199	+
	200	+Example:
	201	+
	202	+```python
	203	+artifact = tla.compile(vadd, tx, ty, options="--npu-arch 3510")
	204	+artifact(tx, ty, block_num=1)
	205	+artifact(tx, ty, block_num=1) # launch again with the same binary
	206	+```
	207	+
	208	+---
	209	+
	210	+#### `TlaJitFunction.compile`
	211	+
	212	+Source: [`catlass.dsl.TlaJitFunction.compile`](../../../catlass/dsl.py#L195)
	213	+
	214	+Description:
	215	+
	216	+Compile this `@tla.kernel` function and return a `TlaKernelArtifact`.
	217	+Use `tla.compile(fn, *args, options=...)` as the usual Host entry; call
	218	+`.compile()` only when you already hold a `TlaJitFunction` and need the
	219	+raw `TlaKernelArtifact`.
	220	+
	221	+Prototype:
	222	+
	223	+```python
	224	+TlaJitFunction.compile(, type_args: Sequence[Any] \| None = None, *kwargs: Any) -> TlaKernelArtifact
	225	+```
	226	+
	227	+Parameters:
	228	+
	229	+- `type_args` (`Sequence[Any] \| None`): Host tensors / scalars used as
	230	+ compile type samples. Optional; default `None` (no tensor
	231	+ specialization).
	232	+- `kwargs`: Host compile kwargs. Pass `options="--npu-arch 3510"` to
	233	+ select the public chip name. Cache / IR-dump knobs use `CATLASS_DSL_*`
	234	+ environment variables.
	235	+
	236	+Constraints:
	237	+
	238	+- `type_args` are compile-time type samples; they need not be bound NPU
	239	+ buffers (`make_fake_tensor` is valid).
	240	+- Pass the public chip name with `options="--npu-arch 3510"`;
	241	+ unsupported tokens raise at compile time.
	242	+
	243	+Example:
	244	+
	245	+```python
	246	+artifact = my_kernel.compile(
	247	+ type_args=[tx, ty],
	248	+ options="--npu-arch 3510",
	249	+)
	250	+```
	251	+
	252	+---
	253	+
	254	+### 2.2 Launch
	255	+
	256	+Run a compiled kernel on the NPU. After `tla.compile`, call the executor or `TlaJitExecutor.launch`. After calling `@tla.kernel`, use `KernelLauncher.launch` (or invoke the launcher).
	257	+
	258	+#### `TlaJitExecutor.launch`
	259	+
	260	+Source: [`catlass.base_dsl.jit_executor.TlaJitExecutor.launch`](../../../catlass/base_dsl/jit_executor.py#L99)
	261	+
	262	+Description:
	263	+
	264	+Launch a compiled kernel on the NPU after `tla.compile`, passing runtime
	265	+kernel arguments and launch options (for example `block_num`, `stream`).
	266	+
	267	+Prototype:
	268	+
	269	+```python
	270	+TlaJitExecutor.launch(launch_args: Any, , block_num: int \| None = None, args: Sequence[Any] \| None = None, **kwargs: Any) -> TlaExecutionResult
	271	+```
	272	+
	273	+Parameters:
	274	+
	275	+- `launch_args` (`Any`): Positional runtime kernel arguments matching
	276	+ the `@tla.kernel` signature (bound Host tensors, scalars, or
	277	+ `@dataclass` instances). Mutually exclusive with `args=`.
	278	+- `block_num` (`int \| None`): Number of blocks to launch. Optional;
	279	+ default `1`. Must be an `int` when provided.
	280	+- `args` (`Sequence[Any] \| None`): Explicit runtime argument sequence.
	281	+ Optional; default `None`. Cannot be combined with non-empty
	282	+ `*launch_args`.
	283	+- `stream` (`Any`, via `**kwargs`): Optional ACL stream handle (often
	284	+ an `int`). When omitted, uses `torch.npu.current_stream` if available;
	285	+ otherwise set `stream=` explicitly or `CATLASS_DSL_NPU_DEVICE`.
	286	+
	287	+Constraints:
	288	+
	289	+- `artifact(...)` and `.launch(...)` share the same runtime rules.
	290	+- `*launch_args` and `args=` must not both be non-empty
	291	+ (`TlaUnsupportedAbiError`).
	292	+- Launch args must be bound NPU buffers for tensors (`from_dlpack`);
	293	+ `make_fake_tensor` samples are for compile only.
	294	+- `block_num` must be an `int` (default `1`).
	295	+
	296	+Example:
	297	+
	298	+```python
	299	+artifact = tla.compile(vadd, tx, ty, options="--npu-arch 3510")
	300	+artifact(tx, ty, block_num=1)
	301	+# same as:
	302	+artifact.launch(tx, ty, block_num=1)
	303	+# or pass args explicitly:
	304	+artifact.launch(args=(tx, ty), block_num=1)
	305	+```
	306	+
	307	+---
	308	+
	309	+#### `KernelLauncher.launch`
	310	+
	311	+Source: [`catlass.catlass_dsl.tla.KernelLauncher.launch`](../../../catlass/catlass_dsl/tla.py#L75)
	312	+
	313	+Description:
	314	+
	315	+Launch a `@tla.kernel` on the NPU. Obtain this object by calling the
	316	+decorated kernel (`launcher = my_kernel(*tensors, options=...)`); that
	317	+call does not launch. Then call `launcher.launch(...)` or invoke the
	318	+launcher (`launcher(block_num=...)`, equivalent to
	319	+`.launch(args=..., **kwargs)`). Compiles when there is no cached artifact
	320	+or runtime options changed; reuses the cached artifact when runtime
	321	+options are unchanged. To compile once and launch repeatedly with compile
	322	+and launch separated, use `tla.compile` and the returned
	323	+`TlaJitExecutor`.
	324	+
	325	+Prototype:
	326	+
	327	+```python
	328	+KernelLauncher.launch(, block_num: int \| None = None, type_args: Sequence[Any] \| None = None, args: Sequence[Any] \| None = None, *kwargs: Any) -> TlaExecutionResult
	329	+```
	330	+
	331	+Parameters:
	332	+
	333	+- `block_num` (`int \| None`): Number of blocks to launch. Optional;
	334	+ default `1` (also taken from kwargs stored when the launcher was
	335	+ constructed). Must be an `int` when provided.
	336	+- `type_args` (`Sequence[Any] \| None`): Compile-time type samples.
	337	+ Optional; inferred from `args` / constructor launch args when omitted.
	338	+- `args` (`Sequence[Any] \| None`): Explicit runtime argument sequence.
	339	+ Optional. Cannot be combined with launch args already stored on the
	340	+ launcher from the first call (`my_kernel(*tensors)`).
	341	+- `stream` (`Any`, via `**kwargs`): Optional ACL stream handle (often
	342	+ an `int`). When omitted, uses `torch.npu.current_stream` if available;
	343	+ otherwise set `stream=` explicitly or `CATLASS_DSL_NPU_DEVICE`.
	344	+- `options` (`str`, via `**kwargs`): Public chip name, e.g.
	345	+ `options="--npu-arch 3510"`. May be set on the first call or here;
	346	+ kwargs from this call override values stored when the launcher was
	347	+ constructed.
	348	+
	349	+Constraints:
	350	+
	351	+- Calling `@tla.kernel` returns `KernelLauncher` and does not launch.
	352	+ This method (or calling the launcher) compiles when there is no cached
	353	+ artifact or runtime options changed, then launches; it does not
	354	+ recompile when runtime options are unchanged and a cached artifact
	355	+ exists.
	356	+- When the first call already passed tensors (`my_kernel(tx, ty)`), pass
	357	+ only launch kwargs such as `block_num` on the second call / `.launch`.
	358	+- Repeated `.launch` on the same launcher reuses the cached artifact
	359	+ when runtime options are unchanged. Use `tla.compile` when compile and
	360	+ launch must be separated explicitly.
	361	+- `args=` must not be set if the launcher already holds launch args
	362	+ (`TlaUnsupportedAbiError`).
	363	+- Launch args must be bound NPU buffers for tensors (`from_dlpack`);
	364	+ `make_fake_tensor` samples are for compile / type samples only.
	365	+- `block_num` must be an `int` (default `1`).
	366	+
	367	+Example:
	368	+
	369	+```python
	370	+@tla.kernel
	371	+def vadd(src: tla.Tensor, dst: tla.Tensor) -> None:
	372	+ with tla.vector():
	373	+ tla.copy(src, dst)
	374	+
	375	+vadd(tx, ty, options="--npu-arch 3510")(block_num=1)
	376	+# or:
	377	+launcher = vadd(tx, ty, options="--npu-arch 3510")
	378	+launcher.launch(block_num=1)
	379	+# or pass args on .launch when the first call had none:
	380	+vadd(options="--npu-arch 3510").launch(args=(tx, ty), block_num=1)
	381	+```
	382	+
	383	+---
	384	+
	385	+### 2.3 Inspect
	386	+
	387	+Dump frontend TLA IR without building a device binary or launching. See `TlaJitFunction.dump_mlir`.
	388	+
	389	+#### `TlaJitFunction.dump_mlir`
	390	+
	391	+Source: [`catlass.dsl.TlaJitFunction.dump_mlir`](../../../catlass/dsl.py#L253)
	392	+
	393	+Description:
	394	+
	395	+Return the TLA IR (`tlair`) MLIR text for this kernel. Does not compile
	396	+to a device binary and does not launch.
	397	+
	398	+Prototype:
	399	+
	400	+```python
	401	+TlaJitFunction.dump_mlir(*, type_args: Sequence[Any] \| None = None) -> str
	402	+```
	403	+
	404	+Parameters:
	405	+
	406	+- `type_args` (`Sequence[Any] \| None`): Host tensors / scalars used as
	407	+ type samples, same as `.compile()`. Optional; default `None`.
	408	+
	409	+Constraints:
	410	+
	411	+- `type_args` follow the same rules as `.compile()`.
	412	+- The returned string is frontend TLA IR (`tlair`), not the HIVM/LLVM
	413	+ form stored on `TlaKernelArtifact.lowered_llvm`.
	414	+
	415	+Example:
	416	+
	417	+```python
	418	+text = my_kernel.dump_mlir(type_args=[fa, fb])
	419	+print(text[:500])
	420	+```
	421	+
	422	+---
	423	+
	424	+## 3. Host Tensor
	425	+
	426	+Build Host `tla.Tensor` objects and mark layout extents dynamic so one artifact can run at different shapes. See also `docs/zh/kernel_development/core_concepts/layout.md`.
	427	+
	428	+### 3.1 Binding
	429	+
	430	+Bind a real NPU buffer with `from_dlpack`, or a metadata-only sample with `make_fake_tensor`.
	431	+
	432	+#### `from_dlpack`
	433	+
	434	+Source: [`catlass.tla.runtime.from_dlpack`](../../../catlass/tla/runtime.py#L625)
	435	+
	436	+Description:
	437	+
	438	+Bind a DLPack NPU tensor to a TLA Host tensor (zero-copy). The returned
	439	+object shares the device buffer of `tensor_dlpack`.
	440	+
	441	+Prototype:
	442	+
	443	+```python
	444	+tla.from_dlpack(tensor_dlpack: object, *, layout_tag: Any, origin_shape: Any \| None = None, assumed_align: int \| None = None, stream: int \| None = -1, element_type: type \| None = None) -> _Tensor
	445	+```
	446	+
	447	+Parameters:
	448	+
	449	+- `tensor_dlpack` (`object`): Object implementing `__dlpack__()`. Must
	450	+ be an Ascend/NPU buffer (e.g. `torch_npu`). CPU / NumPy are rejected.
	451	+ Required.
	452	+- `layout_tag` (`tla.arch.*`): Layout tag such as `tla.arch.RowMajor`,
	453	+ `tla.arch.ColumnMajor`, `tla.arch.zN`. Required.
	454	+- `origin_shape` (`tuple \| int \| None`): Logical origin as a Python int
	455	+ tree. Optional; derived from the DLPack physical shape and `layout_tag`
	456	+ when omitted. Not a Kernel `tla.make_shape`.
	457	+- `assumed_align` (`int \| None`): Reserved; currently unused.
	458	+- `stream` (`int \| None`): Passed to `__dlpack__(stream=...)`. Default
	459	+ `-1` (no stream sync). `None` omits the `stream` argument.
	460	+- `element_type` (`type \| None`): Optional override for the element
	461	+ type inferred from DLPack. Default `None` keeps the DLPack type.
	462	+ Use when DLPack cannot express the real type (e.g. fp8): pass
	463	+ `tla.Float8E4M3FN` / `Float8E5M2`. Must have the same per-element
	464	+ bit width as the exported buffer.
	465	+
	466	+Constraints:
	467	+
	468	+- Ownership follows the DLPack consumer contract: the capsule is consumed
	469	+ and its deleter runs when the returned tensor is destroyed. A reference
	470	+ to `tensor_dlpack` is also retained, so a temporary source such as
	471	+ `from_dlpack(x.contiguous().to(device), ...)` is safe.
	472	+- A capsule is single-use; passing an already-consumed capsule raises
	473	+ `RuntimeTensorError`. Call `from_dlpack` again for another binding.
	474	+- 2-D `RowMajor` requires `tensor.contiguous()`. 2-D `ColumnMajor`
	475	+ requires `tensor.permute(1, 0).contiguous()`. A mismatch raises
	476	+ `RuntimeTensorError`. Providing `origin_shape` skips that check.
	477	+- Default layout is static. Call `mark_layout_dynamic` /
	478	+ `mark_compact_shape_dynamic` for dynamic extents.
	479	+- When `element_type` is set, its per-element bit width must match the
	480	+ exported DLPack buffer.
	481	+
	482	+Example:
	483	+
	484	+```python
	485	+tx = from_dlpack(x.contiguous(), layout_tag=tla.arch.RowMajor)
	486	+ty = from_dlpack(
	487	+ y.permute(1, 0).contiguous(),
	488	+ layout_tag=tla.arch.ColumnMajor,
	489	+)
	490	+```
	491	+
	492	+---
	493	+
	494	+#### `make_fake_tensor`
	495	+
	496	+Source: [`catlass.tla.runtime.make_fake_tensor`](../../../catlass/tla/runtime.py#L858)
	497	+
	498	+Description:
	499	+
	500	+Build a metadata-only Host tensor with no device buffer (`data_ptr == 0`).
	501	+Use this as a `tla.compile` type sample when no NPU is needed. Bind real
	502	+buffers with `from_dlpack`.
	503	+
	504	+Prototype:
	505	+
	506	+```python
	507	+tla.make_fake_tensor(dtype: Any, shape: Any, stride: Any, *, layout_tag: Any \| None = None, addrspace: Any = AddressSpace.gm, origin_shape: Iterable[Any] \| None = None, coord: Iterable[Any] \| None = None, assumed_align: int \| None = None) -> _Tensor
	508	+```
	509	+
	510	+Parameters:
	511	+
	512	+- `dtype`: Element type such as `tla.Float16` / `tla.Float32`. Required.
	513	+- `shape` (`int \| tuple`): Logical shape tree (nested tuples for zN
	514	+ physical layouts). Required.
	515	+- `stride` (`int \| tuple`): Stride tree; structure must match `shape`.
	516	+ Required.
	517	+- `layout_tag`: `tla.arch` tag. Optional; default `tla.arch.RowMajor`.
	518	+- `addrspace`: Address space. Optional; default `AddressSpace.gm`.
	519	+- `origin_shape` (`int \| tuple \| None`): Logical origin. Optional;
	520	+ defaults to `shape`.
	521	+- `coord` (`int \| tuple \| None`): Coordinate tree. Optional; derived
	522	+ from the layout when omitted (typically zeros).
	523	+- `assumed_align` (`int \| None`): Reserved; currently unused.
	524	+
	525	+Constraints:
	526	+
	527	+- `shape` / `stride` / `origin_shape` / `coord` are Python int trees,
	528	+ not Kernel `tla.make_shape` / `tla.make_stride` / `tla.make_coord`.
	529	+- Always unbound; cannot be launched until replaced by `from_dlpack`.
	530	+- Explicit `shape` / `stride` are kept as given (no layout remap).
	531	+
	532	+Example:
	533	+
	534	+```python
	535	+fa = make_fake_tensor(tla.Float16, (128, 64), (64, 1))
	536	+fzn = make_fake_tensor(
	537	+ tla.Float16,
	538	+ ((16, 2), (16, 4)),
	539	+ ((16, 256), (1, 512)),
	540	+ layout_tag=tla.arch.zN,
	541	+ origin_shape=(32, 64),
	542	+)
	543	+```
	544	+
	545	+---
	546	+
	547	+### 3.2 Dynamic Layout
	548	+
	549	+Mark static layout extents dynamic. See also `docs/zh/kernel_development/core_concepts/layout.md`.
	550	+
	551	+#### `Tensor.mark_layout_dynamic`
	552	+
	553	+Source: [`catlass.tla.runtime._Tensor.mark_layout_dynamic`](../../../catlass/tla/runtime.py#L274)
	554	+
	555	+Description:
	556	+
	557	+Mark every shape mode dynamic so one compiled artifact can run at
	558	+different extents. Strides become dynamic except the leading dimension
	559	+(stride stays `1`). Broadcast strides of `0` are kept. Matching
	560	+`origin_shape` leaves become dynamic so the compile type no longer
	561	+depends on concrete DLPack extents.
	562	+
	563	+Prototype:
	564	+
	565	+```python
	566	+tensor.mark_layout_dynamic(leading_dim: int \| None = None) -> '_Tensor'
	567	+```
	568	+
	569	+Parameters:
	570	+
	571	+- `leading_dim` (`int \| None`): Index of the unit-stride (leading)
	572	+ dimension. Optional; default `None` (inferred from `layout_tag` or
	573	+ compact stride order).
	574	+
	575	+Constraints:
	576	+
	577	+- In-place; returns `self` (chainable).
	578	+- All `coord` leaves must be `0`; sliced views are rejected.
	579	+- `leading_dim` must have stride `1`.
	580	+- For NZFamily layouts, each two-leaf physical shape group maps to one
	581	+ logical `origin_shape` axis.
	582	+
	583	+Example:
	584	+
	585	+```python
	586	+ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
	587	+ta = ta.mark_layout_dynamic()
	588	+artifact = tla.compile(my_kernel, ta, options="--npu-arch 3510")
	589	+```
	590	+
	591	+---
	592	+
	593	+#### `Tensor.mark_compact_shape_dynamic`
	594	+
	595	+Source: [`catlass.tla.runtime._Tensor.mark_compact_shape_dynamic`](../../../catlass/tla/runtime.py#L346)
	596	+
	597	+Description:
	598	+
	599	+Mark one compact shape mode dynamic. Strides of modes major to `mode`
	600	+(whose compact stride product includes that extent) become dynamic as
	601	+well. Matching `origin_shape` leaves are marked so the compile type does
	602	+not depend on the concrete size.
	603	+
	604	+Prototype:
	605	+
	606	+```python
	607	+tensor.mark_compact_shape_dynamic(mode: int, stride_order: tuple[int, ...] \| None = None) -> '_Tensor'
	608	+```
	609	+
	610	+Parameters:
	611	+
	612	+- `mode` (`int`): Flattened shape-leaf index to mark dynamic
	613	+ (0-based). Required.
	614	+- `stride_order` (`tuple[int, ...] \| None`): Compact stride order
	615	+ (outer → inner). Optional; inferred from current strides when omitted.
	616	+
	617	+Constraints:
	618	+
	619	+- In-place; returns `self`.
	620	+- All `coord` leaves must be `0`.
	621	+- `stride_order` must be a permutation of `range(rank)`.
	622	+- For NZFamily layouts, physical modes 0/1 map to logical M and modes
	623	+ 2/3 map to logical N.
	624	+
	625	+Example:
	626	+
	627	+```python
	628	+ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
	629	+ta = ta.mark_compact_shape_dynamic(mode=0)
	630	+```
	631	+
	632	+---

Mpython/tla_dsl/docs/en/api/kernel_api_reference.md+73-266

	@@ -1,12 +1,12 @@
1	<!--	1	<!--
2	-This file is generated by python/tla_dsl/tools/generate_api_reference.py.	2	+This file is generated by python/tla_dsl/tools/generate_kernel_api_reference.py.
3	Do not edit manually. Update docstrings/Examples in catlass/core_api.py	3	Do not edit manually. Update docstrings/Examples in catlass/core_api.py
4	(or the defining module for imported types) instead.	4	(or the defining module for imported types) instead.
5	-->	5	-->
6		6
7	# TLA DSL Kernel API Reference	7	# TLA DSL Kernel API Reference
8		8
9	-This document describes the TLA DSL kernel-side Core APIs (typically imported as `import catlass.tla as tla`). It covers data structures, compute / sync helpers, on-chip resources, and debug printing. See `docs/zh/kernel_development/core_concepts/tensor_binding.md` for Host tensor binding.	9	+This document describes the TLA DSL kernel-side Core APIs (typically imported as `import catlass.tla as tla`). It covers data structures, compute / sync helpers, on-chip resources, and debug printing. Host-side compile / launch / tensor binding are in `docs/en/api/host_api_reference.md`; environment variables are in `docs/zh/kernel_development/core_concepts/env_vars.md`.
10		10
11	Interface descriptions and examples come from each op's source docstring (`Directory:` plus `Description:` / `Parameters:` / `Constraints:` / `Example:`).	11	Interface descriptions and examples come from each op's source docstring (`Directory:` plus `Description:` / `Parameters:` / `Constraints:` / `Example:`).
12		12
	@@ -16,27 +16,27 @@ All APIs must be called inside a `@tla.kernel`-decorated kernel function body.
16		16
17	## Table of Contents	17	## Table of Contents
18		18
19	-- [Basic Data Types and Operations](#basic-data-types-and-operations)	19	+- [1. Basic Data Types and Operations](#1-basic-data-types-and-operations)
20	-- [Data Movement](#data-movement)	20	+- [2. Data Movement](#2-data-movement)
21	-- [Matrix Compute](#matrix-compute)	21	+- [3. Matrix Compute](#3-matrix-compute)
22	-- [Vector Compute](#vector-compute)	22	+- [4. Vector Compute](#4-vector-compute)
23	- - [Mask Compute](#mask-compute)	23	+ - [4.1 Mask Compute](#41-mask-compute)
24	- - [Basic Arithmetic](#basic-arithmetic)	24	+ - [4.2 Basic Arithmetic](#42-basic-arithmetic)
25	- - [Logical Compute](#logical-compute)	25	+ - [4.3 Logical Compute](#43-logical-compute)
26	- - [Compare and Select](#compare-and-select)	26	+ - [4.4 Compare and Select](#44-compare-and-select)
27	- - [Data Fill](#data-fill)	27	+ - [4.5 Data Fill](#45-data-fill)
28	- - [Discrete and Aggregate](#discrete-and-aggregate)	28	+ - [4.6 Discrete and Aggregate](#46-discrete-and-aggregate)
29	- - [Data Rearrange](#data-rearrange)	29	+ - [4.7 Data Rearrange](#47-data-rearrange)
30	- - [Data Compress](#data-compress)	30	+ - [4.8 Data Compress](#48-data-compress)
31	-- [Sync Control](#sync-control)	31	+- [5. Sync Control](#5-sync-control)
32	-- [System Variable Access](#system-variable-access)	32	+- [6. System Variable Access](#6-system-variable-access)
33	-- [Resource Management](#resource-management)	33	+- [7. Resource Management](#7-resource-management)
34	-- [Debug APIs](#debug-apis)	34	+- [8. Debug APIs](#8-debug-apis)
35	-- [Scopes and Control Flow](#scopes-and-control-flow)	35	+- [9. Scopes and Control Flow](#9-scopes-and-control-flow)
36		36
37	---	37	---
38		38
39	-## Basic Data Types and Operations	39	+## 1. Basic Data Types and Operations
40		40
41	Construction and views for front-end structured values such as Shape / Coord / Stride / Layout / Tensor, plus pointer helpers.	41	Construction and views for front-end structured values such as Shape / Coord / Stride / Layout / Tensor, plus pointer helpers.
42		42
	@@ -356,7 +356,7 @@ dst = tla.make_tensor_like(ptr, like=src_tile, layoutTag=tla.arch.RowMajor)
356		356
357	### `make_ptr`	357	### `make_ptr`
358		358
359	-Source: [`catlass.core_api.make_ptr`](../../../catlass/core_api.py#L7234)	359	+Source: [`catlass.core_api.make_ptr`](../../../catlass/core_api.py#L7241)
360		360
361	Description:	361	Description:
362		362
	@@ -391,7 +391,7 @@ ptr = tla.make_ptr(tla.Float16, addr, mem_space=tla.AddressSpace.gm)
391		391
392	### `recast_ptr`	392	### `recast_ptr`
393		393
394	-Source: [`catlass.core_api.recast_ptr`](../../../catlass/core_api.py#L7288)	394	+Source: [`catlass.core_api.recast_ptr`](../../../catlass/core_api.py#L7295)
395		395
396	Description:	396	Description:
397		397
	@@ -421,7 +421,7 @@ ptr_f32 = tla.recast_ptr(ptr_f16, dtype=tla.Float32)
421		421
422	---	422	---
423		423
424	-## Data Movement	424	+## 2. Data Movement
425		425
426	Tensor copies between on-chip and global memory, and UB register load/store.	426	Tensor copies between on-chip and global memory, and UB register load/store.
427		427
	@@ -586,13 +586,13 @@ with tla.vec.func(mode="simd"):
586		586
587	---	587	---
588		588
589	-## Matrix Compute	589	+## 3. Matrix Compute
590		590
591	Cube-side matrix multiply-accumulate (`tla.mmad`).	591	Cube-side matrix multiply-accumulate (`tla.mmad`).
592		592
593	### `mmad`	593	### `mmad`
594		594
595	-Source: [`catlass.core_api.mmad`](../../../catlass/core_api.py#L5199)	595	+Source: [`catlass.core_api.mmad`](../../../catlass/core_api.py#L5204)
596		596
597	Description:	597	Description:
598		598
	@@ -621,6 +621,8 @@ Constraints:
621		621
622	- Must be called inside a `@tla.kernel`-decorated kernel function.	622	- Must be called inside a `@tla.kernel`-decorated kernel function.
623	- Must be called inside `tla.cube()`; `acc`/`lhs`/`rhs` must be matching L0 tiles.	623	- Must be called inside `tla.cube()`; `acc`/`lhs`/`rhs` must be matching L0 tiles.
		624	+- Supported element-type routes include `f16`/`bf16`/`f32` pairs and any
		625	+ `f8e4m3fn` / `f8e5m2` operand pairing, all accumulating into fp32 on L0C.
624	- `init_c` accepts only a Python `bool` or an `i1` SSA value.	626	- `init_c` accepts only a Python `bool` or an `i1` SSA value.
625	- Unknown keyword arguments are not accepted; passing any raises an error.	627	- Unknown keyword arguments are not accepted; passing any raises an error.
626		628
	@@ -635,17 +637,17 @@ with tla.cube():
635		637
636	---	638	---
637		639
638	-## Vector Compute	640	+## 4. Vector Compute
639		641
640	Compute and mask ops on the register-vector path; usually must be called inside `tla.vec.func()`.	642	Compute and mask ops on the register-vector path; usually must be called inside `tla.vec.func()`.
641		643
642	-### Mask Compute	644	+### 4.1 Mask Compute
643		645
644	Mask creation and tail-mask updates.	646	Mask creation and tail-mask updates.
645		647
646	#### `create_mask`	648	#### `create_mask`
647		649
648	-Source: [`catlass.core_api.create_mask`](../../../catlass/core_api.py#L7546)	650	+Source: [`catlass.core_api.create_mask`](../../../catlass/core_api.py#L7553)
649		651
650	Description:	652	Description:
651		653
	@@ -701,7 +703,7 @@ with tla.vec.func(mode="simd"):
701		703
702	#### `update_mask`	704	#### `update_mask`
703		705
704	-Source: [`catlass.core_api.update_mask`](../../../catlass/core_api.py#L7610)	706	+Source: [`catlass.core_api.update_mask`](../../../catlass/core_api.py#L7617)
705		707
706	Description:	708	Description:
707		709
	@@ -732,145 +734,13 @@ with tla.vec.func(mode="simd"):
732		734
733	---	735	---
734		736
735	-### Basic Arithmetic	737	+### 4.2 Basic Arithmetic
736		738
737	Element-wise arithmetic and unary math ops. `VectorSSA` overloads `+` / `-` / `*` / `/` for `add` / `sub` / `mul` / `div` when no `mask=` is needed.	739	Element-wise arithmetic and unary math ops. `VectorSSA` overloads `+` / `-` / `*` / `/` for `add` / `sub` / `mul` / `div` when no `mask=` is needed.
738		740
739	-#### `exp`
740	-
741	-Source: [`catlass.core_api.exp`](../../../catlass/core_api.py#L5921)
742	-
743	-Description:
744	-
745	-Element-wise exponential on a vector (requires f16/f32).
746	-
747	-Prototype:
748	-
749	-```python
750	-tla.exp(operand: VectorSSA, *, mask: MaskSSA \| None = None) -> VectorSSA
751	-```
752	-
753	-Parameters:
754	-
755	-- `operand` (`VectorSSA`): Source vector register. Required.
756	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
757	-
758	-Constraints:
759	-
760	-- Must be called inside a `@tla.kernel`-decorated kernel function.
761	-- Must be called inside `tla.vec.func()`; element type must be f16/f32.
762	-
763	-Example:
764	-
765	-```python
766	-with tla.vec.func(mode="simd"):
767	- y = tla.exp(x_reg)
768	-```
769	-
770	----
771	-
772	-#### `log`
773	-
774	-Source: [`catlass.core_api.log`](../../../catlass/core_api.py#L5943)
775	-
776	-Description:
777	-
778	-Element-wise logarithm on a vector (requires f16/f32).
779	-
780	-Prototype:
781	-
782	-```python
783	-tla.log(operand: VectorSSA, *, mask: MaskSSA \| None = None) -> VectorSSA
784	-```
785	-
786	-Parameters:
787	-
788	-- `operand` (`VectorSSA`): Source vector register. Required.
789	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
790	-
791	-Constraints:
792	-
793	-- Must be called inside a `@tla.kernel`-decorated kernel function.
794	-- Must be called inside `tla.vec.func()`; element type must be f16/f32.
795	-
796	-Example:
797	-
798	-```python
799	-with tla.vec.func(mode="simd"):
800	- y = tla.log(x_reg)
801	-```
802	-
803	----
804	-
805	-#### `sqrt`
806	-
807	-Source: [`catlass.core_api.sqrt`](../../../catlass/core_api.py#L5965)
808	-
809	-Description:
810	-
811	-Element-wise square root on a vector (requires f16/f32).
812	-
813	-Prototype:
814	-
815	-```python
816	-tla.sqrt(operand: VectorSSA, *, mask: MaskSSA \| None = None) -> VectorSSA
817	-```
818	-
819	-Parameters:
820	-
821	-- `operand` (`VectorSSA`): Source vector register. Required.
822	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
823	-
824	-Constraints:
825	-
826	-- Must be called inside a `@tla.kernel`-decorated kernel function.
827	-- Must be called inside `tla.vec.func()`; element type must be f16/f32.
828	-
829	-Example:
830	-
831	-```python
832	-with tla.vec.func(mode="simd"):
833	- y = tla.sqrt(x_reg)
834	-```
835	-
836	----
837	-
838	-#### `abs`
839	-
840	-Source: [`catlass.core_api.abs`](../../../catlass/core_api.py#L5987)
841	-
842	-Description:
843	-
844	-Element-wise absolute value on a vector.
845	-
846	-Prototype:
847	-
848	-```python
849	-tla.abs(operand: VectorSSA, *, mask: MaskSSA \| None = None) -> VectorSSA
850	-```
851	-
852	-Parameters:
853	-
854	-- `operand` (`VectorSSA`): Source vector register. Required.
855	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
856	-
857	-Constraints:
858	-
859	-- Must be called inside a `@tla.kernel`-decorated kernel function.
860	-- Must be called inside `tla.vec.func()`.
861	-
862	-Example:
863	-
864	-```python
865	-with tla.vec.func(mode="simd"):
866	- y = tla.abs(x_reg)
867	-```
868	-
869	----
870	-
871	#### `neg`	741	#### `neg`
872		742
873	-Source: [`catlass.core_api.neg`](../../../catlass/core_api.py#L6009)	743	+Source: [`catlass.core_api.neg`](../../../catlass/core_api.py#L6016)
874		744
875	Description:	745	Description:
876		746
	@@ -903,7 +773,7 @@ with tla.vec.func(mode="simd"):
903		773
904	#### `add`	774	#### `add`
905		775
906	-Source: [`catlass.core_api.add`](../../../catlass/core_api.py#L6188)	776	+Source: [`catlass.core_api.add`](../../../catlass/core_api.py#L6195)
907		777
908	Description:	778	Description:
909		779
	@@ -944,7 +814,7 @@ with tla.vec.func(mode="simd"):
944		814
945	#### `sub`	815	#### `sub`
946		816
947	-Source: [`catlass.core_api.sub`](../../../catlass/core_api.py#L6234)	817	+Source: [`catlass.core_api.sub`](../../../catlass/core_api.py#L6241)
948		818
949	Description:	819	Description:
950		820
	@@ -982,7 +852,7 @@ with tla.vec.func(mode="simd"):
982		852
983	#### `mul`	853	#### `mul`
984		854
985	-Source: [`catlass.core_api.mul`](../../../catlass/core_api.py#L6271)	855	+Source: [`catlass.core_api.mul`](../../../catlass/core_api.py#L6278)
986		856
987	Description:	857	Description:
988		858
	@@ -1019,77 +889,9 @@ with tla.vec.func(mode="simd"):
1019		889
1020	---	890	---
1021		891
1022	-#### `max`
1023	-
1024	-Source: [`catlass.core_api.max`](../../../catlass/core_api.py#L6395)
1025	-
1026	-Description:
1027	-
1028	-Element-wise vector maximum.
1029	-
1030	-Prototype:
1031	-
1032	-```python
1033	-tla.max(lhs: VectorSSA \| Numeric \| bool \| int \| float, rhs: VectorSSA \| Numeric \| bool \| int \| float, *, mask: MaskSSA \| None = None) -> VectorSSA
1034	-```
1035	-
1036	-Parameters:
1037	-
1038	-- `lhs` (`VectorSSA \| Numeric \| bool \| int \| float`): Left-hand operand. Required.
1039	-- `rhs` (`VectorSSA \| Numeric \| bool \| int \| float`): Right-hand operand. Required.
1040	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
1041	-
1042	-Constraints:
1043	-
1044	-- Must be called inside a `@tla.kernel`-decorated kernel function.
1045	-- Must be called inside `tla.vec.func()`.
1046	-
1047	-Example:
1048	-
1049	-```python
1050	-with tla.vec.func(mode="simd"):
1051	- z = tla.max(x_reg, y_reg)
1052	-```
1053	-
1054	----
1055	-
1056	-#### `min`
1057	-
1058	-Source: [`catlass.core_api.min`](../../../catlass/core_api.py#L6396)
1059	-
1060	-Description:
1061	-
1062	-Element-wise vector minimum.
1063	-
1064	-Prototype:
1065	-
1066	-```python
1067	-tla.min(lhs: VectorSSA \| Numeric \| bool \| int \| float, rhs: VectorSSA \| Numeric \| bool \| int \| float, *, mask: MaskSSA \| None = None) -> VectorSSA
1068	-```
1069	-
1070	-Parameters:
1071	-
1072	-- `lhs` (`VectorSSA \| Numeric \| bool \| int \| float`): Left-hand operand. Required.
1073	-- `rhs` (`VectorSSA \| Numeric \| bool \| int \| float`): Right-hand operand. Required.
1074	-- `mask` (`MaskSSA \| None`): Optional execution mask; `None` means all lanes enabled. Optional, default `None`.
1075	-
1076	-Constraints:
1077	-
1078	-- Must be called inside a `@tla.kernel`-decorated kernel function.
1079	-- Must be called inside `tla.vec.func()`.
1080	-
1081	-Example:
1082	-
1083	-```python
1084	-with tla.vec.func(mode="simd"):
1085	- z = tla.min(x_reg, y_reg)
1086	-```
1087	-
1088	----
1089	-
1090	#### `div`	892	#### `div`
1091		893
1092	-Source: [`catlass.core_api.div`](../../../catlass/core_api.py#L6400)	894	+Source: [`catlass.core_api.div`](../../../catlass/core_api.py#L6407)
1093		895
1094	Description:	896	Description:
1095		897
	@@ -1125,13 +927,13 @@ with tla.vec.func(mode="simd"):
1125		927
1126	---	928	---
1127		929
1128	-### Logical Compute	930	+### 4.3 Logical Compute
1129		931
1130	Bitwise and logical ops on Mask / Vector.	932	Bitwise and logical ops on Mask / Vector.
1131		933
1132	#### `bitwise_not`	934	#### `bitwise_not`
1133		935
1134	-Source: [`catlass.core_api.bitwise_not`](../../../catlass/core_api.py#L6154)	936	+Source: [`catlass.core_api.bitwise_not`](../../../catlass/core_api.py#L6161)
1135		937
1136	Description:	938	Description:
1137		939
	@@ -1164,7 +966,7 @@ with tla.vec.func(mode="simd"):
1164		966
1165	#### `bitwise_and`	967	#### `bitwise_and`
1166		968
1167	-Source: [`catlass.core_api.bitwise_and`](../../../catlass/core_api.py#L6830)	969	+Source: [`catlass.core_api.bitwise_and`](../../../catlass/core_api.py#L6837)
1168		970
1169	Description:	971	Description:
1170		972
	@@ -1198,7 +1000,7 @@ with tla.vec.func(mode="simd"):
1198		1000
1199	#### `bitwise_or`	1001	#### `bitwise_or`
1200		1002
1201	-Source: [`catlass.core_api.bitwise_or`](../../../catlass/core_api.py#L6868)	1003	+Source: [`catlass.core_api.bitwise_or`](../../../catlass/core_api.py#L6875)
1202		1004
1203	Description:	1005	Description:
1204		1006
	@@ -1232,7 +1034,7 @@ with tla.vec.func(mode="simd"):
1232		1034
1233	#### `bitwise_xor`	1035	#### `bitwise_xor`
1234		1036
1235	-Source: [`catlass.core_api.bitwise_xor`](../../../catlass/core_api.py#L6906)	1037	+Source: [`catlass.core_api.bitwise_xor`](../../../catlass/core_api.py#L6913)
1236		1038
1237	Description:	1039	Description:
1238		1040
	@@ -1264,13 +1066,13 @@ with tla.vec.func(mode="simd"):
1264		1066
1265	---	1067	---
1266		1068
1267	-### Compare and Select	1069	+### 4.4 Compare and Select
1268		1070
1269	Vector compares that produce masks, and masked select.	1071	Vector compares that produce masks, and masked select.
1270		1072
1271	#### `where`	1073	#### `where`
1272		1074
1273	-Source: [`catlass.core_api.where`](../../../catlass/core_api.py#L6572)	1075	+Source: [`catlass.core_api.where`](../../../catlass/core_api.py#L6579)
1274		1076
1275	Description:	1077	Description:
1276		1078
	@@ -1306,7 +1108,7 @@ with tla.vec.func(mode="simd"):
1306		1108
1307	#### `cmp`	1109	#### `cmp`
1308		1110
1309	-Source: [`catlass.core_api.cmp`](../../../catlass/core_api.py#L6754)	1111	+Source: [`catlass.core_api.cmp`](../../../catlass/core_api.py#L6761)
1310		1112
1311	Description:	1113	Description:
1312		1114
	@@ -1339,13 +1141,13 @@ with tla.vec.func(mode="simd"):
1339		1141
1340	---	1142	---
1341		1143
1342	-### Data Fill	1144	+### 4.5 Data Fill
1343		1145
1344	Constant fill and lane-index sequence construction.	1146	Constant fill and lane-index sequence construction.
1345		1147
1346	#### `full`	1148	#### `full`
1347		1149
1348	-Source: [`catlass.core_api.full`](../../../catlass/core_api.py#L5312)	1150	+Source: [`catlass.core_api.full`](../../../catlass/core_api.py#L5319)
1349		1151
1350	Description:	1152	Description:
1351		1153
	@@ -1378,7 +1180,7 @@ with tla.vec.func(mode="simd"):
1378		1180
1379	#### `arange`	1181	#### `arange`
1380		1182
1381	-Source: [`catlass.core_api.arange`](../../../catlass/core_api.py#L5385)	1183	+Source: [`catlass.core_api.arange`](../../../catlass/core_api.py#L5392)
1382		1184
1383	Description:	1185	Description:
1384		1186
	@@ -1410,13 +1212,13 @@ with tla.vec.func(mode="simd"):
1410		1212
1411	---	1213	---
1412		1214
1413	-### Discrete and Aggregate	1215	+### 4.6 Discrete and Aggregate
1414		1216
1415	Gather elements from a UB tensor by index.	1217	Gather elements from a UB tensor by index.
1416		1218
1417	#### `gather`	1219	#### `gather`
1418		1220
1419	-Source: [`catlass.core_api.gather`](../../../catlass/core_api.py#L6944)	1221	+Source: [`catlass.core_api.gather`](../../../catlass/core_api.py#L6951)
1420		1222
1421	Description:	1223	Description:
1422		1224
	@@ -1448,13 +1250,13 @@ with tla.vec.func(mode="simd"):
1448		1250
1449	---	1251	---
1450		1252
1451	-### Data Rearrange	1253	+### 4.7 Data Rearrange
1452		1254
1453	Interleave / deinterleave and related lane reshuffles.	1255	Interleave / deinterleave and related lane reshuffles.
1454		1256
1455	#### `interleave`	1257	#### `interleave`
1456		1258
1457	-Source: [`catlass.core_api.interleave`](../../../catlass/core_api.py#L6047)	1259	+Source: [`catlass.core_api.interleave`](../../../catlass/core_api.py#L6054)
1458		1260
1459	Description:	1261	Description:
1460		1262
	@@ -1487,7 +1289,7 @@ with tla.vec.func(mode="simd"):
1487		1289
1488	#### `deinterleave`	1290	#### `deinterleave`
1489		1291
1490	-Source: [`catlass.core_api.deinterleave`](../../../catlass/core_api.py#L6100)	1292	+Source: [`catlass.core_api.deinterleave`](../../../catlass/core_api.py#L6107)
1491		1293
1492	Description:	1294	Description:
1493		1295
	@@ -1518,13 +1320,13 @@ with tla.vec.func(mode="simd"):
1518		1320
1519	---	1321	---
1520		1322
1521	-### Data Compress	1323	+### 4.8 Data Compress
1522		1324
1523	Compress valid lanes under a mask.	1325	Compress valid lanes under a mask.
1524		1326
1525	#### `squeeze`	1327	#### `squeeze`
1526		1328
1527	-Source: [`catlass.core_api.squeeze`](../../../catlass/core_api.py#L6601)	1329	+Source: [`catlass.core_api.squeeze`](../../../catlass/core_api.py#L6608)
1528		1330
1529	Description:	1331	Description:
1530		1332
	@@ -1555,7 +1357,7 @@ with tla.vec.func(mode="simd"):
1555		1357
1556	---	1358	---
1557		1359
1558	-## Sync Control	1360	+## 5. Sync Control
1559		1361
1560	In-core / cross-core flags, pipe barriers, mutexes, and local-memory barriers.	1362	In-core / cross-core flags, pipe barriers, mutexes, and local-memory barriers.
1561		1363
	@@ -1955,13 +1757,13 @@ with tla.vec.func(mode="simd"):
1955		1757
1956	---	1758	---
1957		1759
1958	-## System Variable Access	1760	+## 6. System Variable Access
1959		1761
1960	Architecture attributes on `tla.arch` (layout tags, pipe identifiers, block helpers, etc.).	1762	Architecture attributes on `tla.arch` (layout tags, pipe identifiers, block helpers, etc.).
1961		1763
1962	### `arch`	1764	### `arch`
1963		1765
1964	-Source: [`catlass.core_api.arch`](../../../catlass/core_api.py#L7411)	1766	+Source: [`catlass.core_api.arch`](../../../catlass/core_api.py#L7418)
1965		1767
1966	Description:	1768	Description:
1967		1769
	@@ -1994,9 +1796,9 @@ Parameters:
1994	- `sync_threads()`: Barrier across threads of the enclosing SIMT	1796	- `sync_threads()`: Barrier across threads of the enclosing SIMT
1995	`tla.vec.func` (only inside `mode="simt"`).	1797	`tla.vec.func` (only inside `mode="simt"`).
1996	- `get_capacity_in_bytes(mem_scope)`: Byte capacity of an on-chip memory	1798	- `get_capacity_in_bytes(mem_scope)`: Byte capacity of an on-chip memory
1997	- space for the compile target. Takes a `tla.arch` memory-scope token (`L1` /	1799	+ space for the compile target. Takes a `tla.AddressSpace` token
1998	- `L0A` / `L0B` / `L0C` / `UB`). Returns a plain `int`;	1800	+ (`tla.AddressSpace.l1` / `l0a` / `l0b` / `l0c` / `ub`). Returns a plain
1999	- valid on host and inside a kernel (folds to a constant).	1801	+ `int`; valid on host and inside a kernel (folds to a constant).
2000		1802
2001	Constraints:	1803	Constraints:
2002		1804
	@@ -2026,13 +1828,13 @@ ub_bytes = tla.arch.get_capacity_in_bytes(tla.AddressSpace.ub)
2026		1828
2027	---	1829	---
2028		1830
2029	-## Resource Management	1831	+## 7. Resource Management
2030		1832
2031	On-chip scratch allocation via `allocate`.	1833	On-chip scratch allocation via `allocate`.
2032		1834
2033	### `allocate`	1835	### `allocate`
2034		1836
2035	-Source: [`catlass.core_api.allocate`](../../../catlass/core_api.py#L7174)	1837	+Source: [`catlass.core_api.allocate`](../../../catlass/core_api.py#L7181)
2036		1838
2037	Description:	1839	Description:
2038		1840
	@@ -2069,7 +1871,7 @@ ptr = tla.allocate(
2069		1871
2070	---	1872	---
2071		1873
2072	-## Debug APIs	1874	+## 8. Debug APIs
2073		1875
2074	In-kernel scalar / tensor debug printing.	1876	In-kernel scalar / tensor debug printing.
2075		1877
	@@ -2107,7 +1909,7 @@ with tla.vector():
2107		1909
2108	---	1910	---
2109		1911
2110	-## Scopes and Control Flow	1912	+## 9. Scopes and Control Flow
2111		1913
2112	Cube / Vector / `vec.func` regions and kernel-side loop ranges.	1914	Cube / Vector / `vec.func` regions and kernel-side loop ranges.
2113		1915
	@@ -2169,6 +1971,11 @@ Constraints:
2169		1971
2170	- Must be called inside a `@tla.kernel`-decorated kernel function.	1972	- Must be called inside a `@tla.kernel`-decorated kernel function.
2171	- Bounds and step must be compile-time constants for unrollable loops.	1973	- Bounds and step must be compile-time constants for unrollable loops.
		1974	+- Bounds may come from compile-time Numeric values (for example via
		1975	+ `tla.as_numeric(...)`).
		1976	+- Emits `DSLOptimizationWarning` when the loop has 64 or more
		1977	+ iterations; expansion continues. Prefer `tla.range(...)` for large
		1978	+ counted loops.
2172		1979
2173	Example:	1980	Example:
2174		1981
	@@ -2181,7 +1988,7 @@ for k in tla.range_constexpr(0, 4):
2181		1988
2182	### `cube`	1989	### `cube`
2183		1990
2184	-Source: [`catlass.core_api.cube`](../../../catlass/core_api.py#L5104)	1991	+Source: [`catlass.core_api.cube`](../../../catlass/core_api.py#L5109)
2185		1992
2186	Description:	1993	Description:
2187		1994
	@@ -2213,7 +2020,7 @@ with tla.cube():
2213		2020
2214	### `vector`	2021	### `vector`
2215		2022
2216	-Source: [`catlass.core_api.vector`](../../../catlass/core_api.py#L5126)	2023	+Source: [`catlass.core_api.vector`](../../../catlass/core_api.py#L5131)
2217		2024
2218	Description:	2025	Description:
2219		2026
	@@ -2245,7 +2052,7 @@ with tla.vector():
2245		2052
2246	### `vec.func`	2053	### `vec.func`
2247		2054
2248	-Source: [`catlass.core_api._vec_func`](../../../catlass/core_api.py#L5160)	2055	+Source: [`catlass.core_api._vec_func`](../../../catlass/core_api.py#L5165)
2249		2056
2250	Description:	2057	Description:
2251		2058

Mpython/tla_dsl/docs/en/index.md+6-3

	@@ -14,8 +14,11 @@ that have been translated.
14	\| Doc \| Scope \|	14	\| Doc \| Scope \|
15	\|-----\|--------\|	15	\|-----\|--------\|
16	\| [Kernel API Reference](api/kernel_api_reference.md) \| Kernel-side Core APIs (`tla.copy`, `tla.mmad`, vector ops, sync, …). \|	16	\| [Kernel API Reference](api/kernel_api_reference.md) \| Kernel-side Core APIs (`tla.copy`, `tla.mmad`, vector ops, sync, …). \|
		17	+\| [Host API Reference](api/host_api_reference.md) \| Host-side `@tla.kernel`, `tla.compile` / launch, Host tensors. \|
17	\| [DSL Syntax Constraints](core_concepts/syntax_guide.md) \| What Python is legal inside `@tla.kernel`. \|	18	\| [DSL Syntax Constraints](core_concepts/syntax_guide.md) \| What Python is legal inside `@tla.kernel`. \|
18		19
19	-English Kernel API Markdown is generated (`python tools/generate_api_reference.py`);	20	+English Kernel / Host API Markdown is generated
20	-the Chinese Kernel API page is hand-maintained and should be synced when the	21	+(`python tools/generate_kernel_api_reference.py`,
21	-English page changes.	22	+`python tools/generate_host_api_reference.py`);
		23	+the Chinese pages are hand-maintained and should be synced when the
		24	+English pages change.

Mpython/tla_dsl/docs/zh/api/generate_api_docs.md+28-13

	@@ -4,11 +4,23 @@ nav_order: 20
4		4
5	# 生成 API 文档	5	# 生成 API 文档
6		6
7	-CATLASS DSL API 文档由脚本通过 AST 静态解析 `catlass.core_api` 生成 Markdown。	7	+CATLASS DSL API 文档由脚本通过 AST 静态解析源码生成 Markdown，再由仓库根目录
		8	+MkDocs 构建为静态站点。
		9	+
		10	+- Kernel API：`core_api.py`、`tla/tensor.py` → `docs/en/api/kernel_api_reference.md`
		11	+- Host API：Host 源文件 → `docs/en/api/host_api_reference.md`
		12	+
		13	+公共解析 / Markdown 渲染在 `tools/common.py`。
8		14
9	## 前置条件	15	## 前置条件
10		16
11	-生成脚本会导入 `catlass.core_api`，因此需要先完成 [Debug 开发构建](../dsl_development/build_guide/index.md#development-模式构建开发态)：	17	+生成脚本仅做 AST 解析，不依赖 `mlir_core`。构建 MkDocs 站点前安装文档依赖：
		18	+
		19	+```bash
		20	+# /path/to/catlass 需替换为你 clone 的 CATLASS 仓库实际路径
		21	+cd /path/to/catlass/python/tla_dsl
		22	+python -m pip install -r requirements-docs.txt
		23	+```
12		24
13	## 生成 API Reference Markdown	25	## 生成 API Reference Markdown
14		26
	@@ -18,28 +30,31 @@ CATLASS DSL API 文档由脚本通过 AST 静态解析 `catlass.core_api` 生成
18	- `Description:` / `Parameters:` / `Constraints:` / `Example:`	30	- `Description:` / `Parameters:` / `Constraints:` / `Example:`
19		31
20	生成器根据 `Directory:` 建目录树；章节顺序与章节简介写在脚本的	32	生成器根据 `Directory:` 建目录树；章节顺序与章节简介写在脚本的
21	-`DIRECTORY_SECTIONS`（API docstring 只保留归属路径与接口说明）。	33	+`DIRECTORY_SECTIONS`（Kernel）与 `HOST_DIRECTORY_SECTIONS`（Host）。
22	同节内 API 顺序跟随源码定义顺序。	34	同节内 API 顺序跟随源码定义顺序。
23	-生成器只产出英文参考文档 `docs/en/api/kernel_api_reference.md`（自动生成，勿手改）。
24	-中文版 `docs/zh/api/kernel_api_reference.md` 为手工维护（不以术语表 / glossary 自动生成）；英文稿变更后请同步翻译更新中文稿。
25		35
26	-生成脚本通过 AST 解析源码，不要求导入已构建的 `mlir_core`：	36	+生成器产出英文参考文档（自动生成，勿手改）：
27		37
28	-## 生成 Core API Reference	38	+- `docs/en/api/kernel_api_reference.md`（`tools/generate_kernel_api_reference.py`）
		39	+- `docs/en/api/host_api_reference.md`（`tools/generate_host_api_reference.py`）
		40	+
		41	+中文版 `docs/zh/api/kernel_api_reference.md` 与 `docs/zh/api/host_api_reference.md`
		42	+为手工维护；英文稿变更后请同步翻译更新中文稿。
		43	+
		44	+环境变量见 [环境变量](../kernel_development/core_concepts/env_vars.md)，不由 Host API
		45	+生成器扫描。
29		46
30	```bash	47	```bash
31	cd /path/to/catlass/python/tla_dsl	48	cd /path/to/catlass/python/tla_dsl
32	-python tools/generate_api_reference.py	49	+python tools/generate_kernel_api_reference.py
		50	+python tools/generate_host_api_reference.py
33	```	51	```
34		52
35	-生成结果（仅英文）：`docs/en/api/kernel_api_reference.md`
36	-
37	-手工维护的中文参考（不由上述命令生成）：`docs/zh/api/kernel_api_reference.md`
38	-
39	检查生成文件是否与当前代码一致，但不改写文件：	53	检查生成文件是否与当前代码一致，但不改写文件：
40		54
41	```bash	55	```bash
42	-python tools/generate_api_reference.py --check	56	+python tools/generate_kernel_api_reference.py --check
		57	+python tools/generate_host_api_reference.py --check
43	```	58	```
44		59
45	`--check` 在文件过期时输出 diff 并返回非零状态，适合用于提交前检查。	60	`--check` 在文件过期时输出 diff 并返回非零状态，适合用于提交前检查。

Apython/tla_dsl/docs/zh/api/host_api_reference.md+597-0

@@ -0,0 +1,597 @@
	1	+---
	2	+nav_order: 15
	3	+---
	4	+
	5	+<!--
	6	+手工维护的中文 Host API 参考。
	7	+英文源：docs/en/api/host_api_reference.md
	8	+（由 python/tla_dsl/tools/generate_host_api_reference.py + 源码英文 docstring 生成）。
	9	+英文稿变更后请同步翻译更新本文件。
	10	+不要用术语表 / glossary 自动生成本文件。
	11	+-->
	12	+
	13	+# TLA DSL Host API 参考
	14	+
	15	+本文档介绍 TLA DSL 的 Host 侧 API（通常以 `import catlass.tla as tla` 导入）。
	16	+内容覆盖：`@tla.kernel` 装饰器、Host 侧 `@dataclass` 打包、`tla.compile` /
	17	+`KernelLauncher` 启动、Host tensor。
	18	+环境变量见 [环境变量](../kernel_development/core_concepts/env_vars.md)。Kernel 侧接口见 [Kernel API 参考](kernel_api_reference.md)。
	19	+
	20	+接口说明与调用示例来自各 API 源码 docstring；这些接口均在 Python Host 脚本中、
	21	+`@tla.kernel` 函数体外调用。
	22	+
	23	+DLPack 接入教程见 [Host Tensor 接入](../kernel_development/core_concepts/tensor_binding.md)。
	24	+动态 layout 编程见 [静态与动态 Layout](../kernel_development/core_concepts/layout.md)。
	25	+
	26	+---
	27	+
	28	+## 目录
	29	+
	30	+- [1. 装饰器](#1-装饰器)
	31	+- [2. 编译与启动](#2-编译与启动)
	32	+ - [2.1 编译](#21-编译)
	33	+ - [2.2 启动](#22-启动)
	34	+ - [2.3 查看 IR](#23-查看-ir)
	35	+- [3. Host Tensor](#3-host-tensor)
	36	+ - [3.1 创建与绑定](#31-创建与绑定)
	37	+ - [3.2 动态 Layout](#32-动态-layout)
	38	+
	39	+---
	40	+
	41	+## 1. 装饰器
	42	+
	43	+Host 侧 `@tla.kernel` 入口，以及 Host 侧 `@dataclass` 打包。
	44	+被装饰的 kernel 函数体在 Host 端不执行。
	45	+
	46	+### `kernel`
	47	+
	48	+源码： [`catlass.dsl.kernel`](../../../catlass/dsl.py#L305)
	49	+
	50	+功能说明：
	51	+
	52	+将 Python 函数标注为 TLA Kernel 入口。函数体在 Host 端不执行。
	53	+返回 `TlaJitFunction`。调用该对象会返回 `KernelLauncher`（此时不启动）；再调用
	54	+launcher 或 `.launch(...)` 才会编译并执行。
	55	+
	56	+函数原型：
	57	+
	58	+```python
	59	+tla.kernel(fn: Callable[..., Any] \| None = None, *, auto_sync: str \| None = None) -> TlaJitFunction \| Callable[[Callable[..., Any]], TlaJitFunction]
	60	+```
	61	+
	62	+参数说明：
	63	+
	64	+- `fn`（`Callable[..., Any] \| None`）：被装饰的函数。用 `@tla.kernel` 或
	65	+ `@tla.kernel(auto_sync=...)`；只有无法使用装饰器语法时才手写 `tla.kernel(fn)`。
	66	+- `auto_sync`（`str \| None`）：可选。`"v0"` 表示由框架自动插入局部 mutex；
	67	+ 默认 `None`（同步仍由用户显式控制）。
	68	+
	69	+约束说明：
	70	+
	71	+- 被装饰的函数不能用 Python 的 `async def` 定义。
	72	+- `auto_sync` 只能是 `"v0"` 或 `None`。
	73	+- Kernel 参数类型：
	74	+
	75	+ \| 类别 \| 类型 \|
	76	+ \| --- \| --- \|
	77	+ \| Tensor \| `tla.Tensor` \|
	78	+ \| Python 标量 \| `bool` / `int` / `float` \|
	79	+ \| `tla` 标量 \| `Bool`、`Int8/16/32/64`、`UInt8/16/32/64`、`Float16/32`、`BFloat16` \|
	80	+ \| 编译期常量 \| `tla.Constexpr[...]` \|
	81	+ \| 结构体 \| 字段类型属于上表的 `@dataclass` 实例 \|
	82	+
	83	+调用示例：
	84	+
	85	+```python
	86	+@tla.kernel
	87	+def vadd(src: tla.Tensor, dst: tla.Tensor) -> None:
	88	+ with tla.vector():
	89	+ tla.copy(src, dst)
	90	+
	91	+@tla.kernel(auto_sync="v0")
	92	+def vadd_auto(src: tla.Tensor, dst: tla.Tensor) -> None:
	93	+ with tla.vector():
	94	+ tla.copy(src, dst)
	95	+
	96	+vadd(tx, ty, options="--npu-arch 3510")(block_num=1)
	97	+```
	98	+
	99	+---
	100	+
	101	+### `dataclass`
	102	+
	103	+源码： [`dataclasses.dataclass`](../../../catlass/execution_lowering.py#L759)
	104	+
	105	+功能说明：
	106	+
	107	+用 Python 标准库 `@dataclass` 在 Host 侧打包 kernel 入参。可在 Host 上创建实例后传给
	108	+`tla.compile` / 启动；也可在 kernel 内构造字段实例。
	109	+
	110	+函数原型：
	111	+
	112	+```python
	113	+dataclasses.dataclass(cls: type, *, frozen: bool = False, kw_only: bool = False) -> type
	114	+```
	115	+
	116	+参数说明：
	117	+
	118	+- `frozen`（`bool`）：为 `True` 时实例不可变。默认 `False`。
	119	+- `kw_only`（`bool`）：为 `True` 时字段必须按关键字传入。默认 `False`。
	120	+
	121	+约束说明：
	122	+
	123	+- 作为 kernel 入参时，只支持设置 `frozen` / `kw_only`；其它 stdlib 选项
	124	+ （如 `slots=True`、`init=False`）会在编译期报错。
	125	+- 支持的字段类型：
	126	+
	127	+ \| 类别 \| 类型 \| 约束 \|
	128	+ \| --- \| --- \| --- \|
	129	+ \| Tensor \| `tla.Tensor` \| 不支持动态 GM；请改用静态 tensor 字段或顶层 tensor 入参 \|
	130	+ \| Python 标量 \| `bool` / `int` / `float` \| — \|
	131	+ \| `tla` 标量 \| `Bool`、`Int8/16/32/64`、`UInt8/16/32/64`、`Float16/32`、`BFloat16` \| — \|
	132	+ \| 编译期常量 \| `tla.Constexpr[...]` \| 不进入 kernel ABI / IR，且在 kernel 内只读 \|
	133	+
	134	+调用示例：
	135	+
	136	+```python
	137	+from dataclasses import dataclass
	138	+import catlass.tla as tla
	139	+
	140	+@dataclass(frozen=True, kw_only=True)
	141	+class TilingData:
	142	+ TILE_M: tla.Constexpr[int]
	143	+ tiling_int: int
	144	+ out: tla.Tensor
	145	+
	146	+@tla.kernel
	147	+def struct_arg_kernel(tiling: TilingData) -> None:
	148	+ # TILE_M 为编译期常量；tiling_int 为运行时标量。
	149	+ ...
	150	+
	151	+tiling = TilingData(TILE_M=128, tiling_int=64, out=tout)
	152	+artifact = tla.compile(struct_arg_kernel, tiling, options="--npu-arch 3510")
	153	+artifact(tiling, block_num=1)
	154	+```
	155	+
	156	+---
	157	+
	158	+## 2. 编译与启动
	159	+
	160	+将装饰后的 kernel 编译为设备二进制并启动。同一份二进制需要多次启动时，用
	161	+`tla.compile` 再 `artifact(...)` / `.launch(...)`；单次或少量启动可直接调用
	162	+`@tla.kernel` 得到 `KernelLauncher` 再启动。缓存 / 架构 / IR dump 等非函数参数见
	163	+[环境变量](../kernel_development/core_concepts/env_vars.md)。
	164	+
	165	+### 2.1 编译
	166	+
	167	+生成设备二进制。日常入口是 `tla.compile`；
	168	+`TlaJitFunction.compile` 是装饰后函数上的底层辅助接口。
	169	+
	170	+#### `compile`
	171	+
	172	+源码： [`catlass.base_dsl.compiler.CompileCallable.__call__`](../../../catlass/base_dsl/compiler.py#L46)
	173	+
	174	+功能说明：
	175	+
	176	+编译 `@tla.kernel` 函数，返回包装了 `TlaKernelArtifact` 的可调用执行器。
	177	+这是公开的 `tla.compile` 入口。调用返回的执行器即可启动
	178	+（`artifact(*tensors, block_num=...)`）。适合先编译一次，再对同一份二进制多次启动。
	179	+
	180	+函数原型：
	181	+
	182	+```python
	183	+tla.compile(func: Any, args: Any, *kwargs: Any) -> TlaJitExecutor
	184	+```
	185	+
	186	+参数说明：
	187	+
	188	+- `func`（`TlaJitFunction`）：被 `@tla.kernel` 装饰的函数。必填。
	189	+- `args`（`Any`）：作为编译类型样本的 Host tensor / 标量 / `@dataclass` 实例
	190	+ （如 `from_dlpack` 或 `make_fake_tensor` 的返回值）。
	191	+- `kwargs`：Host 编译参数。用 `options="--npu-arch 3510"` 指定芯片名。
	192	+ 缓存 / IR dump / 强制重编译由 `CATLASS_DSL_*` 环境变量控制。
	193	+
	194	+约束说明：
	195	+
	196	+- `func` 必须是 `@tla.kernel` 得到的 `TlaJitFunction`。
	197	+- `args` 只作编译期类型样本，不必绑定 NPU 缓冲（`make_fake_tensor` 合法）。
	198	+- 用 `options="--npu-arch 3510"` 指定芯片名；不支持的取值在编译时报错。
	199	+- `block_num` / `stream` 等启动参数写在返回执行器上
	200	+ （`artifact(...)` / `TlaJitExecutor.launch`），而不是 `tla.compile`。
	201	+
	202	+调用示例：
	203	+
	204	+```python
	205	+artifact = tla.compile(vadd, tx, ty, options="--npu-arch 3510")
	206	+artifact(tx, ty, block_num=1)
	207	+artifact(tx, ty, block_num=1) # 同一份二进制再次启动
	208	+```
	209	+
	210	+---
	211	+
	212	+#### `TlaJitFunction.compile`
	213	+
	214	+源码： [`catlass.dsl.TlaJitFunction.compile`](../../../catlass/dsl.py#L195)
	215	+
	216	+功能说明：
	217	+
	218	+编译当前 `@tla.kernel` 函数并返回 `TlaKernelArtifact`。
	219	+日常 Host 入口是 `tla.compile(fn, *args, options=...)`；只有已持有
	220	+`TlaJitFunction` 且需要原始 `TlaKernelArtifact` 时才调用 `.compile()`。
	221	+
	222	+函数原型：
	223	+
	224	+```python
	225	+TlaJitFunction.compile(, type_args: Sequence[Any] \| None = None, *kwargs: Any) -> TlaKernelArtifact
	226	+```
	227	+
	228	+参数说明：
	229	+
	230	+- `type_args`（`Sequence[Any] \| None`）：作为编译类型样本的 Host tensor / 标量。
	231	+ 可选，默认 `None`（不做张量特化）。
	232	+- `kwargs`：Host 编译参数。用 `options="--npu-arch 3510"` 指定芯片名。
	233	+ 缓存 / IR dump 由 `CATLASS_DSL_*` 环境变量控制。
	234	+
	235	+约束说明：
	236	+
	237	+- `type_args` 只作编译期类型样本，不必绑定 NPU 缓冲（`make_fake_tensor` 合法）。
	238	+- 用 `options="--npu-arch 3510"` 指定芯片名；不支持的取值在编译时报错。
	239	+
	240	+调用示例：
	241	+
	242	+```python
	243	+artifact = my_kernel.compile(
	244	+ type_args=[tx, ty],
	245	+ options="--npu-arch 3510",
	246	+)
	247	+```
	248	+
	249	+---
	250	+
	251	+### 2.2 启动
	252	+
	253	+在 NPU 上运行已编译的 kernel。经 `tla.compile` 后，调用执行器或
	254	+`TlaJitExecutor.launch`；经调用 `@tla.kernel` 后，使用 `KernelLauncher.launch`
	255	+（或直接调用 launcher）。
	256	+
	257	+#### `TlaJitExecutor.launch`
	258	+
	259	+源码： [`catlass.base_dsl.jit_executor.TlaJitExecutor.launch`](../../../catlass/base_dsl/jit_executor.py#L99)
	260	+
	261	+功能说明：
	262	+
	263	+在 NPU 上启动经 `tla.compile` 得到的已编译 kernel，传入运行时入参与启动参数
	264	+（如 `block_num`、`stream`）。
	265	+
	266	+函数原型：
	267	+
	268	+```python
	269	+TlaJitExecutor.launch(launch_args: Any, , block_num: int \| None = None, args: Sequence[Any] \| None = None, **kwargs: Any) -> TlaExecutionResult
	270	+```
	271	+
	272	+参数说明：
	273	+
	274	+- `launch_args`（`Any`）：位置形式的运行时 kernel 入参，与 `@tla.kernel`
	275	+ 签名对应（已绑定的 Host tensor、标量或 `@dataclass` 实例）。与 `args=` 互斥。
	276	+- `block_num`（`int \| None`）：启动的 block 数。可选，默认 `1`；传入时须为 `int`。
	277	+- `args`（`Sequence[Any] \| None`）：显式运行时实参序列。可选，默认 `None`。
	278	+ 不能与非空的 `*launch_args` 同时使用。
	279	+- `stream`（`Any`，经 `**kwargs`）：可选 ACL stream 句柄（常为 `int`）。
	280	+ 省略时优先用 `torch.npu.current_stream`；否则须显式传 `stream=`，
	281	+ 或依赖 `CATLASS_DSL_NPU_DEVICE`。
	282	+
	283	+约束说明：
	284	+
	285	+- `artifact(...)` 与 `.launch(...)` 共用同一套运行时规则。
	286	+- `*launch_args` 与 `args=` 不能同时非空（`TlaUnsupportedAbiError`）。
	287	+- tensor 启动实参须为已绑定的 NPU 缓冲（`from_dlpack`）；
	288	+ `make_fake_tensor` 仅用于编译样本。
	289	+- `block_num` 须为 `int`（默认 `1`）。
	290	+
	291	+调用示例：
	292	+
	293	+```python
	294	+artifact = tla.compile(vadd, tx, ty, options="--npu-arch 3510")
	295	+artifact(tx, ty, block_num=1)
	296	+# 等价于：
	297	+artifact.launch(tx, ty, block_num=1)
	298	+# 或显式传 args：
	299	+artifact.launch(args=(tx, ty), block_num=1)
	300	+```
	301	+
	302	+---
	303	+
	304	+#### `KernelLauncher.launch`
	305	+
	306	+源码： [`catlass.catlass_dsl.tla.KernelLauncher.launch`](../../../catlass/catlass_dsl/tla.py#L75)
	307	+
	308	+功能说明：
	309	+
	310	+在 NPU 上启动 `@tla.kernel`。先调用被装饰的 kernel 得到本对象
	311	+（`launcher = my_kernel(*tensors, options=...)`，此时不启动），再调用
	312	+`launcher.launch(...)` 或直接调用 launcher（`launcher(block_num=...)`，等价于
	313	+`.launch(args=..., **kwargs)`）。尚无缓存产物，或 runtime 选项与上次编译不一致时，
	314	+本方法会先编译再启动；runtime 选项不变且已有缓存产物时，不重新编译，直接启动。
	315	+需要固定一份编译产物并多次启动、且编译与启动分离时，使用 `tla.compile` 返回的
	316	+`TlaJitExecutor`。
	317	+
	318	+函数原型：
	319	+
	320	+```python
	321	+KernelLauncher.launch(, block_num: int \| None = None, type_args: Sequence[Any] \| None = None, args: Sequence[Any] \| None = None, *kwargs: Any) -> TlaExecutionResult
	322	+```
	323	+
	324	+参数说明：
	325	+
	326	+- `block_num`（`int \| None`）：启动的 block 数。可选，默认 `1`（也可来自
	327	+ 构造 launcher 时保存的 kwargs）。传入时须为 `int`。
	328	+- `type_args`（`Sequence[Any] \| None`）：编译期类型样本。可选；省略时由
	329	+ `args` / 第一次调用时的 launch args 推断。
	330	+- `args`（`Sequence[Any] \| None`）：显式运行时实参序列。可选。不能与
	331	+ launcher 上已由第一次调用（`my_kernel(*tensors)`）保存的 launch args 同时使用。
	332	+- `stream`（`Any`，经 `**kwargs`）：可选 ACL stream 句柄（常为 `int`）。
	333	+ 省略时优先用 `torch.npu.current_stream`；否则须显式传 `stream=`，
	334	+ 或依赖 `CATLASS_DSL_NPU_DEVICE`。
	335	+- `options`（`str`，经 `**kwargs`）：芯片名，如 `options="--npu-arch 3510"`。
	336	+ 可在第一次调用或本次传入；本调用 kwargs 覆盖构造 launcher 时保存的值。
	337	+
	338	+约束说明：
	339	+
	340	+- 调用 `@tla.kernel` 返回 `KernelLauncher`，不会启动；本方法（或调用 launcher）
	341	+ 在尚无缓存产物或 runtime 选项变化时编译并启动，runtime 选项不变且已有缓存产物时
	342	+ 不重新编译、直接启动。
	343	+- 第一次调用已传入 tensor（`my_kernel(tx, ty)`）时，第二次调用 / `.launch`
	344	+ 只应传 `block_num` 等启动 kwargs。
	345	+- 对同一 `KernelLauncher` 重复 `.launch` 时，runtime 选项不变则复用已编译产物，
	346	+ 不重新编译。需要显式分离编译与启动时，使用 `tla.compile`。
	347	+- launcher 已持有 launch args 时，不能再传 `args=`（`TlaUnsupportedAbiError`）。
	348	+- tensor 启动实参须为已绑定的 NPU 缓冲（`from_dlpack`）；
	349	+ `make_fake_tensor` 仅用于编译 / 类型样本。
	350	+- `block_num` 须为 `int`（默认 `1`）。
	351	+
	352	+调用示例：
	353	+
	354	+```python
	355	+@tla.kernel
	356	+def vadd(src: tla.Tensor, dst: tla.Tensor) -> None:
	357	+ with tla.vector():
	358	+ tla.copy(src, dst)
	359	+
	360	+vadd(tx, ty, options="--npu-arch 3510")(block_num=1)
	361	+# 或：
	362	+launcher = vadd(tx, ty, options="--npu-arch 3510")
	363	+launcher.launch(block_num=1)
	364	+# 第一次未传 tensor 时，可在 .launch 里传 args：
	365	+vadd(options="--npu-arch 3510").launch(args=(tx, ty), block_num=1)
	366	+```
	367	+
	368	+---
	369	+
	370	+### 2.3 查看 IR
	371	+
	372	+导出前端 TLA IR，不生成设备二进制，也不启动。
	373	+
	374	+#### `TlaJitFunction.dump_mlir`
	375	+
	376	+源码： [`catlass.dsl.TlaJitFunction.dump_mlir`](../../../catlass/dsl.py#L253)
	377	+
	378	+功能说明：
	379	+
	380	+返回该 kernel 的 TLA IR（`tlair`）MLIR 文本。不编译设备二进制，也不 launch。
	381	+
	382	+函数原型：
	383	+
	384	+```python
	385	+TlaJitFunction.dump_mlir(*, type_args: Sequence[Any] \| None = None) -> str
	386	+```
	387	+
	388	+参数说明：
	389	+
	390	+- `type_args`（`Sequence[Any] \| None`）：类型样本，用法同 `.compile()`。
	391	+ 可选，默认 `None`。
	392	+
	393	+约束说明：
	394	+
	395	+- `type_args` 规则与 `.compile()` 相同。
	396	+- 返回的是前端 TLA IR（`tlair`），不是 `TlaKernelArtifact.lowered_llvm` 中的
	397	+ HIVM/LLVM 形式。
	398	+
	399	+调用示例：
	400	+
	401	+```python
	402	+text = my_kernel.dump_mlir(type_args=[fa, fb])
	403	+print(text[:500])
	404	+```
	405	+
	406	+---
	407	+
	408	+## 3. Host Tensor
	409	+
	410	+构造 Host 侧 `tla.Tensor`，并可将静态 layout 尺寸标为动态，使同一份编译产物可在不同 shape 下运行。详见 [静态与动态 Layout](../kernel_development/core_concepts/layout.md)。
	411	+
	412	+### 3.1 创建与绑定
	413	+
	414	+用 `from_dlpack` 绑定真实 NPU 缓冲，或用 `make_fake_tensor` 造仅含元数据的类型样本。
	415	+
	416	+#### `from_dlpack`
	417	+
	418	+源码： [`catlass.tla.runtime.from_dlpack`](../../../catlass/tla/runtime.py#L625)
	419	+
	420	+功能说明：
	421	+
	422	+将 DLPack NPU tensor 零拷贝绑定为 TLA Host tensor。返回对象与 `tensor_dlpack` 共享同一块设备缓冲。
	423	+
	424	+函数原型：
	425	+
	426	+```python
	427	+tla.from_dlpack(tensor_dlpack: object, *, layout_tag: Any, origin_shape: Any \| None = None, assumed_align: int \| None = None, stream: int \| None = -1, element_type: type \| None = None) -> _Tensor
	428	+```
	429	+
	430	+参数说明：
	431	+
	432	+- `tensor_dlpack`（`object`）：实现了 `__dlpack__()` 的对象。须为 Ascend/NPU
	433	+ 缓冲（如 `torch_npu`）。CPU / NumPy 不可用。必填。
	434	+- `layout_tag`（`tla.arch.*`）：布局标签，如 `tla.arch.RowMajor`、
	435	+ `tla.arch.ColumnMajor`、`tla.arch.zN`。必填。
	436	+- `origin_shape`（`tuple \| int \| None`）：逻辑 origin，Python int 树。
	437	+ 可选；省略时由 DLPack 物理 shape 与 `layout_tag` 推导。不是 Kernel 的
	438	+ `tla.make_shape`。
	439	+- `assumed_align`（`int \| None`）：预留参数，当前无实际效果。
	440	+- `stream`（`int \| None`）：传给 `__dlpack__(stream=...)`。默认 `-1`（不做流同步）。
	441	+ `None` 表示省略 `stream` 参数。
	442	+- `element_type`（`type \| None`）：可选。覆盖从 DLPack 推导出的元素类型；
	443	+ 默认 `None` 表示沿用 DLPack。当 DLPack 无法表达真实类型时使用（例如 fp8），
	444	+ 传入 `tla.Float8E4M3FN` / `Float8E5M2`。须与导出缓冲的每元素位宽一致。
	445	+
	446	+约束说明：
	447	+
	448	+- 所有权遵循 DLPack consumer 约定：capsule 会被消费，返回的 Host tensor
	449	+ 销毁时调用 deleter；同时会保留对 `tensor_dlpack` 的引用，因此
	450	+ `from_dlpack(x.contiguous().to(device), ...)` 这类临时源是安全的。
	451	+- capsule 仅能消费一次；再次传入已消费的 capsule 会抛 `RuntimeTensorError`。
	452	+ 需要再次绑定时请重新调用 `from_dlpack`。
	453	+- 二维 `RowMajor` 须先 `tensor.contiguous()`；二维 `ColumnMajor` 须先
	454	+ `tensor.permute(1, 0).contiguous()`。物理布局不符时抛 `RuntimeTensorError`。
	455	+ 显式传入 `origin_shape` 则跳过该检查。
	456	+- 默认得到静态 layout。跨 shape 复用编译产物时再调用
	457	+ `mark_layout_dynamic` / `mark_compact_shape_dynamic`。
	458	+- 若指定 `element_type`，其每元素位宽须与导出的 DLPack 缓冲一致。
	459	+
	460	+调用示例：
	461	+
	462	+```python
	463	+tx = from_dlpack(x.contiguous(), layout_tag=tla.arch.RowMajor)
	464	+ty = from_dlpack(
	465	+ y.permute(1, 0).contiguous(),
	466	+ layout_tag=tla.arch.ColumnMajor,
	467	+)
	468	+```
	469	+
	470	+---
	471	+
	472	+#### `make_fake_tensor`
	473	+
	474	+源码： [`catlass.tla.runtime.make_fake_tensor`](../../../catlass/tla/runtime.py#L830)
	475	+
	476	+功能说明：
	477	+
	478	+构造仅含元数据、不绑定设备缓冲的 Host tensor（`data_ptr == 0`）。
	479	+用于无需 NPU 时给 `tla.compile` 提供类型样本。真实缓冲请用 `from_dlpack`。
	480	+
	481	+函数原型：
	482	+
	483	+```python
	484	+tla.make_fake_tensor(dtype: Any, shape: Any, stride: Any, *, layout_tag: Any \| None = None, addrspace: Any = AddressSpace.gm, origin_shape: Iterable[Any] \| None = None, coord: Iterable[Any] \| None = None, assumed_align: int \| None = None) -> _Tensor
	485	+```
	486	+
	487	+参数说明：
	488	+
	489	+- `dtype`：元素类型，如 `tla.Float16` / `tla.Float32`。必填。
	490	+- `shape`（`int \| tuple`）：逻辑 shape 树（zN 等物理布局用嵌套 tuple）。必填。
	491	+- `stride`（`int \| tuple`）：stride 树，结构须与 `shape` 一致。必填。
	492	+- `layout_tag`：`tla.arch` 标签。可选，默认 `tla.arch.RowMajor`。
	493	+- `addrspace`：地址空间。可选，默认 `AddressSpace.gm`。
	494	+- `origin_shape`（`int \| tuple \| None`）：逻辑 origin。可选，默认等于 `shape`。
	495	+- `coord`（`int \| tuple \| None`）：坐标树。可选；省略时由 layout 推导（通常为零）。
	496	+- `assumed_align`（`int \| None`）：预留参数，当前无实际效果。
	497	+
	498	+约束说明：
	499	+
	500	+- `shape` / `stride` / `origin_shape` / `coord` 须为 Python int 树，
	501	+ 不能是 Kernel 侧 `tla.make_shape` / `tla.make_stride` / `tla.make_coord`。
	502	+- 始终未绑定，不能直接 launch；真实缓冲须改用 `from_dlpack`。
	503	+- 显式传入的 `shape` / `stride` 按原样使用（不做 layout remap）。
	504	+
	505	+调用示例：
	506	+
	507	+```python
	508	+fa = make_fake_tensor(tla.Float16, (128, 64), (64, 1))
	509	+fzn = make_fake_tensor(
	510	+ tla.Float16,
	511	+ ((16, 2), (16, 4)),
	512	+ ((16, 256), (1, 512)),
	513	+ layout_tag=tla.arch.zN,
	514	+ origin_shape=(32, 64),
	515	+)
	516	+```
	517	+
	518	+---
	519	+
	520	+### 3.2 动态 Layout
	521	+
	522	+将静态 layout 尺寸标为动态。详见 [静态与动态 Layout](../kernel_development/core_concepts/layout.md)。
	523	+
	524	+#### `Tensor.mark_layout_dynamic`
	525	+
	526	+源码： [`catlass.tla.runtime._Tensor.mark_layout_dynamic`](../../../catlass/tla/runtime.py#L274)
	527	+
	528	+功能说明：
	529	+
	530	+将所有 shape 维标为动态，使一份 artifact 可接受不同 extents。
	531	+stride 除 leading 维（保持 `1`）外均变为动态；广播 stride `0` 保留。
	532	+对应的 `origin_shape` 叶节点也变为动态，编译类型不再依赖具体 DLPack 尺寸。
	533	+
	534	+函数原型：
	535	+
	536	+```python
	537	+tensor.mark_layout_dynamic(leading_dim: int \| None = None) -> '_Tensor'
	538	+```
	539	+
	540	+参数说明：
	541	+
	542	+- `leading_dim`（`int \| None`）：stride 为 `1` 的 leading 维索引。
	543	+ 可选，默认 `None`（由 `layout_tag` 或紧凑 stride 顺序推断）。
	544	+
	545	+约束说明：
	546	+
	547	+- 原地修改并返回 `self`（可链式调用）。
	548	+- 各 `coord` 叶节点必须为 `0`；切片子视图会失败。
	549	+- `leading_dim` 对应维的 stride 必须为 `1`。
	550	+- NZFamily 布局下，每组两个物理 shape 叶节点对应一个逻辑 `origin_shape` 轴。
	551	+
	552	+调用示例：
	553	+
	554	+```python
	555	+ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
	556	+ta = ta.mark_layout_dynamic()
	557	+artifact = tla.compile(my_kernel, ta, options="--npu-arch 3510")
	558	+```
	559	+
	560	+---
	561	+
	562	+#### `Tensor.mark_compact_shape_dynamic`
	563	+
	564	+源码： [`catlass.tla.runtime._Tensor.mark_compact_shape_dynamic`](../../../catlass/tla/runtime.py#L346)
	565	+
	566	+功能说明：
	567	+
	568	+将指定的一个紧凑 shape 维（`mode`）标为动态。以该维为因子的 major 维 stride
	569	+也会变为动态。对应的 `origin_shape` 叶节点同步标记，编译类型不再依赖具体尺寸。
	570	+
	571	+函数原型：
	572	+
	573	+```python
	574	+tensor.mark_compact_shape_dynamic(mode: int, stride_order: tuple[int, ...] \| None = None) -> '_Tensor'
	575	+```
	576	+
	577	+参数说明：
	578	+
	579	+- `mode`（`int`）：要标记为动态的扁平 shape 叶节点索引（从 0 开始）。必填。
	580	+- `stride_order`（`tuple[int, ...] \| None`）：紧凑 stride 顺序（外层 → 内层）。
	581	+ 可选；省略时由当前 stride 推断。
	582	+
	583	+约束说明：
	584	+
	585	+- 原地修改并返回 `self`。
	586	+- 各 `coord` 叶节点必须为 `0`。
	587	+- `stride_order` 须为 `range(rank)` 的一个排列。
	588	+- NZFamily 布局下，物理维 0/1 对应逻辑 M，物理维 2/3 对应逻辑 N。
	589	+
	590	+调用示例：
	591	+
	592	+```python
	593	+ta = from_dlpack(a.contiguous(), layout_tag=tla.arch.RowMajor)
	594	+ta = ta.mark_compact_shape_dynamic(mode=0)
	595	+```
	596	+
	597	+---

Mpython/tla_dsl/docs/zh/api/index.md+2-1

	@@ -9,4 +9,5 @@ CATLASS DSL 的 API 参考与文档生成维护说明。
9	\| 文档 \| 范围 \|	9	\| 文档 \| 范围 \|
10	\|------\|------\|	10	\|------\|------\|
11	\| [Kernel API 参考](kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|	11	\| [Kernel API 参考](kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|
12	-\| [API 文档生成](generate_api_docs.md) \| 从英文 docstring 重新生成 Kernel API 参考。 \|	12	+\| [Host API 参考](host_api_reference.md) \| Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 \|
		13	+\| [API 文档生成](generate_api_docs.md) \| 从英文 docstring 重新生成 Kernel / Host API 参考。 \|

Mpython/tla_dsl/docs/zh/api/kernel_api_reference.md+68-305

	@@ -5,7 +5,7 @@ nav_order: 10
5	<!--	5	<!--
6	Manually maintained Chinese Kernel API reference.	6	Manually maintained Chinese Kernel API reference.
7	Generated English source of truth: docs/en/api/kernel_api_reference.md	7	Generated English source of truth: docs/en/api/kernel_api_reference.md
8	-(from python/tla_dsl/tools/generate_api_reference.py + English docstrings).	8	+(from python/tla_dsl/tools/generate_kernel_api_reference.py + English docstrings).
9	Translate/update this file by hand when the English reference changes.	9	Translate/update this file by hand when the English reference changes.
10	Do not regenerate this file from a glossary.	10	Do not regenerate this file from a glossary.
11	-->	11	-->
	@@ -13,15 +13,13 @@ Do not regenerate this file from a glossary.
13	# TLA DSL Kernel API 参考	13	# TLA DSL Kernel API 参考
14		14
15	本文档介绍 TLA DSL 的 kernel 侧 Core API（通常以 `import catlass.tla as tla` 导入）。	15	本文档介绍 TLA DSL 的 kernel 侧 Core API（通常以 `import catlass.tla as tla` 导入）。
16	-内容覆盖基本数据类型、计算与同步接口、片上资源管理以及调试打印。Host tensor 接入见 [Host Tensor 接入](../kernel_development/core_concepts/tensor_binding.md)。	16	+内容覆盖基本数据类型、计算与同步接口、片上资源管理以及调试打印。Host 侧编译 / 启动 / tensor 绑定见 [Host API 参考](host_api_reference.md)；DLPack 接入教程见 [Host Tensor 接入](../kernel_development/core_concepts/tensor_binding.md)。
17		17
18	接口说明与调用示例来自各 op 源码 docstring；所有接口均须在 `@tla.kernel` 装饰的	18	接口说明与调用示例来自各 op 源码 docstring；所有接口均须在 `@tla.kernel` 装饰的
19	kernel 函数体内调用。	19	kernel 函数体内调用。
20		20
21	---	21	---
22		22
23	----
24	-
25	## 目录	23	## 目录
26		24
27	- [基本数据类型与操作](#基本数据类型与操作)	25	- [基本数据类型与操作](#基本数据类型与操作)
	@@ -50,7 +48,7 @@ Shape / Coord / Stride / Layout / Tensor 等前端结构化值的构造与视图
50		48
51	### `make_shape`	49	### `make_shape`
52		50
53	-源码： [`catlass.core_api.make_shape`](../../../catlass/core_api.py#L3517)	51	+源码： [`catlass.core_api.make_shape`](../../../catlass/core_api.py#L3519)
54		52
55	功能说明：	53	功能说明：
56		54
	@@ -90,13 +88,9 @@ zn_shape = tla.make_shape((16, 8), (16, 4))
90		88
91	---	89	---
92		90
93	----
94	-
95	----
96	-
97	### `make_coord`	91	### `make_coord`
98		92
99	-源码： [`catlass.core_api.make_coord`](../../../catlass/core_api.py#L3558)	93	+源码： [`catlass.core_api.make_coord`](../../../catlass/core_api.py#L3560)
100		94
101	功能说明：	95	功能说明：
102		96
	@@ -125,13 +119,9 @@ coord = tla.make_coord(block_row, 0)
125		119
126	---	120	---
127		121
128	----
129	-
130	----
131	-
132	### `make_stride`	122	### `make_stride`
133		123
134	-源码： [`catlass.core_api.make_stride`](../../../catlass/core_api.py#L3587)	124	+源码： [`catlass.core_api.make_stride`](../../../catlass/core_api.py#L3589)
135		125
136	功能说明：	126	功能说明：
137		127
	@@ -190,13 +180,9 @@ nz_stride = tla.make_stride((1, 1024), (16, 256))
190		180
191	---	181	---
192		182
193	----
194	-
195	----
196	-
197	### `make_layout`	183	### `make_layout`
198		184
199	-源码： [`catlass.core_api.make_layout`](../../../catlass/core_api.py#L3647)	185	+源码： [`catlass.core_api.make_layout`](../../../catlass/core_api.py#L3649)
200		186
201	功能说明：	187	功能说明：
202		188
	@@ -254,13 +240,9 @@ zn = tla.make_layout(
254		240
255	---	241	---
256		242
257	----
258	-
259	----
260	-
261	### `tile_view`	243	### `tile_view`
262		244
263	-源码： [`catlass.core_api.tile_view`](../../../catlass/core_api.py#L3816)	245	+源码： [`catlass.core_api.tile_view`](../../../catlass/core_api.py#L3818)
264		246
265	功能说明：	247	功能说明：
266		248
	@@ -293,13 +275,9 @@ tile = tla.tile_view(
293		275
294	---	276	---
295		277
296	----
297	-
298	----
299	-
300	### `make_tensor`	278	### `make_tensor`
301		279
302	-源码： [`catlass.core_api.make_tensor`](../../../catlass/core_api.py#L3863)	280	+源码： [`catlass.core_api.make_tensor`](../../../catlass/core_api.py#L3865)
303		281
304	功能说明：	282	功能说明：
305		283
	@@ -336,10 +314,6 @@ tensor = tla.make_tensor(ptr, layout, coord=tla.make_coord(0, 0))
336		314
337	---	315	---
338		316
339	----
340	-
341	----
342	-
343	### `make_tensor_like`	317	### `make_tensor_like`
344		318
345	源码： [`catlass.core_api.make_tensor_like`](../../../catlass/core_api.py#L4060)	319	源码： [`catlass.core_api.make_tensor_like`](../../../catlass/core_api.py#L4060)
	@@ -374,13 +348,9 @@ dst = tla.make_tensor_like(ptr, like=src_tile, layoutTag=tla.arch.RowMajor)
374		348
375	---	349	---
376		350
377	----
378	-
379	----
380	-
381	### `make_ptr`	351	### `make_ptr`
382		352
383	-源码： [`catlass.core_api.make_ptr`](../../../catlass/core_api.py#L7000)	353	+源码： [`catlass.core_api.make_ptr`](../../../catlass/core_api.py#L7241)
384		354
385	功能说明：	355	功能说明：
386		356
	@@ -412,13 +382,9 @@ ptr = tla.make_ptr(tla.Float16, addr, mem_space=tla.AddressSpace.gm)
412		382
413	---	383	---
414		384
415	----
416	-
417	----
418	-
419	### `recast_ptr`	385	### `recast_ptr`
420		386
421	-源码： [`catlass.core_api.recast_ptr`](../../../catlass/core_api.py#L7054)	387	+源码： [`catlass.core_api.recast_ptr`](../../../catlass/core_api.py#L7295)
422		388
423	功能说明：	389	功能说明：
424		390
	@@ -448,22 +414,18 @@ ptr_f32 = tla.recast_ptr(ptr_f16, dtype=tla.Float32)
448		414
449	---	415	---
450		416
451	----
452	-
453	----
454	-
455	## 数据搬运	417	## 数据搬运
456		418
457	片上与全局内存之间的 tensor 拷贝，以及 UB 寄存器 load/store。	419	片上与全局内存之间的 tensor 拷贝，以及 UB 寄存器 load/store。
458		420
459	### `copy`	421	### `copy`
460		422
461	-源码： [`catlass.core_api.copy`](../../../catlass/core_api.py#L4250)	423	+源码： [`catlass.core_api.copy`](../../../catlass/core_api.py#L4255)
462		424
463	功能说明：	425	功能说明：
464		426
465	在 tile 之间拷贝数据。硬件通路由 `src`/`dst` 地址空间决定（vector：GM↔UB、UB→L1；	427	在 tile 之间拷贝数据。硬件通路由 `src`/`dst` 地址空间决定（vector：GM↔UB、UB→L1；
466	-cube：GM→L1、L1→L0A/L0B、L0C→GM\|UB、L1→UB）。两侧 layout tag 选择格式转换（例如 ND→zN）。	428	+cube：GM→L1、L1→L0A/L0B、L0C→GM\|UB\|L1）。两侧 layout tag 选择格式转换（例如 ND→zN）。
467		429
468	拷贝 / 切块大小按各 tile 的逻辑 `origin_shape`（不是嵌套物理 `shape`）。	430	拷贝 / 切块大小按各 tile 的逻辑 `origin_shape`（不是嵌套物理 `shape`）。
469	物理 `shape` / `stride` 描述这些逻辑元素如何存放（凑齐对齐长度、zN 打包等）。	431	物理 `shape` / `stride` 描述这些逻辑元素如何存放（凑齐对齐长度、zN 打包等）。
	@@ -539,10 +501,6 @@ with tla.cube():
539		501
540	---	502	---
541		503
542	----
543	-
544	----
545	-
546	### `Tensor.load`	504	### `Tensor.load`
547		505
548	源码： [`catlass.tla.tensor._Tensor.load`](../../../catlass/tla/tensor.py#L215)	506	源码： [`catlass.tla.tensor._Tensor.load`](../../../catlass/tla/tensor.py#L215)
	@@ -579,8 +537,6 @@ with tla.vec.func(mode="simd"):
579		537
580	---	538	---
581		539
582	----
583	-
584	### `Tensor.store`	540	### `Tensor.store`
585		541
586	源码： [`catlass.tla.tensor._Tensor.store`](../../../catlass/tla/tensor.py#L383)	542	源码： [`catlass.tla.tensor._Tensor.store`](../../../catlass/tla/tensor.py#L383)
	@@ -617,15 +573,13 @@ with tla.vec.func(mode="simd"):
617		573
618	---	574	---
619		575
620	----
621	-
622	## 矩阵运算	576	## 矩阵运算
623		577
624	Cube 侧矩阵乘加（`tla.mmad`）。	578	Cube 侧矩阵乘加（`tla.mmad`）。
625		579
626	### `mmad`	580	### `mmad`
627		581
628	-源码： [`catlass.core_api.mmad`](../../../catlass/core_api.py#L5134)	582	+源码： [`catlass.core_api.mmad`](../../../catlass/core_api.py#L5204)
629		583
630	功能说明：	584	功能说明：
631		585
	@@ -651,6 +605,7 @@ tla.mmad(acc: Tensor, lhs: Tensor, rhs: Tensor, init_c: bool \| Bool \| None = Non
651		605
652	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。	606	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。
653	- 须在 `tla.cube()` 内调用；`acc`/`lhs`/`rhs` 须为匹配的 L0 tile。	607	- 须在 `tla.cube()` 内调用；`acc`/`lhs`/`rhs` 须为匹配的 L0 tile。
		608	+- 支持的元素类型通路包括 `f16`/`bf16`/`f32`，以及任意 `f8e4m3fn` / `f8e5m2` 操作数配对，累加到 L0C 上的 fp32。
654	- `init_c` 仅接受 Python `bool` 或 `i1` SSA 值。	609	- `init_c` 仅接受 Python `bool` 或 `i1` SSA 值。
655	- 不接受未知关键字参数；传入则报错。	610	- 不接受未知关键字参数；传入则报错。
656		611
	@@ -665,10 +620,6 @@ with tla.cube():
665		620
666	---	621	---
667		622
668	----
669	-
670	----
671	-
672	## Vector 运算	623	## Vector 运算
673		624
674	寄存器 Vector 路径上的计算与 mask 操作，通常须在 `tla.vec.func()` 内调用。	625	寄存器 Vector 路径上的计算与 mask 操作，通常须在 `tla.vec.func()` 内调用。
	@@ -679,7 +630,7 @@ Mask 创建与尾块更新。
679		630
680	#### `create_mask`	631	#### `create_mask`
681		632
682	-源码： [`catlass.core_api.create_mask`](../../../catlass/core_api.py#L7312)	633	+源码： [`catlass.core_api.create_mask`](../../../catlass/core_api.py#L7553)
683		634
684	功能说明：	635	功能说明：
685		636
	@@ -732,13 +683,9 @@ with tla.vec.func(mode="simd"):
732		683
733	---	684	---
734		685
735	----
736	-
737	----
738	-
739	#### `update_mask`	686	#### `update_mask`
740		687
741	-源码： [`catlass.core_api.update_mask`](../../../catlass/core_api.py#L7378)	688	+源码： [`catlass.core_api.update_mask`](../../../catlass/core_api.py#L7617)
742		689
743	功能说明：	690	功能说明：
744		691
	@@ -769,15 +716,11 @@ with tla.vec.func(mode="simd"):
769		716
770	---	717	---
771		718
772	----
773	-
774	----
775	-
776	### 基础算术	719	### 基础算术
777		720
778	#### `exp`	721	#### `exp`
779		722
780	-源码： [`catlass.core_api.exp`](../../../catlass/core_api.py#L5731)	723	+源码： [`catlass.core_api.exp`](../../../catlass/core_api.py#L5786)
781		724
782	功能说明：	725	功能说明：
783		726
	@@ -808,13 +751,9 @@ with tla.vec.func(mode="simd"):
808		751
809	---	752	---
810		753
811	----
812	-
813	----
814	-
815	#### `log`	754	#### `log`
816		755
817	-源码： [`catlass.core_api.log`](../../../catlass/core_api.py#L5753)	756	+源码： [`catlass.core_api.log`](../../../catlass/core_api.py#L5808)
818		757
819	功能说明：	758	功能说明：
820		759
	@@ -845,13 +784,9 @@ with tla.vec.func(mode="simd"):
845		784
846	---	785	---
847		786
848	----
849	-
850	----
851	-
852	#### `sqrt`	787	#### `sqrt`
853		788
854	-源码： [`catlass.core_api.sqrt`](../../../catlass/core_api.py#L5775)	789	+源码： [`catlass.core_api.sqrt`](../../../catlass/core_api.py#L5830)
855		790
856	功能说明：	791	功能说明：
857		792
	@@ -882,13 +817,9 @@ with tla.vec.func(mode="simd"):
882		817
883	---	818	---
884		819
885	----
886	-
887	----
888	-
889	#### `abs`	820	#### `abs`
890		821
891	-源码： [`catlass.core_api.abs`](../../../catlass/core_api.py#L5797)	822	+源码： [`catlass.core_api.abs`](../../../catlass/core_api.py#L5852)
892		823
893	功能说明：	824	功能说明：
894		825
	@@ -919,13 +850,9 @@ with tla.vec.func(mode="simd"):
919		850
920	---	851	---
921		852
922	----
923	-
924	----
925	-
926	#### `neg`	853	#### `neg`
927		854
928	-源码： [`catlass.core_api.neg`](../../../catlass/core_api.py#L5819)	855	+源码： [`catlass.core_api.neg`](../../../catlass/core_api.py#L6016)
929		856
930	功能说明：	857	功能说明：
931		858
	@@ -956,13 +883,9 @@ with tla.vec.func(mode="simd"):
956		883
957	---	884	---
958		885
959	----
960	-
961	----
962	-
963	#### `add`	886	#### `add`
964		887
965	-源码： [`catlass.core_api.add`](../../../catlass/core_api.py#L5999)	888	+源码： [`catlass.core_api.add`](../../../catlass/core_api.py#L6195)
966		889
967	功能说明：	890	功能说明：
968		891
	@@ -1001,13 +924,9 @@ with tla.vec.func(mode="simd"):
1001		924
1002	---	925	---
1003		926
1004	----
1005	-
1006	----
1007	-
1008	#### `sub`	927	#### `sub`
1009		928
1010	-源码： [`catlass.core_api.sub`](../../../catlass/core_api.py#L6045)	929	+源码： [`catlass.core_api.sub`](../../../catlass/core_api.py#L6241)
1011		930
1012	功能说明：	931	功能说明：
1013		932
	@@ -1043,13 +962,9 @@ with tla.vec.func(mode="simd"):
1043		962
1044	---	963	---
1045		964
1046	----
1047	-
1048	----
1049	-
1050	#### `mul`	965	#### `mul`
1051		966
1052	-源码： [`catlass.core_api.mul`](../../../catlass/core_api.py#L6082)	967	+源码： [`catlass.core_api.mul`](../../../catlass/core_api.py#L6278)
1053		968
1054	功能说明：	969	功能说明：
1055		970
	@@ -1086,13 +1001,9 @@ with tla.vec.func(mode="simd"):
1086		1001
1087	---	1002	---
1088		1003
1089	----
1090	-
1091	----
1092	-
1093	#### `max`	1004	#### `max`
1094		1005
1095	-源码： [`catlass.core_api.max`](../../../catlass/core_api.py#L6127)	1006	+源码： [`catlass.core_api.max`](../../../catlass/core_api.py#L6181)
1096		1007
1097	功能说明：	1008	功能说明：
1098		1009
	@@ -1124,13 +1035,9 @@ with tla.vec.func(mode="simd"):
1124		1035
1125	---	1036	---
1126		1037
1127	----
1128	-
1129	----
1130	-
1131	#### `min`	1038	#### `min`
1132		1039
1133	-源码： [`catlass.core_api.min`](../../../catlass/core_api.py#L6167)	1040	+源码： [`catlass.core_api.min`](../../../catlass/core_api.py#L6221)
1134		1041
1135	功能说明：	1042	功能说明：
1136		1043
	@@ -1162,13 +1069,9 @@ with tla.vec.func(mode="simd"):
1162		1069
1163	---	1070	---
1164		1071
1165	----
1166	-
1167	----
1168	-
1169	#### `div`	1072	#### `div`
1170		1073
1171	-源码： [`catlass.core_api.div`](../../../catlass/core_api.py#L6207)	1074	+源码： [`catlass.core_api.div`](../../../catlass/core_api.py#L6407)
1172		1075
1173	功能说明：	1076	功能说明：
1174		1077
	@@ -1204,15 +1107,11 @@ with tla.vec.func(mode="simd"):
1204		1107
1205	---	1108	---
1206		1109
1207	----
1208	-
1209	----
1210	-
1211	### 逻辑计算	1110	### 逻辑计算
1212		1111
1213	#### `bitwise_not`	1112	#### `bitwise_not`
1214		1113
1215	-源码： [`catlass.core_api.bitwise_not`](../../../catlass/core_api.py#L5965)	1114	+源码： [`catlass.core_api.bitwise_not`](../../../catlass/core_api.py#L6161)
1216		1115
1217	功能说明：	1116	功能说明：
1218		1117
	@@ -1243,13 +1142,9 @@ with tla.vec.func(mode="simd"):
1243		1142
1244	---	1143	---
1245		1144
1246	----
1247	-
1248	----
1249	-
1250	#### `bitwise_and`	1145	#### `bitwise_and`
1251		1146
1252	-源码： [`catlass.core_api.bitwise_and`](../../../catlass/core_api.py#L6576)	1147	+源码： [`catlass.core_api.bitwise_and`](../../../catlass/core_api.py#L6837)
1253		1148
1254	功能说明：	1149	功能说明：
1255		1150
	@@ -1281,13 +1176,9 @@ with tla.vec.func(mode="simd"):
1281		1176
1282	---	1177	---
1283		1178
1284	----
1285	-
1286	----
1287	-
1288	#### `bitwise_or`	1179	#### `bitwise_or`
1289		1180
1290	-源码： [`catlass.core_api.bitwise_or`](../../../catlass/core_api.py#L6614)	1181	+源码： [`catlass.core_api.bitwise_or`](../../../catlass/core_api.py#L6875)
1291		1182
1292	功能说明：	1183	功能说明：
1293		1184
	@@ -1319,13 +1210,9 @@ with tla.vec.func(mode="simd"):
1319		1210
1320	---	1211	---
1321		1212
1322	----
1323	-
1324	----
1325	-
1326	#### `bitwise_xor`	1213	#### `bitwise_xor`
1327		1214
1328	-源码： [`catlass.core_api.bitwise_xor`](../../../catlass/core_api.py#L6652)	1215	+源码： [`catlass.core_api.bitwise_xor`](../../../catlass/core_api.py#L6913)
1329		1216
1330	功能说明：	1217	功能说明：
1331		1218
	@@ -1357,36 +1244,33 @@ with tla.vec.func(mode="simd"):
1357		1244
1358	---	1245	---
1359		1246
1360	----
1361	-
1362	----
1363	-
1364	### 比较与选择	1247	### 比较与选择
1365		1248
1366	#### `where`	1249	#### `where`
1367		1250
1368	-源码： [`catlass.core_api.where`](../../../catlass/core_api.py#L6291)	1251	+源码： [`catlass.core_api.where`](../../../catlass/core_api.py#L6579)
1369		1252
1370	功能说明：	1253	功能说明：
1371		1254
1372	-按 mask 在两路 vector 间逐元素选择。	1255	+按 mask 在两路 vector 间逐元素选择；在 SIMT 区域内也可在两路 per-thread 标量间选择。
1373		1256
1374	函数原型：	1257	函数原型：
1375		1258
1376	```python	1259	```python
1377	-tla.where(mask: MaskSSA, x: VectorSSA, y: VectorSSA) -> VectorSSA	1260	+tla.where(mask: Any, x: Any, y: Any) -> Any
1378	```	1261	```
1379		1262
1380	参数说明：	1263	参数说明：
1381		1264
1382	-- `mask`（`MaskSSA`）：选择掩码；真取 `x`，假取 `y`。必填。	1265	+- `mask`（`MaskSSA \| Bool`）：选择掩码；真取 `x`，假取 `y`。可为整 vector 的 `MaskSSA`，或 SIMT 区域内比较得到的 `Bool`。必填。
1383	-- `x`（`VectorSSA`）：掩码为真时的取值。必填。	1266	+- `x`（`VectorSSA \| Numeric`）：掩码为真时的取值。必填。
1384	-- `y`（`VectorSSA`）：掩码为假时的取值。必填。	1267	+- `y`（`VectorSSA \| Numeric`）：掩码为假时的取值。必填。
1385		1268
1386	约束说明：	1269	约束说明：
1387		1270
1388	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。	1271	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。
1389	- 须在 `tla.vec.func()` 内调用；`mask`/`x`/`y` 的有效元素布局须匹配。	1272	- 须在 `tla.vec.func()` 内调用；`mask`/`x`/`y` 的有效元素布局须匹配。
		1273	+- per-thread 形式要求 `mode="simt"`，并生成 `tla.simt_where`。
1390		1274
1391	调用示例：	1275	调用示例：
1392		1276
	@@ -1395,15 +1279,10 @@ with tla.vec.func(mode="simd"):
1395	z = tla.where(m, x_reg, y_reg)	1279	z = tla.where(m, x_reg, y_reg)
1396	```	1280	```
1397		1281
1398	----
1399	-
1400	----
1401	-
1402	----
1403		1282
1404	#### `cmp`	1283	#### `cmp`
1405		1284
1406	-源码： [`catlass.core_api.cmp`](../../../catlass/core_api.py#L6498)	1285	+源码： [`catlass.core_api.cmp`](../../../catlass/core_api.py#L6761)
1407		1286
1408	功能说明：	1287	功能说明：
1409		1288
	@@ -1436,15 +1315,11 @@ with tla.vec.func(mode="simd"):
1436		1315
1437	---	1316	---
1438		1317
1439	----
1440	-
1441	----
1442	-
1443	### 数据填充	1318	### 数据填充
1444		1319
1445	#### `full`	1320	#### `full`
1446		1321
1447	-源码： [`catlass.core_api.full`](../../../catlass/core_api.py#L5243)	1322	+源码： [`catlass.core_api.full`](../../../catlass/core_api.py#L5319)
1448		1323
1449	功能说明：	1324	功能说明：
1450		1325
	@@ -1475,13 +1350,9 @@ with tla.vec.func(mode="simd"):
1475		1350
1476	---	1351	---
1477		1352
1478	----
1479	-
1480	----
1481	-
1482	#### `arange`	1353	#### `arange`
1483		1354
1484	-源码： [`catlass.core_api.arange`](../../../catlass/core_api.py#L5316)	1355	+源码： [`catlass.core_api.arange`](../../../catlass/core_api.py#L5392)
1485		1356
1486	功能说明：	1357	功能说明：
1487		1358
	@@ -1513,15 +1384,11 @@ with tla.vec.func(mode="simd"):
1513		1384
1514	---	1385	---
1515		1386
1516	----
1517	-
1518	----
1519	-
1520	### 离散与聚合	1387	### 离散与聚合
1521		1388
1522	#### `gather`	1389	#### `gather`
1523		1390
1524	-源码： [`catlass.core_api.gather`](../../../catlass/core_api.py#L6690)	1391	+源码： [`catlass.core_api.gather`](../../../catlass/core_api.py#L6951)
1525		1392
1526	功能说明：	1393	功能说明：
1527		1394
	@@ -1553,15 +1420,11 @@ with tla.vec.func(mode="simd"):
1553		1420
1554	---	1421	---
1555		1422
1556	----
1557	-
1558	----
1559	-
1560	### 数据重排	1423	### 数据重排
1561		1424
1562	#### `interleave`	1425	#### `interleave`
1563		1426
1564	-源码： [`catlass.core_api.interleave`](../../../catlass/core_api.py#L5856)	1427	+源码： [`catlass.core_api.interleave`](../../../catlass/core_api.py#L6054)
1565		1428
1566	功能说明：	1429	功能说明：
1567		1430
	@@ -1592,13 +1455,9 @@ with tla.vec.func(mode="simd"):
1592		1455
1593	---	1456	---
1594		1457
1595	----
1596	-
1597	----
1598	-
1599	#### `deinterleave`	1458	#### `deinterleave`
1600		1459
1601	-源码： [`catlass.core_api.deinterleave`](../../../catlass/core_api.py#L5910)	1460	+源码： [`catlass.core_api.deinterleave`](../../../catlass/core_api.py#L6107)
1602		1461
1603	功能说明：	1462	功能说明：
1604		1463
	@@ -1629,15 +1488,11 @@ with tla.vec.func(mode="simd"):
1629		1488
1630	---	1489	---
1631		1490
1632	----
1633	-
1634	----
1635	-
1636	### 数据压缩	1491	### 数据压缩
1637		1492
1638	#### `squeeze`	1493	#### `squeeze`
1639		1494
1640	-源码： [`catlass.core_api.squeeze`](../../../catlass/core_api.py#L6345)	1495	+源码： [`catlass.core_api.squeeze`](../../../catlass/core_api.py#L6608)
1641		1496
1642	功能说明：	1497	功能说明：
1643		1498
	@@ -1668,17 +1523,13 @@ with tla.vec.func(mode="simd"):
1668		1523
1669	---	1524	---
1670		1525
1671	----
1672	-
1673	----
1674	-
1675	## 同步控制	1526	## 同步控制
1676		1527
1677	核内 / 跨核 flag、pipe barrier、mutex 与本地内存屏障。	1528	核内 / 跨核 flag、pipe barrier、mutex 与本地内存屏障。
1678		1529
1679	### `flag`	1530	### `flag`
1680		1531
1681	-源码： [`catlass.core_api.flag`](../../../catlass/core_api.py#L4442)	1532	+源码： [`catlass.core_api.flag`](../../../catlass/core_api.py#L4496)
1682		1533
1683	功能说明：	1534	功能说明：
1684		1535
	@@ -1714,13 +1565,9 @@ with tla.vector():
1714		1565
1715	---	1566	---
1716		1567
1717	----
1718	-
1719	----
1720	-
1721	### `cross_flag`	1568	### `cross_flag`
1722		1569
1723	-源码： [`catlass.core_api.cross_flag`](../../../catlass/core_api.py#L4495)	1570	+源码： [`catlass.core_api.cross_flag`](../../../catlass/core_api.py#L4549)
1724		1571
1725	功能说明：	1572	功能说明：
1726		1573
	@@ -1750,13 +1597,9 @@ cf = tla.cross_flag("aic_aiv", mode=2)
1750		1597
1751	---	1598	---
1752		1599
1753	----
1754	-
1755	----
1756	-
1757	### `cross_core_set_flag`	1600	### `cross_core_set_flag`
1758		1601
1759	-源码： [`catlass.core_api.cross_core_set_flag`](../../../catlass/core_api.py#L4567)	1602	+源码： [`catlass.core_api.cross_core_set_flag`](../../../catlass/core_api.py#L4625)
1760		1603
1761	功能说明：	1604	功能说明：
1762		1605
	@@ -1789,13 +1632,9 @@ with tla.cube():
1789		1632
1790	---	1633	---
1791		1634
1792	----
1793	-
1794	----
1795	-
1796	### `cross_core_wait_flag`	1635	### `cross_core_wait_flag`
1797		1636
1798	-源码： [`catlass.core_api.cross_core_wait_flag`](../../../catlass/core_api.py#L4613)	1637	+源码： [`catlass.core_api.cross_core_wait_flag`](../../../catlass/core_api.py#L4669)
1799		1638
1800	功能说明：	1639	功能说明：
1801		1640
	@@ -1827,13 +1666,9 @@ with tla.vector():
1827		1666
1828	---	1667	---
1829		1668
1830	----
1831	-
1832	----
1833	-
1834	### `set_flag`	1669	### `set_flag`
1835		1670
1836	-源码： [`catlass.core_api.set_flag`](../../../catlass/core_api.py#L4658)	1671	+源码： [`catlass.core_api.set_flag`](../../../catlass/core_api.py#L4712)
1837		1672
1838	功能说明：	1673	功能说明：
1839		1674
	@@ -1863,13 +1698,9 @@ with tla.vector():
1863		1698
1864	---	1699	---
1865		1700
1866	----
1867	-
1868	----
1869	-
1870	### `wait_flag`	1701	### `wait_flag`
1871		1702
1872	-源码： [`catlass.core_api.wait_flag`](../../../catlass/core_api.py#L4684)	1703	+源码： [`catlass.core_api.wait_flag`](../../../catlass/core_api.py#L4738)
1873		1704
1874	功能说明：	1705	功能说明：
1875		1706
	@@ -1899,13 +1730,9 @@ with tla.vector():
1899		1730
1900	---	1731	---
1901		1732
1902	----
1903	-
1904	----
1905	-
1906	### `pipe_barrier`	1733	### `pipe_barrier`
1907		1734
1908	-源码： [`catlass.core_api.pipe_barrier`](../../../catlass/core_api.py#L4710)	1735	+源码： [`catlass.core_api.pipe_barrier`](../../../catlass/core_api.py#L4764)
1909		1736
1910	功能说明：	1737	功能说明：
1911		1738
	@@ -1935,13 +1762,9 @@ with tla.vector():
1935		1762
1936	---	1763	---
1937		1764
1938	----
1939	-
1940	----
1941	-
1942	### `mutex`	1765	### `mutex`
1943		1766
1944	-源码： [`catlass.core_api.mutex`](../../../catlass/core_api.py#L4745)	1767	+源码： [`catlass.core_api.mutex`](../../../catlass/core_api.py#L4807)
1945		1768
1946	功能说明：	1769	功能说明：
1947		1770
	@@ -1971,13 +1794,9 @@ mtx = tla.mutex("l1_buf", id=0)
1971		1794
1972	---	1795	---
1973		1796
1974	----
1975	-
1976	----
1977	-
1978	### `mutex_guard`	1797	### `mutex_guard`
1979		1798
1980	-源码： [`catlass.core_api.mutex_guard`](../../../catlass/core_api.py#L4793)	1799	+源码： [`catlass.core_api.mutex_guard`](../../../catlass/core_api.py#L4855)
1981		1800
1982	功能说明：	1801	功能说明：
1983		1802
	@@ -2007,13 +1826,9 @@ with tla.mutex_guard(mtx):
2007		1826
2008	---	1827	---
2009		1828
2010	----
2011	-
2012	----
2013	-
2014	### `mutex_lock`	1829	### `mutex_lock`
2015		1830
2016	-源码： [`catlass.core_api.mutex_lock`](../../../catlass/core_api.py#L4834)	1831	+源码： [`catlass.core_api.mutex_lock`](../../../catlass/core_api.py#L4896)
2017		1832
2018	功能说明：	1833	功能说明：
2019		1834
	@@ -2043,13 +1858,9 @@ tla.mutex_lock(mtx, pipe=tla.arch.MTE2)
2043		1858
2044	---	1859	---
2045		1860
2046	----
2047	-
2048	----
2049	-
2050	### `mutex_unlock`	1861	### `mutex_unlock`
2051		1862
2052	-源码： [`catlass.core_api.mutex_unlock`](../../../catlass/core_api.py#L4864)	1863	+源码： [`catlass.core_api.mutex_unlock`](../../../catlass/core_api.py#L4926)
2053		1864
2054	功能说明：	1865	功能说明：
2055		1866
	@@ -2079,13 +1890,9 @@ tla.mutex_unlock(mtx, pipe=tla.arch.MTE2)
2079		1890
2080	---	1891	---
2081		1892
2082	----
2083	-
2084	----
2085	-
2086	### `local_mem_bar`	1893	### `local_mem_bar`
2087		1894
2088	-源码： [`catlass.core_api.local_mem_bar`](../../../catlass/core_api.py#L4893)	1895	+源码： [`catlass.core_api.local_mem_bar`](../../../catlass/core_api.py#L4956)
2089		1896
2090	功能说明：	1897	功能说明：
2091		1898
	@@ -2116,17 +1923,13 @@ with tla.vec.func(mode="simd"):
2116		1923
2117	---	1924	---
2118		1925
2119	----
2120	-
2121	----
2122	-
2123	## 系统变量访问	1926	## 系统变量访问
2124		1927
2125	挂在 `tla.arch` 上的架构属性（布局标签、pipe、block 辅助等）。	1928	挂在 `tla.arch` 上的架构属性（布局标签、pipe、block 辅助等）。
2126		1929
2127	### `arch`	1930	### `arch`
2128		1931
2129	-源码： [`catlass.core_api.arch`](../../../catlass/core_api.py#L7170)	1932	+源码： [`catlass.core_api.arch`](../../../catlass/core_api.py#L7418)
2130		1933
2131	功能说明：	1934	功能说明：
2132		1935
	@@ -2157,7 +1960,7 @@ tla.arch
2157	`tla.vec.func(mode="simt")` 内使用）。	1960	`tla.vec.func(mode="simt")` 内使用）。
2158	- `sync_threads()`：对当前 SIMT `tla.vec.func` 内线程做 barrier（仅	1961	- `sync_threads()`：对当前 SIMT `tla.vec.func` 内线程做 barrier（仅
2159	`mode="simt"`）。	1962	`mode="simt"`）。
2160	- - `get_capacity_in_bytes(mem_scope)`：返回编译目标上某片上存储空间的字节容量。入参为 `tla.arch` 的 memory-scope token（`L1` / `L0A` / `L0B` / `L0C` / `UB`）。返回普通 `int`；host 侧与kernel 内均可使用（kernel 内会折叠为常量）。	1963	+ - `get_capacity_in_bytes(mem_scope)`：返回编译目标上某片上存储空间的字节容量。入参为 `tla.AddressSpace`（`tla.AddressSpace.l1` / `l0a` / `l0b` / `l0c` / `ub`）。返回普通 `int`；host 侧与 kernel 内均可使用（kernel 内会折叠为常量）。
2161		1964
2162	约束说明：	1965	约束说明：
2163		1966
	@@ -2186,17 +1989,13 @@ ub_bytes = tla.arch.get_capacity_in_bytes(tla.AddressSpace.ub)
2186		1989
2187	---	1990	---
2188		1991
2189	----
2190	-
2191	----
2192	-
2193	## 资源管理	1992	## 资源管理
2194		1993
2195	片上缓冲分配。	1994	片上缓冲分配。
2196		1995
2197	### `allocate`	1996	### `allocate`
2198		1997
2199	-源码： [`catlass.core_api.allocate`](../../../catlass/core_api.py#L6938)	1998	+源码： [`catlass.core_api.allocate`](../../../catlass/core_api.py#L7181)
2200		1999
2201	功能说明：	2000	功能说明：
2202		2001
	@@ -2233,17 +2032,13 @@ ptr = tla.allocate(
2233		2032
2234	---	2033	---
2235		2034
2236	----
2237	-
2238	----
2239	-
2240	## 调试接口	2035	## 调试接口
2241		2036
2242	kernel 内标量 / tensor 调试打印。	2037	kernel 内标量 / tensor 调试打印。
2243		2038
2244	### `print`	2039	### `print`
2245		2040
2246	-源码： [`catlass.core_api.print`](../../../catlass/core_api.py#L3355)	2041	+源码： [`catlass.core_api.print`](../../../catlass/core_api.py#L3359)
2247		2042
2248	功能说明：	2043	功能说明：
2249		2044
	@@ -2275,17 +2070,13 @@ with tla.vector():
2275		2070
2276	---	2071	---
2277		2072
2278	----
2279	-
2280	----
2281	-
2282	## 作用域和控制流	2073	## 作用域和控制流
2283		2074
2284	Cube / Vector / `vec.func` 区域以及 kernel 侧循环范围。	2075	Cube / Vector / `vec.func` 区域以及 kernel 侧循环范围。
2285		2076
2286	### `range`	2077	### `range`
2287		2078
2288	-源码： [`catlass.core_api.range`](../../../catlass/core_api.py#L4943)	2079	+源码： [`catlass.core_api.range`](../../../catlass/core_api.py#L5008)
2289		2080
2290	功能说明：	2081	功能说明：
2291		2082
	@@ -2317,15 +2108,9 @@ for i in tla.range(0, n, 1):
2317		2108
2318	---	2109	---
2319		2110
2320	----
2321	-
2322	----
2323	-
2324	----
2325	-
2326	### `range_constexpr`	2111	### `range_constexpr`
2327		2112
2328	-源码： [`catlass.core_api.range_constexpr`](../../../catlass/core_api.py#L4993)	2113	+源码： [`catlass.core_api.range_constexpr`](../../../catlass/core_api.py#L5058)
2329		2114
2330	功能说明：	2115	功能说明：
2331		2116
	@@ -2347,6 +2132,8 @@ tla.range_constexpr(start: int, end: int \| None = None, step: int \| None = None)
2347		2132
2348	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。	2133	- 须在 `@tla.kernel` 装饰的 kernel 函数体内调用。
2349	- 起止与步长须为编译期常量，用于可展开循环。	2134	- 起止与步长须为编译期常量，用于可展开循环。
		2135	+- 边界也可来自 `tla.as_numeric(...)` 等编译期 Numeric 值。
		2136	+- 迭代次数达到 64 次及以上时发出 `DSLOptimizationWarning`，但继续展开；大循环应优先用 `tla.range(...)`。
2350		2137
2351	调用示例：	2138	调用示例：
2352		2139
	@@ -2357,15 +2144,9 @@ for k in tla.range_constexpr(0, 4):
2357		2144
2358	---	2145	---
2359		2146
2360	----
2361	-
2362	----
2363	-
2364	----
2365	-
2366	### `cube`	2147	### `cube`
2367		2148
2368	-源码： [`catlass.core_api.cube`](../../../catlass/core_api.py#L5039)	2149	+源码： [`catlass.core_api.cube`](../../../catlass/core_api.py#L5109)
2369		2150
2370	功能说明：	2151	功能说明：
2371		2152
	@@ -2395,15 +2176,9 @@ with tla.cube():
2395		2176
2396	---	2177	---
2397		2178
2398	----
2399	-
2400	----
2401	-
2402	----
2403	-
2404	### `vector`	2179	### `vector`
2405		2180
2406	-源码： [`catlass.core_api.vector`](../../../catlass/core_api.py#L5061)	2181	+源码： [`catlass.core_api.vector`](../../../catlass/core_api.py#L5131)
2407		2182
2408	功能说明：	2183	功能说明：
2409		2184
	@@ -2433,15 +2208,9 @@ with tla.vector():
2433		2208
2434	---	2209	---
2435		2210
2436	----
2437	-
2438	----
2439	-
2440	----
2441	-
2442	### `vec.func`	2211	### `vec.func`
2443		2212
2444	-源码： [`catlass.core_api._vec_func`](../../../catlass/core_api.py#L5095)	2213	+源码： [`catlass.core_api._vec_func`](../../../catlass/core_api.py#L5165)
2445		2214
2446	功能说明：	2215	功能说明：
2447		2216
	@@ -2473,9 +2242,3 @@ with tla.vector():
2473	```	2242	```
2474		2243
2475	---	2244	---
2476	-
2477	----
2478	-
2479	----
2480	-
2481	----

Mpython/tla_dsl/docs/zh/index.md+4-2

	@@ -12,10 +12,12 @@ nav_order: 0
12	\| [环境准备](dsl_development/build_guide/index.md) \| 环境要求、安装方式（Conda / Docker）与最短上手路径。 \|	12	\| [环境准备](dsl_development/build_guide/index.md) \| 环境要求、安装方式（Conda / Docker）与最短上手路径。 \|
13	\| [编译与测试](dsl_development/build_guide/index.md) \| `./build.sh` 构建、pytest、lit 与 NPU 端到端示例。 \|	13	\| [编译与测试](dsl_development/build_guide/index.md) \| `./build.sh` 构建、pytest、lit 与 NPU 端到端示例。 \|
14	\| [Kernel API 参考](api/kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|	14	\| [Kernel API 参考](api/kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|
		15	+\| [Host API 参考](api/host_api_reference.md) \| Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 \|
15	\| [Host Tensor 接入](kernel_development/core_concepts/tensor_binding.md) \| Host 侧 `from_dlpack` / `make_fake_tensor`，供 `tla.compile` / 启动使用。 \|	16	\| [Host Tensor 接入](kernel_development/core_concepts/tensor_binding.md) \| Host 侧 `from_dlpack` / `make_fake_tensor`，供 `tla.compile` / 启动使用。 \|
16	\| [静态与动态 Layout](kernel_development/core_concepts/layout.md) \| 静态 / 动态 layout；在 Host tensor 上标记动态；在 kernel 中编程。 \|	17	\| [静态与动态 Layout](kernel_development/core_concepts/layout.md) \| 静态 / 动态 layout；在 Host tensor 上标记动态；在 kernel 中编程。 \|
17	\| [DSL 语法约束](kernel_development/core_concepts/syntax_guide.md) \| `@tla.kernel` 内允许的 Python 写法。 \|	18	\| [DSL 语法约束](kernel_development/core_concepts/syntax_guide.md) \| `@tla.kernel` 内允许的 Python 写法。 \|
18	\| [环境变量](kernel_development/core_concepts/env_vars.md) \| `CATLASS_DSL_*` 及相关环境变量。 \|	19	\| [环境变量](kernel_development/core_concepts/env_vars.md) \| `CATLASS_DSL_*` 及相关环境变量。 \|
19	-\| [构建 API 文档](api/generate_api_docs.md) \| 如何从英文 docstring 重新生成 `docs/en/api/kernel_api_reference.md`。 \|	20	+\| [构建 API 文档](api/generate_api_docs.md) \| 如何从英文 docstring 重新生成 Kernel / Host API 参考。 \|
20		21
21	-英文 Kernel API 由脚本生成（`python tools/generate_api_reference.py`）；中文 Kernel API 为手工维护，英文稿变更后请同步更新。	22	+英文 Kernel / Host API 由脚本生成（`python tools/generate_kernel_api_reference.py`、
		23	+`python tools/generate_host_api_reference.py`）；中文稿为手工维护，英文稿变更后请同步更新。

Mpython/tla_dsl/docs/zh/kernel_development/core_concepts/index.md+1-0

	@@ -12,4 +12,5 @@ CATLASS DSL 的核心概念与编程模型，包括 DSL 语法约束、控制流
12	\| [DSL 控制流](control_flow.md) \| Python staging 与运行时控制流的边界。 \|	12	\| [DSL 控制流](control_flow.md) \| Python staging 与运行时控制流的边界。 \|
13	\| [DSL Layout](layout.md) \| 静态 / 动态 layout 的含义与 kernel 侧编程。 \|	13	\| [DSL Layout](layout.md) \| 静态 / 动态 layout 的含义与 kernel 侧编程。 \|
14	\| [DSL Tensor 接入](tensor_binding.md) \| Host 侧 `from_dlpack` / `make_fake_tensor`。 \|	14	\| [DSL Tensor 接入](tensor_binding.md) \| Host 侧 `from_dlpack` / `make_fake_tensor`。 \|
		15	+\| [Host API 参考](../../api/host_api_reference.md) \| Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 \|
15	\| [DSL 环境变量](env_vars.md) \| `CATLASS_DSL_*` 及相关环境变量。 \|	16	\| [DSL 环境变量](env_vars.md) \| `CATLASS_DSL_*` 及相关环境变量。 \|

Mpython/tla_dsl/docs/zh/kernel_development/core_concepts/layout.md+1-1

	@@ -4,7 +4,7 @@ nav_order: 30
4		4
5	# DSL Layout	5	# DSL Layout
6		6
7	-本文介绍静态与动态 layout 的含义、如何把 Host tensor 设成动态 layout，以及在 Kernel 中如何编程。`from_dlpack` 等接入方式见 [DSL Tensor 接入](tensor_binding.md)。	7	+本文介绍静态与动态 layout 的含义、如何把 Host tensor 设成动态 layout，以及在 Kernel 中如何编程。`from_dlpack` 等接入方式见 [DSL Tensor 接入](tensor_binding.md)；`mark_*_dynamic` 等接口见 [Host API 参考](../../api/host_api_reference.md)。
8		8
9	---	9	---
10		10

Mpython/tla_dsl/docs/zh/kernel_development/core_concepts/syntax_guide.md+14-1

	@@ -24,7 +24,7 @@ CATLASS DSL 采用Python作为kernel描述语言，但由于NPU架构、性能
24	\| 类别 \| 判定 \| 例子 \|	24	\| 类别 \| 判定 \| 例子 \|
25	\| --- \| --- \| --- \|	25	\| --- \| --- \| --- \|
26	\| 静态 \| 编译期确定 \| 字面量、`tla.Constexpr[T]` 参数、`tla.const_expr(...)` 的值 \|	26	\| 静态 \| 编译期确定 \| 字面量、`tla.Constexpr[T]` 参数、`tla.const_expr(...)` 的值 \|
27	-\| 动态 \| 运行时确定 \| 张量元素、`tla.arch.block_idx()`、动态循环的循环变量及其运算结果（运行时变量类型为 `tla.Int32`/`tla.Bool` 等 `tla.*` 标量类型） \|	27	+\| 动态 \| 运行时确定 \| 张量元素、`tla.arch.block_idx()`、`tla.arch.block_num()`、动态循环的循环变量及其运算结果（运行时变量类型为 `tla.Int32`/`tla.Bool` 等 `tla.*` 标量类型） \|
28		28
29	由此区分两类控制流：	29	由此区分两类控制流：
30		30
	@@ -71,6 +71,19 @@ kernel 中出现的普通 Python 函数（模块级函数、不在白名单里
71	tla.make_coord(8, 0)	71	tla.make_coord(8, 0)
72	```	72	```
73		73
		74	+### 编译期展开
		75	+
		76	+需要小规模、有意的编译期展开时，使用 `tla.range_constexpr(...)`。边界须为编译期 Python 整数（也可来自 `tla.as_numeric(...)` 等编译期 Numeric 值）；Python 在构建 kernel 时执行循环并展开循环体。迭代次数达到 64 次及以上时，CATLASS 会在展开前发出一条 `DSLOptimizationWarning`，但仍会继续展开。不需要展开时应优先使用 `range(...)` 或 `tla.range(...)`。
		77	+
		78	+```python
		79	+@tla.kernel
		80	+def static_stages(count: tla.Constexpr[int]) -> None:
		81	+ for stage in tla.range_constexpr(count):
		82	+ emit_stage(stage)
		83	+```
		84	+
		85	+编译期 `while` 使用 `while tla.const_expr(condition):`，告警行为相同；条件写错可能导致编译无法终止，有界重复更推荐 `tla.range_constexpr(...)`。
		86	+
74	### 规划中的语义变更	87	### 规划中的语义变更
75		88
76	以下语义变更已在评审中确认，合入代码后本文档相应章节将同步更新。当前编写 kernel 时建议直接采用目标写法，避免后续迁移：	89	以下语义变更已在评审中确认，合入代码后本文档相应章节将同步更新。当前编写 kernel 时建议直接采用目标写法，避免后续迁移：

Mpython/tla_dsl/docs/zh/kernel_development/core_concepts/tensor_binding.md+1-1

	@@ -4,7 +4,7 @@ nav_order: 40
4		4
5	# DSL Tensor 接入	5	# DSL Tensor 接入
6		6
7	-本文说明如何在 Host 侧得到可供 `tla.compile` / 启动使用的 `tla.Tensor`：用 [DLPack](https://github.com/dmlc/dlpack) 的 `from_dlpack`（`torch` / `torch_npu`）绑定真实缓冲，或用 `make_fake_tensor` 造不带设备指针的类型样本。静态 / 动态 layout 见 [DSL Layout](layout.md)。	7	+本文说明如何在 Host 侧得到可供 `tla.compile` / 启动使用的 `tla.Tensor`：用 [DLPack](https://github.com/dmlc/dlpack) 的 `from_dlpack`（`torch` / `torch_npu`）绑定真实缓冲，或用 `make_fake_tensor` 造不带设备指针的类型样本。静态 / 动态 layout 见 [DSL Layout](layout.md)。接口完整说明见 [Host API 参考](../../api/host_api_reference.md)。
8		8
9	---	9	---
10		10

Mpython/tla_dsl/tests/test_api_reference_generation.py+29-7

	@@ -1,20 +1,22 @@
1	from __future__ import annotations	1	from __future__ import annotations
2		2
3	import difflib	3	import difflib
		4	+import importlib
4	import pathlib	5	import pathlib
5	import sys	6	import sys
6		7
7		8
8	-def test_generated_api_reference_is_current() -> None:	9	+def _assert_generated_doc_is_current(
9	- """Fail when docs/en/api/kernel_api_reference.md is stale relative to core_api.py / generator."""	10	+ relative: str, module_name: str, generate_fn_name: str, regen_hint: str
		11	+) -> None:
10	package_root = pathlib.Path(__file__).resolve().parents[1]	12	package_root = pathlib.Path(__file__).resolve().parents[1]
11	- doc = package_root / "docs" / "en" / "api" / "kernel_api_reference.md"	13	+ doc = package_root / relative
12	assert doc.is_file(), f"missing checked-in API reference: {doc}"	14	assert doc.is_file(), f"missing checked-in API reference: {doc}"
13		15
14	sys.path.insert(0, str(package_root / "tools"))	16	sys.path.insert(0, str(package_root / "tools"))
15	- from generate_api_reference import generate # noqa: E402	17	+ gen = importlib.import_module(module_name)
16		18
17	- expected = generate(docs_dir=doc.parent)	19	+ expected = getattr(gen, generate_fn_name)(docs_dir=doc.parent)
18	existing = doc.read_text(encoding="utf-8")	20	existing = doc.read_text(encoding="utf-8")
19	if existing == expected:	21	if existing == expected:
20	return	22	return
	@@ -29,7 +31,27 @@ def test_generated_api_reference_is_current() -> None:
29	)	31	)
30	)	32	)
31	raise AssertionError(	33	raise AssertionError(
32	- "docs/en/api/kernel_api_reference.md is out of date. Regenerate with:\n"	34	+ f"{relative} is out of date. Regenerate with:\n"
33	- " cd python/tla_dsl && python3 tools/generate_api_reference.py\n"	35	+ f" cd python/tla_dsl && {regen_hint}\n"
34	f"{diff}"	36	f"{diff}"
35	)	37	)
		38	+
		39	+
		40	+def test_generated_api_reference_is_current() -> None:
		41	+ """Fail when docs/en/api/kernel_api_reference.md is stale."""
		42	+ _assert_generated_doc_is_current(
		43	+ "docs/en/api/kernel_api_reference.md",
		44	+ "generate_kernel_api_reference",
		45	+ "generate",
		46	+ "python3 tools/generate_kernel_api_reference.py",
		47	+ )
		48	+
		49	+
		50	+def test_generated_host_api_reference_is_current() -> None:
		51	+ """Fail when docs/en/api/host_api_reference.md is stale."""
		52	+ _assert_generated_doc_is_current(
		53	+ "docs/en/api/host_api_reference.md",
		54	+ "generate_host_api_reference",
		55	+ "generate",
		56	+ "python3 tools/generate_host_api_reference.py",
		57	+ )

Rpython/tla_dsl/tools/generate_api_reference.py→python/tla_dsl/tools/common.py+176-385

Apython/tla_dsl/tools/generate_host_api_reference.py+271-0

Apython/tla_dsl/tools/generate_kernel_api_reference.py+295-0

	@@ -9,4 +9,5 @@ CATLASS DSL 的 API 参考与文档生成维护说明。
9	\| 文档 \| 范围 \|	9	\| 文档 \| 范围 \|
10	\|------\|------\|	10	\|------\|------\|
11	\| [Kernel API 参考](kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|	11	\| [Kernel API 参考](kernel_api_reference.md) \| Kernel 侧 Core API（`tla.copy`、`tla.mmad`、Vector 运算、同步等）。 \|
12	-\| [API 文档生成](generate_api_docs.md) \| 从英文 docstring 重新生成 Kernel API 参考。 \|	12	+\| [Host API 参考](host_api_reference.md) \| Host 侧 `@tla.kernel`、`tla.compile` / 启动、Host tensor。 \|
		13	+\| [API 文档生成](generate_api_docs.md) \| 从英文 docstring 重新生成 Kernel / Host API 参考。 \|