https://github.com/danielbrodi/lowlevelassembler
Program in C designed to act as an assembler, converting assembly commands into binary code with efficient preprocessing, label checking, parsing, and file management. Ensures correct conversion with strict error handling and optimal memory management practices, making it act like an ideal assembler for low-level programming tasks.
https://github.com/danielbrodi/lowlevelassembler
assembler assembly assembly-language assembly-language-programming binary binary-code binary-conversion binary-converter c c-programming compiler compiler-construction compiler-design compilers low-level low-level-design low-level-memory-manipulation low-level-programming memory-leak memory-management
Last synced: 2 months ago
JSON representation
Program in C designed to act as an assembler, converting assembly commands into binary code with efficient preprocessing, label checking, parsing, and file management. Ensures correct conversion with strict error handling and optimal memory management practices, making it act like an ideal assembler for low-level programming tasks.
- Host: GitHub
- URL: https://github.com/danielbrodi/lowlevelassembler
- Owner: danielbrodi
- License: mit
- Created: 2024-06-21T11:13:37.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2024-12-14T17:39:52.000Z (5 months ago)
- Last Synced: 2025-03-15T05:14:40.671Z (2 months ago)
- Topics: assembler, assembly, assembly-language, assembly-language-programming, binary, binary-code, binary-conversion, binary-converter, c, c-programming, compiler, compiler-construction, compiler-design, compilers, low-level, low-level-design, low-level-memory-manipulation, low-level-programming, memory-leak, memory-management
- Language: C
- Homepage:
- Size: 484 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Low Level Assembler [](#) [](#)
## Overview
The **Low Level Assembler** is a program designed to act as an assembler, converting assembly commands into their binary counterparts.
The conversion process involves multiple stages to ensure accurate and reliable assembly-to-binary transformation.
This assembler handles preprocessing, label checking, parsing, and file writing, producing multiple output files to give a detailed view of the assembly-to-binary conversion process.
## Features
- **Preprocessing**: Reads and expands macros.
- **Label Checking**: Validates labels for any discrepancies.
- **Parsing**: Analyzes and validates the syntax.
- **File Generation**: Produces a processed file (*.am), entry labels file (*.ent), extern labels file (*.ext), and a binary code file (*.ob).
- **Error Handling**: Strong focus on error handling to ensure accurate conversions.
- **Memory Management**: Ensures all allocated memory is appropriately freed after use.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Files](#files)
- [Contributing](#contributing)
- [License](#license)
## Installation
To use the assembler, clone the repository and compile the source code:
```bash
git clone https://github.com/danielbrodi/LowLevelAssembler.git
cd LowLevelAssembler
make
```
## Usage
To run the assembler, use the following command:
```bash
./assembler ...
```
Each should be an assembly file you wish to process.
The program will generate corresponding output files with the following extensions:
- *.am* for the processed file.
- *.ent* for the entry labels file.
- *.ext* for the extern labels file.
- *.ob* for the binary code file.
#### Run the Command
```bash
./assembler tests/example.asm
```
This command will process **example.asm** located in the **tests** directory and generate **example.am**, **example.ent**, **example.ext**, and **example.ob** files.
## Flow Example
### Input File: `example.as`
The sample example file for running can be found in the [**tests**](./tests) directory, among other test files that you can run.
```assembly
.entry LENGTH
.extern W
MAIN: mov @r3, LENGTH
LOOP: jmp L1
prn -5
bne W
sub @r1, @r4
bne L3
L1: inc K
.entry LOOP
jmp W
END: stop
STR: .string "abcdef"
LENGTH: .data 6, -9, 15
K: .data 22
.extern L3
```
### Processing Steps
#### Step 1: Macro Expansion
```assembly
.entry LENGTH
.extern W
MAIN: mov @r3, LENGTH
LOOP: jmp L1
prn -5
bne W
sub @r1, @r4
bne L3
L1: inc K
.entry LOOP
jmp W
END: stop
STR: .string "abcdef"
LENGTH: .data 6, -9, 15
K: .data 22
.extern L3
```
#### Step 2: Label Checking
The assembler checks for any discrepancies or errors in the labels, such as undefined labels or duplicate definitions. In this example, no discrepancies were found.
#### Step 3: Parsing and Binary Code Generation
**Binary Machine Code**
| Address | Source Code | Binary Code |
|---------|---------------------------|---------------------|
| 0100 | MAIN: mov @r3, LENGTH | 101000001100 |
| | | 000110000000 |
| | | 000111110110 |
| 0103 | LOOP: jmp L1 | 000100101100 |
| | | 000111000110 |
| 0105 | prn -5 | 000110000100 |
| | | 111111101100 |
| 0107 | bne W | 000101001100 |
| | | 000000000001 |
| 0109 | sub @r1, @r4 | 101001110100 |
| | | 000010010000 |
| 0111 | bne L3 | 000101001100 |
| | | 000000000001 |
| 0113 | L1: inc K | 000011101100 |
| | | 001000000010 |
| 0115 | jmp W | 000100101100 |
| | | 000000000001 |
| 0117 | END: stop | 000111100000 |
| 0120 | STR: .string "abcdef" | 000001100001 |
| | | 000001100010 |
| | | 000001100011 |
| | | 000001100100 |
| | | 000001100101 |
| | | 000001100110 |
| | | 000000000000 |
| 0125 | LENGTH: .data 6, -9, 15 | 000000000110 |
| | | 111111110111 |
| | | 000000001111 |
| 0128 | K: .data 22 | 000000010110 |
#### Step 4: Writing Output Files
**example.ob**
Binary machine code output file containing the compiled instructions in base64 format.
```
18 11
oM
GA
H2
Es
HG
GE
/s
FM
AB
p0
CQ
FM
AB
Ds
IC
Es
AB
Hg
Bh
Bi
```
**example.ent**
Entry labels output file listing symbols marked as entry points with their corresponding addresses.
Listed in decimal (base 10) format.
```
LOOP 103
LENGTH 125
```
**example.ext**
External labels output file listing symbols referenced but not defined within the program.
Listed in decimal (base 10) format.
```
W 108
L3 112
W 116
```
> Note: If there are no external labels, the `.ext` file will not be created. Similarly, if there are no entry labels, the `.ent` file will not be created.
## Files
### Source Files
- **assembler.c**: Main file containing the program's entry point and core logic.
- **preprocessor.c**: Handles macro expansion.
- **label_checker.c**: Validates labels.
- **parser.c**: Parses and validates the syntax.
- **file_writer.c**: Writes the output files.
### Output Files
- **.am**: Processed file after macro expansion.
- **.ent**: File containing entry labels.
- **.ext**: File containing external labels.
- **.ob**: Binary code file, converted to base64.
## Contributing
Contributions are welcome!
Please fork the repository and create a pull request with your changes.
1. Fork the repository.
2. Create a new branch (`git checkout -b add-feature-branch`).
3. Commit your changes (`git commit -am 'Add new feature'`).
4. Push to the branch (`git push origin add-feature-branch`).
5. Create a new Pull Request.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Additional Information
For more detailed information about the program's workflow, refer to the comments in the [assembler.c](assembler.c) file.
### Main Method Workflow
```c
/**
* Serves as the program's entry point. The flow of the program includes:
* 1. Initiation of the program state. The assumption of the program is that the starting memory block is
* located at address '100'.
* 2. Reading files and appending appropriate extensions(.am, .ext, .ent, .ob).
* 3. Preprocessing: reading and expanding macros.
* 4. Checking labels for any discrepancies.
* 5. Parsing files to understand and validate the syntax.
* 6. Writing all labels, both entry & external to separated files(.ext, .ent).
* 7. Conversion from binary to base64 and save in a file (.ob).
* Note: If any of the stages encounters an error or fails, the program will not produce a base64 *.ob file.
* 8. Finally, freeing the program state after processing.
*/
```
## Contact
For any questions or feedback, feel free to open an issue or contact me:
- **Daniel Brodsky** - [Linkedin](https://www.linkedin.com/in/daniel-brod/)
### Special thanks to Lior Katav for writing this software with me.