#------------------------------
# lc3/src/Makefile
#
# This file is a way to run commands and also
# provides documentation. It is in sections:
#  (D) "make usage" to get started.
#      See the bottom of this Makefile.
#  (1) compile and simulate verilog code w/ "iverilog", "vvp".
#  (2) lc3os.bin: assemble LC3 operating system from source, and
#      convert it to a format suitable for loading into memory
#      by iverilog's readmemb(). SEE (4) for tools needed.
#  (3) prog.bin: assemble and convert lc3 assembly program 
#      for verilog testbench as a user program (load to x3000).
#  (4) lc3tools: build and install assembler and other tools.
#  (4.5) Configure, build, and install the LC3 C compiler, lcc.
#  (4.6) Compile C code to LC3 assembly.
#  (5) kb: build keyboard interface, run simulation w/ kb.
#  (6) OS incremental builds, separate assembly, and so forth.
#  (M) source code linking for drivers; clean up.
#
# WARNING, THIS MAKEFILE DOCUMENTS SUGGESTED ACTIONS. YOU MAY
# HAVE TO DO THINGS DIFFERENTLY ON YOUR SYSTEM.
#

#-------------------------------------------------------------
#--(SECT 1)--------- compile/run verilog code.
#-- "testVerilogCompile_foo.v" is verilog source 
#-- for some device model, the device being tested.
# NB--" ;\" causes multiple commands to run in the same shell.

testVerilogCompile::
	cp testVerilogCompile_fooHeader.vh ../run
	cp testVerilogCompile_fooTestBench.v ../run
	cp testVerilogCompile_foo.v ../run
	cd ../run; \
	iverilog testVerilogCompile_fooHeader.vh \
		 testVerilogCompile_foo.v \
		 testVerilogCompile_fooTestBench.v; \
	vvp a.out

#-- Note: when testing assembly programs (not the LC3 design)
#-- we only need to compile the LC3 model once. We can then 
#-- reuse a.out, running our code via "vvp a.out".
#-- Library "lc3-run.jelib" is for that purpose. It has one
#-- testbench that reads "lc3os.bin" into memory at x0200.
#-- This fakes the boot process. You can add a readmemb line
#-- that also reads "prog.bin" into memory at x3000. This 
#-- fakes user program loading.

#-------------------------------------------------------------
#--(SECT 2)---- assemble and convert LC3 operating system code.
#--- (2.a) pre-process source code (see lc3pre).
#--- (2.b) Assemble the resulting .asm file.
#--- (2.c) Convert the .obj to for iverilog's readmemb().
#--- (2.d) Delete the first line, the ".ORIG" header.
#--- The result will be in ../run/lc3os.bin.
#--- NB--Edit the Make variable, OS, as needed, or
#--- commandline overide, e.g., "make lc3os.bin OS=testINT".

OS=lc3os-v1-bare
os.bin::
	@echo "###########################################"
	@echo "######### BUILDING lc3os.bin     ##########"
	@echo "######### from  ${OS}.asm        ##########"
	@echo "###########################################"
	@echo ""
	@echo "------ preprocessing --------"
	@echo ""
	cat ${OS}.asm | lc3pre > ${OS}_pre.asm
	@echo ""
	@echo "-------- assembling ---------"
	@echo ""
	lc3as ${OS}_pre.asm
	@echo ""
	@echo "-------- converting ---------"
	@echo ""
	cat ${OS}_pre.obj | obj2bin | sed '1d' > ${OS}_pre.bin
	@echo ""
	@echo "-------- copying to ../run ---------"
	@echo ""
	cp ${OS}_pre.bin ../run/lc3os.bin
	@echo ""
	@echo "-------- clean up -----------"
	@echo " DO make clean TO CLEAN UP"
	@echo ""
	@echo "##########################################"
	@echo "######## DONE BUILDING lc3os.bin  ########"
	@echo "##########################################"

#-------------------------------------------------------------
#--(SECT 3)- Assemble/convert a user program.
#-- The result will be in ../run/<filename>.bin.
#-- NB--Edit the Make variable, PROG, as needed, or
#-- commandline overide, e.g., "make prog.bin PROG=testINT".

PROG=testALLinstrRTI
prog.bin::
	@echo "###########################################"
	@echo "######### BUILDING ${PROG}.bin   ##########"
	@echo "######### from  ${PROG}.asm      ##########"
	@echo "###########################################"
	@echo ""
	@echo "------ preprocessing --------"
	@echo ""
	cat ${PROG}.asm | lc3pre > ${PROG}_pre.asm
	@echo ""
	@echo "-------- assembling ---------"
	@echo ""
	lc3as ${PROG}_pre.asm
	@echo ""
	@echo "-------- converting ---------"
	@echo ""
	cat ${PROG}_pre.obj | obj2bin | sed '1d'>${PROG}_pre.bin
	@echo ""
	@echo "-------- copying to ../run ---------"
	@echo ""
	cp ${PROG}_pre.bin ../run/${PROG}.bin
	@echo ""
	@echo "-------- clean up -----------"
	@echo " DO make clean TO CLEAN UP"
	@echo "##########################################"
	@echo "######## DONE BUILDING ${PROG}.bin #######"
	@echo "##########################################"

#-------------------------------------------------------------
#--(SECT 4.)---tools
# Build and install the assembler, file format converter,
# lc3 stand-alone simulator, compiler, and so forth.
# The lc3as assembler for unix is built from the
# lc3tools_v12.zip sources, with its own configure and 
# Makefile. See the lc3tools_v12/README if the make fails.
# Builds for other tools (lc3as, obj2bin, ...) are shown below. 

lc3tools::
	@echo "You must set your PATH environment variables."
	@echo "DO"
	@echo "    make Path"
	@echo "to see instructions."
	@echo "DO"
	@echo "    make usage"
	@echo "to see other instructions."
	make ../bin/lc3as
	make ../bin/obj2bin
	make ../bin/unix2dosEOLN
	make ../bin/kb
	make ../bin/text2bin
	make ../bin/lc3pre

../bin/lc3as: lc3tools_v12.zip
	unzip lc3tools_v12.zip
	cd lc3tools; ./configure ; make
	-cp ./lc3tools/lc3as ../bin
	-cp ./lc3tools/lc3convert ../bin
	-cp ./lc3tools/lc3sim ../bin
	-cp ./lc3tools/lc3sim-tk ../bin
	-cp ./lc3tools/lc3as.exe ../bin
	-cp ./lc3tools/lc3convert.exe ../bin
	-cp ./lc3tools/lc3sim.exe ../bin
	@echo "If copy failed, are tools in ../bin complete?"
	@echo "You only need one of lc3as or lc3as.exe, e.g."

../bin/obj2bin: obj2bin.c
	cc obj2bin.c -o ../bin/obj2bin

../bin/unix2dosEOLN: unix2msEOLN.c
	cc unix2msEOLN.c -o ../bin/unix2dosEOLN

../bin/text2bin: text2bin.c
	cc -o ../bin/text2bin text2bin.c

../bin/lc3pre: lc3pre
	cp lc3pre ../bin/lc3pre

#-------------------------------------------------------------
#--(SECT 4.5)------ Build the C compiler, lcc.
lcc::
	@echo '-----------------------------'
	cd ../bin; unzip ../src/lcc.zip
	@echo 'Alter configuration file by hand to build lcc:'
	@echo '1: cd ../bin/lcc-1.3.'
	@echo '2: vi configure'
	@echo '3: Change INSTALL_DIR and TOP_DIR, e.g., '
	@echo '  INSTALL_DIR=/Users/squier/LC3dev/trunk/bin'
	@echo '  TOP_DIR=/Users/squier/LC3dev/trunk/bin/lcc-1.3'
	@echo ' Use full pathname to bin directory. Do not use'
	@echo ' pathnames with embedded spaces, see'
	@echo '   make PATH'
	@echo '4: sh configure'
	@echo '5: make'
	@echo '6: make install'
	@echo '7: cd ..; ./lcc fig.16.14.c'
	@echo 'If that goes well, you are set.'
	@echo '-----------------------------'

#-------------------------------------------------------------
#--(SECT 4.6)------ Compile LC3 C code to LC3 assembly code.
CSRC=myC
cc::
	lcc ${CSRC}.c

#-- Gives "a.asm" along w/ "a.sym" and "a.obj". If "main" is not
#-- a function in myC.c, the complaint can be ignored: We
#-- and hand link with other assembly sources. See docs
#-- for an explanation of lcc's .asm.

#--(SECT 5.)--- Keyboard interface and runtime simulation:
#-- kb.c forks and execs "vvp a.out" to run verilog simulation.
#-- The lc3 display output goes to the controlling window.

../bin/kb: kb.c kbIn.v
	cc kb.c -o ../bin/kb

#-- This next is an example of kb usage with a testbench.v.
#-- We assume that testbench.v is an LC3 simulation.
#-- The point is to have the testbench ready for kb to run it.
#-- kb runs "vvp a.out"; the compiled testbench must be "a.out",
#-- which is the default for iverilog.
#-- The "; \" causes all three commands to run in same shell.

kbrun::                
	cd ../run; \
	iverilog testbench.v; \
	../bin/kb

#-------------------------------------------------------------
#--(SECT 6.)-- OS incremental builds, separate module assembly.
#-------------------------------------------------------------

ASM=putc
as::
	@echo "------ preprocessing --------"
	cat ${ASM}.asm | lc3pre > ${ASM}_pre.asm
	@echo "-------- assembling ---------"
	lc3as ${ASM}_pre.asm

DST=puts_driver
SRC=puts
addST::
	echo "// ${SRC}------------" >> ${DST}_st.asm
	cat ${SRC}_pre.sym >> ${DST}_st.asm

1ST=putc_driver
2ND=putc
link::
	cat ${2ND}_pre.obj | sed 's/..//'>${2ND}.obj
	cat ${1ST}_pre.obj ${2ND}.obj > ${1ST}.obj

OBJ=putc_driver
2bin::
	cat ${OBJ}.obj | obj2bin | sed '1d' > ${OBJ}.bin

#-------------------------------------------------------------
#--(SECT M)-- misc.: Source code linking for drivers; clean.

putc_driver: putc_driver.asm putc.asm
	echo ".ORIG x0200" > putcd.asm
	cat putc_driver.asm putc.asm >> putcd.asm
	echo ".END" >> putcd.asm
	make os.bin 'OS=putcd'

puts_driver: puts_driver.asm puts.asm putc.asm
	echo ".ORIG x0200" > putsd.asm
	cat puts_driver.asm puts.asm >> putsd.asm
	cat putc.asm >> putsd.asm
	echo ".END" >> putsd.asm
	make os.bin 'OS=putsd'

kbsvc_driver: kbsvc_driver.asm kbsvc.asm puts.asm putc.asm
	echo ".ORIG x0200" > kbd.asm
	cat kbsvc_driver.asm kbsvc.asm >> kbd.asm
	cat puts.asm putc.asm >> kbd.asm
	cat ints.asm >> kbd.asm
	echo ".END" >> kbd.asm
	make os.bin 'OS=kbd'

clean::
	-rm *.obj *.bin *.sym *.lst *.hex a.out a.exe _*.asm 
	-rm _lc3pre* *_pre.asm putcd* putsd* kbd*

#-------------------------------------------------------------
#--(SECT D)-- Documentation
usage::
	@echo 'documentation:'
	@echo ' make TOOLS'
	@echo ' make PATH'
	@echo ' make PRE'
	@echo ' make SIM'
	@echo ' make DEBUG'
	@echo ' '
	@echo 'actions:'
	@echo ' make testVerilogCompile'
	@echo ' make os.bin OS=lc3os'
	@echo ' make prog.bin PROG=testVID'
	@echo ' make lc3tools'
	@echo ' make lcc'
	@echo ' make cc C=foo'
	@echo ' make kbrun'
	@echo ' make as ASM=putc'
	@echo ' make link 1ST=putc_driver 2ND=putc'
	@echo ' make addST DST=puts_driver SRC=puts'
	@echo ' make 2bin OBJ=putc_driver'
	@echo ' make clean'
PATH::
	@echo 'PATH--------- Set your shell PATH variable'
	@echo 'to your "bin" directory. For bash:'
	@echo '  cd '
	@echo '  vi .bash_profile'
	@echo '  PATH=<pathToBin>:$${PATH}'
	@echo 'where <pathToBin> is the full pathname to'
	@echo 'your trunk/bin. NB--You cannot have'
	@echo 'embedded spaces in <pathToBin>. If so,'
	@echo '  ln -s <path> <link>'
	@echo 'E.g.,'
	@echo '  pwd'
	@echo ' ".../squier/Documents/My\ Documents/trunk"'
	@echo '  cd'
	@echo '  ln -s Documents/My\ Documents/trunk foo'
	@echo '  PATH=<pre>/squier/foo/bin:$${PATH}'
	@echo 'where <pre> is the path prefix.'
	@echo '-------------------------'
PRE::
	@echo '-----PRE-PROCESSING source code.'
	@echo 'Extend a language, make it readable:'
	@echo 'sed provides string substitution and m4 '
	@echo 'provides string substition with arguments.'
	@echo 'Files:'
	@echo '-- lc3pre_Language_Extensions.txt: a summary'
	@echo '-- lc3pre: sed/m4 assembly pre-processor'
	@echo '-------------------------'
BIN::
	@echo '----Object file (.obj) conversion.'
	@echo 'Assembler's .obj output is "pure" binary;'
	@echo 'verilog's readmemb() reads text files.'
	@echo 'Our .bin file format is a text version'
	@echo 'of .obj: each pure binary 16-bit word in'
	@echo '.obj file is translated to a 16-char text'
	@echo 'line ascii chars, '0' and '1', giving the'
	@echo 'word's value in base 2 notation. The .obj'
	@echo 'header, i.e., .ORIG info, is stripped off:'
	@echo 'it is meaningless to readmemb().'
	@echo '-------------------------'

SIM::
	@echo '------Simulation Environment.'
	@echo 'Verilog simulation will be run in trunk/run. In'
	@echo 'most of our verilog testbench code, readmemb()'
	@echo 'reads a file, eg. "lc3os.bin". Files need to'
	@echo 'be in trunk/run. Defaults for this Makefile put'
	@echo '.bin files there.
	@echo '-------------------------'

TOOLS::
	@echo '----TOOLS, Building tools.'
	@echo 'C compiler, assembler-linker, converter, '
	@echo '(lcc, lc3as, obj2bin) need to be compiled'
	@echo 'from C sources (e.g., lc3tools_v12.zip).'
	@echo '   make lc3tools'
	@echo '   make lcc'
	@echo '-------------------------'
	@echo 'Other tools: ------------'
	@echo 'lc3diff, compares two directories for changes.'
	@echo 'Standard tools you should know/use: '
	@echo '  shell scripts, sed, m4, diff, cmp '
	@echo '  ps, od, make, cat, find, grep, bash'
	@echo '  ln, "|", ">", "<", awk, kill'

DEBUG::
	@echo ' ---- Debugging simulators'
	@echo ' Standalone LC3 debuggers, e.g., PennSim.jar,'
	@echo ' are good for quick coding experiments: Load'
	@echo ' an .obj and see how it works. NB--LC3'
	@echo ' architectures do not correspond exactly'
	@echo ' with our LC3 design, and have restrictions,'
	@echo ' e.g., interrupts are not implemented. '