diff --git a/README.md b/README.md index ffc0f97..2bfb890 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,43 @@ -# Implementation of Hack Computer Architecture in VHDL +# Hack -## Features +* [Introduction](#introduction) +* [Features](#features) +* [Tools](#tools) +* [License](#license) +* [Import VHDL Sources](#import-vhdl-sources) +* [Simulation](#simulation) + * [Caveats](#simulation-caveats) +* [Issues](#issues) +* [Road Map](#road-map) +* [Wish List and Ideas For Extension](wish-list-and-ideas-for-extension) +* [Related Projects](#related-projects) + +## Introduction + +Implementation of Hack Computer Architecture in VHDL. This implementation seeks to be +thoroughly verified through simulation using [GHDL][] and eventually implemented on a FPGA. + +## Features * Follows a similar structure to the implementation describe by the *Nand to Tetris* book * Uses open-source tools wherever possible -## Tools +## Tools The creation of this software was made possible by the following open source tools and libraries, and most notably, *Noam Nisan*, and *Shimon Schocken* who created the *Nand to -Tetris* course and accompanying book "The Elements of Computing Systems, Building a Modern -Computer from First Principe's". +Tetris* course and accompanying book *The Elements of Computing Systems, Building a Modern +Computer from First Principe's*. * [Gnu Emacs][], because there is no place like home; and no greater editor! * [GHDL][], for VHDL compilation/simulation. * [GtkWave][], for viewing waveform dumps (vcd, fst, etc..) -## License +## License This project is licensed under the [GPLv3][]. Please see the LICENSE file for full details. -## Import VHDL Sources +## Import VHDL Sources $ cd src $ ghdl -i --workdir=work *.vhdl @@ -29,10 +46,10 @@ All units can then be built by building the top most unit, computer_tb, as follo $ ghdl -m --workdir=work computer_tb.vhdl -## Simulation +## Simulation For every VHDL entity defined in `src` there is a accompanying test bench. The test bench has -`_tb` appended to the end of the entities file name (Eg. cpu.vhdl and cpu_tb.vhdl). Each test +`_tb` appended to the end of the entities file name (Eg. `cpu.vhdl` and `cpu_tb.vhdl`). Each test bench consists of test data derived from the *Nand to Tetris* course. The simulated clock (defined in `src/clock.vhdl` is set to a frequency of *1 GHz*, but this is configurable though use of a generic property of the clock entity. @@ -56,7 +73,7 @@ file of your choosing, or if none is given it will use `src/asm/Fib.hack`. Examp $ ghdl -r computer_tb -gprogram_file=asm/MemoryFill.hack --stop-time=10ns --vcd=wave/vcd/computer-memory-fill.vcd $ vcd2fst wave/vcd/computer-memory-fill.vcd wave/vcd/computer-memory-fill.fst -This will run a simulation for 10ns (for computer_tb a stop-time is required otherwise the +This will run a simulation for *10 ns* (for `computer_tb` a stop-time is required otherwise the simulation will run forever) and output a vcd dump to `src/wave/vcd/computer-memory-fill.vcd`. See `ghdl --help` and the [GHDL][] man page for more details on its command line options. @@ -68,15 +85,16 @@ Another example, running the default `src/asm/Fib.hack` program: Note that converting the vcd file to an fst file using vcd2fst is sometimes necessary when the simulations become large. This mostly is the case with the computer_tb unit. -### Caveats +### Caveats -Currently the computer_tb unit doesn't allow keyboard input or show monitor output; that is, +Currently the `computer_tb` unit doesn't allow keyboard input or show monitor output; that is, the memory maps are unimplemented as simulating the physical devices in VHDL is challenging, and the implementation of them on actual hardware is dependent on the FPGA board being used. -The address ranges of the memory maps however, exist and are read/writeable as you would -expect. +The address ranges of the memory maps however, exist (*or rather will exist in a upcoming +commit*) and are read/writeable as you would expect (see the [issues](#issues) section for more +information). -The computer_tb unit also doesn't allow one to reset the system without explicitly modifying +The `computer_tb` unit also doesn't allow one to reset the system without explicitly modifying the vhdl code of computer_tb. This could be fixed by implementing computer as its own entity with one input (reset) for testing purposes. Then multiple test benches could be written to test various aspects of the machine. Better yet, similar to how testing is done in the *Nand to @@ -84,7 +102,7 @@ Tetris* course, we could have another generic property on the test bench to spec file' which could be used to compare the output of various signals from the implementation when running a given program. This however, is currently not implemented. - Testing the output of a simulation (using computer_tb) of a given hack program also is not +Testing the output of a simulation (using `computer_tb`) of a given hack program also is not implemented and is somewhat involved. The primitive screen could be implemented by doing txt dumps that represent the memory map at a @@ -103,15 +121,15 @@ decimal), is read it will return 0x000 and if written will not retain its value. fix in the coming week, so viewing what a program does to the memory map and keyboards becomes easier/feasible in [GtkWave][]. -TLDR: computer_tb can be used to simulate any .hack program, though there is no screen or -keyboard connected, and the reset button during simulation unless the VHDL code of computer_tb +TLDR: `computer_tb` can be used to simulate any .hack program, though there is no screen or +keyboard connected, and the reset button during simulation unless the VHDL code of `computer_tb` is modified to so. -## Issues +## Issues When simulating the computer using the computer_tb unit, the -g command line switch is only available in very recent versions of [GHDL][] (later then 2015-03-07; see -[ticket(http://sourceforge.net/p/ghdl-updates/tickets/37/?limit=25)]). Thus to run various +[ticket](http://sourceforge.net/p/ghdl-updates/tickets/37/?limit=25)). Thus to run various .hack programs in the simulation, one must edit the source file referenced in `src/computer_tb.vhdl`. @@ -123,14 +141,15 @@ labels when processing 'for ... generate' statements. To address this issue two save files are provided, `src/wave/gtkw/computer.gtkw` is for the older version of [GtkWave][] and `src/wave/gtkw/computer-ghdl-new.gtkw` is for the newer version (later then 2015-03-07). -## Road Map +## Road Map Acquire an FPGA so that I can implement this design on real hardware. Currently I've been leaning towards a -[Nexys 4 DDR](http://www.digilentinc.com/Products/Detail.cfm?NavPath=2,400,1338&Prod=NEXYS4DDR). -Once I have an FPGA for testing I hope to implement the following features. Though it would be nice to -implement the simulation of the screen and keyboard but this seems nearly unfeasible, and a -better use of time would be to implement the design on real hardware. +[Nexys 4 DDR](http://www.digilentinc.com/Products/Detail.cfm?NavPath=2,400,1338&Prod=NEXYS4DDR) +or a [Basys 3](http://www.digilentinc.com/Products/Detail.cfm?NavPath=2,400,1288&Prod=BASYS3). +Once I have an FPGA for testing I hope to implement the following features. Though it would be +nice to implement the simulation of the screen and keyboard but this seems nearly unfeasible, +and a better use of time would be to implement the design on real hardware. * VGA output and associated memory map (perhaps find a backwards compatible way to add color to the system, support various VGA modes, etc..) @@ -139,7 +158,7 @@ better use of time would be to implement the design on real hardware. * Use some onboard nonvolatile memory to store the ROM * Implement an OS to be put on the ROM which can load programs, manage resources, etc.. -### Wish List and Ideas for Extension +### Wish List and Ideas for Extension * Modify the add16 unit to avoid [propagation delays](http://en.wikipedia.org/wiki/Propagation_delay) by passing a carry @@ -151,6 +170,15 @@ better use of time would be to implement the design on real hardware. - Implement a Memory Management Unit (MMU) - Others... +## Related Projects + +To run a *Hack Assembly* program in the simulation it must be in its machine language +representation; that is it needs to be passed through an assembler. One such assembler is the +one provided with the *Nand to Tetris* course. I have also written another one, name `Asmblr`, +which is faster and more fully featured. For more information see the +[Asmblr](http://git.rekahsoft.ca/hackasm) repository and its accompanying +[README](http://git.rekahsoft.ca/hackasm/about). + [Gnu Emacs]: http://www.gnu.org/software/emacs/ [GPLv3]: https://www.gnu.org/licenses/gpl.html [GHDL]: http://ghdl.free.fr/