Branch: slice/S.8c. Commit only there; never to trunk.

Needs: S.8a (the tree arena) and S.8b (the microbit machine) merged.

Read first:

• docs/phases/S-small-targets.md, slice S.8.
• docs/tasks/S.8a.md and src/glint/shell/tree.cr: the nodes.
• docs/tasks/S.8b.md and spec/qemu/microbit_spec.cr: how a raw image is run and how semihosting ends it.
• src/glint/shell/matcher.cr: the no-heap style that image code keeps.

Claim. emit turns a tree of S.8a's nodes into Cortex-M0+ (ARMv6-M, Thumb) code that computes the same Int32 Crystal computes, raising on overflow as Crystal does, and the code runs on QEMU's Cortex-M0.

Passage. The maintainer: "an emit method that walks the ast to generate m0+ code that can be saved, loaded and run for fast performance."

Make:

• src/glint/shell/thumb.cr, an encoder for the ARMv6-M instructions emit and the harness use, each writing 16-bit halfwords (32 for BL) little-endian into a caller's buffer. Only ARMv6-M encodings: no Thumb-2 instructions such as MOVW, CBZ, IT or wide LDR.
• src/glint/shell/emit.cr, Emit.function(arena, root, out : UInt8*, capacity : Int32, base : UInt32, overflow : UInt32) : Int32. It writes one function (BL-callable, result in r0, up to 8 local slots in its stack frame) and returns its size in bytes, or a negative status: FULL (buffer too small), RANGE (a branch can't reach), BAD_TREE. No heap, no exceptions, no constants of StaticArray.
• What Crystal means, kept:
  • ADD and SUB check signed overflow (V flag) and branch to the overflow address, as Crystal's + and - raise OverflowError.
  • LT gives a Bool in Crystal, so it may only be the condition of IF or WHILE; anywhere else is BAD_TREE.
  • WHILE gives nil, so it may only be the first child of SEQ.
  • IF needs an else in this first set (otherwise its value can be nil); c = NONE is BAD_TREE.
  • LOCAL of a slot never assigned earlier in evaluation order is BAD_TREE (Crystal would reject it as undefined).
  • Every Int32 literal, including negative values and Int32::MIN, with no literal pool unless you report why one is simpler.
• Conditional branches reach ±2 KiB: an inverted short branch over an unconditional B. Beyond that, RANGE.
• spec/support/thumb_image.cr builds a raw flash image with the same encoder: vector table (SP 0x20004000; reset; HardFault to a stub that writes hardfault and exits 2), a harness that calls the function with BL, writes r0 as 8 lowercase hex digits and a newline with SYS_WRITE0, and exits 0; and the overflow stub, which writes overflow and exits 1.

• spec/shell/emit_spec.cr:

  • Encoder cases: MOVS r0, #42 is 2a 20; ADDS r0, r1, r0 is 08 18; SUBS r0, r1, r0 is 08 1a; CMP r1, r0 is 81 42; BKPT 0xab is ab be; PUSH {lr} is 00 b5; POP {pc} is 00 bd. These are written from the ARMv6-M manual by the reviewer, not yet checked by a disassembler, because x86-1's LLVM has no ARM target; if QEMU disagrees, say so.
  • Each program below is built in an Arena, emitted, run under -M microbit, and its output and exit status checked. The spec keeps each program's Crystal text beside it:

  Crystal	Output	Exit
  42	0000002a	0
  -7	fffffff9	0
  2147483647	7fffffff	0
  -2147483648	80000000	0
  x = 5; y = x + 3; y - 10	fffffffe	0
  x = 0; while x < 10; x = x + 3; end; x	0000000c	0
  if 3 < 2; 1; else; 2; end	00000002	0
  x = 0; i = 0; while i < 1000; x = x + i; i = i + 1; end; x	00079f2c	0
  x = 2147483647; x + 1	overflow	1
  x = -2147483648; x - 1	overflow	1

  • Each BAD_TREE rule above, FULL for a one-byte buffer, and RANGE for a WHILE whose body emits more than 2 KiB (use a larger arena).

• Size: report emit.cr and thumb.cr lines, and the bytes emitted for the 1000-iteration program.

Constraints. emit.cr and thumb.cr compile into image code later, so they follow S.8a's constraints. The harness and specs may use the standard library. Nothing in the image requires them yet. crystal tool format --check passes.