From 4ea967c6089bbcaba5d71145546d288e186fba40 Mon Sep 17 00:00:00 2001
From: Melodi <62381002+Melodi17@users.noreply.github.com>
Date: Fri, 29 Aug 2025 07:54:56 +1000
Subject: added readme

---
 .DS_Store | Bin 10244 -> 10244 bytes
 README.md |  47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 README.md

diff --git a/.DS_Store b/.DS_Store
index 8a469c7..c144fc0 100644
Binary files a/.DS_Store and b/.DS_Store differ
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3832c04
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+# 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).
\ No newline at end of file
-- 
cgit v1.3.1