commit 5c25183eee499db2e6d43608b70a853650e91381 from: Sven M. Hallberg date: Sun Sep 11 17:33:48 2022 UTC add README commit - f466152267b9b2e5b182ead9ad81db7667512114 commit + 5c25183eee499db2e6d43608b70a853650e91381 blob - /dev/null blob + 483393654b89bbcae335eec1e45d6f733bff8709 (mode 644) --- /dev/null +++ README @@ -0,0 +1,122 @@ + + +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 + + 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.