Narrow integer instructions (#628)

Dentosal · web-flow · commit cad8e6978917 · 2025-03-11T15:39:47.000+02:00
Closes #626. VM PRs: FuelLabs/fuel-vm#922 and FuelLabs/fuel-vm#923. Implementing correct overflow handling for narrow integer types (`u8`, `u16`, `u32`) is tedious, error prone, and needs lots of instructions. Likewise, memory load/store operations with these involve lots of expensive bitmasking. This change provides the functionality on the vm level. Only operations for which the overflow handling is different with narrow integers are implemented. For instance, multiplication is definitely different as `256 * 2` overflows `u8` but doesn't overflow `u64`. In comparison, division is not, it never creates results larger than the original value. The operations silently truncate the input operands to the correct bit width, meaning that `niop $ra $rb $rc NIOP_U8 | NIOP_ADD` with `$rb = 0xff01`, `$rc = 0x02` sets `$ra = 3` without panicking. Same goes for store operations, and that was already the case with `SB`. It's up to the compiler or user to take this into account. As always I'm trying to sneak in cool new features. Here it's the `XNOR` operating mode, which is extremely useful for generating bitmasks. For instance `niop $ra $zero $zero NIOP_U32 | NIOP_XNOR` sets `$ra` to `0xffffffff`. ### Before requesting review - [x] I have reviewed the code myself ### After merging, notify other teams - [ ] [Sway compiler](https://github.com/FuelLabs/sway/) - [ ] [Platform documentation](https://github.com/FuelLabs/devrel-requests/issues/new?assignees=&labels=new+request&projects=&template=NEW-REQUEST.yml&title=%5BRequest%5D%3A+) (for out-of-organization contributors, the person merging the PR will do this)
diff --git a/spell-check-custom-words.txt b/spell-check-custom-words.txt
@@ -275,4 +275,6 @@ incentivize
 EIPS
 eip
 eips
-ethereum
+ethereum
+xnor
+XNOR
diff --git a/src/fuel-vm/instruction-set.md b/src/fuel-vm/instruction-set.md
@@ -22,6 +22,7 @@
   - [`MUL`: Multiply](#mul-multiply)
   - [`MULI`: Multiply immediate](#muli-multiply-immediate)
   - [`MLDV`: Fused multiply-divide](#mldv-fused-multiply-divide)
+  - [`NIOP`: Narrow integer operation](#niop-narrow-integer-operation)
   - [`NOOP`: No operation](#noop-no-operation)
   - [`NOT`: Invert](#not-invert)
   - [`OR`: OR](#or-or)
@@ -32,7 +33,6 @@
   - [`SRLI`: Shift right logical immediate](#srli-shift-right-logical-immediate)
   - [`SUB`: Subtract](#sub-subtract)
   - [`SUBI`: Subtract immediate](#subi-subtract-immediate)
-  - [`SUBI`: Subtract immediate](#subi-subtract-immediate)
   - [`WDCM`: 128-bit integer comparison](#wdcm-128-bit-integer-comparison)
   - [`WQCM`: 256-bit integer comparison](#wqcm-256-bit-integer-comparison)
   - [`WDOP`: Misc 128-bit integer operations](#wdop-misc-128-bit-integer-operations)
@@ -69,6 +69,8 @@
   - [`CFS`: Shrink call frame](#cfs-shrink-call-frame)
   - [`CFSI`: Shrink call frame immediate](#cfsi-shrink-call-frame-immediate)
   - [`LB`: Load byte](#lb-load-byte)
+  - [`LQW`: Load quarter word](#lqw-load-quarter-word)
+  - [`LHW`: Load half word](#lhw-load-half-word)
   - [`LW`: Load word](#lw-load-word)
   - [`MCL`: Memory clear](#mcl-memory-clear)
   - [`MCLI`: Memory clear immediate](#mcli-memory-clear-immediate)
@@ -80,6 +82,8 @@
   - [`PSHH`: Push a set of high registers to stack](#pshh-push-a-set-of-high-registers-to-stack)
   - [`PSHL`: Push a set of low registers to stack](#pshl-push-a-set-of-low-registers-to-stack)
   - [`SB`: Store byte](#sb-store-byte)
+  - [`SQW`: Store quarter word](#sqw-store-quarter-word)
+  - [`SHW`: Store half word](#shw-store-half-word)
   - [`SW`: Store word](#sw-store-word)
 - [Contract Instructions](#contract-instructions)
   - [`BAL`: Balance of contract ID](#bal-balance-of-contract-id)
@@ -537,6 +541,55 @@ If the result of after the division doesn't fit into a register, `$of` is assign
 
 `$err` is cleared.
 
+### `NIOP`: Narrow integer operation
+
+|             |                                                                                     |
+|-------------|-------------------------------------------------------------------------------------|
+| Description | Perform an ALU operation with overflow handing for 8, 16 or 32 bit integers         |
+| Operation   | `$rA = op($rB,$rC);`                                                                |
+| Syntax      | `niop $rA, $rB, $rC, imm`                                                           |
+| Encoding    | `0x00 rA rB rC i`                                                                   |
+| Notes       | Operations that would be identical with their 64-bit counterparts are not available |
+
+The six-bit immediate value is used to select operating mode, as follows:
+
+Bits     | Short name | Description
+---------|------------|-------------------------------------
+`..XXXX` | `op`       | Operation selection, see below
+`XX....` | `width`    | Operation width, see below
+
+Then the actual operation that's performed:
+
+`op` | Name | Description
+-----|-------|---------------------------
+0    | `add` | Add (`a = b + c`)
+1    | `mul` | Multiply (`a = b * c`)
+2    | `exp` | Exponentiate (`a = b ** c`)
+3    | `sll` | Bit shift left (logical) (`a = b << c`)
+4    | `xnor`| Bitwise xnor (`a = b ^ (!c)`).
+other| -     | Reserved and must not be used
+
+And operation width:
+
+`width`| Bits
+-------|------
+0      | 8
+1      | 16
+2      | 32
+3      | Reserved and must not be used
+
+All operations first truncate their operands to the given bit width,
+then perform the operation with overflow checking on that size. The
+result always fits within the bit width of the operation.
+
+Operations set `$of` and `$err` similarly to their 64-bit counterparts.
+`XNOR` has no counterpart, and it always clears both `$of` and `$err`.
+
+Panic if:
+
+- Reserved bits of the immediate are set
+- `$rA` is a [reserved register](./index.md#semantics)
+
 ### `NOOP`: No operation
 
 |             |                        |
@@ -1383,6 +1436,36 @@ Panic if:
 - `$rA` is a [reserved register](./index.md#semantics)
 - `$rB + imm + 1` overflows or `> VM_MAX_RAM`
 
+### `LQW`: Load quarter word
+
+|             |                                                                      |
+|-------------|----------------------------------------------------------------------|
+| Description | A quarter word is loaded from the specified address offset by `imm`. |
+| Operation   | ```$rA = MEM[$rB + (imm * 2), 2];```                                 |
+| Syntax      | `lqw $rA, $rB, imm`                                                  |
+| Encoding    | `0x00 rA rB i i`                                                     |
+| Notes       |                                                                      |
+
+Panic if:
+
+- `$rA` is a [reserved register](./index.md#semantics)
+- `$rB + (imm * 2) + 2` overflows or `> VM_MAX_RAM`
+
+### `LHW`: Load half word
+
+|             |                                                                      |
+|-------------|----------------------------------------------------------------------|
+| Description | A half word is loaded from the specified address offset by `imm`.    |
+| Operation   | ```$rA = MEM[$rB + (imm * 4), 4];```                                 |
+| Syntax      | `lhw $rA, $rB, imm`                                                  |
+| Encoding    | `0x00 rA rB i i`                                                     |
+| Notes       |                                                                      |
+
+Panic if:
+
+- `$rA` is a [reserved register](./index.md#semantics)
+- `$rB + (imm * 4) + 4` overflows or `> VM_MAX_RAM`
+
 ### `LW`: Load word
 
 |             |                                                              |
@@ -1565,6 +1648,31 @@ Panic if:
 - `$rA + imm + 1` overflows or `> VM_MAX_RAM`
 - The memory range `MEM[$rA + imm, 1]`  does not pass [ownership check](./index.md#ownership)
 
+### `SQW`: Store quarter word
+
+|             |                                                                                               |
+|-------------|-----------------------------------------------------------------------------------------------|
+| Description | The two least significant bytes of  of `$rB` is stored at the address `$rA` offset by `imm`.  |
+| Operation   | ```MEM[$rA + (imm * 2), 2] = $rB;```                                                          |
+| Syntax      | `sqw $rA, $rB, imm`                                                                           |
+| Encoding    | `0x00 rA rB i i`                                                                              |
+| Notes       |                                                                                               |
+
+### `SHW`: Store half word
+
+|             |                                                                                               |
+|-------------|-----------------------------------------------------------------------------------------------|
+| Description | The four least significant bytes of  of `$rB` is stored at the address `$rA` offset by `imm`. |
+| Operation   | ```MEM[$rA + (imm * 4), 4] = $rB;```                                                          |
+| Syntax      | `shw $rA, $rB, imm`                                                                           |
+| Encoding    | `0x00 rA rB i i`                                                                              |
+| Notes       |                                                                                               |
+
+Panic if:
+
+- `$rA + (imm * 4) + 4` overflows or `> VM_MAX_RAM`
+- The memory range `MEM[$rA + (imm * 4), 4]`  does not pass [ownership check](./index.md#ownership)
+
 ### `SW`: Store word
 
 |             |                                                                    |
