initial vision description

1 files changed, 140 insertions, 0 deletions

diff --git a/doc/thesis.tex b/doc/thesis.tex
new file mode 100644
index 0000000..ffee297
--- /dev/null
+++ b/doc/thesis.tex
@@ -0,0 +1,140 @@
+% \documentclass[polish,12pt]{aghthesis}
+\documentclass[english,12pt]{aghthesis}% dla pracy w jêzyku angielskim. Uwaga, w przypadku strony tytu³owej zmiana jêzyka dotyczy tylko kolejno¶ci wersji jêzykowych tytu³u pracy. 
+
+% Szablon przystosowany jest do druku dwustronnego. 
+
+\usepackage[latin2]{inputenc}
+\usepackage{url}
+
+\author{Wojciech Kosior}
+
+\titlePL{Stanowisko laboratoryjne do ewaluacji wykonywania kodu WebAssembly w uk³adzie logiki programowalnej}
+\titleEN{Laboratory station based on programmable logic device for WebAssembly execution evaluation}
+
+\fieldofstudy{Informatyka}
+
+\supervisor{dr in¿.\ Robert Brzoza-Woch}
+
+\date{2020}
+
+
+\begin{document}
+
+\maketitle
+
+\section{\SectionTitleProjectVision}
+\label{sec:cel-wizja}
+
+\subsection{General information}
+The goal of this thesis is creation of a laboratory station for execution of WebAssembly
+on an FPGA device. The project's codename is WMF - WebAssembly Machine for FPGA.
+WebAssembly or Wasm standard defines a bytecode format for executable programs,
+as well as it's text representation. The goal of the bytecode is to enable
+efficient interpretation and keep the size of the binary small.
+Although it's been created mainly for use on web pages,
+it is suited for other environments as well, including embedded ones.
+Programming languages, even those with manual memory management
+and pointer arithmetics, can be compiled to Wasm bytecode. 
+Hence, a standard-conforming WebAssembly interpreter is capable of running
+code written in any of the languages, for which a compiler exists. This currently
+includes C, C++, C\#, Rust and others. 
+Wasm bytecode runs on a virtual stack machine. Most existing environments
+either interpret it directly or use JiT compilation.
+
+
+\subsection{Problem}
+WebAsm interpretation could possibly be made faster with hardware designed specifically
+for this task. Such hardware would also benefit from already existing tools
+for generating and working with the bytecode.
+In terms of this thesis a Wasm machine is going to be implemented in a hardware
+description language. The product is going to be used to execute WebAssembly binary
+on an FPGA board.
+Other projects attempting that have been started (\url{https://github.com/lastmjs/wasm-metal},
+\url{https://github.com/piranna/wasmachine}), but stalled in an early stage.
+
+\subsection{Concept}
+The designed Wasm machine is going to be a stack machine. It's distinguishable parts
+will be control unit, arithmetic logic unit, peripherals and possibly also stack
+(which, depending on design decision, can also reside fully in RAM) and floating-point unit.
+The machine shall work together with random-access memory residing on the development board.
+It shall communicate with the outside through peripherals (see below).
+
+\subsection{Functional requirements}
+The system shall consist of a Wasm machine design in a hardware description language,
+as well as documentation and example WebAssembly programs for execution.
+Instructions should be provided how to synthesize the design and load it to the FPGA
+device along with the example code.
+The environment should execute WebAssembly as specified in Minimum Viable Product.
+It should also enable communication of the executed program with other devices
+using UART or USB. Ability for Wasm code to use a VGA display is desired, but not
+mandatory.
+
+\subsection{Non-functional requirements}
+In programmable logic projects test benches play a very important role.
+The risk of having a failing part in the design has to be minimized
+in case of silicon realization, where each chip fabrication brings
+additional costs. The design created as part of this thesis shall be
+testable. The test suite would be run with the use of a simulator,
+as it doesn't carry the risk of design's dependence on hardware-specific
+behaviour.
+
+\subsection{Technologies}
+The iCE40HX8K-EVB FPGA development board has been chosen due to it's low cost and
+support by free software toolchain. While programmable logic device's small size
+may cause some limits, this will also force the Wasm wachine to be implemented
+size-efficiently.
+Verilog hardware description language is going to be used for synthesizable code as
+well as for testbenches. Verilog is the HDL used with the toolchain
+and also the one thesis' author knows the most. Other advantage of using verilog is
+it's wide support and simplicity. 
+Yosys, arachne-pnr/nextpnr and icestorm are the development tools used for
+verilog synthesis, place\&route and bitstream generation for the chosen device.
+The tols are under active development.
+A simulator for test benches is also needed for the project. Icarus Verilog Simulator,
+which is free software can be used for that.
+Some means of communication with the Wasm machine on the FPGA are required.
+One possibility is to use the include a verilog UART module, which could be operated by
+the executing WebAssembly program to communicate with a computer. UART is a simple
+device the author is already common with. If data transfers with higher speed are
+desired, a USB peripheral could possibly be written at the cost of bigger effort and
+higher complexity. As USB ports are common, it could be used to communicate
+the device with a wide range of computers, despite lack of USB certification.
+VGA output could also be generated with programmable logic to enable executed
+code to use a video display.
+
+\subsection{Risks}
+One high risk is that the Wasm machine will be too complex to fit on the chosen FPGA chip.
+If this happens, the number of gates resulting from the HDL code will have to
+be reduced. One solution would be to implement some instructions in terms of
+microcode. Another one would be to resign from supporting some of the wasm features.
+Another, medium risk, is that the WebAssembly bytecode might prove difficult to
+interpret directly by the hardware, especially as it was designed for small binary size.
+In such case, some pre-evaluated form of the bytecode could be used instead.
+This step of pre-evaluation could be performed by software on a computer
+before loading the code to the board or on the device itself by some kind of bootloader.
+In the unlikely situation of some other serious problems arising, it should
+be also possible to realize a different stack or register machine in programmable
+logic instead and execute a software Wasm interpreter on it. This approach, however,
+wouldn't have the main advantage of improving speed.
+
+\section{\SectionTitleScope}
+\label{sec:zakres-funkcjonalnosci}
+\emph{TODO}
+
+\section{\SectionTitleRealizationAspects}
+\label{sec:wybrane-aspekty-realizacji}
+\emph{TODO}
+
+\section{\SectionTitleWorkOrganization}
+\label{sec:organizacja-pracy}
+\emph{TODO}
+
+\section{\SectionTitleResults}
+\label{sec:wyniki-projektu}
+\emph{TODO}
+
+\nocite{olimex_repo}
+
+\bibliography{bibliography}
+
+\end{document}