{"id":18893409,"url":"https://github.com/xtaci/tmach","last_synced_at":"2025-07-27T06:05:52.794Z","repository":{"id":147664509,"uuid":"67876405","full_name":"xtaci/tmach","owner":"xtaci","description":"256bit vm","archived":false,"fork":false,"pushed_at":"2025-02-13T17:01:21.000Z","size":63,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-08T03:39:36.496Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xtaci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-10T14:46:28.000Z","updated_at":"2025-02-14T03:18:09.000Z","dependencies_parsed_at":"2025-02-10T05:35:00.884Z","dependency_job_id":null,"html_url":"https://github.com/xtaci/tmach","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xtaci/tmach","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtaci%2Ftmach","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtaci%2Ftmach/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtaci%2Ftmach/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtaci%2Ftmach/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xtaci","download_url":"https://codeload.github.com/xtaci/tmach/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xtaci%2Ftmach/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267312253,"owners_count":24067773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T08:13:34.997Z","updated_at":"2025-07-27T06:05:52.788Z","avatar_url":"https://github.com/xtaci.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## **tmach Virtual Machine Instruction Set Architecture Specification**\n### **1. Registers**\n\n#### **1.1 General-Purpose Registers**\n- **Width**: 256 bits.\n- **Function**: Store integer or floating-point data.\n- **Classification**:\n  - **Integer Registers**: `R0` to `R7` for integer operations.\n  - **Floating-Point Registers**: `F0` to `F7` for floating-point operations.\n- **Encoding**:\n  - `R0` to `R7`: `0000` to `0111`.\n  - `F0` to `F7`: `1000` to `1111`.\n\n#### **1.2 Address Registers**\n- **Width**: 32 bits.\n- **Function**: Used for memory address calculations.\n- **Registers**: `A0` to `A7`.\n- **Encoding**: Each address register is uniquely identified by a 4-bit code from `0000` to `0111`.\n\n#### **1.3 Special-Purpose Registers**\n- **Status Register (SR)**:\n  - **Width**: 8 bits.\n  - **Function**: Records the results of arithmetic and logical operations.\n  - **Flags**:\n    - **Bit 0**: Zero Flag (ZF) – Set to 1 if the result of the previous operation is zero.\n    - **Bit 1**: Overflow Flag (OF) – Set to 1 if an arithmetic overflow occurs.\n    - **Bit 2**: Divide-by-Zero Flag (DF) – Set to 1 if division by zero is attempted.\n    - **Bits 3–5**: Comparison Result (CR) – Encodes the outcome of a `CMP` instruction (e.g., \"less than,\" \"equal,\" or \"greater than\").\n    - **Bits 6–7**: Reserved for future use.\n\n- **Program Counter (PC)**:\n  - **Function**: Stores the address of the next instruction to execute.\n  - **Property**: Read-only.\n\n- **Jump Return Register (J)**:\n  - **Function**: Automatically stores the return address (the address of the instruction immediately following a jump) when a jump instruction is executed.\n  - **Property**: Read-only; used to facilitate function calls and returns.\n\n---\n\n### **2. Instruction Set**\n\n#### **2.1 Memory Access Instructions**\n- **Function**: Load data from memory into registers or store register data into memory.\n- **Address Calculation**: Memory addresses are **fully determined by address registers** (no offset).\n- **Instruction Format**:\n  - **LOAD**: `LOAD Rd, [Ax]`\n    - Loads data from the memory address stored in `Ax` into register `Rd`.\n  - **STORE**: `STORE Rs, [Ax]`\n    - Stores the contents of register `Rs` into the memory address stored in `Ax`.\n- **Machine Code Format (16 bits)**:\n  - **Opcode**: 8 bits.\n  - **Target/Source Register**: 4 bits.\n  - **Address Register**: 4 bits.\n\n**Examples**:\n- `LOAD R2, [A1]`:\n  - Opcode: `0x08`\n  - Target Register: `0010` (R2)\n  - Address Register: `0001` (A1)\n  - Machine Code: `0x0821`\n\n- `STORE R3, [A2]`:\n  - Opcode: `0x09`\n  - Source Register: `0011` (R3)\n  - Address Register: `0010` (A2)\n  - Machine Code: `0x0932`\n\n---\n\n#### **2.2 Arithmetic Instructions**\n- **Function**: Perform arithmetic operations (addition, subtraction, multiplication, division).\n- **Operand Type**: Determined by the register name (`R` for integer, `F` for floating-point).\n- **Instruction Format**:\n  - **ADD**: `ADD Rd, Rs, Rt`\n    - Adds the values in `Rs` and `Rt`, storing the result in `Rd`.\n  - **SUB**: `SUB Rd, Rs, Rt`\n    - Subtracts `Rt` from `Rs`, storing the result in `Rd`.\n  - **MUL**: `MUL Rd, Rs, Rt`\n    - Multiplies `Rs` and `Rt`, storing the result in `Rd`.\n  - **DIV**: `DIV Rd, Rs, Rt`\n    - Divides `Rs` by `Rt`, storing the result in `Rd`. Sets the `DF` flag if division by zero occurs.\n- **Machine Code Format (24 bits)**:\n  - **Opcode**: 8 bits.\n  - **Source Register 1**: 4 bits.\n  - **Source Register 2**: 4 bits.\n  - **Destination Register**: 4 bits.\n  - **Reserved**: 4 bits (unused).\n\n**Example**:\n- `ADD R0, R1, R2`:\n  - Opcode: `0x01`\n  - Source Register 1: `0001` (R1)\n  - Source Register 2: `0010` (R2)\n  - Destination Register: `0000` (R0)\n  - Machine Code: `0x010012`\n\n---\n\n#### **2.3 Comparison Instruction**\n- **Function**: Compare two register values and update the Status Register (SR).\n- **Instruction Format**:\n  - **CMP**: `CMP Rs, Rt`\n    - Compares `Rs` and `Rt`, updating the `ZF`, `LT`, and `GT` flags.\n- **Machine Code Format (16 bits)**:\n  - **Opcode**: 8 bits.\n  - **Source Register 1**: 4 bits.\n  - **Source Register 2**: 4 bits.\n\n**Example**:\n- `CMP R0, R1`:\n  - Opcode: `0x05`\n  - Source Register 1: `0000` (R0)\n  - Source Register 2: `0001` (R1)\n  - Machine Code: `0x0501`\n\n---\n\n#### **2.4 Type Conversion Instructions**\n- **Function**: Convert between integer and floating-point representations.\n- **Instruction Format**:\n  - **ITOF**: `ITOF Fd, Rs`\n    - Converts the integer value in `Rs` to a floating-point value, stored in `Fd`.\n  - **FTOI**: `FTOI Rd, Fs`\n    - Converts the floating-point value in `Fs` to an integer value, stored in `Rd`.\n\n---\n\n#### **2.5 Logical and Bitwise Instructions**\n- **Function**: Perform bitwise operations.\n- **Instruction Format**:\n  - **AND**: `AND Rd, Rs, Rt`\n    - Bitwise AND of `Rs` and `Rt`, stored in `Rd`.\n  - **OR**: `OR Rd, Rs, Rt`\n    - Bitwise OR of `Rs` and `Rt`, stored in `Rd`.\n  - **XOR**: `XOR Rd, Rs, Rt`\n    - Bitwise XOR of `Rs` and `Rt`, stored in `Rd`.\n  - **NOT**: `NOT Rd, Rs`\n    - Bitwise NOT of `Rs`, stored in `Rd`.\n  - **LSH**: `LSH Rd, N`\n    - Left-shifts the value in `Rd` by `N` bits.\n  - **RSH**: `RSH Rd, N`\n    - Right-shifts the value in `Rd` by `N` bits.\n  - **CSH**: `CSH Rd, N`\n    - Cyclically shifts the value in `Rd` by `N` bits.\n\n---\n\n#### **2.6 Control Flow Instructions**\n- **Function**: Modify program flow based on the Status Register (SR) flags.\n- **Instruction Format**:\n  - **JMP**: `JMP Addr`\n    - Unconditionally jumps to the address `Addr` and saves the return address in `J`.\n  - **Conditional Jumps**:\n    - **JZ**: Jump if `ZF == 1`.\n    - **JNZ**: Jump if `ZF == 0`.\n    - **JGT**: Jump if `GT == 1`.\n    - **JLT**: Jump if `LT == 1`.\n    - **JEQ**: Jump if `ZF == 1`.\n\n---\n\n#### **2.7 Miscellaneous Instruction**\n- **NOP**: No operation (used for timing or alignment).\n\n---\n\n### **3. Machine Code Format Overview**\n\n#### **3.1 Memory Access Instructions (16 bits)**\n| Field           | Length | Description                     |\n|------------------|--------|---------------------------------|\n| Opcode           | 8 bits | e.g., `0x08` for `LOAD`         |\n| Target/Source Reg| 4 bits | General-purpose register (R/F)  |\n| Address Register | 4 bits | Address register (A0–A7)        |\n\n#### **3.2 Arithmetic/Logical Instructions (24 bits)**\n| Field           | Length | Description                     |\n|------------------|--------|---------------------------------|\n| Opcode           | 8 bits | e.g., `0x01` for `ADD`          |\n| Source Register 1| 4 bits | e.g., `Rs`                      |\n| Source Register 2| 4 bits | e.g., `Rt`                      |\n| Destination Reg  | 4 bits | e.g., `Rd`                      |\n| Reserved         | 4 bits | Unused                          |\n\n#### **3.3 Jump Instructions (32 bits)**\n| Field           | Length | Description                     |\n|------------------|--------|---------------------------------|\n| Opcode           | 8 bits | e.g., `0x10` for `JMP`          |\n| Address          |32 bits | Full memory address to jump to  |\n\n---\n\n### **4. Offset Support at the Assembly Language Level**\n- **Implementation**:\n  - **Address Calculation Macros**: For example, `LOAD R0, [A1 + 30]` is translated by the assembler into two instructions:\n    1. Use `ADD` to compute `A1 + 30` and store the result in a temporary address register (e.g., `A2`).\n    2. Execute `LOAD R0, [A2]`.\n  - **Pseudo-Instructions**: Provide syntax like `LOAD R0, [A1 + 30]`, which the assembler automatically converts into low-level instructions.\n\n---\n\n### **5. Summary**\nThe **tmach Virtual Machine Instruction Set** is designed for simplicity and flexibility, with memory addressing fully controlled by 32-bit address registers. By removing offsets from hardware instructions, the design achieves greater compactness, while offset support is reintroduced at the assembly language level through macros or pseudo-instructions. This architecture is well-suited for high-precision computations, embedded systems, and scenarios requiring efficient control flow. Future enhancements could include stack support for nested function calls and expanded status flag definitions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtaci%2Ftmach","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxtaci%2Ftmach","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxtaci%2Ftmach/lists"}