{"id":18478990,"url":"https://github.com/dfriend01/risc-assembler","last_synced_at":"2025-06-29T15:03:41.197Z","repository":{"id":167698881,"uuid":"443435027","full_name":"DFriend01/RISC-Assembler","owner":"DFriend01","description":"An assembler written in python for a customized assembly language","archived":false,"fork":false,"pushed_at":"2022-05-02T02:17:23.000Z","size":683,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-13T18:48:34.826Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/DFriend01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2021-12-31T22:33:22.000Z","updated_at":"2024-11-26T13:51:58.000Z","dependencies_parsed_at":"2023-06-26T00:01:58.828Z","dependency_job_id":null,"html_url":"https://github.com/DFriend01/RISC-Assembler","commit_stats":null,"previous_names":["dfriend01/risc-assembler"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DFriend01/RISC-Assembler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DFriend01%2FRISC-Assembler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DFriend01%2FRISC-Assembler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DFriend01%2FRISC-Assembler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DFriend01%2FRISC-Assembler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DFriend01","download_url":"https://codeload.github.com/DFriend01/RISC-Assembler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DFriend01%2FRISC-Assembler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262614458,"owners_count":23337277,"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":[],"created_at":"2024-11-06T12:12:58.581Z","updated_at":"2025-06-29T15:03:41.182Z","avatar_url":"https://github.com/DFriend01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RISC-Assembler\n\nThis is an assembler written in python that translates a custom assembly language into 32-bit binary instructions.\n\n## Instruction Set\n\nRefer to the [instruction set](https://github.com/DFriend01/RISC-Assembler/blob/main/docs/InstructionSet.pdf) to see which instructions are supported and how they function. Take a look at the [instruction encodings](https://github.com/DFriend01/RISC-Assembler/blob/main/docs/InstructionEncodings.pdf) to see how all the instructions are encoded into 32 bits.\n\n## Syntax Rules\n\n### Instructions\n- Instructions are **case insensitive** and indentation/extra spaces are ignored\n- Valid registers are denoted as R0 through R9 and SP (R0, R1, R2, ... R9, SP)\n- Literals cannot exceed 1 byte and must be expressed as hexadecimal values prefixed with `0x`\n  - Example: `0xCD`, `0xbd`, and `0x0056` are all acceptable, but not `0xDCEF` and `AA`\n- Instructions must be written on their own lines\n- Arguments are separated by spaces, and are **not** comma-separated\n- Comments can be denoted with a `#` either inline with an instruction or on its own line\n- All instructions must follow the instruction set\n\n### Constants\n- Names of constants cannot be keywords (register names or instruction names)\n- Constant names may not contain spaces and cannot start with a digit\n- Constant names are **case insensitive**\n- Constant values are 1-byte literals and can be declared by the following:\n  - `CONSTANT \u003cname\u003e \u003cliteral\u003e`\n  - Example: `CONSTANT foo 0xAB`\n- There cannot be duplicate constant names\n- If both a label and a constant share the same name, the constant will always take precedence over the label\n\n### Labels\n- Names of labels cannot be keywords (register names or instruction names)\n- Label names may not contain spaces and cannot start with a digit\n- Label names are **case insensitive**\n- Labels may be declared either on its own line or inline with an instruction, and are declared like the following:\n  - `\u003cname\u003e: \u003coptional instruction\u003e`\n  - Example: `bar: mov r1 0x0`\n  - Notice how the `:` is not separated by a space from the label name\n- Labels may only be used by jump instructions and the `CALL` instruction.\n\nA violation of any of the above will result in a syntax error and compilation will fail.\n\n## Example Program\n\n```\n# This is an example program\n\nCONSTANT foo 0x1\nconstant bar 0x2\n\nMOV R1 foo         # Move 1 into register R1\nmov r2 bar         # Move 2 into register R2\n\n# Labelling\nsubroutine: CMP r1 r2\n\n            MOVL R3 0x00AA\n            MOVE R3 0x0\n            MOVG R3 0xab\n\nsillylabel:\n\n            jmp subroutine\n\n```\n\n## Usage\n\n### Execution\n```\nUsage: python3 assemble.py -i [INPUT PATH] -o [OUTPUT PATH] [OPTIONS]\nExample: python3 assemble.py -i foo/input.txt -o bar/output.txt -s -b\n```\n- Compiles an assembly file formatted as a **text file (.txt)**\n- The input assembly file must exist and must be a text file\n- The output path does not necessarily need to already exist, but needs to be a path to a text file\n\n### Options\n```\n-s        If output file already exists, do not overwrite it\n-b        Output binary instruction encodings. By default,\n            instruction encodings are in hexadecimal\n--help    Display this message\n```\n\n## Setup\n\n### Step 1: Set up the virtual environment (optional)\nA virtual environment is optional, but highly recommended. Refer to the [python docs](https://docs.python.org/3/tutorial/venv.html) if you are\nunfamiliar with virtual environments. Execute the following **in the project\nroot directory**:\n\n```\n# Install virtualenv globally if not already installed\npython3 -m pip install virtualenv\n\n# Create the virtual environment\npython3 -m venv env\n\n# Activate the virtual environment\nenv/Scripts/activate (Windows)\nsource env/bin/activate (Unix)\n```\n\n### Step 2: Install the RISCAssembler package\nIf you are using a virtual environment, activate it first. Then, execute\n`pip install -e .`. **Make sure you are in the project root directory when\nrunning this command**.\n\n## Running the Tests\nTo run all of the tests at once, execute `python3 -m unittest discover -s test -p '*_test.py'`. Alternatively, one can go into the `test` directory and\nrun the specific test file directly.\n\n## TODO\n\n### Minimum Requirements\n- [x] Convert instructions to their corresponding encoding\n- [x] Throw an error for invalid instructions\n- [x] Allow for comments\n- [x] Instruction encodings are printed to a text file on its own line\n\n### Additional Features\n- [x] Declaring constants\n- [x] Support literal labels for subroutines\n- [ ] Support pipelining instructions by stalling the processor for causal dependencies\n- [x] Support using a stack pointer register\n- [x] Provide error description for syntax errors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfriend01%2Frisc-assembler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdfriend01%2Frisc-assembler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdfriend01%2Frisc-assembler/lists"}