tilework 0.18.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +21 -0
  3. data/lib/tilework/backend/cpu/dsl_codegen.rb +509 -0
  4. data/lib/tilework/backend/cpu/ops_codegen.rb +451 -0
  5. data/lib/tilework/backend/cpu.rb +156 -0
  6. data/lib/tilework/buffer.rb +753 -0
  7. data/lib/tilework/capabilities.rb +183 -0
  8. data/lib/tilework/compat/cuda.h +66 -0
  9. data/lib/tilework/compat/hip.h +35 -0
  10. data/lib/tilework/compat/metal.h +45 -0
  11. data/lib/tilework/conformance.rb +2296 -0
  12. data/lib/tilework/core_ext.rb +21 -0
  13. data/lib/tilework/dialect.rb +67 -0
  14. data/lib/tilework/dsl.rb +722 -0
  15. data/lib/tilework/dtype/bfloat.rb +31 -0
  16. data/lib/tilework/dtype/cast.rb +88 -0
  17. data/lib/tilework/dtype/half.rb +98 -0
  18. data/lib/tilework/graph/builder.rb +1073 -0
  19. data/lib/tilework/graph/fusion.rb +520 -0
  20. data/lib/tilework/graph/grad.rb +443 -0
  21. data/lib/tilework/graph/high_level.rb +266 -0
  22. data/lib/tilework/graph/kernels.rb +403 -0
  23. data/lib/tilework/graph/node.rb +27 -0
  24. data/lib/tilework/graph/op.rb +290 -0
  25. data/lib/tilework/graph/optim.rb +183 -0
  26. data/lib/tilework/graph/plan.rb +1086 -0
  27. data/lib/tilework/graph/pool.rb +178 -0
  28. data/lib/tilework/graph/region.rb +210 -0
  29. data/lib/tilework/graph/residency.rb +449 -0
  30. data/lib/tilework/graph/state.rb +64 -0
  31. data/lib/tilework/graph/tensor.rb +124 -0
  32. data/lib/tilework/graph.rb +213 -0
  33. data/lib/tilework/kernel.rb +163 -0
  34. data/lib/tilework/math/conv.rb +270 -0
  35. data/lib/tilework/math/fft.rb +172 -0
  36. data/lib/tilework/math/nn.rb +1103 -0
  37. data/lib/tilework/math/philox.rb +194 -0
  38. data/lib/tilework/math/random.rb +232 -0
  39. data/lib/tilework/math/tensor_core.rb +269 -0
  40. data/lib/tilework/ops.rb +682 -0
  41. data/lib/tilework/runtime/offload.rb +498 -0
  42. data/lib/tilework/runtime/submission.rb +163 -0
  43. data/lib/tilework/runtime/telemetry.rb +112 -0
  44. data/lib/tilework/scope.rb +33 -0
  45. data/lib/tilework/version.rb +5 -0
  46. data/lib/tilework.rb +345 -0
  47. metadata +92 -0
@@ -0,0 +1,722 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tilework
4
+ # A DSL that turns kernels written as Ruby blocks into the CUDA-flavored
5
+ # dialect. Argument types are unknown when the block is defined, so a
6
+ # signature is built from the actual arguments at call time and source is
7
+ # specialized per signature (the output is ordinary dialect, so it rides
8
+ # the Dialect layer and the PSO cache as is).
9
+ #
10
+ # The supported Ruby subset is a whitelist; anything else is a CompileError
11
+ # with a line number. The AST comes from RubyVM::AbstractSyntaxTree (which
12
+ # ties the DSL to MRI).
13
+ module DSL
14
+ BLOCK = 256
15
+
16
+ BUILTIN_IDS = {
17
+ global_id_x: "GLOBAL_ID_X",
18
+ global_id_y: "GLOBAL_ID_Y",
19
+ local_id_x: "LOCAL_ID_X",
20
+ group_id_x: "GROUP_ID_X",
21
+ }.freeze
22
+ MATH_FNS = { exp: 1, log: 1, sqrt: 1, sin: 1, cos: 1, tanh: 1, pow: 2 }.freeze
23
+ ARITH_OPS = %i[+ - * / %].freeze
24
+ COMPARE_OPS = %i[== != < <= > >=].freeze
25
+
26
+ # One signature element: buffers carry an element type, scalars a value
27
+ # type. shape is [rows, cols] when the argument is a :buffer with a 2D
28
+ # shape (used to expand buf[r, c] and as compile-time constants for
29
+ # buf.rows / buf.cols), nil otherwise. storage is the in-memory spelling;
30
+ # only float16 differs from type (:float). Half precision is **a storage
31
+ # type only** and always widened to float in expressions (in a bare
32
+ # expression __half's operator* and friends match ambiguously).
33
+ Param = Struct.new(:kind, :type, :shape, :storage) # kind: :buffer | :scalar | :var
34
+
35
+ # A constant fixed at transpile time (an unroll loop variable or a host
36
+ # numeric constant appearing in an expression). code is the C literal to
37
+ # embed, type is :int / :float.
38
+ Const = Struct.new(:code, :type)
39
+
40
+ # An alias to a name inside the kernel (an argument / local variable) when
41
+ # an unroll element is a symbol. name is the identifier to emit; assignable
42
+ # says whether it can be assigned (only :var).
43
+ Alias = Struct.new(:name, :type, :assignable)
44
+
45
+ module_function
46
+
47
+ def signature_for(args)
48
+ args.map do |arg|
49
+ case arg
50
+ when Buffer
51
+ shape = arg.matrix? ? arg.shape : nil
52
+ # Half precision is :float as a type (expressions use float) but is
53
+ # declared as GPU_HALF; resolve_index inserts the cast on reads.
54
+ if %i[float16 bfloat16].include?(arg.dtype)
55
+ storage = arg.dtype == :float16 ? "GPU_HALF" : "GPU_BFLOAT"
56
+ Param.new(:buffer, :float, shape, storage)
57
+ else
58
+ Param.new(:buffer, arg.dtype == :int32 ? :int : :float, shape)
59
+ end
60
+ when Integer then Param.new(:scalar, :int)
61
+ when Float then Param.new(:scalar, :float)
62
+ else
63
+ raise LaunchError, "unsupported kernel argument: #{arg.class} (expected Tilework::Buffer, Float, or Integer)"
64
+ end
65
+ end
66
+ end
67
+
68
+ # Ruby block + signature → dialect kernel source
69
+ class Transpiler
70
+ def initialize(block, signature, name, domain: nil)
71
+ @block = block
72
+ @signature = signature
73
+ @name = name
74
+ @domain = domain # [x range, y range]; nil means an explicit launch, so no guard
75
+ @binding = block.binding # closure binding used to resolve unroll / host constants
76
+ end
77
+
78
+ def transpile
79
+ scope = ast_of(@block)
80
+ locals, args_node, body = scope.children
81
+ param_names = locals.first(args_node.children[0])
82
+ unless param_names.length == @signature.length
83
+ raise CompileError,
84
+ "kernel '#{@name}' takes #{param_names.length} parameters but was called with #{@signature.length} arguments"
85
+ end
86
+
87
+ @env = param_names.zip(@signature).to_h
88
+ # Names of buffers written in the body (targets of buf[i] = ...).
89
+ # Unwritten buffers become device const* to benefit from the constant cache.
90
+ @written = {}
91
+
92
+ # The const decision needs @written, so translate the body before declaring params.
93
+ lines = body.nil? ? [] : statements(body, 1)
94
+
95
+ params = param_names.zip(@signature).map do |pname, param|
96
+ if param.kind == :buffer
97
+ # Unwritten buffers are const (decided by scanning the body, so a
98
+ # mistake shows up as a compile error, not a silent wrong result).
99
+ # No restrict: aliasing the same buffer could break it.
100
+ qualifier = @written[pname] ? "device" : "device const"
101
+ "#{qualifier} #{param.storage || param.type}* #{pname}"
102
+ else
103
+ "constant #{param.type}& #{pname}"
104
+ end
105
+ end
106
+ <<~KERNEL
107
+ GPU_KERNEL void #{@name}(GPU_ARGS,
108
+ #{params.join(",\n ")}) {
109
+ #{domain_guard}#{lines.join("\n")}
110
+ }
111
+ KERNEL
112
+ end
113
+
114
+ private
115
+
116
+ # Keep threads outside the launch domain out of the body. A grid launches
117
+ # whole blocks only, so extra edge threads always run. An early return
118
+ # keeps existing lines' indentation unchanged (DSL kernels never use
119
+ # GPU_BARRIER, so some threads returning early is safe).
120
+ def domain_guard
121
+ return "" if @domain.nil?
122
+
123
+ x, y = @domain
124
+ cond = ["GLOBAL_ID_X >= #{x}"]
125
+ cond << "GLOBAL_ID_Y >= #{y}" if y > 1
126
+ " if (#{cond.join(' || ')}) return;\n"
127
+ end
128
+
129
+ def ast_of(block)
130
+ RubyVM::AbstractSyntaxTree.of(block)
131
+ rescue StandardError => e
132
+ raise CompileError, "Tilework.kernel requires a block defined in a readable source file: #{e.message}"
133
+ end
134
+
135
+ def unsupported!(node, what = nil)
136
+ raise CompileError,
137
+ "unsupported Ruby syntax in Tilework.kernel at line #{node.first_lineno}: #{what || node.type}"
138
+ end
139
+
140
+ # --- Statements ---
141
+
142
+ def statements(node, depth)
143
+ list = node.type == :BLOCK ? node.children : [node]
144
+ list.flat_map { |n| statement(n, depth) }
145
+ end
146
+
147
+ def statement(node, depth)
148
+ pad = " " * depth
149
+ case node.type
150
+ when :LASGN, :DASGN, :DASGN_CURR
151
+ [pad + assign(node)]
152
+ when :ATTRASGN
153
+ [pad + index_assign(node)]
154
+ when :IF, :UNLESS
155
+ if_statement(node, depth)
156
+ when :WHILE
157
+ cond, = expr(node.children[0])
158
+ [pad + "while (#{cond}) {", *statements(node.children[1], depth + 1), pad + "}"]
159
+ when :ITER
160
+ loop_statement(node, depth)
161
+ else
162
+ unsupported!(node)
163
+ end
164
+ end
165
+
166
+ def assign(node)
167
+ name, value_node = node.children
168
+ code, type = expr(value_node)
169
+ if (existing = @env[name])
170
+ case existing
171
+ when Const
172
+ unsupported!(node, "cannot assign to unrolled constant '#{name}'")
173
+ when Alias
174
+ unsupported!(node, "cannot assign to read-only '#{name}' (:#{existing.name})") unless existing.assignable
175
+ unsupported!(node, "reassigning #{type} value to #{existing.type} variable '#{name}'") if
176
+ existing.type == :int && type == :float
177
+ "#{existing.name} = #{code};"
178
+ else
179
+ unsupported!(node, "reassigning #{type} value to #{existing.type} variable '#{name}'") if
180
+ existing.type == :int && type == :float
181
+ "#{name} = #{code};"
182
+ end
183
+ else
184
+ @env[name] = Param.new(:var, type)
185
+ "#{type} #{name} = #{code};"
186
+ end
187
+ end
188
+
189
+ def index_assign(node)
190
+ recv, mid, args = node.children
191
+ unsupported!(node, "#{mid} assignment") unless mid == :[]=
192
+ parts = args.children.compact
193
+ # ATTRASGN's arguments are [indices..., value] ([idx, value] for one
194
+ # index, [r, c, value] for two).
195
+ value_node = parts.pop
196
+ target, elem = resolve_index(recv, parts, node)
197
+ # After resolve_index, recv is a buffer parameter's LVAR/DVAR. Record its
198
+ # name as written, removing it from const.
199
+ @written[recv.children[0]] = true
200
+ val_code, val_type = expr(value_node)
201
+ val_code = "(#{elem})(#{val_code})" unless val_type == elem
202
+ "#{target} = #{val_code};"
203
+ end
204
+
205
+ def if_statement(node, depth)
206
+ pad = " " * depth
207
+ # UNLESS also has children [condition, body, else]; only the condition is negated
208
+ cond_node, then_node, else_node = node.children
209
+ cond, = expr(cond_node)
210
+ cond = "!(#{cond})" if node.type == :UNLESS
211
+ lines = [pad + "if (#{cond}) {", *statements(then_node, depth + 1)]
212
+ lines += [pad + "} else {", *statements(else_node, depth + 1)] if else_node
213
+ lines << (pad + "}")
214
+ end
215
+
216
+ def loop_statement(node, depth)
217
+ pad = " " * depth
218
+ call, scope = node.children
219
+
220
+ # unroll(host_array) do |a, b| ... end: not a loop at GPU run time —
221
+ # the host array is iterated in Ruby at transpile time and the body duplicated.
222
+ return unroll_statement(call, scope, depth) if call.type == :FCALL && call.children[0] == :unroll
223
+
224
+ var = scope.children[0].first
225
+ recv, mid = call.children
226
+ recv = unwrap_block(recv)
227
+ header =
228
+ case mid
229
+ when :times
230
+ count, type = expr(recv)
231
+ unsupported!(node, "non-integer .times receiver") unless type == :int
232
+ "for (int #{var} = 0; #{var} < #{count}; #{var}++) {"
233
+ when :each
234
+ unsupported!(node, "each on #{recv.type}") unless %i[DOT2 DOT3].include?(recv.type)
235
+ lo, lo_t = expr(recv.children[0])
236
+ hi, hi_t = expr(recv.children[1])
237
+ unsupported!(node, "non-integer range bounds") unless lo_t == :int && hi_t == :int
238
+ cmp = recv.type == :DOT3 ? "<" : "<="
239
+ "for (int #{var} = #{lo}; #{var} #{cmp} #{hi}; #{var}++) {"
240
+ else
241
+ unsupported!(node, "block call .#{mid} (only .times and range .each loop)")
242
+ end
243
+
244
+ outer = @env.key?(var) ? @env[var] : nil
245
+ @env[var] = Param.new(:var, :int)
246
+ body = scope.children[2] ? statements(scope.children[2], depth + 1) : []
247
+ outer ? @env[var] = outer : @env.delete(var)
248
+ [pad + header, *body, pad + "}"]
249
+ end
250
+
251
+ # Expands unroll(collection) do |a, b| ... end. collection is evaluated in
252
+ # the host binding; for each element the block parameters are inserted
253
+ # into @env as constants, the body is translated, and the outputs are
254
+ # concatenated. The loop variable is a compile-time constant, so there is
255
+ # no for/while — the body is simply duplicated.
256
+ def unroll_statement(fcall, scope, depth)
257
+ arg_nodes = fcall.children[1]&.children&.compact || []
258
+ unsupported!(fcall, "unroll takes exactly one argument") unless arg_nodes.length == 1
259
+
260
+ collection = host_eval(arg_nodes.first)
261
+ unless collection.is_a?(Array)
262
+ raise CompileError, "unroll expects a host Array, got #{collection.class} (at line #{fcall.first_lineno})"
263
+ end
264
+
265
+ locals, args_node, body = scope.children
266
+ param_names = locals.first(args_node.children[0])
267
+
268
+ collection.flat_map do |element|
269
+ values = param_names.length == 1 ? [element] : Array(element)
270
+ unless values.length == param_names.length
271
+ raise CompileError,
272
+ "unroll block expects #{param_names.length} value(s) but element #{element.inspect} yields #{values.length}"
273
+ end
274
+
275
+ with_bindings(param_names.zip(values)) do
276
+ body ? statements(body, depth) : []
277
+ end
278
+ end
279
+ end
280
+
281
+ # Temporarily inserts unroll loop variables into @env, evaluates the block, then restores.
282
+ def with_bindings(pairs)
283
+ saved = pairs.map { |name, _| [name, @env.fetch(name, :__absent)] }
284
+ pairs.each { |name, value| @env[name] = bind_value(value) }
285
+ yield
286
+ ensure
287
+ saved.each { |name, old| old == :__absent ? @env.delete(name) : (@env[name] = old) }
288
+ end
289
+
290
+ # Turns an unroll element's value into a binding for the loop variable.
291
+ # number → Const (embedded as a C literal)
292
+ # symbol → Alias (an alias to a kernel argument / local variable)
293
+ def bind_value(value)
294
+ case value
295
+ when Integer then Const.new(value.to_s, :int)
296
+ when Float then Const.new("#{value}f", :float)
297
+ when Symbol
298
+ target = @env[value] or
299
+ raise CompileError, "unroll symbol :#{value} does not name a kernel parameter or variable"
300
+ case target
301
+ when Param then Alias.new(value.to_s, target.type, target.kind == :var)
302
+ else target # already a Const / Alias, so chain it as is
303
+ end
304
+ else
305
+ raise CompileError, "unroll values must be Integer, Float, or Symbol, got #{value.class} (#{value.inspect})"
306
+ end
307
+ end
308
+
309
+ # Evaluates an AST node as a host value (for unroll arguments and host
310
+ # constants in expressions). Only constants, local variables and
311
+ # numeric/array literals are allowed; no arbitrary code runs.
312
+ def host_eval(node)
313
+ case node.type
314
+ when :INTEGER, :FLOAT, :LIT then node.children[0]
315
+ when :STR then node.children[0]
316
+ when :LVAR, :DVAR then @binding.local_variable_get(node.children[0])
317
+ when :CONST, :COLON2, :COLON3 then @binding.eval(const_name(node))
318
+ when :LIST, :ARRAY then node.children.compact.map { |c| host_eval(c) }
319
+ else
320
+ raise CompileError,
321
+ "cannot evaluate host expression (#{node.type}) at line #{node.first_lineno}; " \
322
+ "use a constant, local variable, or literal"
323
+ end
324
+ end
325
+
326
+ def const_name(node)
327
+ case node.type
328
+ when :CONST then node.children[0].to_s
329
+ when :COLON2 then "#{node.children[0] ? const_name(node.children[0]) : ''}::#{node.children[1]}"
330
+ when :COLON3 then "::#{node.children[0]}"
331
+ else unsupported!(node, "constant reference")
332
+ end
333
+ end
334
+
335
+ # Resolves a constant appearing in an expression (like WIN_LENGTH) on the
336
+ # host and embeds it as a C literal if numeric. Non-numerics such as arrays
337
+ # cannot be embedded in an expression.
338
+ def host_const(node)
339
+ value = host_eval(node)
340
+ case value
341
+ when Integer then [value.to_s, :int]
342
+ when Float then ["#{value}f", :float]
343
+ else unsupported!(node, "constant #{const_name(node)} is #{value.class}, not a number")
344
+ end
345
+ end
346
+
347
+ # --- Expressions → [C code, type (:int | :float)] ---
348
+
349
+ def expr(node)
350
+ case node.type
351
+ when :LIT
352
+ literal(node, node.children[0])
353
+ when :INTEGER then [node.children[0].to_s, :int]
354
+ when :FLOAT then literal(node, node.children[0])
355
+ when :LVAR, :DVAR
356
+ variable(node)
357
+ when :OPCALL
358
+ opcall(node)
359
+ when :AND, :OR
360
+ # a && b && c puts every operand in one AND node rather than nesting,
361
+ # so fold all children, not just children[0..1].
362
+ op = node.type == :AND ? "&&" : "||"
363
+ parts = node.children.compact.map { |child| expr(child).first }
364
+ ["(#{parts.join(" #{op} ")})", :int]
365
+ when :CALL
366
+ call(node)
367
+ when :VCALL
368
+ builtin(node)
369
+ when :CONST, :COLON2, :COLON3
370
+ host_const(node)
371
+ when :IF
372
+ ternary(node)
373
+ when :BLOCK
374
+ expr(unwrap_block(node))
375
+ else
376
+ unsupported!(node)
377
+ end
378
+ end
379
+
380
+ # Some Ruby versions parse grouping parentheses inside an expression
381
+ # (e.g. 1.0 + (2.0 + 3.0), (lo...hi).each) as a single-element :BLOCK node
382
+ # (normally for begin/end or multiple statements). In expression or
383
+ # receiver context a :BLOCK is always this one-element parenthesis
384
+ # pattern, so unwrap it. Anything else (not exactly one element, or not a
385
+ # :BLOCK) returns node as is.
386
+ def unwrap_block(node)
387
+ return node unless node.type == :BLOCK
388
+
389
+ children = node.children.compact
390
+ unsupported!(node, "expected a single parenthesized expression") unless children.length == 1
391
+ children.first
392
+ end
393
+
394
+ def literal(node, value)
395
+ case value
396
+ when Integer then [value.to_s, :int]
397
+ when Float then ["#{value}f", :float]
398
+ else unsupported!(node, "#{value.class} literal")
399
+ end
400
+ end
401
+
402
+ def variable(node)
403
+ name = node.children[0]
404
+ entry = @env[name]
405
+ case entry
406
+ when Const then [entry.code, entry.type] # a constant inserted by unroll
407
+ when Alias then [entry.name, entry.type] # an alias bound by unroll to a kernel variable
408
+ when Param
409
+ unsupported!(node, "buffer '#{name}' must be indexed") if entry.kind == :buffer
410
+ [name.to_s, entry.type]
411
+ else
412
+ unsupported!(node, "unknown variable '#{name}'")
413
+ end
414
+ end
415
+
416
+ def opcall(node)
417
+ recv, op, args = node.children
418
+ if args.nil? # unary operator
419
+ code, type = expr(recv)
420
+ case op
421
+ when :-@ then ["(-#{code})", type]
422
+ when :! then ["(!#{code})", :int]
423
+ else unsupported!(node, "unary #{op}")
424
+ end
425
+ else
426
+ l, lt = expr(recv)
427
+ r, rt = expr(args.children[0])
428
+ if COMPARE_OPS.include?(op)
429
+ ["(#{l} #{op} #{r})", :int]
430
+ elsif ARITH_OPS.include?(op)
431
+ type = lt == :float || rt == :float ? :float : :int
432
+ unsupported!(node, "% on float operands") if op == :% && type == :float
433
+ ["(#{l} #{op} #{r})", type]
434
+ else
435
+ unsupported!(node, "operator #{op}")
436
+ end
437
+ end
438
+ end
439
+
440
+ def call(node)
441
+ recv, mid, args = node.children
442
+ case
443
+ when mid == :[]
444
+ code, elem, storage = resolve_index(recv, args.children.compact, node)
445
+ # Half cannot sit in a bare expression (operators match ambiguously); widen to float.
446
+ read = storage == "GPU_BFLOAT" ? "GPU_BFLOAT_TO_FLOAT(#{code})" : "((float)#{code})"
447
+ [storage ? read : code, elem]
448
+ when recv.type == :CONST && recv.children[0] == :Math
449
+ math_call(node, mid, args)
450
+ when mid == :abs && args.nil?
451
+ code, type = expr(recv)
452
+ [type == :float ? "fabs(#{code})" : "abs(#{code})", type]
453
+ when (mid == :rows || mid == :cols) && args.nil? && %i[LVAR DVAR].include?(recv.type)
454
+ shape = buffer_shape(recv, node, "call .#{mid}")
455
+ [(mid == :rows ? shape[0] : shape[1]).to_s, :int]
456
+ else
457
+ unsupported!(node, "method call .#{mid}")
458
+ end
459
+ end
460
+
461
+ def math_call(node, mid, args)
462
+ arity = MATH_FNS[mid] or unsupported!(node, "Math.#{mid}")
463
+ actual = args ? args.children.compact : []
464
+ unsupported!(node, "Math.#{mid} takes #{arity} arguments") unless actual.length == arity
465
+ converted = actual.map { |a| "(float)(#{expr(a).first})" }
466
+ ["#{mid}(#{converted.join(', ')})", :float]
467
+ end
468
+
469
+ def builtin(node)
470
+ name = node.children[0]
471
+ macro = BUILTIN_IDS[name] or unsupported!(node, "unknown identifier '#{name}'")
472
+ [macro, :int]
473
+ end
474
+
475
+ def ternary(node)
476
+ cond_node, then_node, else_node = node.children
477
+ unsupported!(node, "if expression without else") if then_node.nil? || else_node.nil?
478
+ cond, = expr(cond_node)
479
+ t, tt = expr(then_node)
480
+ e, et = expr(else_node)
481
+ ["(#{cond} ? #{t} : #{e})", tt == :float || et == :float ? :float : :int]
482
+ end
483
+
484
+ # Handles buf[i] (1D) and buf[r, c] (2D, expanded to a row-major flat
485
+ # index) alike. Returns [C index expression (e.g. "buf[i]"), element type,
486
+ # storage type]. **No cast is inserted** — it is also used as an assignment
487
+ # target; the read side (#call) widens to float based on the storage type.
488
+ def resolve_index(recv, idx_nodes, ctx)
489
+ case idx_nodes.length
490
+ when 1
491
+ target, elem, storage = buffer_ref(recv, ctx)
492
+ idx, idx_type = expr(idx_nodes[0])
493
+ unsupported!(ctx, "non-integer buffer index") unless idx_type == :int
494
+ ["#{target}[#{idx}]", elem, storage]
495
+ when 2
496
+ target, elem, cols, storage = buffer_ref_2d(recv, ctx)
497
+ r, r_type = expr(idx_nodes[0])
498
+ c, c_type = expr(idx_nodes[1])
499
+ unsupported!(ctx, "non-integer buffer index") unless r_type == :int && c_type == :int
500
+ ["#{target}[((#{r}) * #{cols}) + (#{c})]", elem, storage]
501
+ else
502
+ unsupported!(ctx, "buffer indexing takes 1 or 2 indices, got #{idx_nodes.length}")
503
+ end
504
+ end
505
+
506
+ def buffer_ref(node, ctx)
507
+ unsupported!(ctx, "indexing a non-variable") unless %i[LVAR DVAR].include?(node.type)
508
+ name = node.children[0]
509
+ param = @env[name]
510
+ unsupported!(ctx, "'#{name}' is not a buffer parameter") unless param.is_a?(Param) && param.kind == :buffer
511
+ [name.to_s, param.type, param.storage]
512
+ end
513
+
514
+ # For buf[r, c]; only arguments called with a 2D-shaped Buffer.
515
+ def buffer_ref_2d(node, ctx)
516
+ name, type, storage = buffer_ref(node, ctx)
517
+ [name, type, buffer_shape(node, ctx, "index it as buf[r, c]")[1], storage]
518
+ end
519
+
520
+ # For buf.rows / buf.cols; only arguments called with a 2D-shaped Buffer.
521
+ def buffer_shape(node, ctx, purpose)
522
+ name = node.children[0]
523
+ param = @env[name]
524
+ unless param&.shape
525
+ raise CompileError,
526
+ "'#{name}' is not a 2D buffer for this call (pass a Buffer with a 2D shape, " \
527
+ "e.g. Buffer.from_matrix, to #{purpose})"
528
+ end
529
+ param.shape
530
+ end
531
+ end
532
+ end
533
+
534
+ # A callable kernel generated from a Ruby DSL block.
535
+ #
536
+ # A specialized compiled kernel is cached for each argument signature.
537
+ class DSLKernel
538
+ attr_reader :name
539
+
540
+ # Creates a callable DSL kernel.
541
+ #
542
+ # @param name [String] kernel name
543
+ # @param block [Proc] supported Tilework DSL body
544
+ # @param out [Integer, nil] output parameter index to allocate automatically
545
+ # @param out_dtype [Symbol, nil] dtype for an automatically allocated output
546
+ # @return [DSLKernel]
547
+ #
548
+ # out: the output buffer's position (0-based index of the block
549
+ # parameter). When given, call/.() allocates the output buffer and
550
+ # returns it (the output is omitted from the call arguments).
551
+ # Otherwise every argument is passed.
552
+ # out_dtype: the type of the auto-allocated output (:float32 / :int32).
553
+ # Inferred from the input Buffers when omitted (int32 if all are
554
+ # int32, float32 otherwise). For kernels whose output type differs
555
+ # from the inputs.
556
+ def initialize(name, block, out: nil, out_dtype: nil)
557
+ raise ArgumentError, "Tilework.kernel requires a block" if block.nil?
558
+
559
+ @name = name
560
+ @block = block
561
+ @out = out
562
+ @out_dtype = out_dtype
563
+ @compiled = {}
564
+ end
565
+
566
+ # Launches the kernel over an inferred or explicit domain.
567
+ #
568
+ # @param args [Array<Buffer, Numeric>] kernel inputs
569
+ # @param over [Integer, Array<Integer>, nil] explicit one- or two-dimensional domain
570
+ # @return [Buffer, nil] an allocated output when `out:` was configured
571
+ #
572
+ # Automatic grid/block launch. The domain is, by default:
573
+ # - over: when given (an Integer for 1D, [cols, rows] for 2D)
574
+ # - otherwise the shape of a 2D-shaped Buffer argument, as a 2D domain
575
+ # - otherwise the length of the longest Buffer argument, as a 1D domain
576
+ # A 2D domain launches with global_id_x = column and global_id_y = row.
577
+ #
578
+ # The generator inserts the bounds guard automatically. A grid launches
579
+ # whole blocks only (Metal's dispatchThreadgroups and CUDA's cuLaunchKernel
580
+ # alike), so extra edge threads always run, but they never execute the body
581
+ # with an index outside the domain. This structurally prevents out-of-range
582
+ # writes from a forgotten guard — harmless padding on Metal, a neighbor
583
+ # buffer corrupted on CUDA.
584
+ def call(*args, over: nil)
585
+ domain = resolve_domain(args, over)
586
+
587
+ if @out
588
+ unless (0..args.length).cover?(@out)
589
+ raise LaunchError, "kernel '#{@name}' out: #{@out} is out of range for #{args.length} call arguments"
590
+ end
591
+
592
+ dtype = @out_dtype || (args.grep(Buffer).all? { |b| b.dtype == :int32 } ? :int32 : :float32)
593
+ out_buf = domain.new_buffer(dtype)
594
+ full_args = args.dup.insert(@out, out_buf)
595
+ kernel_for(full_args, block: domain.block, domain: domain)
596
+ .launch(grid: domain.grid, block: domain.block, args: full_args)
597
+ out_buf
598
+ else
599
+ kernel_for(args, block: domain.block, domain: domain)
600
+ .launch(grid: domain.grid, block: domain.block, args: args)
601
+ end
602
+ end
603
+
604
+ # Launches with explicitly supplied dimensions and waits for completion.
605
+ #
606
+ # @param grid [Integer, Array<Integer>]
607
+ # @param block [Integer, Array<Integer>]
608
+ # @param args [Array<Buffer, Numeric>]
609
+ # @return [nil]
610
+ def launch(grid:, block:, args: [])
611
+ kernel_for(args, block: block).launch(grid: grid, block: block, args: args)
612
+ end
613
+
614
+ # Launches with explicitly supplied dimensions without waiting.
615
+ #
616
+ # @param grid [Integer, Array<Integer>]
617
+ # @param block [Integer, Array<Integer>]
618
+ # @param args [Array<Buffer, Numeric>]
619
+ # @return [nil]
620
+ def launch_async(grid:, block:, args: [])
621
+ kernel_for(args, block: block).launch_async(grid: grid, block: block, args: args)
622
+ end
623
+
624
+ # Returns generated dialect source for inspection.
625
+ #
626
+ # @param args [Array<Buffer, Numeric>] representative argument values
627
+ # @param block [Integer, Array<Integer>, nil] block dimensions for source generation
628
+ # @param over [Integer, Array<Integer>, nil] domain used for generated bounds guards
629
+ # @return [String]
630
+ #
631
+ # With over: the source includes the same bounds guard as a real launch.
632
+ # Otherwise it tries the same rules as .(), and when mixed shapes make that
633
+ # impossible it returns guard-free source (for debugging that only wants the
634
+ # signature).
635
+ def source_for(args, block: nil, over: nil)
636
+ domain = begin
637
+ resolve_domain(args, over)
638
+ rescue LaunchError
639
+ nil
640
+ end
641
+ generate_source(args, block, domain)
642
+ end
643
+
644
+ private
645
+
646
+ # A value object holding the launch domain (1D or 2D) and the grid / block /
647
+ # output allocation derived from it.
648
+ Domain1D = Struct.new(:n) do
649
+ def grid = (n / DSL::BLOCK.to_f).ceil
650
+ def block = DSL::BLOCK
651
+ def new_buffer(dtype) = Buffer.new(dtype, n)
652
+ # [x range, y range] for the automatic bounds guard
653
+ def extents = [n, 1]
654
+ end
655
+
656
+ Domain2D = Struct.new(:cols, :rows) do
657
+ TILE = 16 # block: [16, 16] = 256 threads (matching the 1D DSL::BLOCK)
658
+
659
+ def grid = [(cols / TILE.to_f).ceil, (rows / TILE.to_f).ceil]
660
+ def block = [TILE, TILE]
661
+ def new_buffer(dtype) = Buffer.new(dtype, cols * rows, shape: [rows, cols])
662
+ def extents = [cols, rows]
663
+ end
664
+
665
+ def resolve_domain(args, over)
666
+ case over
667
+ when Array
668
+ unless over.length == 2 && over.all? { |d| d.is_a?(Integer) && d.positive? }
669
+ raise LaunchError, "over: must be a positive Integer or [cols, rows], got #{over.inspect}"
670
+ end
671
+ Domain2D.new(over[0], over[1])
672
+ when Integer
673
+ Domain1D.new(over)
674
+ when nil
675
+ matrices = args.grep(Buffer).select(&:matrix?)
676
+ shapes = matrices.map(&:shape).uniq
677
+ if shapes.length > 1
678
+ raise LaunchError, "kernel '#{@name}' got 2D buffer arguments with different shapes: #{shapes.inspect}; " \
679
+ "pass over: explicitly to disambiguate"
680
+ elsif shapes.length == 1
681
+ Domain2D.new(matrices.first.cols, matrices.first.rows)
682
+ else
683
+ n = args.grep(Buffer).map(&:length).max or
684
+ raise LaunchError, "kernel '#{@name}' needs a Buffer argument or over: to infer launch size"
685
+ Domain1D.new(n)
686
+ end
687
+ else
688
+ raise LaunchError, "over: must be a positive Integer or [cols, rows], got #{over.inspect}"
689
+ end
690
+ end
691
+
692
+ # Dialect backends' generated source does not depend on block, so the
693
+ # signature alone is the key. The domain is baked into the source as the
694
+ # bounds guard's literals, so like the shape (signature) it is part of the
695
+ # cache key. In practice over: almost always follows from argument shapes,
696
+ # so caching is just as effective.
697
+ def kernel_for(args, block:, domain: nil)
698
+ signature = DSL.signature_for(args)
699
+ extents = domain&.extents
700
+ # DSLKernel instances (like NN.head_slice's @head_gather) may be reused
701
+ # across backends, so backend is part of the key to avoid returning a
702
+ # pipeline built for another backend.
703
+ backend = Tilework.backend
704
+ # Backends that cannot use the dialect (:cpu) do not bake grid/block into
705
+ # the source, so pass raw: true.
706
+ raw = !Tilework.capabilities[:dialect]
707
+ @compiled[[backend, signature, extents]] ||=
708
+ Tilework.compile(generate_source(args, block, domain), name: @name, raw: raw)
709
+ end
710
+
711
+ def generate_source(args, block, domain = nil)
712
+ extents = domain&.extents
713
+ return DSL::Transpiler.new(@block, DSL.signature_for(args), @name, domain: extents).transpile if Tilework.capabilities[:dialect]
714
+
715
+ unless Tilework.bridge.respond_to?(:dsl_codegen)
716
+ raise Error, "the #{Tilework.backend.inspect} backend doesn't support dialect kernel strings " \
717
+ "and doesn't implement dsl_codegen either"
718
+ end
719
+ Tilework.bridge.dsl_codegen.transpile(@block, args, name: @name, domain: extents)
720
+ end
721
+ end
722
+ end