commit - f466152267b9b2e5b182ead9ad81db7667512114
commit + 5c25183eee499db2e6d43608b70a853650e91381
blob - /dev/null
blob + 483393654b89bbcae335eec1e45d6f733bff8709 (mode 644)
--- /dev/null
+++ README
+
+
+NAME
+ hackem - an emulator for the Hack computer featuring (paper) tape I/O
+
+SYNOPSIS
+ hackem [-f frequency] [-s factor] [-t file] prog.rom
+ rom prog.rom < prog.hack
+
+DESCRIPTION
+ This repository contains an emulator for the computer described in "The
+ Elements of Computing Systems" and the course "From Nand to Tetris" by
+ Nisan and Schocken.
+
+ The emulator expects a raw ROM image in platform byte order that can be
+ produced with the supplied 'rom' tool. The tool accepts a superset of
+ the .hack file format. Each line of input must contain exactly 16 ASCII-
+ encoded binary digits representing an instruction. As an extension,
+ whitespace, empty lines, and shell-style comments introduced by a '#'
+ character are ignored.
+
+ This implementation is designed to integrate well with the Unix command
+ line. It detects idiomatic infinite loops that are usually used to halt
+ execution and terminates with the contents of D register as exit status.
+ To facilitate data processing, it is extended with three memory-mapped
+ I/O devices that are not described in the book:
+
+ - A punched tape reader bound to standard input.
+ - A tape punch bound to standard output.
+ - An auxiliary printer (using the same interface as the tape
+ punch) bound to standard error.
+
+ The screen and keyboard as described by Nisan and Schocken are not
+ currently supported. Reads from the keyboard address always return zero.
+ The screen memory acts like regular RAM.
+
+ The options are as follows:
+
+ -f frequency
+ Set the simulated clock frequency, in Hertz (cycles per second).
+ The default is 1000.
+
+ -s factor
+ Scale simulation time by the given factor, without changing the
+ clock frequency. Fractional factors are supported. Factors <1
+ speed up execution. A factor of 0 eliminates tick delay, letting
+ the simulation proceed at maximum speed. The default is 1.
+
+ -t file
+ Trace CPU state during execution, written to the given file in
+ tab-separated value (.tsv) format.
+
+TAPE INTERFACES
+ The tape reader provides two addresses, mapped to 0x7000 and 0x7001.
+
+ The first address reflects the current value under the read head. It is
+ well-defined only when the control word at the second address indicates a
+ valid position. A negative value indicates the end of the tape, or no
+ tape present at all - corresponding to EOF on standard input.
+
+ Writing to the first address has no effect.
+
+ The second address provides control over the tape feed. Writing 1 to it
+ will advance the tape by one position. The result of writing any other
+ value is undefined.
+
+ Reading from the second address yields a status word. A negative value
+ (bit 15 set) indicates that the value at the read address is valid. All
+ other bits are undefined.
+
+ Thus, the procedure to acquire one byte of input is as follows:
+
+ 1. Write 1 to 0x7001.
+ 2. Read 0x7001 until it is negative.
+ 3. Read 0x7000; if it is negative, indicate the end of input.
+ 4. Otherwise, the value read from 0x7000 is the input byte.
+
+ The tape punch provides two addresses, mapped to 0x7002 and 0x7003.
+
+ A write to the first address causes the corresponding byte to be output
+ and the tape advanced automatically to the next position. The result is
+ only well-defined if the status word at offset 1 indicates readiness.
+
+ The result of reading from the first address is undefined.
+
+ Reading from the second address yields a status word. A negative value
+ (bit 15 set) indicates that the tape is in position for new output. This
+ is invalid, however, if bit 14 is also set. Bit 14 indicates the end of
+ the tape or that no tape is present, corresponding to EOF on standard
+ output. All other bits are undefined.
+
+ The result of writing to the status word is undefined.
+
+ Thus, the procedure to produce one byte of output is as follows:
+
+ 1. Read 0x7003 until it is negative.
+ 2. If bit 14 is set, indicate an error.
+ 3. Write the output byte to 0x7002.
+
+ The auxiliary printer, corresponding to standard error, exposes the same
+ interface as the tape punch but is mapped at addresses 0x7004 and 0x7005.
+
+BUILDING
+ Simply run 'make' to build and 'make test' to execute the supplied tests.
+
+ This implementation targets the Unix environment, specifically OpenBSD.
+ Patches that port it to other systems are welcome.
+
+SEE ALSO
+ Noam Nisan and Shimon Schocken, The Elements of Computing Systems, second
+ edition, MIT Press, 2021.
+
+ https://nand2tetris.org
+
+AUTHORS
+ Sven M. Hallberg <pesco@khjk.org>
+
+ Released under the terms of the ISC license.
+
+ The files 'add.hack' and 'max.hack' were derived from similar files
+ included with nand2tetris materials. They are distributed under Creative
+ Commons Non-Commercial Attribution Share-Alike (CC BY-NC-SA) 3.0 license.
