{"id":16253026,"url":"https://github.com/digitsensitive/tiny4cpu","last_synced_at":"2025-04-11T05:16:15.156Z","repository":{"id":217736780,"uuid":"744699951","full_name":"digitsensitive/Tiny4CPU","owner":"digitsensitive","description":"Tiny4CPU is a lightweight and educational 4-bit CPU emulator","archived":false,"fork":false,"pushed_at":"2024-03-03T18:50:49.000Z","size":4151,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-11T05:16:11.409Z","etag":null,"topics":["4-bit-cpu","assembly","computer-architecture","emulator","microprocessor","simulation"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitsensitive.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":"2024-01-17T20:38:26.000Z","updated_at":"2024-12-31T13:36:43.000Z","dependencies_parsed_at":"2024-02-06T21:38:34.434Z","dependency_job_id":"9f33ffcc-2133-4afa-ab67-6573c410b657","html_url":"https://github.com/digitsensitive/Tiny4CPU","commit_stats":null,"previous_names":["digitsensitive/tiny4cpu"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitsensitive%2FTiny4CPU","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitsensitive%2FTiny4CPU/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitsensitive%2FTiny4CPU/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitsensitive%2FTiny4CPU/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitsensitive","download_url":"https://codeload.github.com/digitsensitive/Tiny4CPU/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248345274,"owners_count":21088245,"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","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":["4-bit-cpu","assembly","computer-architecture","emulator","microprocessor","simulation"],"created_at":"2024-10-10T15:15:43.156Z","updated_at":"2025-04-11T05:16:15.135Z","avatar_url":"https://github.com/digitsensitive.png","language":"C","readme":"# Tiny4CPU\r\n\r\n![GitHub repo size](https://img.shields.io/github/repo-size/digitsensitive/Tiny4CPU)\r\n\r\nTiny4CPU is a lightweight and educational 4-bit CPU emulator designed for\r\nsimplicity. This project provides a hands-on exploration into the fundamentals\r\nof computer architecture, offering a platform to experiment with assembly\r\nlanguage programming in a compact environment.\r\n\r\nDive into the world of microprocessors with Tiny4CPU and witness the power of\r\n4 bits in action.\r\n\r\n\u003cimg src=\"./tiny4cpu.gif\" alt=\"Tiny4CPU\" style=\"width: 100%;\"/\u003e\r\n\r\nCode for the upper example:\r\n\r\n```bash\r\n; Usage of instruction OUT\r\n\r\n; Init Register X to 0\r\nInit:\r\nLDX #0\r\n\r\n; Main Loop\r\nLoop:\r\nADX #1\r\nOUT #0\r\nJMP Loop\r\n```\r\n\r\n## Features\r\n\r\n- 4-bit architecture with its own assembler and disassembler\r\n- 16-instruction set for data manipulation and control flow\r\n- 2 general-purpose registers and memory space of 8 bytes\r\n- Ability to adjust CPU clock cycles for synchronization in milliseconds\r\n- Assembly language support\r\n- Modular and extensible design\r\n- Comprehensive documentation\r\n- Examples for each instruction\r\n\r\n## How to write a program for the Tiny4CPU\r\n\r\nTiny4CPU programs are written in T4C Assembly and saved as `*.t4c` files.\r\nUse the Tiny4CPU Assembler to assembly your program to a `*.bin` file.\r\nAfter that, load your ROM `*.bin` file using the Tiny4CPU executable, including\r\nthe file path and the clock time in milliseconds.\r\n\r\nThe recommended clock time is 1000 milliseconds.\r\n\r\nExample:\r\n\r\n```bash\r\n./assembler .../examples/output.t4c\r\n./tiny4cpu .../examples/output.bin 1000\r\n```\r\n\r\n## Instruction set architecture (ISA)\r\n\r\n### Instruction Set\r\n\r\nTiny4CPU has `16 opcodes` (operation code, OP or instruction machine code),\r\nwhich are all `one byte long` and stored `big-endian`. Big-endian means that\r\nthe most-significant-byte is saved in memory first (i.e. the lower memory address).\r\nCurrently only 10 of potentially 16 opcodes are defined.\r\n\r\n| Mnemonic | Instruction | Description                                       |\r\n| -------- | ----------- | ------------------------------------------------- |\r\n| LDX      | 0000 kkkk   | Load Register X with immediate nibble value k     |\r\n| LDY      | 0001 kkkk   | Load Register Y with immediate nibble value k     |\r\n| ADX      | 0010 kkkk   | Add immediate nibble value k to Register X        |\r\n| ADY      | 0011 kkkk   | Add immediate nibble value k to Register Y        |\r\n| SUX      | 0100 kkkk   | Subtract immediate nibble value k from Register X |\r\n| SUY      | 0101 kkkk   | Subtract immediate nibble value k from Register Y |\r\n| OUT      | 0110 kkkk   | Set output to nibble value from register (1)      |\r\n| JXZ      | 0111 kkkk   | Jump to memory address k if Register X is zero    |\r\n| JYZ      | 1000 kkkk   | Jump to memory address k if Register Y is zero    |\r\n| JMP      | 1001 kkkk   | Unconditional jump to memory address k            |\r\n| ---      | 1010        | Unused                                            |\r\n| ---      | 1011        | Unused                                            |\r\n| ---      | 1100        | Unused                                            |\r\n| ---      | 1101        | Unused                                            |\r\n| ---      | 1110        | Unused                                            |\r\n| ---      | 1111        | Unused                                            |\r\n\r\n(1) Use value #0 for Register X or value #1 for Register Y\r\n\r\n### Registers\r\n\r\n| Register | Size (bits) | Description                  |\r\n| -------- | ----------- | ---------------------------- |\r\n| PC       | 4           | Program Counter              |\r\n| IR       | 8           | Instruction Register         |\r\n| IAR      | 8           | Instruction Address Register |\r\n| ACC      | 4           | Accumulator                  |\r\n| MAR      | 4           | Memory Address Register      |\r\n| RX       | 4           | General-purpose register X   |\r\n| RY       | 4           | General-purpose register Y   |\r\n\r\n### Memory\r\n\r\n- Mono-directional 4-bit address-bus from the microprocessor unit (MPU) to memory\r\n- The memory layout consists of one Memory Address Register (MAR).\r\n  The MAR is connected to two 2x4 decoder, enabling addressing of up\r\n  to 16 memory locations\r\n- Each memory location holds 4 bits of data, resulting in a total memory size\r\n  of 8 bytes\r\n\r\n## References\r\n\r\n- [ANSI Escape Code](https://en.wikipedia.org/wiki/ANSI_escape_code)\r\n- [ANSI Escape Sequences, Github](https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797)\r\n- [ASCII Chart](https://en.cppreference.com/w/cpp/language/ascii)\r\n- [DDL4-CPU, A Modular 4-Bit CPU Design by Dave](https://hackaday.io/project/158510/logs)\r\n- [Github project td4-py by yashikota](https://github.com/yashikota/td4-py)\r\n- [How to Build a CPU by Iku Watanabe](https://www.amazon.co.jp/CPU%E3%81%AE%E5%89%B5%E3%82%8A%E3%81%8B%E3%81%9F-%E6%B8%A1%E6%B3%A2-%E9%83%81/dp/4839909865/ref=asap_bc?ie=UTF8)\r\n- [Symbl](https://symbl.cc/en)\r\n- [yashikota/td4-py](https://github.com/yashikota/td4-py)\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitsensitive%2Ftiny4cpu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitsensitive%2Ftiny4cpu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitsensitive%2Ftiny4cpu/lists"}