Skip to content

Port from stdpp bitvectors to stdlib bits - #2

Merged
andres-erbsen merged 3 commits into
mit-plv:mainfrom
JasonGross:fable/stdlib-bits
Oct 24, 2026
Merged

andres-erbsen merged 3 commits into
mit-plv:mainfrom
JasonGross:fable/stdlib-bits

Conversation

@JasonGross

@JasonGross JasonGross commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Uses rocq-stdlib's bits n (Zmod (2^n), rocq-stdlib >= 9.1) as the carrier of type.Bits instead of std++'s bv n, so quartz shares one bit-vector type with the other mit-plv projects; std++ is no longer a dependency at all (vec is Vector.t). Widths are Z again, as before the std++ port.

App is stdlib's Zmod.app with the first operand in the low bits and result width n + m, which is what the C++ and SystemVerilog printers already emitted (main's Rocq semantics put the first operand high, so generated code disagreed with the spec); type.pack follows the same layout, and Processor.v's Concat keeps its hi/lo meaning as UnsignedResize (App lo hi). Slice s l is Zmod.firstn l (Zmod.skipn s v). The BV module is now Module Zmod, adding only new names (embed_bool, nonzero, bool_cases, ...) to the stdlib namespace and shadowing nothing; constants are bits.of_Z; the printers print Z widths; a lemma that restated a stdlib one is gone; ten bit-semantics tests from the andreser/monomorphize-Zmod branch are added, plus five tests that pin down every observable difference between the two ports on both backends (the comparison and the test table are in comments below).

dune build (lang, examples, all tests) passes in 14 s, as on main, with the same warning kinds and no admits; the harness run agrees with the interpreter on all 40 SystemVerilog and 42 C++ tests. Requested by @andres-erbsen on mit-plv/kami#51; the matching granite port follows and will pin this branch.

Written by Claude Fable 5.1.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm

@andres-erbsen

Copy link
Copy Markdown
Collaborator

Please also take a look at https://github.com/mit-plv/quartz/tree/andreser/monomorphize-Zmod (an older branch that already uses Zmod) and consider any differences between this PR and that branch -- keep the best option in each case, report back here.

@JasonGross

Copy link
Copy Markdown
Contributor Author

Compared this PR with the andreser/monomorphize-Zmod branch point by point and took the better option in each case. The branch also carries the monomorphization plugin, pp.v, the quartz_type scope and the cpu tests; those are a separate feature and are not part of this PR.

Topic andreser/monomorphize-Zmod This PR before Kept Why
Carrier and index bits n, Bits (sz : Z) same same stdlib's bits is indexed by Z, and type.wf already carries 0 <= sz.
std++ dependency none std++ base/vector for vec and fun_to_vec none vec is only an alias of Vector.t; std++ vector also turns [# into a token, which breaks the #st[#idx] notation in Processor.v. default_array is a Fixpoint again.
App App {n m} : Bits (n + m), interpreted as Zmod.app, first operand low App (sz : Z), interpreted as Zmod.firstn sz (Zmod.app lo hi), first operand high (as in main) branch The C++ and SystemVerilog printers on main both put the first operand in the low bits, so main's Rocq semantics disagreed with the generated code. Zmod.app is the direct stdlib operation; a width change is a separate Resize.
Concat (Processor.v) shifts, Or and casts on top of App one App sz hi lo UnsignedResize (App lo hi) Same hi/lo meaning for all users, one real operation plus one cast that unresizesame removes when the width is hi_w + lo_w.
type.pack layout Zmod.app (pack snd) (pack fst) etc., first component high first component low, firstn casts branch Matches the App semantics above and the printed code; no width casts needed.
Slice not present (extract via shift + resize) Zmod.firstn l (Zmod.skipn s v) this PR Slice exists on main; its interpretation is stdlib's slice with the width given explicitly.
IsZero, EqBits Zmod.eqb Zmod.zero, Zmod.eqb with the embed_bool coercion inserted implicitly BV.embed_bool (Zmod.eqb v Zmod.zero), BV.embed_bool (Zmod.eqb a b) this PR Same terms; writing the coercion makes the interpreter readable without Set Printing Coercions.
Bool module Module Zmod in domain.v, shadowing stdlib's Zmod; Cases2 (Zmod.mk 2 0 I) Module BV (main's name), Cases2 Zmod.zero/Zmod.one this PR No shadowing of the stdlib module (downstream code had to write ZmodDef.Zmod.and), no use of the private constructor.
Constants Zmod.of_Z _ 773 bits.of_Z _ 773 this PR Same term, the width is visible.
Resize bits.of_Z _ (Zmod.signed v) / bits.of_Z _ (Zmod.unsigned v) same same
interp_unresizesame rewrite ?Zmod.of_Z_unsigned, ?Zmod.of_Z_signed signed_inj + signed_of_Z + smod_signed branch Shorter, uses the two stdlib lemmas made for this.
interp_unapp0l/r via Zmod.hprop_Zmod_1 via bits.unsigned_width0 branch Follows from taking the branch's App.
unsigned_resize_id kept deleted deleted It restates Zmod.of_Z_unsigned.
Printers pp_Z widths; App printed at width n + m pp_Z widths; App printed with the explicit width branch Follows from App.
Tests 10 bit-semantics tests (test_app_shift, test_mul_7bit, test_signed_cmp_corner, test_srs_lt, test_shift_zero, test_add_overflow_diff, test_mul_diff, test_mul_shift, test_either_pack, test_bitwidth_reproducer) main's tests ported both The extra tests exercise exactly the operations the port touches; they are added with main's shift and Mul signatures.
Number notation for bits none none none Not needed in quartz; granite adds one for Zmod in its own Bits.v.
Tactics, lemma libraries none none none
dune/opam depends on rocq-stdlib >= 9.1.0 only rocq-stdlib, rocq-stdpp branch See the std++ row.

Result: dune build (lang + examples) and all test files build with Rocq 9.2 and stdlib 9.1.0; build time and warnings are unchanged from main.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

@andres-erbsen

andres-erbsen commented Sep 14, 2026 •

Copy link
Copy Markdown
Collaborator

Do all differences between the two Zmod ports have tests for both C++ and SystemVerilog backends? If not, add appropriate tests that distinguish between these behaviors in this PR. EDIT: I mean the observable differences, no need to test internal implementation differences.

Comment thread test/test_struct_unit.v Outdated
Comment on lines 1 to 2
From Stdlib Require Import Bits.
(*! sv:reject *)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

The test-harness-configuration comment should always be on the first line if there is one.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in every test file (this one and test_either_unit_unit.v); the harness directive is line 1 again, and the new tests have none.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

@andres-erbsen

Copy link
Copy Markdown
Collaborator

It would be nice to rename "BV" to "Zmod". Would it be straightforward to refactor so that no stdlib names are shadowed, just new definitions are added to the Zmod namespace?

JasonGross and others added 2 commits September 15, 2026 00:57
Use rocq-stdlib's `bits n` (`Zmod (2^n)`, stdlib >= 9.1) as the carrier
of `type.Bits` instead of std++'s `bv n`, so that quartz shares one
bit-vector type with the other mit-plv projects. This removes the
rocq-stdpp-bitvector dependency and, since `vec` was the only remaining
use, std++ altogether.

Widths are `Z` again, as they were before the std++ port: stdlib's
`bits` is indexed by `Z`, and `type.wf` already carries the `0 <= sz`
side condition that the stdlib range lemmas need. The operations map
directly: `Zmod.add/sub/opp/and/or/xor/not`, shifts `Zmod.slu/sru/srs`
by the unsigned value of the amount, `Zmod.eqb` for `IsZero`/`EqBits`,
`bits.of_Z` of the signed/unsigned value for `Resize`, and
`Zmod.firstn l (Zmod.skipn s v)` for `Slice s l`.

`App` is `Zmod.app` again, with result type `Bits (n + m)` and the
first operand in the low bits. The std++ port had made `App` take an
explicit result width and put the first operand in the high bits, which
contradicted the C++ and SystemVerilog printers (both emit the first
operand low); the printers were right, so the Rocq semantics returns to
them and `Concat` in Processor.v resizes `App lo hi`. `type.pack` is
built from bare `Zmod.app` in the same order.

The boolean helpers (`embed_bool`, `nonzero`, `bool_cases`, ...) live in
a module named `Zmod` in domain.v, so they read as `Zmod.embed_bool`
next to the stdlib operations. That module only adds names: it defines
nothing that stdlib's `Zmod` modules define, so `Zmod.add`, `Zmod.eqb`,
`Zmod.of_Z`, ... still resolve to the stdlib constants without any
`ZmodDef.` prefix. The case analyses come from `Zmod.in_elements`.
`unsigned_resize_id`, which restated `Zmod.of_Z_unsigned`, is gone. The
tests use `bits.of_Z` and `Zmod.zero` for constants, keep the harness
directive comment on their first line, and gain the bit-semantics tests
from the andreser/monomorphize-Zmod branch.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
Every test is checked on all three evaluators (the Rocq interpreter,
slang on the SystemVerilog output, and the compiled C++ output), so a
test whose expected value differs between two candidate semantics pins
down which one the language has. Add tests for the operations where the
stdlib port and the andreser/monomorphize-Zmod branch differ, with
operands chosen so that the other reading would produce another value:

- test_app_asym: `App` of a 2-bit 1 and a 3-bit 5 is 5'h15, so the
  first operand is in the low bits and the width is n + m (the other
  operand order gives 5'hd).
- test_app_resize: the same `App` under an `UnsignedResize` to 8 bits
  is 8'h15, the shape `Concat` in Processor.v uses.
- test_slice_mid: `Slice 3 4` of 8'hb5 is 4'h6, so the slice starts at
  bit s and takes l bits (swapping firstn and skipn gives 0).
- test_slice_overrun: `Slice 5 8` of 8'hb5 is 8'h5, so a slice that
  reaches past the operand zero-extends.
- test_xor: 4'hc xor 4'ha is 4'h6 (and gives 4'h8, or gives 4'he); the
  branch has no `Xor`.

test_all_ops shifted by the full 32-bit operand 0xbad1dea5. The
interpreter computes `Zmod.slu` through `Z.shiftl`, so producing its
expected output meant building a three-billion-bit integer, and the
test's `.out` rule ran out of memory (on main as well). Shift by the
16-bit resized value 0xbeef instead, as the branch's version of this
test does: the amount is still larger than the width, so the test keeps
checking that oversized shifts saturate to zero and to the sign bit on
both backends.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
@JasonGross

Copy link
Copy Markdown
Contributor Author

Tests (commit 47dfe79): every observable difference between the two Zmod ports now has a test that both backends check against the interpreter, with values chosen so that the other behaviour fails. Full run: 40 SystemVerilog and 42 C++ tests agree with the interpreter (clang 19, UBSan; ASan could not run under this machine's virtual-memory limit), and the 3 sv:reject / 1 cpp:reject tests are rejected.

difference test value checked C++ SV
App: first operand in the low bits, result width n+m (PR = branch; std++ main and the earlier draft: explicit width, first operand high) test_app_asym (new) App (2-bit 1) (3-bit 5) = 5'h15 (first-operand-high gives 5'hd) pass pass
App under UnsignedResize (the Concat shape; the branch's Concat used shift + or) test_app_resize (new) 8'h15 (other order: 8'hd) pass pass
existing App tests (symmetric operands, do not fix the order) test_app_shift, test_signed_app_compare, test_shift_context 4'h7, 1'h1, 32'h0 pass pass
type.pack layout: first component high; Either: payload low, tag in the top bit (PR = branch; earlier draft: first component low with width casts) test_pack_pixel, test_make_tuple, test_either_pack, test_all_consts, test_array_of_arrays, test_unit_cast, test_wrap_value2 25'h1ab002a, 65'h55ffffffaa, 2'h1 (tag-low layout gives 2'h2), 33'h54243465, 192'h2b0000002a0000002a0000002a0000002a0000002a, 2'h3, 33'h1000000ff pass pass
Slice s l = Zmod.firstn l (Zmod.skipn s v) (branch has no Slice; extracts with shift + resize) test_slice_mid (new) Slice 3 4 of 8'hb5 = 4'h6 (firstn/skipn swapped gives 4'h0) pass pass
Slice reaching past the operand zero-extends test_slice_overrun (new) Slice 5 8 of 8'hb5 = 8'h5 pass pass
Xor exists (main and PR; the branch dropped it) test_xor (new) 4'hc ^ 4'ha = 4'h6 (and: 4'h8, or: 4'he) pass pass
shifts by an amount >= width saturate (0 / 0 / sign fill) test_all_ops (now evaluable), test_mul_shift, test_shift_context r_slu = 0, r_sru = 0, r_srs = 0xffffffff inside the 546-bit packed record (546'h8549...0b77); 4'h0; 32'h0 pass pass
shift amount width: PR keeps main's Slu {n} : Bits n -> Bits n -> Bits n, branch has Slu {n m} none typing difference only: a program with a different-width amount does not typecheck in the PR, so there is no value to check n/a n/a
Resize, constants (bits.of_Z and Zmod.of_Z are the same constant), IsZero/EqBits (same term, coercion written out), Mul identical in both ports; covered by test_add_context, test_not_context, test_srs_context, test_add_overflow_diff, test_mul_7bit, test_mul_diff, test_signed_cmp_corner, test_srs_lt, test_all_ops 16'h0, 16'hff, 16'hff, 8'h0, 7'h10, 8'he1, 1'h0, 1'h1, 546'h... pass pass
C++ printer: the branch wraps every arithmetic op in (unsigned _BitInt(n))(...); PR = main prints bare ops textual only; every C++ test above (42) agrees with the interpreter on clang 19, including 1-bit Not/IsZero (test_make_tuple), 4-bit overflow (test_add_overflow_diff) and 7-bit Mul (test_mul_7bit) pass
Processor.v Concat implementation, BV/Zmod module, dune/opam deps not observable through the interpreter or a printed test program (Processor.v is not under test/; the test theory depends on quartz.lang only)

Harness limits: none of the constructs above is unsupported on a backend; the only tests not checked on a backend are the pre-existing reject tests. Processor.v's Concat is not under test/ (the test theory depends on quartz.lang only), so test_app_resize replicates its expression shape instead. test_all_ops now shifts by the 16-bit resized value: shifting by the 32-bit operand made the interpreter's Compute run out of memory, on main as well, so that test had never been evaluable; the amount is still at least the width, so it still checks saturation.

Rename: done. Module Zmod in lang/domain.v contains only new names (embed_bool, nonzero, nonzero_bool, Cases2, cases2, BoolCases, bool_cases); none exists in the stdlib's Zmod modules. Checked in a scratch file importing quartz that all 49 Zmod.<name> spellings granite uses still locate to the stdlib constants and that nothing needs ZmodDef.Zmod.x. One caveat: a bare Import Zmod. after loading quartz picks the quartz module (no file does that; Import ZmodBase.Zmod selects the stdlib one).


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

@andres-erbsen

Copy link
Copy Markdown
Collaborator

create a new PR stacked on top of this one to bring remaining changes from https://github.com/mit-plv/quartz/tree/andreser/monomorphize-stdpp up to date with latest work on this PR and granite

@JasonGross

Copy link
Copy Markdown
Contributor Author

On it: rebasing andreser/monomorphize-stdpp (4 commits over main) onto this PR's tip, then checking granite against it; the stacked PR will follow.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

@JasonGross

Copy link
Copy Markdown
Contributor Author

Stacked PR: #3 (monomorphize-stdpp rebased onto this tip, one extra commit sanitizing binder names for the printers; 66 tests pass). granite is being built against it now; any granite fallout goes into a PR stacked on mit-plv/granite#1.


Written by Claude Fable 5.1 via Claude Code (session https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
JasonGross added a commit to JasonGross/granite that referenced this pull request Sep 16, 2026
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YJbiRBkJtM7x6PvYV6hmEm
andres-erbsen added a commit that referenced this pull request Oct 24, 2026
Monomorphized CPU and shared pretty-printing on stdlib bits (stacked on #2)
@andres-erbsen
andres-erbsen merged commit 8db5ff9 into mit-plv:main Oct 24, 2026
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.

2 participants