{"id":20323383,"url":"https://github.com/anishsharma21/memory-map-emulator","last_synced_at":"2025-03-04T10:15:52.279Z","repository":{"id":253220678,"uuid":"837856420","full_name":"anishsharma21/Memory-Map-Emulator","owner":"anishsharma21","description":"See machine code run visually with an emulated map of the memory","archived":false,"fork":false,"pushed_at":"2024-08-18T08:24:49.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-14T14:11:18.614Z","etag":null,"topics":["emulation","machine-language","memory-allocation","opcodes","ram","von-neumann-machine"],"latest_commit_sha":null,"homepage":"","language":"Python","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/anishsharma21.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}},"created_at":"2024-08-04T08:41:30.000Z","updated_at":"2024-09-29T08:22:03.000Z","dependencies_parsed_at":"2024-11-14T19:33:02.764Z","dependency_job_id":"5eefc7c5-6f5f-476a-b107-150d9b955d34","html_url":"https://github.com/anishsharma21/Memory-Map-Emulator","commit_stats":null,"previous_names":["anishsharma21/custom-isa-emulation","anishsharma21/von-neumann-a-emulator","anishsharma21/memory-map-emulator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anishsharma21%2FMemory-Map-Emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anishsharma21%2FMemory-Map-Emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anishsharma21%2FMemory-Map-Emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anishsharma21%2FMemory-Map-Emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anishsharma21","download_url":"https://codeload.github.com/anishsharma21/Memory-Map-Emulator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241827169,"owners_count":20026601,"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":["emulation","machine-language","memory-allocation","opcodes","ram","von-neumann-machine"],"created_at":"2024-11-14T19:27:52.395Z","updated_at":"2025-03-04T10:15:52.253Z","avatar_url":"https://github.com/anishsharma21.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memory Map Emulator\n\n## Project Overview\n\nHave you ever wondered what it means to 'run' a program? What goes on under the hood? What did the first programs look like visually?\n\nWell, in this project, you can write machine code and watch your program run visually in memory (emulated).\n\nIn more technical terms, this project involves emulating the changing memory map (RAM) in a Von Neumann-architected computer as it runs a program, i.e. it shows what happens in a simple computer when a simple (or complex) program is run. Programs are written in a defined format and adhere to a custom Instruction Set Architecture (ISA). When the main program (written in Python) is run, you can specify a program for emulation by its file name and then step forward by pressing `enter`, seeing the operations being performed, a description of each step, and, of course, a map of the memory as it changes over time.\n\nThis project is inspired by the incredible book *CODE: The Hidden Language of Hardware and Software*. A must-read for anyone who wants to know how computers really work from the ground up - it's completely beginner-friendly, with no previous knowledge required, and takes you from mere 1s and 0s all the way to building your own computer.\n\n### How do I run it?\n\nOpen your terminal and run the following command:\n\n```bash\ngit clone https://github.com/anishsharma21/Memory-Map-Emulator\n```\n\nThen, in the same directory, run the following command:\n\n```bash\npython3 main.py\n```\n\nYou'll be prompted with:\n\n```plaintext\nEnter the file name: \n```\n\nThere are many pre-written programs you can run and can be found in the `programs` directory. You can type in the full filename, like `p1.txt` or you can just type in `p1`. This way, you don't need to specify the extension, you can simply write the name of your file. \n\nYou can also add your own programs to the `programs` directory. Programs must be written with the `.txt` extension.\n\nP.S. `p7.txt` is pretty interesting to run 👀\n\nIf you don't have [python3](https://www.python.org/downloads/) installed, go to this link to install it.\n\n## ISA Specification\n\n### Instruction Set Architecture\n\n| Operation            | Code | Mnemonic |\n|----------------------|------|----------|\n| Load                 | 10h  | LOD      |\n| Store                | 11h  | STO      |\n| Add                  | 20h  | ADD      |\n| Subtract             | 21h  | SUB      |\n| Add with Carry       | 22h  | ADC      |\n| Subtract with Borrow | 23h  | SBB      |\n| Jump                 | 30h  | JMP      |\n| Jump if Zero         | 31h  | JZ       |\n| Jump if Carry        | 32h  | JC       |\n| Jump if Not Zero     | 33h  | JNZ      |\n| Jump if Not Carry    | 34h  | JNC      |\n| Halt                 | FFh  | HLT      |\n\n- **A**: Accumulator\n- **Memory Range**: [0000h - FFFFh] (64KB memory, 16-bit addresses)\n\n### Machine Code Format\n\nEach program consists of memory address declarations, and memory inputs that follow. \n\n```plaintext\n[ADDRESS]:\n##h\n##h\n```\n\nYou declare a memory address, and then bytes that you want to input to create your program.\n\nFurther details about creating your own programs can be found in `documentation/isa-raw-format.txt`.\n\n**Endianness**: Big-endian (high-byte stored in lower address)\n\n## Example Program\n\nHere is a simple program that adds 2 numbers together:\n\n```plaintext\n0000h:\n10h\n10h\n00h\n\n20h\n10h\n01h\n\n11h\n10h\n02h\n\nFFh\n\n1000h:\n01h\n01h\n00h\n```\n\nIn the above program, the line `0000h` indicates that from here onwards, each newline will correspond to a byte of data the will need to be inputted into memory. In this case, you can see the bytes being inputted in sequences of 3. These are instructions - the first byte is the instruction opcode (see above for the list of opcodes) and the next 2 relate to a 16-bit address in memory. You don't need to add new lines between each instruction sequence, but it makes it easier to read and distinguish between 'instruction code' and 'data'. The memory declared after `0000h` is declared as instructions to be run, while memory after `1000h` is used by the program as memory to be accessed.\n\nThis program can be run by choosing `p1.txt` (or just `p1`) as the file when running the main program.\n\n### Description\n\nThe program above loads the value at memory `1000h`, then adds the value at memory location `1001h`. It then stores the current accumulator value at address `1002h` before halting.\n\n### Emulation Goals\n\n- `Real-Time Memory Display`: The Python program will display the entire memory set in the terminal, updating in real-time with each instruction cycle.\n- `Instruction Highlighting`: Each instruction will be highlighted as the program progresses to show what is happening at each step.\n\n### Contributing\n\nContributions are welcome! Please fork the repository and submit pull requests.\n\n### License\n\nThis project is licensed under the MIT License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanishsharma21%2Fmemory-map-emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanishsharma21%2Fmemory-map-emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanishsharma21%2Fmemory-map-emulator/lists"}