Merge pull request #41 from cs-pub-ro/didactic-assembler

Didactic assembler

.devcontainer/open-toolchain/open.Dockerfile

@@ -41,6 +41,10 @@ RUN apt-get install -y iverilog yosys verilator gtkwave
 RUN apt-get install -y python3 python3-pip && \
     pip3 install Pygments
 
+# install rust for didactic assembler
+RUN curl https://sh.rustup.rs -sSf | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
 # install java and graphviz
 # RUN apt-get install -y openjdk-19-jre graphviz
 

.devcontainer/rust.vivado.Dockerfile

@@ -0,0 +1,6 @@
+# Thin wrapper used for adding the rust toolchain
+FROM gitlab.cs.pub.ro:5050/ac/ac-public/vivado-slim:1.0.0
+
+# install rust for didactic assembler
+RUN curl https://sh.rustup.rs -sSf | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"

.devcontainer/ubuntu/devcontainer.json

@@ -1,6 +1,9 @@
 {
 	"name": "Vivado Slim Dev ubuntu/linux",
-	"image": "gitlab.cs.pub.ro:5050/ac/ac-public/vivado-slim:1.0.0",
+	// "image": "gitlab.cs.pub.ro:5050/ac/ac-public/vivado-slim:1.0.0",
+	"build": {
+		"dockerfile": "../rust.vivado.Dockerfile"
+	},
 	"runArgs": [
 		"--rm",
 		"--privileged"

.devcontainer/windows/devcontainer.json

@@ -1,6 +1,9 @@
 {
 	"name": "Vivado Slim Dev Windows",
-	"image": "gitlab.cs.pub.ro:5050/ac/ac-public/vivado-slim:1.0.0",
+	// "image": "gitlab.cs.pub.ro:5050/ac/ac-public/vivado-slim:1.0.0",
+	"build": {
+		"dockerfile": "../rust.vivado.Dockerfile",
+	},
 	"runArgs": [
 		"--rm",
 		"--privileged"

.devcontainer/x11-linux-generic/Dockerfile

@@ -34,6 +34,10 @@ COPY ./entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 RUN echo "cd /workspaces/computer-architecture" >> /root/.bashrc
 
+# install rust for didactic assembler
+RUN curl https://sh.rustup.rs -sSf | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
 WORKDIR /workspaces/computer-architecture
 # uncomment if vivado shows blank screen
 # RUN echo "export _JAVA_AWT_WM_NONREPARENTING=1" >> /root/.bashrc

didasm/.gitignore

@@ -0,0 +1 @@
+/target

didasm/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "didasm"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+bitfield = "0.17.0"
+once_cell = "1.20.2"
+regex = "1.11.1"
+strum = "0.26.3"
+strum_macros = "0.26.4"

didasm/Makefile

@@ -0,0 +1,5 @@
+install:
+	cargo install --path .
+
+clean:
+	cargo clean

didasm/Readme.md

@@ -0,0 +1,37 @@
+# Didactic assembler 0.1
+To install, just do ```make install``` while inside the dockerfile.
+
+## Usage
+```didasm <input-file> <output-file>```
+
+This will output hex representation of the instructions
+The representation is reversed, because when parsing the ram has the word order ```[15:0]``` instead of ```[0:15]``` like it is usually done in the classroom while decoding.
+For a clearer view of the instruction grouping in the right order, pass ```--beautiful``` as an optional command line argument (it has to be the 3rd argument specifically).
+If by contrast the 3rd argument is ```--quiet```, the only thing that will be outputed is the binary.
+By default if no option is passed, only the original code is commented above the hex value it represents
+
+Supports all instructions from the [ISA description document](../chapters/microprogramable_cpu/control-unit/reading/Biblia.pdf), but does not fully support all the different syntaxes for memory addressing.
+Currently the differences consist in small tweaks such as the impossibility of distinguishing between an immediate value and a displacement in memory (depls), so the direct addressing is done using the cheatsheet syntax (```[depls]```), and indirect is done using (```[[depls]]```).
+
+Also, it only currently supports the addressing mode syntax from the cheatsheet.
+
+## Example program
+Assembly usually has this syntax:
+```asm
+; This is an inline comment, anything written here is regarded as text and will not make it into the final binary representation
+a EQU 5 ; We define a to be constant value 5
+xor ra,ra ; mov ra,0 but faster
+loop_start: ; Relative location in address to jump to. Within this example it will be replaced with 1
+    add [b], ra ; equivalent to add [0x3F1], ra (see explanations later)
+    inc ra
+    cmp ra, a ; After preprocessing will be cmp ra, 5
+    jne loop_start ; For conditional jumps relative offsets are used
+
+end: ; 
+    out 0 ; We share the result with the outside world
+    hlt
+
+0x03F0: ; Placing numbers instead of identifiers for labels represent what will be written at an arbitrary memory address (specific to this assembler only!)
+4 ; Any number without an instruction can be converted into a 16bit word (specific to this assembler only!)
+b: 15  ; Since b is the next word after address 0x03F0, this will be translated to 0x03F1.
+```