Add discussion of ebreak w/examples

book/Makefile

@@ -1,9 +1,11 @@
+SUBDIRS=
+#	programs/src
+
 TOP=..
 include $(TOP)/Make.rules
 
-TEXPATH=./float:./intro:./rv32:./copyright:./license:./elements:binary
+TEXPATH=float:intro:rv32:copyright:license:elements:binary:programs/src
 
-SUBDIRS=
 
 all:: book.pdf
 

book/programs/chapter.tex

@@ -1,9 +1,42 @@
 \chapter{Writing RISC-V Programs}
 
 
-\enote{Introduce the register names and aliases here.  
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-Should we use ISA names or actual names here?}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Using {\tt ebreak} to Stop \rvddt{} Execution}
 
+The \insn{ebreak} instruction exists for the sole purpose of transferring control back 
+to a debugging environment.\cite[p.~24]{rvismv1v22:2017}
+
+When \rvddt{} executes an \insn{ebreak} instruction, it will immediately terminate any
+executing {\em trace} or {\em go} command currently executing and return to the
+command prompt without advancing the \reg{pc} register.  
+
+The machine language encoding shows that \insn{ebreak} has no operands.
+
+\DrawInsnTypeEPicture{ebreak}{00000000000100000000000001110011}
+
+\listingRef{ebreak/ebreak.out} demonstrates that since \rvddt{} does 
+not advance the \reg{pc} when it encounters an \insn{ebreak} instruction, 
+subsequent {\em trace} and/or {\em go} commands will re-execute the same \insn{ebreak} 
+and halt the simulation again (and again).  
+This feature is intended to help prevent overzealous users from accidently 
+running past the end of a code fragment.\footnote{This was one of the first {\em enhancements}
+I needed for myself \tt:-)}
+
+\listing{ebreak/ebreak.S}{A one-line \insn{ebreak} program.}
+
+\listing{ebreak/ebreak.out}{\insn{ebreak} stopps \rvddt{} without advancing \reg{pc}.}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{todo}
+
+
+\enote{Introduce the register names and aliases here.  
+Should we use ISA names or actual names here?}%
 Ideas for order of introducing operations and instructions.
 
 \section{Using {\tt addi} to Set Register Values}
@@ -20,9 +53,6 @@ Ideas for order of introducing operations and instructions.
 
 Demonstrate various addi instructions. 
 
-\section{Using {\tt ebreak} to Stopping rvddt Execution}
-
-Introduce ebreak \& demonstrate.
 
 
 \section{Other Instructions With Immediate Operands}

book/programs/src/Make.rules

@@ -0,0 +1,55 @@
+
+ARCH=riscv32-unknown-elf
+
+CC=$(ARCH)-gcc
+AS=$(ARCH)-as
+LD=$(ARCH)-ld
+OBJCOPY=$(ARCH)-objcopy
+OBJDUMP=$(ARCH)-objdump
+SIZE=$(ARCH)-size
+
+#LDFLAGS+=-nostdlib -Wl,-Ttext=0x0,-Tdata=0x8000
+LDFLAGS+=-nostdlib -Wl,-Ttext=0x0
+
+CFLAGS+=-ffreestanding -fno-pic
+CFLAGS+=-march=rv32i -mabi=ilp32
+CFLAGS+=-Wl,--no-relax			# see: https://github.com/riscv/riscv-gcc/issues/120
+
+ASFLAGS+=$(CFLAGS)
+
+CLEAN_DIRS=$(SUBDIRS:%=clean-%)
+ALL_DIRS=$(SUBDIRS:%=all-%)
+
+.PHONY: all clean world $(CLEAN_DIRS) $(ALL_DIRS)
+
+
+%.bin : %
+	$(OBJCOPY) $< -O binary $@
+
+%.lst : %
+	$(OBJDUMP) -dr $< > $<.lst
+
+% : %.o
+	$(LINK.c) $(LDFLAGS) -o $@ $^ $(LDLIBS)
+	$(SIZE) -x -A $@
+
+%.s: %.c
+	$(COMPILE.c) -S -o $@ $<
+
+%.srec: %
+	$(OBJCOPY) $< -O srec $@ 
+
+
+
+
+all:: $(ALL_DIRS)
+
+clean:: $(CLEAN_DIRS)
+
+$(ALL_DIRS)::
+	$(MAKE) -C $(@:all-%=%) all
+
+$(CLEAN_DIRS)::
+	$(MAKE) -C $(@:clean-%=%) clean
+
+world:: clean all

book/programs/src/Makefile

@@ -0,0 +1,6 @@
+
+SUBDIRS=\
+	ebreak
+
+TOP=.
+include $(TOP)/Make.rules

book/programs/src/ebreak/.gitignore

@@ -0,0 +1 @@
+load4regs

book/programs/src/ebreak/Makefile

@@ -0,0 +1,18 @@
+
+PROG=ebreak
+
+all:: $(PROG).out $(PROG).lst
+
+$(PROG).out:: $(PROG).bin
+	./run.sh > $@ 2>&1
+
+$(PROG).bin:: $(PROG)
+
+clean::
+	rm -f $(PROG) *.o *.lst *.bin *.srec *.out
+
+TOP=..
+include $(TOP)/Make.rules
+
+
+

book/programs/src/ebreak/ebreak.S

@@ -0,0 +1,6 @@
+	.text				# put this into the text section
+	.align	2			# align to a multiple of 4
+	.globl	_start
+
+_start:
+	ebreak

book/programs/src/ebreak/run.sh

@@ -0,0 +1,10 @@
+prompt="$" 
+cmd="rvddt -f ebreak.bin"
+echo "$prompt $cmd"
+$cmd <<!
+d 0 16
+t 0 1000
+t
+g 0
+r
+!