#------------------
# run/Makefile
#------------------

#---------------------------
# This Makfile contains commands to run a couple of specific
# simulations:
# (1) lc3-run
#     This simulation testbench runs the LC3 as if it were
#     a standalone piece of hardware: no debugging output
#     is produced. It is intended to be used with kb, which
#     provides an interface to the host's keyboard and display.
#     The testbench source code is in lc3-run.v and the 
#     verilog-compiled output is in lc3-run.out. The latter
#     can be copied to "a.out" as needed. See targets below.
# (2) top_test_lc3os
#     This is the same as lc3-run, but with full debugging
#     output. It finishes when code executes HALT, or via
#     the commandline [ctl][C] and "finish".
#     See either the top_test_lc3os.v source code or the
#     top_test_lc3os cell in the test.jelib Electric library.
# (3) top_test_lc3os_w_INT
#     This is the same as top_test_lc3os, but the keyboard
#     interface is set to cause keyboard interrupts repeatedly,
#     if they are enabled.
# (4)
#     Targets "state18" and "opcodes" process debugging output
#     to make it easier reading. See target "debug".
# (5)
#     Target "kb_input" takes a prepared text file of keyboard input
#     and creates a readmemb() readable version.
#------------------------------
usage::
	@echo '  make run (runs "lc3run", reads "lc3os.bin")'
	@echo '  make run-kb (+ keyboard, [ESC] to exit)'
	@echo '  make run2 (runs "lc3run2.out", reads "prog.bin"+"lc3os.bin")'
	@echo '  make run2-kb (+ keyboard, [ESC] to exit)'
	@echo '  make os (runs "top_test_lc3os", reads "lc3os.bin")'
	@echo '          (w/ full debug output)'
	@echo '  make os-kb (+ keyboard, [ESC])'
	@echo '  make INT (runs "top_test_lc3os_w_INT", reads "lc3os.bin")' 
	@echo '           (w/ debug + automatic kb INTs, if enabled)' 
	@echo '  make opcodes (reads "foo", converts opcodes, writes "foo2")'
	@echo '  make state18 (reads "foo2", writes state-18 lines to "foo3")'
	@echo '  make debug (does "make opcodes; make state18")'
	@echo '     typical usage:'
	@echo '       make INT > foo'
	@echo '       make debug'
	@echo '       more foo3'
	@echo '  make kb_input (reads "kb_input.txt", writes "kb_input.bin")'

#/*----------------
#* lc3-run
#* Runs the lc3 simulation without debugging input or output.
#* Simulation finishes when the lc3os.bin executes the "halt",
#* or by using the commandline [ctl][C] and entering "finish".
#* Boots lc3os.bin: emulates a ROM booter reading lc3os.bin
#* from disk to memory at 0x0200. lc30s.bin must be in
#* the directory where the simulation runs. lc3-run can be used
#* with or without an interface to host's keyboard and display.
#* For either mode, compile code, "iverilog lc3-run.v", which
#* produces a.out: a.out can be run repeatedly as a simulation
#* engine for code development via "vvp a.out" or "kb". Note
#* that no keyboard input occurs when running via "vvp a.out".
#* This is good for testing display output routines.
#*
#* To run with an interface to host's keyboard and display, run
#*  ../bin/kb instead. kb will run "vvp a.out" and send 
#* keystrokes to lc3's keyboard controller and receive display
#* characters from display controller. 
#* The kb parent and its child processes are terminated
#* by pressing the [ESC] key. If that fails, "ps" and "kill".
#* The lc3's display output goes to controlling window.
#* Note: display output is buffered in host OS: you may not
#* see output until you hit [ENTER].
#*-----------------*/
lc3_run.out: lc3_run.v
	iverilog -o lc3_run.out lc3_run.v
lc3_run2.out: lc3_run2.v
	iverilog -o lc3_run2.out lc3_run2.v

run::
	make lc3_run.out
	vvp lc3_run.out
run2::
	make lc3_run2.out
	vvp lc3_run2.out
run-kb::
	make lc3_run.out
	cp lc3_run.out a.out
	../bin/kb
run2-kb::
	make lc3_run2.out
	cp lc3_run2.out a.out
	../bin/kb

#--------------------------------
# top_test_lc3os
# This testbench is the same as lc3_run, with debug output
# turned on. Best used with code that executes HALT before
# too much output is produced.
#---------------------------------
top_test_lc3os.out: top_test_lc3os.v
	iverilog -o top_test_lc3os.out top_test_lc3os.v
os::
	make top_test_lc3os.out
	vvp top_test_lc3os.out

os-kb::
	make top_test_lc3os.out
	cp top_test_lc3os.out a.out
	../bin/kb

#/*----------------
#* top_test_lc3os_w_INT
#* Tests lc3os's interrupt handling. Runs lc3os.bin at x0200.
#* This runs the LC3 with full debugging on. The keyboard
#* ctl's interface is set so that interrupts, if enabled,
#* will occur soon and repeatedly. The keyboard data is fixed:
#* only the character '2' is received. halt simulation either
#* at the commandline with [ctl][C], or via the HALT trap.
#*
#* The keyboard controller, kb_ctl, reads two text files in a
#* loop. kbHS.txt here is initialized with "03" (ETX),
#* "EndOfTransmission" and is signalling
#* that the keyboard device has new data. The data is sent via
#* kbData.txt, here intially contains "32" (hex notation
#* for ascii '2'. Substitute any character code you like.)
#*
#* LC3 keyboard interrupts are enabled via KBSR[14]=1.
#* If kbHS.txt contains "06" (ACKnowledged), the handshaking
#* indicates no new data is available. No interrupt will occur.
#*-----------------*/
top_test_lc3os_w_INT.out: top_test_lc3os_w_INT.v
	iverilog -o top_test_lc3os_w_INT.out top_test_lc3os_w_INT.v
INT::
	make top_test_lc3os_w_INT.out
	vvp top_test_lc3os_w_INT.out


#------------------------------
# Produce and process debugging output. Given an iverilog "a.out",
# "make debug" produces three files DEBUG.raw, DEBUG.ops, and DEBUG.18only.
# Target "opcodes" translates the first four bits of the IR.
# Target "state18" saves only debugging lines for state 18. 
# Usage might be as follows,
#     iverilog top_rtl_testInstr.v
#     make debug
# which produces the three DEBUG files.
#----------------------------
debug::
	vvp a.out > DEBUG.raw
	make opcodes
	make state18
opcodes::
	cat DEBUG.raw | sed \
        -e 's/IR\[0000 /IR\[ BR /' \
        -e 's/IR\[0001 /IR\[ADD /' \
	-e 's/IR\[0101 /IR\[AND /' \
	-e 's/IR\[1100 /IR\[JMP /' \
	-e 's/IR\[0100 /IR\[JSR /' \
	-e 's/IR\[0010 /IR\[ LD /' \
	-e 's/IR\[1010 /IR\[LDI /' \
	-e 's/IR\[0110 /IR\[LDR /' \
	-e 's/IR\[1110 /IR\[LEA /' \
	-e 's/IR\[1001 /IR\[NOT /' \
	-e 's/IR\[1000 /IR\[RTI /' \
	-e 's/IR\[0011 /IR\[ ST /' \
	-e 's/IR\[1011 /IR\[STI /' \
	-e 's/IR\[0111 /IR\[STR /' \
	-e 's/IR\[1111 /IR\[TRAP/' > DEBUG.ops
state18::
	cat DEBUG.ops | sed -n -e '/((( 18/,/----(/ p' > DEBUG.18only


kb_input::
	@echo 'Only Gods knows why you have to do this by hand:'
	@echo '   cat kb_input.txt | text2bin > kb_input.bin'
	@echo 'Type that into your keyboard.'
#--------------
# Set svn ignore
#-------------
ignore::
	printf "a.out\n*.v\n*.bin\nfoo*\nffo*\nfff*\n*.txt"  > foo
	svn propset --file foo svn:ignore .
	rm foo

clean::
	-rm *.out *.txt foo* *.v *.bin DEBUG*