Merge remote-tracking branch 'origin/next' into work-graph

Author: Joshua You

include/luisa/xir/passes/alias_analysis.h

@@ -19,7 +19,9 @@ struct AliasAnalysisInfo {
     size_t queried_count{0u};
 };
 
-// Run analysis (pre-computes base alloca for all LOCAL instructions)
+// The query is deliberately stateless so operand rewrites cannot leave stale
+// cached alias facts. These entry points are retained for pipeline/report API
+// compatibility.
 [[nodiscard]] LUISA_XIR_API AliasAnalysisInfo alias_analysis_pass_run_on_function(FunctionDefinition *def) noexcept;
 [[nodiscard]] LUISA_XIR_API AliasAnalysisInfo alias_analysis_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;
 

include/luisa/xir/passes/const_fold.h

@@ -10,6 +10,10 @@ class PassReport;
 // This pass folds constant expressions at compile time.
 // Arithmetic operations with all-constant operands are evaluated
 // and replaced with a Constant value.
+// Target-dependent floating-point operations such as LERP and SMOOTHSTEP are
+// left intact when a host evaluation would not preserve strict backend
+// semantics. NaN and signed-zero cases are folded only when backend behavior is
+// unambiguous.
 
 struct ConstFoldInfo {
     size_t folded_inst_count{0u};

include/luisa/xir/passes/coro_cfg_distill.h

@@ -74,6 +74,10 @@ struct CoroCfgDistillResult {
     luisa::vector<FrameValue> frame_values;
 };
 
+// These analysis entry points do not mutate the input, but their scope/liveness
+// results are supported only for unstructured CFG. Call lower_switch followed by
+// destructure_cfg before distilling a function that contains structured or
+// ambiguous control flow (including SWITCH with a null merge).
 [[nodiscard]] LUISA_XIR_API CoroCfgDistillResult coro_cfg_distill_pass_run_on_function(Function *f) noexcept;
 [[nodiscard]] LUISA_XIR_API size_t coro_cfg_distill_pass_run_on_module(Module *m) noexcept;
 

include/luisa/xir/passes/coro_materialize.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <cstddef>
+
 #include <luisa/core/dll_export.h>
 #include <luisa/core/stl/string.h>
 #include <luisa/core/stl/unordered_map.h>
@@ -25,6 +27,14 @@ struct CoroMaterializeInfo {
     size_t suspend_lowered_count{0u};
     size_t resume_lowered_count{0u};
     size_t terminal_lowered_count{0u};
+    // Coro materialization is an unstructured-CFG-only transform. A non-zero
+    // value means the complete request was rejected before any IR was mutated.
+    size_t structured_cfg_error_count{0u};
+    size_t invalid_input_error_count{0u};
+
+    [[nodiscard]] bool succeeded() const noexcept {
+        return structured_cfg_error_count == 0u && invalid_input_error_count == 0u;
+    }
 
     struct TransitionEdge {
         size_t from_scope{0u};
@@ -37,6 +47,12 @@ struct CoroMaterializeInfo {
     luisa::unordered_map<luisa::string, const Type *> name_to_type;
 };
 
+// These entry points require lower_switch followed by destructure_cfg. SWITCH
+// is conservatively rejected even when its merge is null. Rejection is atomic:
+// no matching callable in the module is materialized. The split-aware overload
+// also rejects missing/duplicate/out-of-range scopes, duplicate/null/foreign
+// callables, and a frame argument that is not the callable's own reference
+// argument.
 [[nodiscard]] LUISA_XIR_API CoroMaterializeInfo coro_materialize_pass_run_on_module(Module *m) noexcept;
 [[nodiscard]] LUISA_XIR_API CoroMaterializeInfo coro_materialize_pass_run_on_module_with_cfg(
     Module *m, const CoroCfgDistillResult &cfg) noexcept;

include/luisa/xir/passes/coro_split.h

@@ -28,8 +28,25 @@ struct CoroSplitInfo {
         Value *frame_argument{nullptr};
     };
     luisa::vector<Subroutine> subroutines;
+    // Coro splitting is an unstructured-CFG-only transform. A non-zero value
+    // means the complete request was rejected before any IR was mutated.
+    size_t structured_cfg_error_count{0u};
+    size_t invalid_cfg_error_count{0u};
+
+    [[nodiscard]] bool succeeded() const noexcept {
+        return structured_cfg_error_count == 0u && invalid_cfg_error_count == 0u;
+    }
 };
 
+// Coro split does not lower structured control flow. Call lower_switch first,
+// then destructure_cfg, before invoking this pass. SWITCH is treated as
+// structured/ambiguous even when its merge is null. Module entry points are
+// atomic: if any coroutine definition is unsupported, no definition is split.
+// Explicit distilled CFG input must be non-empty and wholly owned by the module
+// passed to the entry point.
+[[nodiscard]] LUISA_XIR_API CoroSplitInfo coro_split_pass_run_on_module_info(Module *m) noexcept;
+// Compatibility count-only entry points return zero on rejection. Use an
+// Info-returning entry point when the caller must inspect error counts.
 [[nodiscard]] LUISA_XIR_API size_t coro_split_pass_run_on_module(Module *m) noexcept;
 [[nodiscard]] LUISA_XIR_API size_t coro_split_pass_run_on_module_with_cfg(
     Module *m, const CoroCfgDistillResult &cfg) noexcept;

include/luisa/xir/passes/destructure_cfg.h

@@ -20,6 +20,9 @@ struct DestructureCFGInfo {
     size_t leaked_block_count{0u};
 };
 
+// Explicitly lowers structured IF/LOOP/SIMPLE_LOOP/BREAK/CONTINUE constructs
+// in every block owned by the function, including disconnected regions.
+// SwitchInst is intentionally left for lower_switch_pass followed by this pass.
 [[nodiscard]] LUISA_XIR_API DestructureCFGInfo destructure_cfg_pass_run_on_function(Function *function) noexcept;
 [[nodiscard]] LUISA_XIR_API DestructureCFGInfo destructure_cfg_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;
 

include/luisa/xir/passes/fuse_consecutive_buffer_reads.h

@@ -12,6 +12,13 @@ struct FuseConsecutiveBufferReadsInfo {
     size_t fused_read_count{0u};
 };
 
+// This pass is intentionally quarantined as a no-op. XIR typed buffer
+// operations require the access type to equal the buffer element type, so a
+// scalar-to-vector rewrite is not legal without a byte-addressed lowering and
+// backend-independent proofs for alignment, bounds, aliasing, and volatility.
+// The entry points remain available for pipeline/API compatibility and report
+// zero changes.
+
 [[nodiscard]] LUISA_XIR_API FuseConsecutiveBufferReadsInfo
 fuse_consecutive_buffer_reads_pass_run_on_function(Function *function) noexcept;
 

include/luisa/xir/passes/if_conversion.h

@@ -12,8 +12,11 @@ struct IfConversionInfo {
     size_t converted_diamond_count{0u};
     size_t hoisted_inst_count{0u};
     size_t replaced_phi_count{0u};
+    size_t structured_cfg_error_count{0u};
+    [[nodiscard]] bool succeeded() const noexcept { return structured_cfg_error_count == 0u; }
 };
 
+// Unstructured-CFG-only: structured functions are rejected without mutation.
 [[nodiscard]] LUISA_XIR_API IfConversionInfo if_conversion_pass_run_on_function(Function *function) noexcept;
 [[nodiscard]] LUISA_XIR_API IfConversionInfo if_conversion_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;
 

include/luisa/xir/passes/inline.h

@@ -10,8 +10,13 @@ class PassReport;
 struct InlineInfo {
     size_t inlined_call_count{0u};
     size_t removed_callable_count{0u};
+    size_t skipped_recursive_callable_count{0u};
+    size_t skipped_structured_call_count{0u};
 };
 
+// Single-block callees can be inlined into structured callers without changing
+// their CFG. Multi-block inlining is unstructured-CFG-only; calls involving a
+// structured caller or callee are reported and left unchanged.
 [[nodiscard]] LUISA_XIR_API InlineInfo inline_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;
 [[nodiscard]] LUISA_XIR_API InlineInfo inline_all_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;
 

include/luisa/xir/passes/loop_fusion.h

@@ -8,8 +8,12 @@ class PassReport;
 
 struct LoopFusionInfo {
     size_t fused_loop_count{0u};
+    size_t structured_cfg_error_count{0u};
+    [[nodiscard]] bool succeeded() const noexcept { return structured_cfg_error_count == 0u; }
 };
 
+// Unstructured-CFG-only: structured functions are rejected without mutation.
+// Plain CFG is currently accepted unchanged pending canonical-loop support.
 [[nodiscard]] LUISA_XIR_API LoopFusionInfo loop_fusion_pass_run_on_function(Function *function) noexcept;
 [[nodiscard]] LUISA_XIR_API LoopFusionInfo loop_fusion_pass_run_on_module(Module *module, PassReport *report = nullptr) noexcept;