Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/p4ul-m/copper

Copper is a assembly interpreter.
https://github.com/p4ul-m/copper

assembly command-line-tool interpreter language rust

Last synced: 4 days ago
JSON representation

Copper is a assembly interpreter.

Host: GitHub
URL: https://github.com/p4ul-m/copper
Owner: P4UL-M
Created: 2023-11-22T06:48:56.000Z (about 1 year ago)
Default Branch: master
Last Pushed: 2024-11-22T21:50:36.000Z (2 months ago)
Last Synced: 2024-12-07T03:31:17.635Z (2 months ago)
Topics: assembly, command-line-tool, interpreter, language, rust
Language: Rust
Homepage:
Size: 57.6 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# Copper

## Table of Content
- [What is Copper ?](#what-is-copper)
- [How to use ?](#how-to-use)
- [Instructions](#instruction-sets)

## What is Copper ?

Copper is a assembly interpreter. It It was created for educational purposes. It is a simple language with basic operations. It is a 32-bit architecture with 4 registers. It has a stack and 1024 addressable memory positions of 32 bits. It has a simple syntax and a simple instruction set making it easy to learn and use to get introduced to assembly.

## How to install ?

### Prerequisites

- [Rust](https://www.rust-lang.org/tools/install)
- [Git](https://git-scm.com/downloads)

### Install

```bash
git clone https://github.com/P4UL-M/Copper.git
cd Copper
cargo build
```

### Add to PATH

#### Windows

```plaintext
$env:Path += ";$pwd\target\debug"
```

#### Linux

```plaintext
export PATH="$PATH:$pwd/target/debug"
```

#### MacOS

```plaintext
export PATH="$PATH:$pwd/target/debug"
```

## How to test ?

```plaintext
cargo run \
```

## How to Use ?

To utilize Copper, follow the command line syntax and available options.

### Command Line Syntax:

```plaintext
copper
```

**Options:**
- **-h**, **--help**: Print this help message.
- **-V**, **--version**: Print version information.
- **-v**, **--verbose**: Enable verbose mode.
- **-d**, **--debug**: Enable debug mode.

**Commands:**

**Run Program:**
```plaintext
copper run
```
Execute the Copper program specified by .

**Export Program:**
```plaintext
copper export []
```
Export the Copper program to a binary file. Optionally, you can specify an output file name. If no output file is provided, the default name is used.

**Examples:**

Run a Copper program:
```plaintext
copper program.co
```

Run a Copper program with verbose output:
```plaintext
copper -v run program.co
```

Export a Copper program to the default binary file:
```plaintext
copper export program.co
```

Export a Copper program to a specific binary file:
```plaintext
copper export program.co program.bin
```

## Instruction sets

Refer to the instruction sets below to find the specific functionalities and syntax of Copper.

### LDA \ \/\/\ - `0b00000` *Load register reg1 with the contents of either the contents of reg2, or the memory var or a constant const. Memory regions loads (load into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### STR \\/\ - `0b00001` *Store in the memory position referred by var the value of register reg or a constant const. Register stores (store into register t0, for instance) are NOT ALLOWED.* - 5 bits for instruction - 10 bits for the address of the variable - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the constant or the address of the register *No store from variable to variable allowed*

### PUSH \/\/\ - `0b00010` *Push to the top of the stack the contents of reg or var or a constant const.* - 5 bits for instruction - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### POP \ - `0b00011`
*Pop from the top of the stack and store the value on reg. Storing in a memory region is NOT ALLOWED.*
- 5 bits for instruction
- 12 bits for parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the second register

### AND \ \/\/\ - `0b00100` *Performs a logical AND operation between reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### OR \ \/\/\ - `0b00101` *Performs a logical OR operation between reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### NOT \ - `0b00110`
*Performs a logical NOT operation on register reg and store the result on register reg. Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.*
- 5 bits for instruction
- 2 bits for the address of the register

### ADD \ \/\/\ - `0b00111` *Performs the addition operation of reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### SUB \ \/\/\ - `0b01000` *Performs the subtraction operation of reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. The operation is given by second argument minus the first argument (i.e., reg2 – reg1). Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### DIV \ \/\/\ - `0b01001` *Performs the integer division operation of reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. The operation is given by second argument divided by the first argument (i.e., reg2 / reg1). Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### MUL \ \/\/\ - `0b01010` *Performs the integer multiplication operation of reg1 and a register reg2, a variable var or a constant const, and store the result on register reg1. Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### MOD \ \/\/\ - `0b01011` *Performs the integer modulo operation of reg1 and a register reg2, a variable var or a constant cont, and store the result on register reg1. The operation is given by second argument modulo the first argument (i.e., reg2 mod reg1). Memory regions stores (store result into a variable, for instance) are NOT ALLOWED.* - 5 bits for instruction - 2 bits for the address of the register - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the second register

### INC \ - `0b01100`
*Increments the value of a register reg. Memory increments (incrementing a variable, for instance) are NOT ALLOWED.*
- 5 bits for instruction
- 2 bits for the address of the register

### DEC \ - `0b01101`
*Decrements the value of a register reg. Memory increments (decrementing a variable, for instance) are NOT ALLOWED.*
- 5 bits for instruction
- 2 bits for the address of the register

### BEQ \/\/\ \/\/\ \ - `0b01110`
*Performs a comparison between two values, given by registers, variables or constants. Any combination is permitted. If they are equal, jump to the address defined by the label LABEL.*
- 5 bits for instruction
- 12 bits for parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the register
- 12 bits for second parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the second register
- 3 bits for the address of the jump

### BNE \/\/\ \/\/\ \ - `0b01111`
*Performs a comparison between two values, given by registers, variables or constants. Any combination is permitted. If they are different, jump to the address defined by the label LABEL.*
- 5 bits for instruction
- 12 bits for parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the register
- 12 bits for second parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the second register
- 3 bits for the address of the jump

### BBG \/\/\ \/\/\ \ - `0b10000`
Performs a comparison between two values, given by registers, variables or constants. Any combination is permitted. If the first parameter is bigger than the second parameter, jump to the address defined by the label LABEL.
- 5 bits for instruction
- 12 bits for parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the register
- 12 bits for second parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the second register
- 3 bits for the address of the jump

### BSM \/\/\ \/\/\ \ - `0b10001`
*Performs a comparison between two values, given by registers, variables or constants. Any combination is permitted. If the first parameter is smaller than the second parameter, jump to the address defined by the label LABEL.*
- 5 bits for instruction
- 12 bits for parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the register
- 12 bits for second parameter
- 2 bits for type of the parameter
- 10 bits for the address in the memory, the constant or the address of the second register
- 3 bits for the address of the jump

### JMP \ - `0b10010`
*Jump to the address defined by the label LABEL.*
- 5 bits for instruction
- 3 bits for the address of the jump

### SRL \ \ - `0b10011`
*This operation takes the value in reg and performs a logical shift left of the number of bits defined by the constant const. For instance, the value 0001 left shifted 1 time becomes.*
- 5 bits for instruction
- 2 bits for the address of the register
- 10 bits for the constant

### SRR \ \ - `0b10100`
*This operation takes the value in reg and performs a logical shift right of the number of bits defined by the constant const. For instance, the value 1000 right shifted 1 time becomes.*
- 5 bits for instruction
- 2 bits for the address of the register
- 10 bits for the constant

### HLT - `0b10101`
*End the program execution.*
- 5 bits for instruction

### IN \/\- `0b10110` *This operation take a value of the input stream and assign it to the parameter.* - 5 bits for instruction - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the register

### OUT \/\/\ - `0b10111` *This operation take the value from the parameter such as a constant, a variable or a register and write it in the output stream.* - 5 bits for instruction - 12 bits for parameter - 2 bits for type of the parameter - 10 bits for the address in the memory, the constant or the address of the register

### \: - `0b11110`
*This operation mark the destination of a jump or a conditional jump.*
- 5 bits for instruction
- 3 bits for label name

## Others

### #Category - `0b11111`
- 5 bits for instruction
- 2 bits for category name

### Variable definition
- 1 bits for data type
- 10 bits for variable name
- 10 bits for constant data

### Array definition
- 1 bits for data type
- 10 bits for array name
- 10 bits for array size
- 10 bits for constant data