# Q1 Toolkit
This project aims at providing a compliant toolkit for the theoretical Q1 processor. It features a:
 - Emulator
 - Assembler
 - C Compiler
 - Bus Layout Visualiser

Please refer to the actual [specsheet](https://docs.google.com/document/d/16XX8O_AFQsY8GBgKwSpZ3ZxaH_3T_BIIMt0etGgCU_4/edit?usp=sharing) for the specifications of the Q1.

> Note: This project is actually responsible for the design of the Q1 processor, so changes may occur in the future to the specifications.

## The Emulator
Using the emulator is straightforward. It takes a binary file as input and runs it:
```bash
$ emulator -i binary.q1
```

## The Assembler
The assembler takes an assembly source file as input and produces a binary output file:
```bash
$ assembler -i source.asm -o output.q1
```

## The C Compiler
The C compiler takes a C source file as input and produces an assembly output file:
```bash
$ compiler -i source.c -o output.asm
```
Please note that the compiler is not fully compliant with the C standard. It supports a limited subset of C, including most of the basic features, but does not support all macros, global variables or complex data structures.
Numerics such as `int` and `char` do not support negative values, and floating point numbers are not supported at all.
Using the `-c` flag, the compiler can be set to different comment modes:
- `none`: No comments are added to the output assembly
- `userdefined` (default): Comments are added to the output assembly for user-defined comments (one-liners starting with `//`)
- `generated`: Only comments generated by the compiler itself are added to the output assembly, these are useful for seeing how the compiler translated certain constructs.
- `all`: All comments are added to the output assembly, including those generated by the compiler itself.
The verbose flag `-v` will make the compiler output the generated assembly to the console as well as to the output file.

## The Orchestrator
The orchestrator is a tool designed for performing a full compilation, assembly and emulation cycle on a C source file. It is used as follows:
```bash
$ orchestrator -i source.c
```
Various parts of the process can be disabled using flags:
 - `--no-compile`: Skip the compilation step
 - `--no-assemble`: Skip the assembly step
 - `--no-emulate`: Skip the emulation step
Other step-specific flags can be passed as used in the individual tools. (e.g `-c all` for the compiler comment mode).