Updated README.md
* Fixed some typos and errors * Added table of contents * Added reference to hackasm assembler project Signed-off-by: Collin J. Doering <collin.doering@rekahsoft.ca>
This commit is contained in:
parent
0c737a29d9
commit
516afe7433
80
README.md
80
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 <a name="introduction"></a>
|
||||
|
||||
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 <a name="features"></a>
|
||||
|
||||
* Follows a similar structure to the implementation describe by the *Nand to Tetris* book
|
||||
* Uses open-source tools wherever possible
|
||||
|
||||
## Tools
|
||||
## Tools <a name="tools"></a>
|
||||
|
||||
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 <a name="license"></a>
|
||||
|
||||
This project is licensed under the [GPLv3][]. Please see the LICENSE file for full details.
|
||||
|
||||
## Import VHDL Sources
|
||||
## Import VHDL Sources <a name="import-vhdl-sources"></a>
|
||||
|
||||
$ 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 <a name="simulation"></a>
|
||||
|
||||
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 <a name="simulation-caveats"></a>
|
||||
|
||||
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 <a name="issues"></a>
|
||||
|
||||
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 <a name="road-map"></a>
|
||||
|
||||
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 <a name="wish-list-and-ideas-for-extension"></a>
|
||||
|
||||
* 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 <a name="related-projects"></a>
|
||||
|
||||
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/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user