Add Wishbone datasheets
[AGH_computer_science_engineering_thesis.git] / README.txt
blob1eac24cb0049211ee01532be72f0be118b20ddc6
1 ## About
2 This repository shall contain the the code for 'Laboratory station based on
3 programmable logic device for WebAssembly execution evaluation' developed as my
4 engineering thesis at AGH University of Science and Technology in Cracov,
5 Poland.
7 The project utilizes Verilog HDL. Icarus Verilog Simulator is used for
8 simulation and test benches, while Yosys, arachne-pnr/nextpnr and icestorm are
9 the tools chosen for synthesis, p&r and bitstream generation for Olimex's
10 iCE40HX8K-EVB FPGA.
12 ## Technical choices
13 I'm using one of few FPGAs with fully libre toolchain. SystemVerilog and VHDL
14 are not yet (officially) supported in Yosys, so I'm using Verilog2005.
16 I'm writing my own stack machine CPU for the job. Another option would be to
17 run an existing register-based CPU (picorv32?) on the FPGA and interpret Wasm
18 on it. Despite my thesis' topis is broad anough it would allow that, I didn't
19 go this way, because:
20  - there'd be nothing innovative in this approach,
21  - I'd end up mostly copying other's code, ending up with a copy-paster's
22    thesis...
24 I'm using Wishbone pipelined interconnect for CPU and other components.
26 WebAsm binary format was not designed for direct execution, so I'm instead
27 creating a minimal stack machine, that would allow almost 1:1 translation of
28 Wasm code to it's own instruction format. I still think it's possible to make
29 a CPU, that would execute Wasm directly - it's just matter of a bit more
30 effort.
32 The stack machine is and will be limited. That's why some more complex Wasm
33 instructions (e.g. 64-bit operations, maybe float operations) have to be
34 replaced with calls to software routines.
36 The goal is to write some minimal "bootloader", that would translate Wasm
37 to my stack machine's instructions on-device.
39 The SPI chip on iCE40HX8K-EVB is 2MB big. The configuration stored on it is
40 below 137KB. I'm going to use the remaining memory to store the actual Wasm
41 code for execution.
43 The initial booting code will be preloaded to embedded RAM (iCE40HX8K has such
44 feature and Yosys supports it).
46 I'm using VGA (640x480@60Hz) with self-created text mode for communicating to
47 the outside. UART is also planned.
49 I wrote an assembly for my stack machine (tclasm.tcl). The actual assembly
50 instructions are expressed in terms of tcl command executions, so we could call
51 it pseudo-assembly. Before embracing tcl, I needed a way to express memory
52 reads and writes for some test benches and created a simple macroassembly
53 (include/macroasm.vh). I probably should have used tcl from the beginning...
55 Everything is done through some (quite sophisticated) Makefiles.
57 ## Project structure
58  - Makefile - needs no explaination...
59  - Makefile.config - included by Makefile and Makefile.test, defines variables,
60                      makes it easy to, e.g., change the compiler command
61  - Makefile.util - also included by Makefile and Makefile.test - defines things,
62                    that didn't semantically fit into Makefile.config
63  - design/ - Verilog sources, that will get synthesized for FPGA (+some other
64              files like initial memory contents)
65  - models/ - Verilog modules used in testing
66  - tests/ - benches, each in its own subdirectory, with a Makefile including
67             Makefile.test
68  - tclasm.tcl - implementation of simple assembly in terms of tcl commands
69  - include/ - Verilog header files for inclusion
70  - tools/ - small C programs
71  - COPYING - 0BSD license
72  - README.txt - You're reading it
74 ## Project status
75 I'm a huge bit delayed with the work (should have had a working prototype in
76 June...), but I'm working on it.
78 I had a previous approach to the problem in July. Work was going extremely
79 slowly and I felt, that my code was really bad. This is also because I haven't
80 had any serious hardware design experience before. Now, I started anew. My
81 current approach is less CISCy. I'm also doing everything in the simulator,
82 with test benches for every module and plans to get it to run on the FPGA once
83 the design is able to display something through VGA. That's different from my
84 previous approach, where I was trying to make something run on the board and
85 then write tests for it. I'm now determined to use Wishbone, because I believe
86 it helps me keep the design clean.
88 My stack machine is currently able to do some operations like memory accesses,
89 addition and unsigned division, jumps, but it's not yet ready to have most of
90 Wasm translated to it. At the beginning of September I changed the design and
91 instruction format and rewrote the stack machine. The current one can be
92 considered my third approach :p
94 ### Thoughts
95 It's indeed an interesting project, but from practical point of view - it's
96 still going to be more efficient to JIT-compile Wasm on a register-based
97 architecture... Perhaps it'd be more useful to optimize an exisiting processor
98 (OpenRISC, OpenSPARC, RiscV) for that?