ton-org · gabriel-fallen · Dec 2, 2025 · Dec 2, 2025 · Dec 3, 2025 · github-actions
diff --git a/tvm/instructions.mdx b/tvm/instructions.mdx
@@ -3,10 +3,23 @@ title: "Instructions"
 description: "Interactive reference for TVM instructions"
 mode: "wide"
 ---
+
+The notation employed in the table below, as well as general information on the binary encoding of instructions pertaining to opcodes and immediate arguments, is explained in the [Notation](#notation) section following the table.
-The notation employed in the table below, as well as general information on the binary encoding of instructions pertaining to opcodes and immediate arguments, is explained in the [Notation](#notation) section following the table.
+The [notation](#notation) section explains how the instruction table encodes TVM instruction opcodes and immediate arguments in binary.
-The notation employed in the table below, as well as general information on the binary encoding of instructions pertaining to opcodes and immediate arguments, is explained in the [Notation](#notation) section following the table.
+The [notation](#notation) section explains how the instruction table encodes TVM instruction opcodes and immediate arguments in binary.
+
 import { TvmInstructionTable } from "/snippets/tvm-instruction-table.jsx"
 
 <TvmInstructionTable />
 
+## Notation
+
+TVM instructions are encoded by sequences of bits, not all the same length, but a multiple of a byte in total. The immediate arguments essentially form a part of the instruction and have no special demarcation in a bitstream. This leads to some instructions sharing the same opcode _prefix_. For instance, the `NOP` instruction has the (full) opcode of `0x00`, meaning the null byte, eight consequtive zero bits. At the same time the `XCHG_0I` family of instructions starts with `0x0`—four consequtive zero bits—and continue with a four-bit immediate argument ranging from `0x1` to `0xF`.
-TVM instructions are encoded by sequences of bits, not all the same length, but a multiple of a byte in total. The immediate arguments essentially form a part of the instruction and have no special demarcation in a bitstream. This leads to some instructions sharing the same opcode _prefix_. For instance, the `NOP` instruction has the (full) opcode of `0x00`, meaning the null byte, eight consequtive zero bits. At the same time the `XCHG_0I` family of instructions starts with `0x0`—four consequtive zero bits—and continue with a four-bit immediate argument ranging from `0x1` to `0xF`.
+TVM instructions are encoded by sequences of bits, not all the same length, but a multiple of a byte in total. The immediate arguments form a part of the instruction and have no special demarcation in a bitstream. This leads to some instructions sharing the same opcode _prefix_. For instance, the `NOP` instruction has the (full) opcode of `0x00`, meaning the null byte, eight consequtive zero bits. At the same time the `XCHG_0I` family of instructions starts with `0x0`—four consequtive zero bits—and continue with a four-bit immediate argument ranging from `0x1` to `0xF`.
-TVM instructions are encoded by sequences of bits, not all the same length, but a multiple of a byte in total. The immediate arguments essentially form a part of the instruction and have no special demarcation in a bitstream. This leads to some instructions sharing the same opcode _prefix_. For instance, the `NOP` instruction has the (full) opcode of `0x00`, meaning the null byte, eight consequtive zero bits. At the same time the `XCHG_0I` family of instructions starts with `0x0`—four consequtive zero bits—and continue with a four-bit immediate argument ranging from `0x1` to `0xF`.
+TVM instructions are encoded by sequences of bits, not all the same length, but a multiple of a byte in total. The immediate arguments form a part of the instruction and have no special demarcation in a bitstream. This leads to some instructions sharing the same opcode _prefix_. For instance, the `NOP` instruction has the (full) opcode of `0x00`, meaning the null byte, eight consequtive zero bits. At the same time the `XCHG_0I` family of instructions starts with `0x0`—four consequtive zero bits—and continue with a four-bit immediate argument ranging from `0x1` to `0xF`.
+
+Thus, in the table below the `opcode` column lists instructions' prefixes (without arguments) in hexadecimal representing the corresponding sequence of bits (necessarily a multiple of four). While the `opcode` _box_ on an instruction's card shows the full [TL-B](/languages/tl-b/overview) schema for the instruction, including immediate arguments.
+
+The `s[i]` notation refers to the `i`-th stack slot counting from the top, and the top being the 0th slot. Particular stack slots are refernced directly as `s0`, `s1` and so forth in TASM, FIFT and documentation, and are encoded simply by index in the binary.
+
+The `[32(c+1)] PLDUZ` notation means you need to pick a value for `c`, make the calculation and substitute the result. Say, you pick the value `2`, then you write the instruction as `96 PLDUZ` in FIFT. The reason is that `96` is the actual number of bits to read, while in the bitstream only the value for `c` is stored, while the TVM performs the calculation on its own.
-The `[32(c+1)] PLDUZ` notation means you need to pick a value for `c`, make the calculation and substitute the result. Say, you pick the value `2`, then you write the instruction as `96 PLDUZ` in FIFT. The reason is that `96` is the actual number of bits to read, while in the bitstream only the value for `c` is stored, while the TVM performs the calculation on its own.
+The `[32(c+1)] PLDUZ` notation means a value for `c` is chosen, the calculation is performed, and the result is substituted. For example, with `c = 2`, the instruction is written as `96 PLDUZ` in FIFT. The value `96` is the actual number of bits to read, while the bitstream stores only the value for `c`, and the TVM performs the calculation on its own.
-The `[32(c+1)] PLDUZ` notation means you need to pick a value for `c`, make the calculation and substitute the result. Say, you pick the value `2`, then you write the instruction as `96 PLDUZ` in FIFT. The reason is that `96` is the actual number of bits to read, while in the bitstream only the value for `c` is stored, while the TVM performs the calculation on its own.
+The `[32(c+1)] PLDUZ` notation means a value for `c` is chosen, the calculation is performed, and the result is substituted. For example, with `c = 2`, the instruction is written as `96 PLDUZ` in FIFT. The value `96` is the actual number of bits to read, while the bitstream stores only the value for `c`, and the TVM performs the calculation on its own.
+
 {/* STATIC_START tvm_instructions */}
 <div hidden>
 #### `00` NOP