{"id":19849438,"url":"https://github.com/open-machine/assembler","last_synced_at":"2025-02-28T20:42:14.798Z","repository":{"id":48081692,"uuid":"289991425","full_name":"Open-Machine/Assembler","owner":"Open-Machine","description":"A program that transforms assembly code into machine code.","archived":false,"fork":false,"pushed_at":"2022-01-19T04:53:11.000Z","size":27681,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"stable","last_synced_at":"2025-01-11T12:48:58.030Z","etag":null,"topics":["assembler","assembly","machine-code"],"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:15:16.000Z","updated_at":"2021-08-08T05:10:04.000Z","dependencies_parsed_at":"2022-08-12T18:10:49.482Z","dependency_job_id":null,"html_url":"https://github.com/Open-Machine/Assembler","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FAssembler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FAssembler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FAssembler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Machine%2FAssembler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Machine","download_url":"https://codeload.github.com/Open-Machine/Assembler/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241228921,"owners_count":19930698,"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":["assembler","assembly","machine-code"],"created_at":"2024-11-12T13:20:49.157Z","updated_at":"2025-02-28T20:42:14.767Z","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 Assembler\u003c/h1\u003e\n\u003ch4\u003eCLI app that reads Assembly code and generates Machine Code for Open-Machine's Circuit.\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\u003cb\u003e⚠️ It relies heavily on the \u003ca href=\"https://github.com/Open-Machine/Circuits\"\u003eCircuits\u003c/a\u003e repository and it will not run unless both are in the same folder with the repository names unchanged.\u003c/b\u003e\n\n\u003ca href=\"https://github.com/Open-Machine/Assembler/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/Open-Machine/Assembler\" alt=\"Stars Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/Open-Machine/Assembler\" alt=\"Forks Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-0.0.1-blue\" alt=\"Version Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://coveralls.io/github/Open-Machine/Assembler\"\u003e\u003cimg src=\"https://img.shields.io/coveralls/github/Open-Machine/Assembler\" alt=\"coverage\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/commits/\"\u003e\u003cimg src=\"https://img.shields.io/github/commit-activity/m/Open-Machine/Assembler\" alt=\"commits\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/pulls\"\u003e\u003cimg src=\"https://img.shields.io/github/issues-pr/Open-Machine/Assembler\" alt=\"Pull Requests Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/Open-Machine/Assembler\" alt=\"Issues Badge\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Open-Machine/Assembler/graphs/contributors\"\u003e\u003cimg alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/Open-Machine/Assembler?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/Assembler?color=2b9347\" alt=\"License Badge\"/\u003e\u003c/a\u003e\n\n\u003cbr/\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\n##### *Introduction*\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;1. [📌 Definition and Explanation](#-definition-and-explanation)\n\n##### *Code*\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;2. [🔢 Instructions](#-instructions)\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;3. [🔀 Code Flow and Tips](#-code-flow-and-tips)\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;4. [🔡 Code syntax](#-code-syntax)\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;5. [⌨️ Code Example](#-code-example)\n\n##### *Run*\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;6. [:arrow_forward: Setup and Run](#arrow_forward-setup-and-run)\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;7. [💻 Assembler CLI](#-assembler-cli)\n\n##### *More*\n### \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;9. [📄 Contributing Guidelines](#-contributing-guidelines)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 📌 Definition and Explanation\nAssembly is basically the most basic programming language of a certain hardware. There's a very strong correspondence between the instructions in the language and the architecture's machine code instructions: every instruction in the language is a machine code instruction and vice-versa. It was created so that humans don't had to memorize the machine code instructions which are many numbers.\n\nFrom the Wikipedia:\n\u003e In computer programming, assembly language, often abbreviated asm, is any low-level programming language in which there is a very strong correspondence between the instructions in the language and the architecture's machine code instructions.\n\nBecause of this strong correspondence, the translating process is called assembling instead of compiling, which is the same process but for high-end languages. Those languages do not have this strong correspondence that assembly languages have.\n\nThe core of the assembling process is to identify the assembly instructions and translate them to the circuit's instruction binary equivalent. Similarly, it also has to convert each variable to a memory address.\n\n## Learn more\n\nIf you are interested in knowing more **how this process works** don't be afraid to read at the code.\n\nIf you are interested in knowing more **about the actual circuit** that runs the code you write, click [here](https://github.com/Open-Machine/Circuits/).\n\nIf you are interested in knowing more **about the Open-Computer project**, click [here](https://github.com/Open-Machine/README/).\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 🔢 Instructions\nLet's take a close look at the instructions available. **Don't worry about syntax right now, we will talk about it later.**\n\n**Warning** ⚠️: If you have never programmed in an assembly language (or with this assembly), please read this section and [🔀 Code Flow and Tips](#-code-flow-and-tips) in parallel. The *Code Flow and Tips* section will help you understand what to make with the instructions.\n\n### Symbols Legend\nSome symbols are used in the Instructions Table. Here you can see their meaning.\nSymbol | Explanation\n--- | ---\nACC | The ACC register\nvariable | A variable from the memory\nlabel | Jump label\n[ ] | \"Value of\"\n```${memAddr}``` | Memory address parameter\n```${jumpTo}``` | Instruction index or jump label parameter\n\n### Instructions Table\nAssembly Command | Short Instruction Description | Long Instruction Description | Short Param Description | Long Param Description\n--- | --- | --- | --- | ---\n```nop``` | - | This instruction doesn't perform any action | - | No parameter is required\n```copy ${memAddr}``` | [ACC] = [variable] | A value from the memory is copied to the ACC register | variable | It's the name of the variable that will be used in the instruction\n```store ${memAddr}``` | [variable] = [ACC] | The value from the ACC register is stored into memory | variable | It's the name of the variable that will be used in the instruction\n```add ${memAddr}``` | [ACC] = [ACC] + [variable] | The sum of the value of the ACC register and a value from the memory is stored in the ACC register | variable | It's the name of the variable that will be used in the instruction\n```sub ${memAddr}``` | [ACC] = [ACC] - [variable] | The difference between the value of the ACC register and a value from the memory is stored in the ACC register | variable | It's the name of the variable that will be used in the instruction\n```input ${memAddr}``` | [variable] = input value | The input value is copied to the memory | variable | It's the name of the variable that will be used in the instruction\n```output ${memAddr}``` | Output [variable] | Outputs a value from the memory into the circuit LEDs | variable | It's the name of the variable that will be used in the instruction\n```kill``` | Finishes program | When this instruction is encountered, the program is finished and no more instructions will be executed | - | No parameter is required\n```jmp ${jumpTo}``` | Jump to EE | Jump to another line of code | label | The jump label the program will jump to\n```jg ${jumpTo}``` | Jump to EE if [ACC] \u003e 0 | Jump to another line of code if the value of the ACC register is positive | label | The jump label the program will jump to if the condition is right\n```je ${jumpTo}``` | Jump to EE if [ACC] = 0 | Jump to another line of code if the value of the ACC register is zero | label | The jump label the program will jump to if the condition is right\n```jl ${jumpTo}``` | Jump to EE if [ACC] \u003c 0 | Jump to another line of code if the value of the ACC register is negative | label | The jump label 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 will be very different.\n\n### [Click here](https://github.com/Open-Machine/Circuits/#-code-flow-and-tips) to go the section!\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 🔡 Code Syntax\n**Warning** ⚠️: Assembly languages are specific to their hardware so remember that Open-Computer's Assembly may be different from other assembly languages.\n\nRead the specifications below to learn the code syntax.\n\n## Tabs, spaces and case sensitivity\n- Case sensitive;\n- **Tabs and spaces** can be used interchangeably;\n- Blank or empty lines won't be considered;\n- **Numbers** can be written in hexadecimal in the form of ```0xff``` or in decimal as ```255```;\n\n## Naming Practices\n- A **label name** should start with a letter and the rest of the name can have more letters and numbers;\n- Every name should obey the following regex: ```[a-z][a-zA-Z0-9]*```;\n- Snake-case is not allowed and the use of camel-case is encouraged.\n\n## Jump Label\n- Definition: it marks the line for possible jumps to that line;\n- Form: ```{labelName}:```\n- Remember to follow the [naming practices](#naming-practices)\n\n## Instruction line\n\n***Definition***\n\nAn instruction line is a line that contains an instruction call.\n\n***Components***\n- ```instruction``` is the actual instruction that will be executed, it must be one of the following in the instruction table;\n- ```arg``` can be a jump label or a number (depending on the instruction)\n\n***Form***\n- A instruction line should be in the following form ```{instruction} [arg]```;\n- An instruction line should obey the following regex: ```^[\\t ]*(((nop)|(copy)|(store)|(add)|(sub)|(input)|(output)|(kill)|(jmp)|(jg)|(je)|(jl))(([\\t ]+[a-z][a-zA-Z0-9]*)|()))[\\t ]*$```\n\n***Instructions List***\n\nCheck out [here](#-instructions) the instruction table to know what instructions you can use and their parameters.\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# ⌨️ 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: Since the ```input``` instruction doesn't wait for a change, expect the output to be zero.*\n```sh\n# data inputs\ninput 0x55\ninput 0x56\n\n# sum\ncopy 0x55\nadd 0x56\nstore 0x57\n\n# output\noutput 0x57\n\n# if output higher than zero, it will output zero\ncopy 0x57\nje finish # if\njl finish # if\noutput 0xff # [0xff] = 0 since we didn't change it\n\nfinish:\n\nkill\n```\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# :arrow_forward: Setup and Run\nThese are the steps to setup and run Open-Computer's Assembler.\n\nYou can find more information about the assembler CLI [here](#-assembler-cli) and about running the circuit [here](https://github.com/Open-Machine/Circuits/#️-run).\n\n## Setup\n1. Build the GoLang project\n\t```sh\n\t./setup.sh\n\t```\n2. Clone [Open-Computer's Circuit Repository](https://github.com/Open-Machine/Circuits/)\n\n\tYou will need this repository to run the assembled program.\n\n\tIf you have git installed in your terminal, run:\n\t```sh\n\tgit clone https://github.com/Open-Machine/Circuits/\n\t```\n\n## Assemble\nAssemble your code\n```sh\n./assembler assemble ${main.asm}\n```\n\n## Run\nThere are two ways of running your application from the machine code generated by the ```assemble``` command.\n\n### GUI Mode\nIn this mode, you will be able to see everything that is happening to the circuits in real time and interact with it by changing the inputs.\n\nYou can watch [this video](https://www.youtube.com/watch?v=NAITQqdOw7c) as an introduction to Logisim-Evolution, which is the program that we will be using to simulate the circuit.\n\n1. Navigate to the Circuits repository\n2. Start the circuit: follow the steps \u003ca href=\"https://github.com/Open-Machine/Circuits/#i-start-the-circuit\"\u003eto Start the Circuit\u003c/a\u003e\n3. Right click in the RAM and click \"Load Image\"\n4. Select the assembled file\n\n   You should select the file generated by the assemble program, not the file with the assembly code.\n\n5. To run the program (start the clock simulation), follow the steps \u003ca href=\"https://github.com/Open-Machine/Circuits/#iii-run-the-circuit\"\u003eto Run the Circuit\u003c/a\u003e\n\n\n### CLI Mode\nIn this mode, you will only be able to see the outputs of your application. You just have to run:\n```sh\njava -jar logisim-evolution.jar main.circ -load ${assembled_file} -tty table\n```\n*Remember to write the name of the file that was generated by the assembler command instead of ```${assembled_file}```*.\n\n#### About the outputs\n\nThe outputs will appear on the console following this pattern: ```{16 bits of the main output}     {4 bit ouptut counter}```.\n\nThe first output can be ignored.\n\n## Test\n```sh\ngo test ./...\ncd go_scripts/format_circuit_output\ngo test ./...\n```\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n# 💻 Assembler CLI\nYou can use the flag ```--help``` to see all the options.\n\n### Assemble\n```sh\n./assembler assemble --help\n```\n```\nusage: assembler assemble [\u003cflags\u003e] \u003cfile-name\u003e\n\nAssemble assembly code\n\nFlags:\n      --help            Show context-sensitive help (also try --help-long and\n                        --help-man).\n  -r, --rename-exec=\"\"  Provide the name of the executable file that will be created\n                        (if empty, the name will be the same as the assembly code\n                        file)\n\nArgs:\n  \u003cfile-name\u003e  Provide the name of file with the assembly code\n```\n\n### Syntax\n```sh\n./assembler syntax --help\n```\n```\nusage: assembler syntax [\u003cflags\u003e]\n\nHelp with the syntax of this assembly language\n\nFlags:\n      --help                     Show context-sensitive help (also try --help-long\n                                 and --help-man).\n  -e, --example                  Assembly code example with explanation\n  -l, --ls                       List all available instructions\n  -c, --instruction=INSTRUCTION  Explanation of an specific instruction\n```\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/Assembler/blob/stable/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-machine%2Fassembler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-machine%2Fassembler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-machine%2Fassembler/lists"}