Skip to content

feat: add NIP, TUCK, PICK, ROLL stack operations#14

Merged
tetsuo-cpp merged 2 commits intocanonfrom
feat/stack-ops
Feb 16, 2026
Merged

feat: add NIP, TUCK, PICK, ROLL stack operations#14
tetsuo-cpp merged 2 commits intocanonfrom
feat/stack-ops

Conversation

@tetsuo-cpp
Copy link
Owner

Summary

  • Add NIP, TUCK, PICK, ROLL stack manipulation words to reduce stack gymnastics in complex GPU kernel index expressions
  • PICK and ROLL use dynamic runtime indexing into the stack memref; ROLL lowers to an scf.for shift loop
  • Includes translation tests, conversion tests, and all 35 tests pass

Closes #7

Test plan

  • check-warpforth passes (35/35)
  • Translation test verifies Forth source parses to correct forth.* ops
  • Conversion test verifies MemRef lowering patterns for all 4 ops

Copy link
Owner Author

@tetsuo-cpp tetsuo-cpp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review: feat: add NIP, TUCK, PICK, ROLL stack operations

Overview

Adds four new stack manipulation words across all three layers: ODS table definitions, Forth-to-MLIR translation, and MemRef conversion patterns. PICK and ROLL are dynamic (runtime-indexed), with ROLL using an scf.for shift loop. Clean 282-line addition.


Correctness

All four conversion patterns are correct. Verified each against standard Forth semantics:

  • NIP (a b -- b): Loads top, decrements SP, stores at new SP. ✓
  • TUCK (a b -- b a b): Loads both, rearranges, increments SP. ✓
  • PICK (xn...x0 n -- xn...x0 xn): Pops n, computes SP' - n, loads and pushes. ✓ Edge case 0 PICK = DUP works.
  • ROLL (xn...x0 n -- xn-1...x0 xn): Pops n, saves target, shifts with scf.for, stores saved at top. ✓ Edge cases: 0 ROLL = no-op, 1 ROLL = SWAP, 2 ROLL = ROT — all verified.

Stack pointer convention (SP points to top element) is consistent with existing patterns.


Code Quality & Style

  • Follows existing project patterns exactly (constructor, OneToNOpAdaptor alias, boilerplate structure). Good consistency.
  • Stack effect comments on each struct match Forth standard.
  • ODS definitions are well-structured with proper summary/description fields.
  • Pattern registration list reformatting is a clean diff.

Potential Issues

  1. No bounds checking on PICK/ROLL n values — A negative or out-of-range n would read/write out of bounds on the 256-element memref. Consistent with the project's design (untyped stack, programmer ensures safety), so not a blocker, but GPU kernels using these words need care.

  2. ROLL with n=0 — When n=0, rolledAddr == spAfterPop, so the loop range is empty (zero iterations). The saved value is stored back at the same position. Correct but results in a redundant load/store. Minor, not worth optimizing.

  3. Pure trait on PICK/ROLL — Fine at the Forth dialect level (pure SSA transformations on !forth.stack). Consistent with SwapOp, RotOp, etc.


Test Coverage

  • Translation test (stack-ops.forth): Verifies all four words parse to correct forth.* ops. ✓
  • Conversion test (stack-manipulation.mlir): Tests MemRef lowering with CHECK patterns covering all load/store/loop sequences. Pushes literal 2 before PICK and ROLL to exercise dynamic indexing. ✓
  • Missing: no end-to-end pipeline test in test/Pipeline/. Not a blocker since conversion tests cover the patterns, but would add confidence.

Suggestions

  1. Update CLAUDE.md — The Supported Words section lists DUP DROP SWAP OVER ROT but does not include NIP, TUCK, PICK, ROLL. Should be updated to keep docs in sync.
  2. Consider a pipeline test (optional, low priority).

LGTM with the documentation nit. 👍

@tetsuo-cpp tetsuo-cpp merged commit e08d505 into canon Feb 16, 2026
1 check passed
@tetsuo-cpp tetsuo-cpp deleted the feat/stack-ops branch February 16, 2026 00:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Additional stack operations: NIP TUCK PICK ROLL

1 participant