Skip to content

fix: Explain the basics of instruction encoding and notation #1515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gabriel-fallen wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

fix: Explain the basics of instruction encoding and notation #1515

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8294284
Explain the basics of instruction encoding and notation
gabriel-fallen Dec 2, 2025
cfa99a5
Merge branch 'main' into instr-notation-explainer
novusnota Dec 2, 2025
5f984c5
fix: short forward reference and the explanation below the table
gabriel-fallen Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions tvm/instructions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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`.

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.

{/* STATIC_START tvm_instructions */}
<div hidden>
#### `00` NOP
Expand Down