Documentation/deploy.sh

@@ -4,6 +4,6 @@ python3 -m mkdocs build --clean
 
 # Obviously I use public key authentication to login.
 # No secret server information is displayed here :P
-ssh 192.168.0.200 'rm -rf /var/www/b4rt.nl/html/fpgc/'
-rsync -r site/ 192.168.0.200:/var/www/b4rt.nl/html/fpgc/
-ssh 192.168.0.200 'chown bart:www-data -R /var/www/b4rt.nl/html/fpgc/'
+ssh 192.168.0.222 'rm -rf /var/www/b4rt.nl/html/fpgc/'
+rsync -r site/ 192.168.0.222:/var/www/b4rt.nl/html/fpgc/
+ssh 192.168.0.222 'chown bart:www-data -R /var/www/b4rt.nl/html/fpgc/'

Documentation/docs/Build-instructions/.pages

@@ -1,7 +1,6 @@
 nav:
     - verilog.md
     - quartus.md
-    - programmer.md
     - asm.md
     - bcc.md
     - wiki.md

Documentation/docs/Build-instructions/asm.md

@@ -1,3 +1,15 @@
 # ASM build instructions
 
-TODO: write this page
+## Assembling a program
+
+To assemble a program, run `python3 Assembler.py > {outfile.list}`. The code is always stored in `code.asm`. The assembler will produce a text file with 32 1's and 0's and some comments for each line. To convert this into a binary, run `compileROM.sh` from the `Programmer` directory.
+
+The arguments `os` or `bdos {offset}` can be used when assembling BDOS and a bdos user program. More details can be found in the Assembler wiki page.
+
+## Assembling a userBDOS program from FPGC
+
+A user program can also be assembled from the FPGC itself using the `asm` userBDOS program found in `BCC/FPGCbuildTools/asm/`. Within BDOS, run `asm {code.asm} {out.bin}`. This assembler will directly assemble to an output binary that can be run from BDOS.
+
+## Assembling a program for simulation in Verilog
+
+See `buildToVerilog.sh` and `simulate.sh` for examples on what is needed to assemble a program into the simulated rom/flash of the FPGC. This is useful for testing very small programs or individual instructions in simulation without having to write binary manually.

Documentation/docs/Build-instructions/bcc.md

@@ -1,3 +1,23 @@
 # BCC build instructions
 
-TODO: write this page
+This page shows how to build C written software for the FPGC using BCC
+
+## Compiling BCC using GCC
+
+To compile the compiler, run `make` in the `BCC/` directory. This will build the `bcc` binary which can then be used to compile C code into ASM code.
+
+## Compile bare metal C program
+
+To compile a C program to run directly on the FPGC, run `bcc {code.c} {file.asm}`. To also assemble and program the FPGC, a convenience script `compileBareMetal.sh` can be used.
+
+## Compile BDOS
+
+To compile the operating system BDOS, run `bcc --os {BDOS.c} {file.asm}`. To also assemble and program the FPGC, a convenience script `compileBDOS.sh` can be used.
+
+## Compile userBDOS program
+
+To compile a program to be run as a program within BDOS, run `bcc --bdos {program.c} {file.asm}`. To also assemble, send/upload and run the program on the FPGC, two convenience scripts can be used: `sendToBDOS.sh` to send the program over the network and run it directly from memory, and `uploadToBDOS.sh [filename to store]` to upload the program over the network to store it in the filesystem.
+
+## Compile userBDOS program from FPGC
+
+A user program can also be compiled from the FPGC itself using the `bcc` userBDOS program found in `BCC/FPGCbuildTools/bcc/`. Within BDOS, run `bcc {code.c} {file.asm}`. As of writing there is no scripting support, so no convenience script to also assemble the program exists.

Documentation/docs/Build-instructions/programmer.md

@@ -1,3 +0,0 @@
-# Programmers
-
-TODO: write this page

Documentation/docs/Build-instructions/quartus.md

@@ -1,7 +1,10 @@
 # Quartus build instructions
 
-TODO: write this page
+The Quartus folder contains all files for actually implementing the FPGC into hardware on an FPGA using the Quartus Prime Lite edition software from Intel. The targeted development board is the QMTECH 5CEF_A5_F23_I7N core board with 64MiB SDRAM.
 
-The Quartus folder contains all files for actually implementing the FPGC into hardware on an FPGA. The targeted development board is the QMTECH EP4CE15 core board with 32MiB SDRAM.
+!!! info
+    There are some slight changes between the code in the Verilog folder and the code in the Quartus folder. For example, the Verilog folder contains simulation files for the SPI flash and SDRAM memory. The Quartus project is on the top level somewhat modified to work on an actual FPGA. This also includes the use of PLLs for creating clocks.
 
-There are some slight changes between the code in the Verilog folder and the code in the Quartus folder. For example, the Verilog folder contains simulation files for the SPI flash and SDRAM memory. The Quartus project is on the top level slightly modified to work on an actual FPGA. This also includes the use of PLLs for creating clocks.
+## Flashing configuation to FPGA
+
+To flash the FPGA design, a very cheap Altera USB Blaster from Aliexpress can be used, although they require some work to get working (libusb issues).

Documentation/docs/Build-instructions/verilog.md

@@ -1,3 +1,15 @@
 # Verilog build/simulate instructions
 
-TODO: write this page
+To simulate the design, iverilog is used. You might need to compile the latest version yourself.
+
+To run the simulation (in this case a testbench of the entire FPGC), run 
+
+```bash
+iverilog -o /home/bart/Documents/FPGA/FPGC6/Verilog/output/output \
+  /home/bart/Documents/FPGA/FPGC6/Verilog/testbench/FPGC_tb.v \
+  && vvp /home/bart/Documents/FPGA/FPGC6/Verilog/output/output
+```
+
+Assuming the testbench generates a `wave.vcd`, run `GTKWave` with this file as argument (or open the file within the program).
+
+Tip: use `ctrl+shft+b` to reload the waveform when overwritten by a new simulation.

Documentation/docs/Build-instructions/wiki.md

@@ -1,4 +1,5 @@
 # Wiki build instructions
+
 This wiki is built using mkdocs, which runs on Python3
 
 ## Installation
@@ -6,17 +7,18 @@ This wiki is built using mkdocs, which runs on Python3
 ```bash
 pip3 install mkdocs mkdocs-material mkdocs-awesome-pages-plugin
 ```
+These packages are also included in the `requirements.txt` of this repo.
 
 ## Run site (development)
 
-Run `./run.sh` to host a local version on localhost:8088.
+Run `./run.sh` to host a local version on `localhost:8088`.
 
-When a file is changed, the website should refresh automatically
+When a file is changed, the website should refresh automatically.
 
 
 ## Deploy site
 
-To deploy the website on my server (only I can do this), run `./deploy.sh`. Just make sure you use public key authentication to the server.
+To deploy the website on my server (only I can do this ofc), run `./deploy.sh`. Just make sure you use public key authentication to the server.
 
 This will:
 

Documentation/docs/Software/asm.md

@@ -1,18 +1,56 @@
 # Assembler for B32P
 
-The basic way to write code for the B32P is by using the B32P assembly language. The assembler compiles the assembly code to 32 bit machine instructions. The input file is currently code.asm, and the output is printed to stdout. The assembler is written in Python3. A [special version written in BCC](#bcc-version) can be run from the FPGC itself.
+The basic way to write code for the B32P is by using the B32P assembly language. The assembler compiles the assembly code to 32 bit machine instructions. The input file is currently hardcoded to `code.asm`, and the output is printed to stdout. The assembler is written in Python3. A [special version written in BCC](#bcc-version) can be run from the FPGC itself.
 
 !!! info
     Since the addition of the C compiler BCC, the focus of the assembler now lies more on assembling BCC's output instead. Still, the bootloaders are written in assembly and some BCC libraries, like the graphics library, also make extensive use of assembly code.
 
 ## Command line arguments
-There are three types of programs the assembler can create, indicated by the following command line parameters:
+There are three types of programs the assembler can create, indicated by command line arguments:
 
-- `os`. For compiling the BDOS operating system. Aside from the length of the program/OS, a jump to Syscall is also added. Assumes the program/OS is run from address 0
-- `bdos {offset}`. For compiling BDOS user programs. No program length is included and the assembler will offset labels to make the code executeable from the given offset
-- no parameters. Assumes program to be run from address 0, length of program is included
+- BDOS OS [arg `os`]. Special mode for assembling the BDOS operating system. This adds a jumpt to the syscall function on address 4, and adds the length of the binary to address 2.
+- BDOS User Program [arg `bdos {offset}`]. Special mode for assembling BDOS user programs. No program length is included and the assembler will offset labels to make the code executeable from the given offset.
+- Bare metal program [no args]. Basic mode for assembling bare metal programs without OS. Adds length of the binary to address 2.
 
-Finally, by adding the `-O` argument at the end will cause the assembler to remove unreached code, which is quite useful because of the lack of dynamic linking.
+Finally, by adding the `-O` argument at the end will cause the assembler to remove unreached code, which is quite useful for compiled C code because of the lack of dynamic linking. This will save quite some space as C libraries are getting more functions over time.
+
+## Output
+The assembler does not directly create a binary. Instead, it outputs the assembled code as a text file containing binary strings of 32 ones and zeros, follwed by a space and comments starting with `//`. This is very useful to see what each instruction is supposed to do, and makes it easy to verify this with the ISA.
+
+Example output:
+```
+00010011000000000000110011011101 //Compute r13 + 12 and write result to r13
+00011100001001110100010000100010 //Set r2 to 10052
+```
+
+The output can be converted into a binary using other tools. For example: `perl -ne 'print pack("B32", $_)' < filename_containing_assembler_output > executable.bin`
+
+## Assembly process
+The assembler performs the following steps in order
+
+1. Read input file into list of lines while removing all comments
+2. Move all `.data`, `.rdata` and `.bss` sections down so the `.code` section becomes one part at the top (only relevant for C compiled code)
+3. Insert libraries (only relevant for non-C compiled code)
+4. Remove unreachable code if requested
+5. Process the define statements
+7. Do pass 1: Compiles lines that can be compiled directly (so without labels) and create new lines for instructions that become multiple lines
+8. Add header code
+9. Process labels
+10. Do pass 2: Compile instructions with labels
+11. Check for remaining labels (there should be none left)
+12. Add length of program if requested
+13. Print result to stdout
+
+## Header
+
+The assembler creates the first few lines of the program, depending on the program type (header code). Because of a bug in B32P, in some cases the CPU will start at address 3 instead of address 0 after the bootloader. Until this is fixed, the 4th instruction also is a jump to Main. For a `-os` program, this looks as follows:
+``` text
+Jump Main
+Jump Int
+[Length of program]
+Jump Main
+Jump Syscall
+```
 
 ## Line types
 Each line is parsed on its own. There are six types of lines:
@@ -34,10 +72,10 @@ Because the BCC compiler is a modified MIPS compiler, its output contains direct
 The assembler will move each non-code section down so it does not interfere with the code.
 
 ### Includes
-By adding an \`include namehere.asm statement, it is possible to add code from other files, like libraries. The way this works in the assembler is by just adding all lines of that file to the code, while recursively importing includes from other files. The assembler makes sure that the same file is never included more than one time. The path to the file is relative to the assembler.
+By adding an \`include namehere.asm statement, it is possible to add code from other files, like libraries. The way this works in the assembler is by just adding all lines of that file to the code, while recursively importing includes from other files. The assembler makes sure that the same file is never included more than one time. The path to the file is relative to the assembler. This is only relevant for non-C code, as the C compiler should not produce assembly includes.
 
 ### Comments
-Comments can be added by using the ';' character. For each line, only the part until the first ';' occurrence will be used by the assembler. This means that anything can be written after the ';'. This all does not go for .ds lines. They must not have any comments. This way it is not needed to use escape characters in the strings
+Comments can be added by using the ';' character. For each line, only the part until the first ';' occurrence will be used by the assembler. This means that anything can be written after the ';'. This all does not hold for .ds lines. They must not have any comments. This way it is not needed to use escape characters in the strings.
 
 ### Defines
 Defines are the first type of lines that are processed by the assembler. A define line should have the following structure:
@@ -69,7 +107,7 @@ You can use two labels directly after each other without any instruction in betw
 When two identical labels are defined, the assembler will complain.
 It does not matter if a label is never referenced.
 However, it does matter when a reference is made to a label that is not defined. In that case the assembler will complain.
-Each of the interrupt handler labels should 'end' with a reti instruction, otherwise the CPU will not return from the interrupt and will probably lock up. However, this is not checked by the assembler.
+Each of the interrupt handler label sections should finish with a reti instruction, otherwise the CPU will not return from the interrupt and will probably lock up. However, this is not checked by the assembler.
 
 ### Instructions
 The instructions are the lines that will be assembled into machine code. Each instruction has its own format with the following description:
@@ -105,9 +143,11 @@ ADD     | R     | C16/R | R     || Compute Arg1 +   Arg2, write result to Arg3
 SUB     | R     | C16/R | R     || Compute Arg1 -   Arg2, write result to Arg3
 SHIFTL  | R     | C16/R | R     || Compute Arg1 <<  Arg2, write result to Arg3
 SHIFTR  | R     | C16/R | R     || Compute Arg1 >>  Arg2, write result to Arg3
+SHIFTRS | R     | C16/R | R     || Compute Arg1 (signed)>> Arg2, write result to Arg3
 NOT     | R     | R     |       || Compute NOT  (~) Arg1, write result to Arg2
-MULTS   | R     | C16/R | R     || (signed) Compute Arg1 *   Arg2, write result to Arg3
-MULTU   | R     | C16/R | R     || (unsigned) Compute Arg1 *   Arg2, write result to Arg3
+MULTS   | R     | C16/R | R     || (signed) Compute Arg1 * Arg2, write result to Arg3
+MULTU   | R     | C16/R | R     || (unsigned) Compute Arg1 * Arg2, write result to Arg3
+MULTFP  | R     | C16/R | R     || (signed, FixedPoint16.16) Compute Arg1 * Arg2, write result to Arg3
 SLT     | R     | C16/R | R     || (signed) If Arg1 < Arg2, write 1 to Arg3, else write 0 to Arg3
 SLTU    | R     | C16/R | R     || (unsigned) If Arg1 < Arg2, write 1 to Arg3, else write 0 to Arg3
 LOAD    | C16   | R     |       || Load (unsigned) 16 bit constant from Arg1 into Arg2
@@ -127,44 +167,11 @@ L   = Label
 S   = String
 
 Note: All constants are signed except stated otherwise
-*  Optional argument with same type as Arg1. Has 'no limit' on number of arguments
+*  Optional argument with same type as Arg1. Has no limit on number of arguments
 ** Data is placed after each other to make blocks of 32 bits. If a block cannot be made, it will be padded by zeros
 ```
 
 Each Cx type argument (constant) can be written in decimal, binary (with 0b prefix) or hex (with 0x prefix).
 
-The assembler creates the first few lines of the program, depending on the program type (header code). Because of a bug in B32P, in some cases the CPU will start at address 3 instead of address 0 after the bootloader. Until this is fixed, the 4th instruction also is a jump to Main. For a `-os` program, this looks as follows:
-``` text
-Jump Main
-Jump Int
-[Length of program]
-Jump Main
-Jump Syscall
-Jump Int4
-```
-
-## Assembling process
-The assembler does the following things the the following order:
-
-1. Remove all comments, while reading the input file line by line
-2. Move all non-.code directive sections down
-3. Insert libraries
-4. (optionally) Remove uncreached code
-5. Process the define statements
-6. Compile all lines that can directly be compiled (so without labels)
-7. Insert header code
-8. Create new lines for instructions that become multiple lines
-9. Process all labels
-10. Recompile the lines that had a label before
-11. Check if all labels are processed
-12. Calculate and write program length
-13. Print result to stdout
-
-### Input and output files
-The assembler will always read the code from code.asm and write the result to stdout. I might add file handling in the future, but for now it is not needed.
-
-## Other things
-I could create my own syntax highlighting for Sublime Text 3, however its Z80 syntax highlighting is already kinda decent on B32P ASM code.
-
 ## BCC version
-To allow for assembling code directly from the FPGC/BDOS itself, a special version of the assembler is written in BCC. This version lacks several features since its goal is to only assemble the output of BCC. It is also more optimized for speed (the compiler, not the code per sé)
+To allow for assembling code directly from the FPGC/BDOS itself, a special version of the assembler is written in BCC. This version lacks several features like includes, defines and line number errors, since its goal is to only assemble the output of BCC (specifically the BCC version running on the FPGC/BDOS as well). It is also more optimized for speed (the compiler, not the code). It also only assembles for BDOS User Programs, so if you want to assemble manually written assembly, you will need to add the userBDOS assembly wrappers yourself.