{"id":31209921,"url":"https://github.com/ulizesr/dez","last_synced_at":"2025-09-21T03:55:37.178Z","repository":{"id":269894869,"uuid":"872598794","full_name":"UlizesR/Dez","owner":"UlizesR","description":"A C VM that runs dez assembly","archived":false,"fork":false,"pushed_at":"2025-09-17T20:31:20.000Z","size":208,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T22:30:04.053Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UlizesR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-14T18:08:24.000Z","updated_at":"2025-09-17T20:31:23.000Z","dependencies_parsed_at":"2025-09-17T22:12:51.335Z","dependency_job_id":"3a3a4919-8895-4da8-84f3-9488517d06e1","html_url":"https://github.com/UlizesR/Dez","commit_stats":null,"previous_names":["ulizesr/deslib"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UlizesR/Dez","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UlizesR%2FDez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UlizesR%2FDez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UlizesR%2FDez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UlizesR%2FDez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UlizesR","download_url":"https://codeload.github.com/UlizesR/Dez/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UlizesR%2FDez/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276191269,"owners_count":25600409,"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-09-21T02:00:07.055Z","response_time":72,"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":"2025-09-21T03:55:34.951Z","updated_at":"2025-09-21T03:55:37.172Z","avatar_url":"https://github.com/UlizesR.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEZ VM - A Modern Virtual Machine\n\nDEZ VM is a lightweight 32-bit virtual machine designed for educational purposes and simple program execution. It features a complete assembler toolchain with modern language features including labels, comments, and advanced instruction encoding.\n\n## Features\n\n- **32-bit RISC-like instruction set** with 16 general-purpose registers\n- **Complete assembler toolchain** with lexer, parser, and symbol table\n- **Label and comment support** for readable assembly code\n- **Advanced instruction encoding** supporting both register-to-register and register-to-immediate operations\n- **System calls** for I/O operations including string printing\n- **Memory management** with code, data, and stack segments\n- **Binary file format** for compiled programs\n- **Comprehensive test suite** with CTest integration\n- **Enhanced syntax highlighting** with support for binary and hexadecimal numbers\n\n## Architecture\n\n### Memory Layout\n- **Total Memory**: 16KB (4096 words)\n- **Code Segment**: 0x0000 - 0x0FFF (4KB, read-only)\n- **Data Segment**: 0x1000 - 0x1FFF (4KB, writable)\n- **Stack Segment**: 0x2000 - 0x3FFF (8KB, writable)\n\n### Registers\n- **R0 - R15**: 16 general-purpose 32-bit registers\n- **PC**: Program Counter\n- **SP**: Stack Pointer\n- **Flags**: Status flags (zero, carry, overflow)\n\n## Building\n\n```bash\n# Create build directory\nmkdir build \u0026\u0026 cd build\n\n# Build the project\ncmake ..\nmake\n\n# All executables will be created in the bin/ directory\nls bin/\n# asm dez_vm disasm_tool test_assembly test_core test_memory test_performance test_strings\n\n# Run all tests\nctest --output-on-failure\n```\n\n## Usage\n\n### 1. Writing Assembly Code\n\nCreate a `.s` file with your program:\n\n```assembly\n; examples/hello.s\nstart: ; Entry point label\nMOV R0, 42 ; Load value 42 into R0\nSYS R0, PRINT ; Print the value\nHALT ; Stop execution\n```\n\n### 2. Assembling\n\nUse the assembler to compile your assembly code:\n\n```bash\n# From the build directory\n./bin/asm ../examples/hello.s hello.bin\n```\n\n### 3. Running\n\nExecute the compiled binary with the VM:\n\n```bash\n# From the build directory\n./bin/dez_vm hello.bin\n```\n\n### 4. Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nctest --output-on-failure\n\n# Or run specific tests\n./bin/test_assembly\n./bin/test_core\n```\n\n## Instruction Set\n\n### Number Formats\nDEZ assembly supports multiple number formats for immediate values:\n- **Decimal**: `42`, `255`, `4095`\n- **Hexadecimal**: `0x2A`, `0xFF`, `0xFFF` (prefix with `0x`)\n- **Binary**: `0b101010`, `0b11111111`, `0b111111111111` (prefix with `0b`)\n\nAll formats are equivalent and can be used interchangeably:\n```assembly\nMOV R1, 42          ; Decimal\nMOV R2, 0x2A        ; Hexadecimal (same as 42)\nMOV R3, 0b101010    ; Binary (same as 42)\n```\n\n**Note**: Immediate values are limited to 12 bits (0-4095) due to instruction encoding constraints.\n\n### Data Movement\n- `MOV R1, 42` - Load immediate value 42 into R1\n- `MOV R1, R2` - Copy R2 to R1\n\n### Arithmetic\n- `ADD R1, R2, R3` - R1 = R2 + R3 (register-to-register)\n- `ADD R1, R2, 5` - R1 = R2 + 5 (register-to-immediate)\n- `SUB R1, R2, R3` - R1 = R2 - R3 (register-to-register)\n- `SUB R1, R2, 3` - R1 = R2 - 3 (register-to-immediate)\n- `MUL R1, R2, R3` - R1 = R2 * R3\n- `DIV R1, R2, R3` - R1 = R2 / R3\n\n### Memory Operations\n- `STORE R1, 256` - Store R1 at memory address 256\n\n### Control Flow\n- `JMP label` - Jump to label\n- `JZ label` - Jump if zero flag set\n- `JNZ label` - Jump if zero flag not set\n\n### System Calls\n- `SYS R1, PRINT` - Print value in R1\n- `SYS R1, PRINT_CHAR` - Print character in R1\n\n### Other\n- `CMP R1, R2` - Compare R1 and R2 (sets flags)\n- `CMP R1, 5` - Compare R1 with immediate value 5 (sets flags)\n- `HALT` - Halt execution\n- `NOP` - No operation\n\n### Labels and Comments\n- `label:` - Define a label\n- `; This is a comment` - Full-line comment\n- `MOV R0, 42 ; Inline comment` - Inline comment\n\n## Examples\n\n### Hello World\n```assembly\n; Simple hello world program\nstart: ; Entry point\nMOV R0, 42 ; Load value 42 (decimal)\nSYS R0, PRINT ; Print the value\nHALT ; Stop execution\n```\n\n### Number Format Examples\n```assembly\n; Demonstrating different number formats\nstart:\nMOV R0, 42          ; Decimal\nMOV R1, 0x2A        ; Hexadecimal (same as 42)\nMOV R2, 0b101010    ; Binary (same as 42)\nADD R3, R0, R1      ; 42 + 42 = 84\nSYS R3, PRINT       ; Print result\nHALT\n```\n\n### Arithmetic Operations\n```assembly\n; Basic arithmetic with immediate values\nstart:\nMOV R0, 10 ; Load first operand\nMOV R1, 20 ; Load second operand\nADD R2, R0, R1 ; Add: R2 = R0 + R1 = 30\nSUB R3, R0, R1 ; Subtract: R3 = R0 - R1 = -10\nHALT\n```\n\n### Loops and Labels\n```assembly\n; Loop to sum numbers 1 to 5\nstart:\nMOV R0, 5 ; Initialize counter\nMOV R1, 0 ; Initialize sum\n\nloop: ; Loop label\nADD R1, R1, R0 ; Add counter to sum\nSUB R0, R0, 1  ; Decrement counter\nCMP R0, 0      ; Check if counter is zero\nJNZ loop       ; Continue loop if not zero\n\ndone: ; End of loop\nHALT ; Stop execution\n```\n\n### Conditional Logic\n```assembly\n; Conditional jump example\nstart:\nMOV R0, 5 ; Set R0 to 5\nMOV R1, 5 ; Set R1 to 5 (equal to R0)\nCMP R0, R1 ; Compare R0 and R1\nJZ equal ; Jump if equal\nMOV R2, 1 ; This should be skipped\nJMP end ; Jump to end\nequal: ; Jump target for equal case\nMOV R2, 1 ; Set R2 to 1\nend: ; End label\nHALT ; Stop execution\n```\n\n### Memory Operations\n```assembly\n; Store and retrieve values from memory\nstart:\nMOV R0, 123 ; Load value 123\nSTORE R0, 256 ; Store R0 at address 256\nMOV R1, 456 ; Load value 456\nSTORE R1, 257 ; Store R1 at address 257\nHALT ; Stop execution\n```\n\n## Tools\n\n### Assembler (`asm`)\nCompiles assembly source files to binary format:\n```bash\n# From the build directory\n./bin/asm ../examples/hello.s hello.bin\n```\n\n### Disassembler (`disasm_tool`)\nDisassembles binary files back to assembly:\n```bash\n# From the build directory\n./bin/disasm_tool hello.bin\n```\n\n### VM (`dez_vm`)\nExecutes compiled binary files:\n```bash\n# From the build directory\n./bin/dez_vm hello.bin\n```\n\n### Test Suite\nComprehensive test suite with multiple test categories:\n```bash\n# Run all tests\nctest --output-on-failure\n\n# Individual test executables\n./bin/test_assembly  # Assembly integration tests\n./bin/test_core      # Core VM functionality\n./bin/test_memory    # Memory operations\n./bin/test_performance # Performance benchmarks\n./bin/test_strings   # String handling\n```\n\n## File Format\n\nThe binary format consists of:\n1. **Header**: 4-byte instruction count\n2. **Instructions**: 32-bit encoded instructions with advanced encoding:\n   - **Register-to-register**: `(opcode \u003c\u003c 24) | (reg1 \u003c\u003c 20) | (reg2 \u003c\u003c 16) | (reg3 \u003c\u003c 12)`\n   - **Register-to-immediate**: `(opcode \u003c\u003c 24) | (reg1 \u003c\u003c 20) | (reg2 \u003c\u003c 16) | (1 \u003c\u003c 11) | immediate`\n   - **Bit 11 flag**: Distinguishes between register and immediate modes\n3. **String Data**: Raw string data (null-terminated, word-aligned)\n\n## Advanced Features\n\n### Two-Pass Assembly\nThe assembler uses a two-pass approach for proper label resolution:\n1. **First pass**: Collect all label definitions and their addresses\n2. **Second pass**: Parse instructions and resolve label references\n\n### Instruction Encoding\nAdvanced encoding scheme supports both register-to-register and register-to-immediate operations:\n- **Register R0 handling**: Correctly distinguishes between register R0 and immediate value 0\n- **Immediate values**: Supports values up to 2047 (11-bit range)\n- **Flag-based encoding**: Uses bit 11 as a mode flag for unambiguous instruction interpretation\n\n## Development\n\n### Project Structure\n```\nsrc/\n├── core/                    # VM core implementation\n│   ├── dez_vm.c            # Main VM logic with PC management\n│   ├── dez_memory.c        # Memory management\n│   ├── dez_instruction_table.c # Instruction execution with advanced encoding\n│   ├── dez_disasm.c        # Disassembler core\n│   └── dez_disasm.h        # Disassembler header\n├── assembler/              # Assembler toolchain\n│   ├── dez_lexer.c         # Tokenizer with comment support\n│   ├── dez_parser.c        # Two-pass parser with label resolution\n│   ├── dez_symbol_table.c  # Symbol management for labels/constants\n│   ├── dez_assembler.c     # Main assembler interface\n│   └── asm.c              # Assembler command-line tool\n├── main.c                  # VM command-line interface\n└── tools/\n    └── disasm_tool.c       # Disassembler command-line tool\n\ntests/\n├── asm/                    # Assembly test files\n│   ├── test_basic.s        # Basic arithmetic operations\n│   ├── test_memory.s       # Memory operations\n│   ├── test_jumps.s        # Jump instructions\n│   ├── test_conditional.s  # Conditional jumps\n│   ├── test_system.s       # System calls\n│   ├── test_loop.s         # Loop constructs\n│   ├── test_labels.s       # Label functionality\n│   ├── test_comments.s     # Comment support\n│   └── test_mixed.s        # Mixed labels and comments\n├── test_assembly.c         # Assembly integration tests\n├── test_core.c            # Core VM tests\n├── test_memory.c          # Memory operation tests\n├── test_performance.c     # Performance tests\n└── test_strings.c         # String handling tests\n\ninclude/\n└── dez_vm_types.h         # VM type definitions and opcodes\n```\n\n### Adding New Instructions\n\n1. Add opcode to `dez_instruction_type_t` in `include/dez_vm_types.h`\n2. Add instruction metadata to `instruction_table` in `src/core/dez_instruction_table.c`\n3. Implement execution logic in the appropriate handler function\n4. Update the parser to recognize the new instruction syntax\n5. Consider instruction encoding for register vs immediate modes\n\n### Adding New System Calls\n\n1. Add syscall number to `dez_syscall_t` in `include/dez_vm_types.h`\n2. Add handling in `execute_sys()` function in `src/core/dez_instruction_table.c`\n3. Update the parser to recognize the new syscall name\n\n### Testing New Features\n\n1. Add assembly test files in `tests/asm/`\n2. Create corresponding C tests in `tests/test_assembly.c`\n3. Run the full test suite with `ctest --output-on-failure`\n4. Ensure all existing tests continue to pass\n\n\n- Maximum program size: 1024 instructions (4KB code segment)\n- Maximum immediate value: 2047 (11-bit range due to encoding scheme)\n- No floating-point arithmetic\n- No dynamic memory allocation\n- Limited error handling for some edge cases\n\n## Syntax Highlighting\n\nDEZ VM includes comprehensive syntax highlighting support for VS Code with enhanced support for binary and hexadecimal numbers.\n\n### Features\n- **Multiple number formats**: Decimal, hexadecimal (`0x`), and binary (`0b`) with distinct colors\n- **Two built-in themes**: Dark and light themes optimized for different environments\n- **Comprehensive highlighting**: Instructions, registers, labels, system calls, strings, and more\n- **Easy installation**: Available as a VS Code extension package\n\n### Installation\n1. Install the VS Code extension from `syntax-highlighting/dez-assembly-1.0.0.vsix`\n2. Or install from the `syntax-highlighting/vscode-extension/` directory in development mode\n\n### Preview\nSee `syntax-highlighting/syntax-preview.html` for a visual demonstration of the syntax highlighting.\n\n## License\n\nThis project is open source and available under the MIT License.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## Acknowledgments\n\nThis VM was designed as an educational project to demonstrate virtual machine concepts and assembly language implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulizesr%2Fdez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulizesr%2Fdez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulizesr%2Fdez/lists"}