NAND2TETRIS: Hack-CPU 32-bit emulator
 
 
 
Go to file
kaqu 3bc276f266 Entire compiler suite added for convenience 2023-08-04 17:46:27 +02:00
.vscode Sample included, icon added, README improved 2022-08-28 11:31:14 +02:00
OS_Test Sample included, icon added, README improved 2022-08-28 11:31:14 +02:00
compiler Entire compiler suite added for convenience 2023-08-04 17:46:27 +02:00
doc hw docs added 2022-08-20 11:26:13 +02:00
rsc unsafe pointers (need for speed) 2022-09-02 00:39:12 +02:00
src Superfluous GUI garbage removed 2022-09-02 18:02:04 +02:00
.gitignore My 1st Rust program ... 2022-08-10 10:40:52 +02:00
Cargo.lock Removed old comments, used a global constant now! 2022-09-02 12:01:41 +02:00
Cargo.toml Removed old comments, used a global constant now! 2022-09-02 12:01:41 +02:00
README.md Entire compiler suite added for convenience 2023-08-04 17:46:27 +02:00

README.md

HE32, the emulator for a 32-bit version of the Hack CPU

This is a 32-bit version of the hack CPU (actually: a 19-bit version!) from the famous NAND2TETRIS course (https://www.nand2tetris.org/).

Motivation

If you want to run your full blown OS together w/ a somewhat larger application you'll soon find out, that it would require considerably more memory than the original 'ROM' size permits. The original (Java-)emulator does not support it. You will have to write your own emulator & that's what this is all about!

Features:

256KB ROM, 64KB RAM, >65 MegaInstructions/s (just about enough to play 'Pong'!)

Modifications

It's input file is a 32-bit variant of the original *.hack file 'binary' text output, the extension used shall be *.hack32. NOTE: You will have to adapt your hack assembler source to cope with 18-bit addresses (hence 256KB ROM) and 18-bit PC, A & D registers.

Hack OS modifications: Sys.jack: The emulator requires the modification of Sys.wait (simply return immediately) - if you don't want to wait forever ... Math.jack: Math.multiply will require adjustment to use 18 bits.

Usage

Usage is dead simple: he32 <hack32_filename>

Prerequisites

The application uses the Qt5-GUI. You will need to have Qt5 installed (ex. for Ubuntu/Mint):

sudo apt-get install cmake  
sudo apt-get install qt5-default qttools5-dev qt5-qmake libqt5designer5  
sudo apt-get install libasound2-dev libudev-dev  

Next, follow the Rust installation instructions.

Make sure you have qt5ct installed ('Qt5 Settings') & set the following env. variable

QT_QPA_PLATFORMTHEME="qt5ct"

To reproduce my viewing experience, adjust Qt5 settings (command: qt5ct) to:

1st tab 'Appearance':  
    Style: 'Fusion'  
    Standard dialogs: 'Default'  
    Palette: 'Custom'  
    Color scheme: 'darker'  
2nd tab 'Fonts':  
    General: 'Ubuntu 9'  
    Monospace: 'Ubuntu Mono 9'  
3rd tab 'Icon theme':  
    Mint-Y-Dark-Sand  
4th tab 'Interface':  
    -- no changes --  
5th tab 'Style Sheets':  
    -- none selected --  

Hint: It is recommended to run actual applications as release-builds only, you may experience poor performance otherwise. Use:

cargo run --release ./OS_Test/OS_Test.hack32

You may also modify the 'Look' via qt5ct ...

Have fun!

Addendum

For convenience I've added my compiler suite. Take note, that the assembler may produce the original 16bit binary format as well as the emulator required 32bit version (option: --bit32).

The 32bit format: Bit15 is moved to Bit31, Bit16..Bit18 extend the addressable range from 64Kb to 256kB (see source for details ... 😎).