From ee5aa178bb5957b0f049ebda7686c1e1796f94be Mon Sep 17 00:00:00 2001 From: cwhitak3r Date: Fri, 27 Mar 2026 17:13:56 +0800 Subject: [PATCH] docs(assembly): clarify div vs u32div semantics --- CHANGELOG.md | 2 ++ docs/src/user_docs/assembly/field_operations.md | 6 ++++-- docs/src/user_docs/assembly/u32_operations.md | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a41a8307dd..f152fd04dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,8 @@ #### Bug Fixes - Reverted `InvokeKind::ProcRef` back to `InvokeKind::Exec` in `visit_mut_procref` and added an explanatory comment (#2893). +- Fixed `FastProcessor` so `after_exit` trace decorators execute when tracing is enabled without debug mode, and added a tracing-only regression test. +- Strengthened assembly docs to clarify that `div` is field division and to cross-reference `u32div` for integer floor division (#2911). #### Changes - [BREAKING] Sync execution and proving APIs now require `SyncHost`; async `Host`, `execute`, and `prove` remain available ([#2865](https://github.com/0xMiden/miden-vm/pull/2865)). diff --git a/docs/src/user_docs/assembly/field_operations.md b/docs/src/user_docs/assembly/field_operations.md index 53acaf5624..60d9cca907 100644 --- a/docs/src/user_docs/assembly/field_operations.md +++ b/docs/src/user_docs/assembly/field_operations.md @@ -28,14 +28,16 @@ The message is hashed and turned into a field element. If the error code is omit ### Arithmetic and Boolean operations -The arithmetic operations below are performed in a 64-bit [prime field](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$. Also, the result of divisions may appear counter-intuitive because divisions are defined via inversions. +The arithmetic operations below are performed in a 64-bit [prime field](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$. + +**Important:** `div` is field division, i.e. $a \cdot b^{-1} \mod p$, not integer floor division. For integer division, use [`u32div`](./u32_operations.md#arithmetic-operations) (or [`u32divmod`](./u32_operations.md#arithmetic-operations)). | Instruction | Stack_input | Stack_output | Notes | | ------------------------------------------------------------------------------ | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------ | | add
- *(1 cycle)*
add.*b*
- *(1-2 cycle)* | [b, a, ...] | [c, ...] | $c \leftarrow (a + b) \mod p$ | | sub
- *(2 cycles)*
sub.*b*
- *(2 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow (a - b) \mod p$ | | mul
- *(1 cycle)*
mul.*b*
- *(2 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow (a \cdot b) \mod p$ | -| div
- *(2 cycles)*
div.*b*
- *(2 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow (a \cdot b^{-1}) \mod p$
Fails if $b = 0$ | +| div
- *(2 cycles)*
div.*b*
- *(2 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow (a \cdot b^{-1}) \mod p$
Fails if $b = 0$
For integer floor division, use [`u32div`](./u32_operations.md#arithmetic-operations). | | neg
- *(1 cycle)* | [a, ...] | [b, ...] | $b \leftarrow -a \mod p$ | | inv
- *(1 cycle)* | [a, ...] | [b, ...] | $b \leftarrow a^{-1} \mod p$
Fails if $a = 0$ | | pow2
- *(16 cycles)* | [a, ...] | [b, ...] | $b \leftarrow 2^a$
Fails if $a > 63$ | diff --git a/docs/src/user_docs/assembly/u32_operations.md b/docs/src/user_docs/assembly/u32_operations.md index 54ee8c6367..ef17a71b63 100644 --- a/docs/src/user_docs/assembly/u32_operations.md +++ b/docs/src/user_docs/assembly/u32_operations.md @@ -95,7 +95,7 @@ The message is hashed and turned into a field element. If the error code is omit | u32wrapping_mul
- *(2 cycles)*
u32wrapping_mul.*b*
- *(3-4 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow (a \cdot b) \mod 2^{32}$
Undefined if $max(a, b) \ge 2^{32}$ | | u32widening_madd
- *(1 cycle)* | [b, a, c, ...] | [d, e, ...] | $d \leftarrow (a \cdot b + c) \mod 2^{32}$
$e \leftarrow \lfloor(a \cdot b + c) / 2^{32}\rfloor$
Undefined if $max(a, b, c) \ge 2^{32}$ | | u32wrapping_madd
- *(3 cycles)* | [b, a, c, ...] | [d, ...] | $d \leftarrow (a \cdot b + c) \mod 2^{32}$
Undefined if $max(a, b, c) \ge 2^{32}$ | -| u32div
- *(2 cycles)*
u32div.*b*
- *(3-4 cycles)* | [b, a, ...] | [d, c, ...] | $c \leftarrow \lfloor a / b\rfloor$
$d \leftarrow a \mod b$
Fails if $b = 0$
Undefined if $max(a, b) \ge 2^{32}$ | +| u32div
- *(2 cycles)*
u32div.*b*
- *(3-4 cycles)* | [b, a, ...] | [d, c, ...] | $c \leftarrow \lfloor a / b\rfloor$
$d \leftarrow a \mod b$
Fails if $b = 0$
Undefined if $max(a, b) \ge 2^{32}$
For field division in $\mathbb{F}_p$, use [`div`](./field_operations.md#arithmetic-and-boolean-operations). | | u32mod
- *(3 cycles)*
u32mod.*b*
- *(4-5 cycles)* | [b, a, ...] | [c, ...] | $c \leftarrow a \mod b$
Fails if $b = 0$
Undefined if $max(a, b) \ge 2^{32}$ | | u32divmod
- *(1 cycle)*
u32divmod.*b*
- *(2-3 cycles)* | [b, a, ...] | [d, c, ...] | $c \leftarrow \lfloor a / b\rfloor$
$d \leftarrow a \mod b$
Fails if $b = 0$
Undefined if $max(a, b) \ge 2^{32}$ |