{"id":15060488,"url":"https://github.com/open-machine/circuits","last_synced_at":"2026-01-26T08:35:01.242Z","repository":{"id":48258997,"uuid":"289989657","full_name":"Open-Machine/Circuits","owner":"Open-Machine","description":"A basic computer circuit using made only using logic gates.","archived":false,"fork":false,"pushed_at":"2022-01-19T04:52:32.000Z","size":16691,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"stable","last_synced_at":"2025-03-15T05:17:11.368Z","etag":null,"topics":["assembly","circuits","cpu"],"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/Open-Machine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-24T17:07:41.000Z","updated_at":"2022-01-19T04:52:35.000Z","dependencies_parsed_at":"2022-08-24T04:20:43.045Z","dependency_job_id":null,"html_url":"https://github.com/Open-Machine/Circuits","commit_stats":null,"previous_names":["open-machine/computer-circuits"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FCircuits","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FCircuits/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FCircuits/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FCircuits/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Machine","download_url":"https://codeload.github.com/Open-Machine/Circuits/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243685591,"owners_count":20330983,"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":["assembly","circuits","cpu"],"created_at":"2024-09-24T22:59:25.477Z","updated_at":"2026-01-26T08:35:01.199Z","avatar_url":"https://github.com/Open-Machine.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e \n\u003ch1\u003eOpen Machine's Circuits\u003c/h1\u003e\n\u003ch4\u003eCircuits of a basic computer.\u003c/h4\u003e\n\n\u003ci\u003eThis repository is a component of a larger project: \u003cb\u003e\u003ca href=\"https://github.com/Open-Machine/README\"\u003eOpen-Machine\u003c/a\u003e\u003c/b\u003e - an open-source computer developed from scratch.\u003c/i\u003e\n\n\u003ca href=\"https://github.com/Open-Machine/Circuits/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/Open-Machine/Circuits\" alt=\"Stars Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/Open-Machine/Circuits\" alt=\"Forks Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-0.0.1-blue\" alt=\"Version Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/commits/\"\u003e\u003cimg src=\"https://img.shields.io/github/commit-activity/m/Open-Machine/Circuits\" alt=\"commits\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/pulls\"\u003e\u003cimg src=\"https://img.shields.io/github/issues-pr/Open-Machine/Circuits\" alt=\"Pull Requests Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/Open-Machine/Circuits\" alt=\"Issues Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/graphs/contributors\"\u003e\u003cimg alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/Open-Machine/Circuits?color=2b9348\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Circuits/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/Open-Machine/Circuits?color=2b9348\" alt=\"License Badge\"/\u003e\u003c/a\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/Open-Machine/README/stable/Media/logo-horizontal.png\" alt=\"open-machine\"/\u003e\n\n\u003cbr/\u003e\n\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 🔖 Table of Contents\n### 1. [💻 How does a computer work behind the curtains?](#-how-does-a-computer-work-behind-the-curtains)\n### 2. [🔢 Machine Code](#-machine-code)\n### 3. [🔀 Code Flow and Tips](#-code-flow-and-tips)\n### 4. [⌨️ Machine Code Example](#-machine-code-example)\n### 5. [▶️ Run](#️-run)\n### 6. [▶️ Test](#️-test)\n### 7. [📄 Contributing Guidelines](#-contributing-guidelines)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 💻 How does a computer work behind the curtains?\n\nOf course, I don't know and won't tell you everything about how a computer works. However, let's take a closer look to the its components and main functions so you know at least what you are looking at when running the circuit simulation.\n\n## Circuit Components\n\n#### Central Processing Unit (CPU)\nThe CPU is the brain of the computer, where every instruction is processed. It is composed by the sub-components below:\n  - *Control Unit (CU)*: it controls the CPU flags, which are used to direct the execution of the instructions;\n  - *Arithmetic Logic Unit (ALU)*: it performs sums, subtractions and comparisons between numbers;\n  - *Registers*: they are a small memories in the CPU for auxiliary purposes and faster accessed;\n  \n  \tThe Open-Machine's Circuit only has two registers: the accumulator (ACC) and the program counter (PC) registers.\n\n#### Random Access Memory (RAM)\nRAM is a temporary memory, which means that when the computer is turned off, all of its data is lost. However, it is very fast and serves, among other things, to store variables during the execution of programs.\n\n#### Disk\nDisk is a permanent memory, which means that it is used to store data that shouldn't be deleted after turning it off. However, it is slower than RAM. The disk can be an Hard Drive (HD) or Solid-State Drive (SSD).\n\n#### Input/Output Devices\nFor an actual computer to work, you also need input devices such as keyboard and mouse, and output devices such as screen.\n\n\u003cbr/\u003e\n\n*ps: Since the Open-Computer's is a basic computer, complex input and output devices and disk were chosen not to be implemented. However, the plan is to build it on the future.*\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 🔢 Machine Code\n\nLet's take a close look at the instructions available. A machine code command takes 16 bits in which first 4 bits represent the instruction and the following 12 bits are the parameter address. For example, in the command ```0x1202```, the instruction is ```0x1``` and the parameter address is ```0x202```.\n\n## Instructions Table\nLet's look at all of the instructions at our disposal.\n\n### Symbols Legend for the Instructions Table\nSymbol | Explanation\n--- | ---\nACC | The ACC register\nEE | Represents a memory index\n[ ] | \"Value of\"\n\n### Instructions Table\nMachine Code | Short Instruction Description | Long Instruction Description | Short Param Description | Long Param Description\n--- | --- | --- | --- | ---\n0x0 | - | This instruction **doesn't perform any action** | - | No parameter is required\n0x1 | [ACC] = [EE] | A value from the memory is **copied** to the **ACC** register | variable | Memory address of a variable that will be used in the instruction\n0x2 | [EE] = [ACC] | The value from the ACC register is **stored** into **memory** | variable | Memory address of a variable that will be used in the instruction\n0x3 | [ACC] = [ACC] + [EE] | The **sum** of the value of the **ACC** register and a value from the memory is stored in the ACC register | variable | Memory address of a variable that will be used in the instruction\n0x4 | [ACC] = [ACC] - [EE] | The **difference** between the value of the ACC register and a value from the memory is stored in the ACC register | variable | Memory address of a variable that will be used in the instruction\n0x7 | [EE] = input value | The **input** value is copied to the **memory** | variable | Memory address of a variable that will be used in the instruction\n0x8 | Output [EE] | Outputs a value from the memory into the circuit LEDs | variable | Memory address of a variable that will be used in the instruction\n0x9 | Finishes program | When this instruction is encountered, the **program is finished** and no more instructions will be executed | - | No parameter is required\n0xa | Jump to EE | **Jump** to another line of code | instruction | Memory address of a instruction the program will jump to\n0xb | Jump to EE if [ACC] \u003e 0 | **Jump** to another line of code **if** the value of the ACC register is **positive** | instruction | Memory address of a instruction the program will jump to if the condition is right\n0xd | Jump to EE if [ACC] = 0 | **Jump** to another line of code **if** the value of the ACC register is **zero** | instruction | Memory address of a instruction the program will jump to if the condition is right\n0xf | Jump to EE if [ACC] \u003c 0 | **Jump** to another line of code **if** the value of the ACC register is **negative** | instruction | Memory address of a instruction the program will jump to if the condition is right\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 🔀 Code Flow and Tips\nThis section will help you think more in an assembly way.\n\nBecause Open-Machine's Circuit only has very simple commands and very few registers, the way to think about your assembly code has to be very different.\n\n### Storage\nThe circuit has two components that store data: the ACC register and the memory RAM. Both of these are volatile memories, which means that when the circuit is turned the data lost. Let's take a closer look in the memories available and when they should be used:\n- **RAM**: is the main memory, it can store thousands of bits and every variable should be stored here.\n- **ACC register**: is an auxiliary memory for arithmetic operations that can store only one value. It must not store variables indefinitely. \n\n\tMost CPUs have many registers, so in those cases some registers can be used to store variables indefinitely. However, since Open-Computer's circuit only offers one register, it must be used exclusively as an auxiliary memory for the instructions.\n\n### Operation Flow\nSince the circuit has only one register, the flow of the operations will be a little bit different, following a pattern somewhat similar to:\n\n1. Change the value of ACC register\n2. Do an instruction\n3. Store the value of the ACC register in RAM\n\n**For example**, if you want to sum variables A and B and store the result in C you could use the following instructions:\n1. Copy the value of variable A to the ACC register\n2. Use the sum instruction to sum the value of ACC register with B and store the result in the ACC register\n3. Store the value of the ACC register in C memory address\n\n### IFs, WHILEs, FORs and procedures\nIf that's your first time programming assembly, it must be very strange to know that there are no ```if```s, ```while```s and ```for```s. However, it's not that hard not having those keywords, because all of those things can be done with the combination arithmetic operations and conditional and unconditional jumps.\n\nLet me show you an example. Imagine you have this code written in C and wanted to translate it to assembly.\n```c\n\t// before\n\tif (a \u003e b) {\n\t\t// ...\n\t}\n\t// after\n```\nOne way of doing it would be:\n1. **Copy** the value of ```a``` from RAM to the ACC register\n2. Update the value of the ACC register with the result of the ```subtraction``` between the value of the ACC register and ```b```\n3. **Jump** to **step 5** if the ACC register is greater than zero\n4. One or more instructions inside the ```if``` statement\n\t\n\t```c\n\t// ...\n\t```\n\n5. After instructions\n\n\t```c\n\t// after\n\t```\n\n### More tips\n- Remember to add the **kill** instruction at the **end of your program** to kill the execution\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# ⌨️ Machine Code Example\nThe following assembly code gets two numbers from input and outputs the sum of them. If the sum is greater than zero it will output zero.\n\n*ps: Remember to change the input before starting the clock simulation, because the ```input``` instruction doesn't wait for anything to happen to get the input data.*\n\n```sh\n# data inputs\n7055\n7056\n\n# sum\n1055\n3056\n2057\n\n# output\n8057\n\n# if output higher than zero, it will output zero\n1057\nd00b # if=0\nf00b # if\u003c0\n80ff # [0xff] is zero since we didn't change it\n\n9000\n```\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# ▶️ Run\nIn this section, you will see how to execute the circuit in the GUI.\n\nYou can watch [this video](https://www.youtube.com/watch?v=NAITQqdOw7c) as an introduction to Logisim-Evolution, which is the program we will be using to simulate the circuit.\n\n### I. Start the circuit\n1. Run the machine:\n\t```sh\n\tjava -jar logisim-evolution.jar\n\t```\n2. Import the circuit file by navigating the menu:\n   *```File -\u003e Open -\u003e Select main.circ from the repository folder```*\n3. Open Main file on the left side of Logisim\n\n### II. Program the circuit\n1. Right-click on the RAM component and select ```Edit Contents```\n2. Paste the machine code you wrote at the beginning of the RAM\n3. You may want to change some values of the memory as if you were initializing variables\n\n### III. Run the circuit\n3. Run the Program by navigating the menu: *```Simulate -\u003e Enable 'Ticks Enabled'```*\n   - You can change the speed of the program by navigating the menu: \n\t*```Simulate -\u003e Tick Frequency```*. ***To get the fastest execution, select the top item.***\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# ▶️ Test\nTo test the circuit, visit [README Test](test/README.md).\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 📄 Contributing Guidelines\nCheck out the contributing guidelines [here](https://github.com/Open-Machine/Circuits/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-machine%2Fcircuits","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-machine%2Fcircuits","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-machine%2Fcircuits/lists"}