From 8294284c0f7c5b58a0cfbc532cdb549982b5870c Mon Sep 17 00:00:00 2001 From: Alexander Chichigin Date: Tue, 2 Dec 2025 15:45:33 +0300 Subject: [PATCH 1/2] Explain the basics of instruction encoding and notation --- tvm/instructions.mdx | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tvm/instructions.mdx b/tvm/instructions.mdx index 7a44aafa3..6d06b6f25 100644 --- a/tvm/instructions.mdx +++ b/tvm/instructions.mdx @@ -3,6 +3,26 @@ title: "Instructions" description: "Interactive reference for TVM instructions" mode: "wide" --- + +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. + import { TvmInstructionTable } from "/snippets/tvm-instruction-table.jsx" From 5f984c5073bf4da88951112b0ce59862d3b4df1c Mon Sep 17 00:00:00 2001 From: Alexander Chichigin Date: Wed, 3 Dec 2025 16:07:22 +0300 Subject: [PATCH 2/2] fix: short forward reference and the explanation below the table --- tvm/instructions.mdx | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/tvm/instructions.mdx b/tvm/instructions.mdx index a3db0e894..988940f77 100644 --- a/tvm/instructions.mdx +++ b/tvm/instructions.mdx @@ -4,28 +4,21 @@ description: "Interactive reference for TVM instructions" mode: "wide" --- -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`. +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. -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. +import { TvmInstructionTable } from "/snippets/tvm-instruction-table.jsx" -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. +## Notation -import { TvmInstructionTable } from "/snippets/tvm-instruction-table.jsx" +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 */}