PiDP-8/I Software

# Some *.py files are generated by Autosetup, so they need different
# handling than the other libraries for the out-of-tree build case.
PIDP8I_DIRS := lib/pidp8i/dirs.py
PIDP8I_DIN  := @srcdir@/$(PIDP8I_DIRS).in
GENNED_PY   := \
	lib/pidp8i/__init__.py \
	lib/pidp8i/ips.py \
	lib/pidp8i/os8opts.py \
	$(PIDP8I_DIRS)

SIMH_PY     := lib/simh.py
SIMH_PY_SRC := @srcdir@/$(SIMH_PY)

OS8RUN        = bin/os8-run
OS8SCRIPT      := lib/os8script.py
OS8CP	      := bin/os8-cp



OS8RUN_PY_ALL  := $(GENNED_PY) $(OS8SCRIPT) $(SIMH_PY_SRC)
OS8RUN_SRCS    := $(OS8RUN) $(OS8RUN_PY_ALL) $(PIDP8I_DIN)

# If you edit this directory list, you should probably also edit
# the argument list to the mkadrules call in auto.def!
BUILDDIRS := \
	bin \
	libexec \
	obj/cc8/cross \
	obj/d8tape \
	obj/misc \
	obj/palbart \
	obj/pidp8i \
	obj/SIMH \
	obj/SIMH/PDP8

INSTDIRS := bin etc lib/pidp8i libexec share/boot share/media share/include share/man/man1

SIM_OBJS := \
	obj/pidp8i/gpio-common.o \
	obj/pidp8i/main.o \
	obj/SIMH/PDP8/pdp8_df.o \
	obj/SIMH/PDP8/pdp8_cpu.o \
	obj/SIMH/PDP8/pdp8_clk.o \

PALBART_OBJS := obj/palbart/palbart.o

ifeq (@BUILD_DEEPER_THOUGHT@, 1)
BINS += bin/deeper
endif

TEST_TMP_BINS = bin/ptp2txt bin/pidp8i-sim bin/os8-run

LIBS = -lm -ldl -lpthread

ASM_PTS     := $(wildcard @srcdir@/src/asm/*.pal)
ASM_PTS     := $(subst @srcdir@/src/asm,bin,$(ASM_PTS))
ASM_PTS     := $(ASM_PTS:.pal=-pal.pt)
FC_EX_PTS   := $(wildcard @srcdir@/examples/*.fc)
FC_EX_PTS   := $(subst @srcdir@/examples,bin,$(FC_EX_PTS))

	boot/1.script \
	boot/5.script

# List of *.in files from auto.def file, except for this present file
# (Makefile.in) which is handled separately.  This list should only
# change when the list of "make-template" calls in auto.def changes.
# 
# The OS8RUN_INFILES set of files are those which, if changed, require
# rebuilding the OS/8 media.  Touching the combined set merely causes
# a reconfig and build.
#
# The PRECIOUS set are those whose outfiles we want make(1) to treat as
# "precious", meaning it won't delete files generated by a target if the
# rule being processed to create that target fails.
# 
# The rest have no special treatment.
OS8RUN_INFILES = \
	@srcdir@/lib/pidp8i/__init__.py.in \
	@srcdir@/lib/pidp8i/ips.py.in \
	@srcdir@/media/os8/init.tx.in \
	@srcdir@/media/os8/3finit.tx.in \
	@srcdir@/src/pidp8i/main.c.in \
	$(PIDP8I_DIN)
PRECIOUS_INFILES = \
	@srcdir@/Makefile.in \
    @srcdir@/examples/Makefile.in \
    @srcdir@/src/Makefile.in \
    @srcdir@/src/cc8/Makefile.in \
    @srcdir@/src/SIMH/Makefile.in \
    @srcdir@/src/SIMH/PDP8/Makefile.in
INFILES = \
	@srcdir@/bin/pidp8i.in \
	@srcdir@/boot/0.script.in \
	@srcdir@/boot/2.script.in \
	@srcdir@/boot/3.script.in \
	@srcdir@/boot/4.script.in \
	@srcdir@/boot/6.script.in \
	@srcdir@/boot/7.script.in \
	@srcdir@/boot/run.script.in \
	@srcdir@/boot/run-v3f.script.in \
	@srcdir@/etc/pidp8i.service.in \
	@srcdir@/etc/sudoers.in \
	@srcdir@/etc/usb-mount@.service.in \
	@srcdir@/src/pidp8i/gpio-common.c.in \
	@srcdir@/tools/simh-update.in \
	$(OS8CP) \
	$(OS8RUN_INFILES)
OS8RUN_OUTFILES := $(subst @srcdir@/,,$(OS8RUN_INFILES))
OS8RUN_OUTFILES := $(subst .in,,$(OS8RUN_OUTFILES))
PRECIOUS_OUTFILES := $(subst @srcdir@/,,$(PRECIOUS_INFILES))
PRECIOUS_OUTFILES := $(subst .in,,$(PRECIOUS_OUTFILES))
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(OUTFILES))

OS8_DIST_RK05 = bin/v3d-dist.rk05
OS8_SRC_RK05 = @OS8_SRC_RK05@
OS8_BOOT_DISK = bin/@OS8_BOOT_DISK@
OS8_RK05S = $(OS8_DIST_RK05) $(OS8_BOOT_DISK) $(OS8_SRC_RK05)

OS8_SCRIPTS_DIR = @srcdir@/media/os8/scripts

V3D_DIST_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-dist-rk05.os8
V3D_SRC_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-src-rk05.os8
V3D_RK05_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-rk05.os8

OS8CP := bin/os8-cp

V3F_SRCDIR = @srcdir@/src/os8/v3f
V3F_BUILD_RK05 = obj/v3f-build.rk05
V3F_MANIFEST = actions.txt

V3F_MADE_RK05 = bin/v3f-made.rk05

V3F_MAKER = $(OS8_SCRIPTS_DIR)/v3f-control.os8

ALL_TU56_SCRIPT = $(OS8_SCRIPTS_DIR)/all-tu56.os8

CUSP_COPYIN_SCRIPT = $(OS8_SCRIPTS_DIR)/cusp-copyin.os8

OS8_BOOT_TAPE = bin/@OS8_BOOT_TAPE@
V3D_TC08_TU56 = bin/v3d-tc08.tu56
V3D_TD12K_TU56 = bin/v3d-td12k.tu56
V3F_TC08_TU56 = bin/v3f-tc08.tu56
V3F_TD12K_TU56 = bin/v3f-td12k.tu56
V3F_BOOT_TAPE= bin/v3f-@OS8_TAPE_DEVICE@.tu56

CLTXT = /boot/cmdline.txt

ADF := adrules.mk


#### TARGETS ###########################################################

.PHONY: all tags
.PRECIOUS: $(PRECIOUS_OUTFILES)

all: \
	$(OUTFILES) $(PRECIOUS_OUTFILES) \
	$(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) \
	$(ASM_PTS) $(FC_EX_PTS) $(PAL_EX_PTS) \
	$(OS8_RK05S) $(V3F_MADE_RK05) $(V3D_TC08_TU56) \
	$(V3D_TD12K_TU56) $(V3F_TC08_TU56) $(V3F_TD12K_TU56)

clean:
	@rm -f $(BINS) $(BOOTSCRIPTS) $(ASM_PTS) $(PAL_EX_PTS) $(LISTINGS) \
		$(OUTFILES) $(ADF) \
		$(OS8_RK05S) $(V3F_MADE_RK05) $(V3F_BUILD_RK05) $(V3D_TC08_TU56) \
		$(V3D_TD12K_TU56) $(V3F_TC08_TU56) $(V3F_TD12K_TU56) \
		config.log cscope.out tags \
		bin/*.pt  bin/*.save bin/txt2ptp \
		lib/*.pyc lib/*/*.pyc lib/pidp8i/dirs.py lib/pidp8i/ips.py \
		obj/*.log obj/*.pt obj/os8.opts \
		src/config.h \
		@srcdir@/examples/*.err
	@find obj \( -name \*.o -o -name \*.d \) -delete
	@-rmdir -p $(BUILDDIRS) 2> /dev/null || true

distclean: clean
	@rm -f \
		$(PRECIOUS_OUTFILES) \
		config.log \
		autosetup/jimsh0 \
		src/config.h

ctags tags:
	ctags -R @srcdir@/src @srcdir@/lib
ifeq (@HAVE_PROG_CSCOPE@, 1)
	@cscope -bR -s@srcdir@
endif

install: all instdirs
	@echo Installing to @prefix@...

	)
	@(test -x /sbin/setcap && \
		for f in @prefix@/bin/pidp8i-* ; do \
			echo "Setting real-time priority capabilities on $$(basename $$f)..." ; \
			/sbin/setcap 'cap_sys_nice=eip' $$f ; \
		done \
	) || true
	@test -e @MEDIADIR@/os8/local.tu56 && \
		echo "Skipping media image and SIMH boot script reinstall." || \
		$(MAKE) mediainstall

	@# If this is a Debian-type system, install needed helper programs
	@test -x /usr/bin/apt-get -a ! -x /usr/bin/screen && apt-get -y install screen || true

	@# Remove usbmount: we've replaced that with bin/usb-mount and friends.

		@INSTALL@ -m 755 bin/cc8 @prefix@/bin && \
		@INSTALL@ -m 644 @srcdir@/src/cc8/include/* @prefix@/share/include

	@# Install palbart stuff
	@@INSTALL@ -m 755 bin/palbart @prefix@/bin
	@@INSTALL@ -m 644 @srcdir@/src/palbart/palbart.1 @prefix@/share/man/man1

	@# Install os8-run and its dependencies
	@echo "Installing os8run..."
	@@INSTALL@ -m 775 -g @INSTGRP@ $(OS8RUN) @prefix@/bin
	@( for src in $(OS8RUN_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=@prefix@/$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}c $${dest}c ; \
	  done \
	)

	@echo "Creating installation directory tree..."
	@for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -d @prefix@/$$d ; done

mediainstall: instdirs
	@echo "[Re]installing OS and program media..."
	@cd @srcdir@ ; \
	find media \( \
		-name \*.os8 -o \
		-name \*.bin  -o \
		-name \*.dsk  -o \
		-name \*.rk05 -o \
		-name \*.tu56 \
	\) -exec @INSTALL@ -D -m 664 -o @INSTUSR@ -g @INSTGRP@ {} @ABSPREFIX@/share/{} \;
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.rk05 @ABSPREFIX@/share/media/os8
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.tu56 @ABSPREFIX@/share/media/os8
	@@INSTALL@ -m 664 -o @INSTUSR@ -g @INSTGRP@ boot/*.script @BOOTDIR@


# For reasons I do not understand, the two runs of os8-run create new
# log files rather than appending the second run to the first file.

# We need both logs, so we take steps to get them with mv, and cat.
os8-sys: test-tmp-tools
	$(OS8RUN)@OS8_OPTS@ $(V3D_DIST_SCRIPT)
	mv obj/os8-run.log obj/os8-run1.log
	$(OS8RUN)@OS8_OPTS@ $(V3D_RK05_SCRIPT)
	mv obj/os8-run.log obj/os8-run2.log
	cat obj/os8-run1.log obj/os8-run2.log >obj/os8-run.log

reconfig:
	@AUTOREMAKE@

release: all
	@srcdir@/tools/mkrel

run: $(SIM)
	$(SIM) boot/run.script

runf run-v3f: $(SIM) $(V3F_BOOT_TAPE)
	$(SIM) boot/run-v3f.script

run-tss8: $(SIM)
	$(SIM) boot/tss8.script

simh-update simh-update-f:
	@@srcdir@/tools/simh-update $(subst simh-update,,$@)

# Enable this target only if all of the test-os8-run prereqs
# were installed at configure time.
ifeq (@CAN_TEST_OS8_RUN@, 1)
test-os8-run:
	tools/test-os8-run
endif

test-tmp-tools:
	@echo "Installing os8run dependencies..."
	@( for src in $(OS8RUN_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=./$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}c $${dest}c ; \
	  done \
	)
	@( for src in $(TEST_TMP_BINS) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=./$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 755 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	  done \
	)
	@( cd ./bin ; \
	   echo "Installing txt2ptp symlink..." ; \
	   ln -f ptp2txt txt2ptp ; \
	)


# Build the OS/8 binary media needed by 0.script.
#
# We use order-only prerequisites for the simulator here because we only
# care that it *exists*, not whether it is newer than the previously
# built RK05 media or not.
#
# Also notice that the init.tx file is not a prerequisite: we purposely
# do not rebiuld the RK05 media just because the configure script was
# re-run, which *always* regenerates the init.tx file because the
# timestamp always changes from one run to the next.  (Until computers
# get fast enough to do a complete re-configure in under a second,
# anyway!)  The thing is, we only want the RK05 bin media rebuilt when
# the configure --*-os8-* options change.  *That* is when we care about
# the updated init.tx file, not before.  We needn't even make it an
# order-only prereq because configure and the INFILES rules above ensure
# that it always exists.
V3D_DIST_SRCS := \
	$(OS8RUN) $(PIDP8I_DIN) \
	lib/pidp8i/dirs.py \
	$(V3D_DIST_SCRIPT) \
	@srcdir@/media/os8/al-*-ba-*.tu56 \
	@srcdir@/media/os8/subsys/*.tu56

# Temporary: We depend on ALL the patches, but really we've picked them over.
V3D_PATCHES := \
	@srcdir@/media/os8/patches/*.patch8

# Dependency on the contents of the v3f source directory.
V3F_SOURCES := \
	@srcdir@/src/os8/v3f/*.PA \
	@srcdir@/src/os8/v3f/*.MA \
	@srcdir@/src/os8/v3f/*.BI


$(OS8_DIST_RK05): $(V3D_DIST_SRCS) | $(SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_DIST_SCRIPT)

$(OS8_BOOT_DISK): $(V3D_RK05_SCRIPT) $(OS8_DIST_RK05) $(V3D_PATCHES) | $(SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_RK05_SCRIPT)


# Also build an OS/8 source disk, as a convenience to avoid the 
# need to mount up the 7 source tapes in succession.
#
# Using an order-only dependency for the simulator and the bin disk: we
# only need *a* version of each, they don't have to be recent!
OS8_SRC_SRCS = \
	$(OS8RUN) $(PIDP8I_DIN) \
	lib/pidp8i/dirs.py \
	$(V3D_SRC_SCRIPT) \
	@srcdir@/media/os8/al-*-sa-*.tu56

$(OS8_SRC_RK05): $(OS8_DIST_RK05) $(OS8_SRC_SRCS) | $(SIM) $(OS8_BOOT_DISK)
	$(OS8RUN)@OS8_OPTS@ $(V3D_SRC_SCRIPT)

# Build the source disk for OS/8 V3F
$(V3F_BUILD_RK05): $(V3F_SRCDIR)/$(V3F_MANIFEST) $(V3F_SOURCES) | $(OS8_BOOT_DISK)
	cd $(V3F_SRCDIR); @builddir@/$(OS8CP) -v --action-file $(V3F_MANIFEST)

# Make a disk with binaries assembled from the V3F source disk
$(V3F_MADE_RK05): $(V3F_BUILD_RK05) $(V3F_MAKER)
	$(OS8RUN) $(V3F_MAKER)

# Make a bootable OS/8 v3f TCO8 DECtape image
$(V3F_TC08_TU56): $(V3F_MADE_RK05) $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT)
	$(OS8RUN) $(ALL_TU56_SCRIPT) --enable v3f

# Make a bootable OS/8 v3f TD8E 12K DECtape image
$(V3F_TD12K_TU56): $(V3F_MADE_RK05) $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT)
	$(OS8RUN) $(ALL_TU56_SCRIPT) --enable v3f --enable td12k

# Make a bootable OS/8 v3d TCO8 DECtape image
$(V3D_TC08_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_BOOT_DISK) 
	$(OS8RUN) $(ALL_TU56_SCRIPT)

# Make a bootable OS/8 v3d TD8E 12K DECtape image
$(V3D_TD12K_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_BOOT_DISK) 
	$(OS8RUN) $(ALL_TU56_SCRIPT) --enable td12k

# Rule for building PAL assembly language programs in src/asm/*.pal.
obj/%.lst bin/%-pal.pt: @srcdir@/src/asm/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/src/asm/$*.lst obj
	mv @srcdir@/src/asm/$*.rim bin/$*-pal.pt

# We purposely list only one of the OUTFILES on the left hand side
# because to list them all is to invite Make to run N copies of the
# configure script in parallel up to the limit of -j or the number of
# files in INFILES, whichever is lower.  Order-only prerequisites can't
# help here (|) as that only affects the right hand side.
ifeq ($(findstring clean,$(MAKECMDGOALS)),)
media/os8/init.tx: $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
	@AUTOREMAKE@ && $(MAKE)
media/os8/3finit.tx: $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
	@AUTOREMAKE@ && $(MAKE)

# Also do it if the autodep tool is newer than its output, suggesting
# that if re-run, it would generate different output.
$(ADF): @srcdir@/tools/mkadrules
	@AUTOREMAKE@ && $(MAKE)
endif

*   **--disable-os8-k12** - Leave out the Kermit-12 implementation
    normally installed to `RKA0:`

*   **--disable-os8-macrel** - Leave the MACREL v2 assembler and its
    associated FUTIL V8B tool out.





*   **--disable-os8-src** - Do not build the `os8v3d-src.rk05` disk
    image from the OS/8 source tapes.  This is not controlled by
    `--os8-minimal` because that only affects `os8v3d-bin.rk05`.

*   **--disable-os8-uwfocal** - Leave out the U/W FOCAL V4E programming
    environment normally installed to `RKA0:`.
    

You can read more about this [in the wiki][oce].

[oce]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+Console+TTY+Setup


### Patches

The build process creates a baseline disk image called `v3d-dist.rk05`.
This is considered a read-only master. Then a copy is made called

`v3d.rk05`. This is the default OS/8 rk05 image assigned to the IF=0 and IF=7
boot options.

In keeping with the standards of good systm management
this image incorporates all mandatory patches, as well as
optional patches appropriate to proper operation of the system.
For details on the available patches, the selection criteria,
and information about other optional patches see the [OS/8 system patches][os8p]
document.

[bdt2]:  https://tangentsoft.com/pidp8i/file/media/os8/al-4712c-ba-os8-v3d-2.1978.tu56
[cl]:    https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md
[cs]:    https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[mkos8]: https://tangentsoft.com/pidp8i/doc/trunk/libexec/mkos8
[os8mf]: https://tangentsoft.com/pidp8i/file/media/os8
[tlrm]:  https://tangentsoft.com/pidp8i/doc/trunk/README.md

    alt-serial-mod    => "use GPIO drive scheme suitable for James L-W's serial mod method"
    cc8-cross=1       => "do not build the cc8 cross-compiler on the host"
    debug-mode        => "create a debug build (default is release)"
    lowercase:        => "select how lowercase input is to be handled"
    no-lamp-simulator => "use simple LED driver instead of incandescent lamp simulator"
    os8-focal=1       => "leave FOCAL 69 and U/W FOCAL off the built OS/8 RK05 image"
    os8-minimal       => "set all --disable-os8-* options, giving minimal OS/8 bin disk"

    os8-src=1         => "do not build v3d-src.rk05 from OS/8 source tapes"
    serial-mod        => "use GPIO drive scheme suitable for Oscar Vermeulen's serial mod method"
    throttle:         => "override the throttle values in the boot scripts"
    usb-automount=1   => "do not automatically mount USB drives for SING_STEP + DF"
    boot-tape-config:  => "Boot tape configuration: tc08, or td12k"
    boot-tape-version: => "OS/8 version for boot tape, either v3d or v3f"
}

options $alloptions

# use btc and btv to set defaults because I can't get the documented
# syntax of <name>:=<value> to work.

# Default boot-tape-config is tc08
set btc [opt-val boot-tape-config]
if {$btc eq ""} {set btc "tc08"}

# Default boot-tape-version is v3d
set btv [opt-val boot-tape-version]
if {$btv eq ""} {set btv "v3d"}

define USB_AUTOMOUNT [opt-bool usb-automount]

# Make our own array of os8 options so we can apply the meta options
foreach {opt def desc} $os8opts {
    set os8bool($opt) [opt-bool os8-$opt]
}
set os8bool(src) [opt-bool os8-src]

# Handle interdependent options
if {$os8bool(cc8) && !$os8bool(fortran-ii)} {
    set $os8bool(fortran-ii) 1
    msg-result "WARNING: Re-enabling OS/8 FORTRAN II: OS/8 CC8 requires it."
}

# Now build the options to mkos8
set os8_opts ""
foreach {opt def desc} $os8opts {
    set val $os8bool($opt)
    if {$os8min} {
        # Minimal mode disables everything optional.
        #
        # We can't have "except for" logic because we can't tell
        # explicitly-given options from implicit ones.
        set act " not"
        if {$def} { append os8_opts " --disable $opt" }
    } elseif {$val} {
        set act ""
        if {!$def} {
            # User is enabling a normally-disabled option, so pass it along
            # to mkos8 explicitly.
            append os8_opts " --enable $opt"
        }
    } else {
        set act " not"
        if {$def} {
            append os8_opts " --disable $opt"
        }
    }
    msg-result "Will$act add $desc to the built OS/8 RK05 image"
}

# And generate lib/pidp8i/os8opts.py
set os "# GENERATED BY auto.def; DO NOT MODIFY.\n\nopts = {\n"
foreach {opt def desc} $os8opts {
    set act [expr {$def ? "Leave $desc off" : "Add $desc to"}]
    append os "\t\"" $opt "\": \[ $def,\
        \"$act the built OS/8 RK05 image\" \],\n"
}
append os "}\n"     ; # saved later!

# Handle the OS/8 options not passed to mkos8 generically by above.
if {$os8src} {
    msg-result "Building v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 bin/v3d-src.rk05
} else {
    msg-result "Will not build v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 {}
}
# Define our boot image. (Note, we ALWAYS apply patches.)

define OS8_BOOT_DISK "v3d.rk05"

# Compose our boot tape image name from boot-tape-config and boot-tape-version
# Pull defaults from $btc for boot-tape-config, and $btv for boot-tape-version.

set btn "$btv-$btc.tu56"

msg-result "Boot tape name: $btn"

define OS8_BOOT_TAPE $btn
define OS8_TAPE_DEVICE $btc
if {$btc eq "tc08"} {
    define SIMH_TAPE_DEVICE "dt"
} else {
    define SIMH_TAPE_DEVICE "td"
}    


# React to remaining chosen command line options
if {[opt-bool alt-serial-mod]} {
    if {[opt-bool serial-mod]} {
        user-error "You cannot request both --alt-serial-mod and --serial-mod!"
    }

set lv [opt-val lowercase]
if {$lv == ""} { set lv "auto" }
if {$lv == "auto"} {
    define SIMH_PASS_LOWERCASE
} elseif {$lv == "pass"} {
    define SIMH_PASS_LOWERCASE
    append os8_opts " --disable lcmod"
} elseif {$lv == "upper"} {
    append os8_opts " --disable lcmod"
} else {
    user-error "Legal values for --lowercase are {auto,pass,upper}."
}
msg-result "Lowercase handling set to '$lv' mode."

# We've purposely held off exporting the mkos8 option set until now
# because some of the configuration options can affect the option set.
define OS8_OPTS $os8_opts
if {![file exists "lib/pidp8i"]} { file mkdir "lib/pidp8i" }
if {![file exists "obj/pidp8i"]} { file mkdir "obj/pidp8i" }
if {![file exists "obj/SIMH/PDP8"]} { file mkdir "obj/SIMH/PDP8" }
write-if-changed "lib/pidp8i/os8opts.py" $os

# Force a rebuild of the OS/8 media if the option set changed.
if {![file exists "obj"]} { file mkdir "obj" }
write-if-changed "obj/os8.opts" $os8_opts {
    file delete -force bin/v3d-dist.rk05
    msg-result "os8 options changed; will rebuild OS/8 disk images."
}

# High-level definitions
set builddir [get-define builddir]
set srcdir [get-define srcdir]
set cores [exec $srcdir/tools/corecount]

# Get host, user, and date info for use by media/os8/init.tx.
catch {exec hostname} host
set user $::env(USER)
define BUILDUSER "$user@$host"
define BUILDTS [clock format [clock seconds] -format "%Y.%m.%d at %T %Z"]

# The os8-run script requires Python and some non-core modules.
set status [catch {exec python -c exit} result]
if {$status != 0} {
    user-error "Python does not appear to be installed here.  It is required."
}
msg-result "Python is installed here."
set status [catch {exec python -c "import pexpect" 2> /dev/null} result]
if {$status != 0} {

    append msg "\nOR:\n"
    append msg "\n    sudo easy_install pkg_resources\n"
    append msg "\nOR:\n"
    append msg "\n    sudo apt install python-pkg-resources\n"
    user-error $msg
}
msg-result "Python module pkg_resources is installed here."

# Check for Perl and that it can run the test corpus builder.  Not fatal
# if it can't, since only developers and deep testers need it.
set status [catch {exec perl -e exit} result]
if {$status == 0} {
    set status [catch {exec perl -c "[get-define srcdir]/tools/test-os8-run" 2> /dev/null} result]
    if {$status == 0} {
        set status [catch {exec lz4 -h 2> /dev/null} result]
        if {$status == 0} {
            msg-result "All test-os8-run prereqs available here."
            define CAN_TEST_OS8_RUN 1
        } else {
            msg-result "Cannot test-os8-run without lz4; try apt install liblz4-tool."
        }
    } else {
        msg-result "Cannot test-os8-run: fix with 'sudo cpanm --installdeps .'"
    }
} else {
    msg-result "Cannot test-os8-run: Perl is not available."
}

# Build Deeper Thought if we find it here
if {[file exists "[get-define srcdir]/src/misc/deeper.c"]} {
    set ls [string toupper "[get-define LED_DRIVER_MODULE]ls"]
    msg-result "Found Deeper Thought; building it against $ls GPIO module"
    define BUILD_DEEPER_THOUGHT 1
}

# NOTE: If you change the list of files here, change INFILES in
# Makefile.in, too.
make-config-header src/config.h \
    -auto {ENABLE_* HAVE_* PACKAGE_* SIZEOF_*} \
    -bare {ILS_MODE PCB_*}
make-template Makefile.in
make-template bin/pidp8i.in
make-template bin/os8-cp.in
make-template boot/0.script.in
make-template boot/2.script.in
make-template boot/3.script.in
make-template boot/4.script.in
make-template boot/6.script.in
make-template boot/7.script.in
make-template boot/run.script.in
make-template boot/run-v3f.script.in
make-template boot/tss8.script.in
make-template etc/pidp8i.service.in
make-template etc/sudoers.in
make-template etc/usb-mount@.service.in
make-template examples/Makefile.in
make-template lib/pidp8i/__init__.py.in
make-template lib/pidp8i/dirs.py.in
make-template lib/pidp8i/ips.py.in
make-template media/os8/init.tx.in
make-template media/os8/3finit.tx.in
make-template src/Makefile.in
make-template src/cc8/Makefile.in
make-template src/cc8/os8/Makefile.in
make-template src/pidp8i/gpio-common.c.in
make-template src/pidp8i/main.c.in
make-template src/SIMH/Makefile.in
make-template src/SIMH/PDP8/Makefile.in
make-template tools/simh-update.in
exec chmod +x "$builddir/bin/pidp8i" "$builddir/tools/simh-update" "$builddir/bin/os8-cp"

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# Generalized facility to manipulate os8 device images from the POSIX
# (host) side using OS/8 system programs under SIMH.
#
# See USAGE message below for details.
#
# Copyright © 2018 by Bill Cattey and Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys

sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Our local modules
from pidp8i import *
from simh   import *

# Other global Python modules
import glob
import subprocess
import string
import re


#### GLOBALS AND CONSTANTS #############################################

progmsg = True
DEBUG = False
VERBOSE = False
QUIET = False

# Default RK05 system image to attach if no sys specified.
_default_sys_image = "@OS8_BOOT_DISK@"
_default_sys_path = dirs.os8mo + _default_sys_image
_default_att_spec = ["rk", "0", _default_sys_path]

# Regex for parsing an argument string into a sys device
_dev_arg_regex_str = "-(rk|td|dt|rx)(\d?)(s)?"
_dev_arg_re = re.compile(_dev_arg_regex_str)

# Regex for parsing an action file att string into a sys device.  Note
# reuse of regex string from above.
_dev_actfile_regex_str = _dev_arg_regex_str[1:]   # strip -
_dev_actfile_re = re.compile (_dev_actfile_regex_str)

# Map of SIMH device names to OS/8 device name prefixes.
_os8_from_simh_dev = {"rk" : "RK", "td" : "DTA", "dt" : "DTA", "rx" : "RX"}

_os8_partitions = {"RK": ["A", "B"]}

# OS/8 file name matching regex
_os8_file_re = re.compile("(\S+):(\S+)?")

# PIP option flags we support and pass thru.  PIP has other options we
# do not try to map to our program functionality.  The key bit is the
# _pip_option_info dict.  The various transforms below it prevent both
# redundant code up here and repeated recomputation below.
_pip_option_info = {
    'a': 'ASCII',
    'b': 'binary',
    'i': 'image',
    'y': 'yank system head',
    'z': 'zero device'
}
_valid_pip_options = sorted(_pip_option_info.keys())
_arg_to_option = dict(zip(
    [ '-' + opt for opt in _valid_pip_options ],
    _valid_pip_options
))
_option_to_pip = dict(zip(
    _valid_pip_options,
    [ '/' + opt.upper() for opt in _valid_pip_options ]
))

# Matches if the string begins with a dollar sign, and has at least
# one slash, returning the string between the dollar sign and the
# first slash in group 1 and the rest in group 2.
# No whitespace in the string.
_expandable_re = re.compile ("^\$([^/\s]+)/(\S*)$")


#### abort_prog ########################################################
# Print err_string and exit with -1 return status.

def abort_prog (err_str):
  print "Abort: " + err_str
  sys.exit(-1)


#### parse_attach ######################################################
# Parser for OS/8 attach spec.

def parse_attach (action_plan, match, imagename):
  if match.group(2) == None or match.group(2) == "":
    abort_prog ("Need unit number for: " + match.group(1) + ".")

  image_spec = [match.group(1), match.group(2), imagename]
  if match.group(3) == 's': 
    if action_plan ["sys"] != None:
      print ("Already specified system device. Ignoring sys mount of: " + imagename)
    else:
      action_plan["sys"] = image_spec
  else:
    action_plan["mount"].append(image_spec)


#### path_expand #######################################################
# Originally developed in os8script.py, but useful here too.
#
# Simple minded variable substitution in a path.
# A path beginning with a dollar sign parses the characters between
# the dollar sign and the first slash seen becomes a name to
# expand with a couple local names: $home and the anchor directories
# defined in lib/pidp8i/dirs.py.
# We abort if the path expansion fails.

def path_expand (path):
  m = re.match(_expandable_re, path)
  if m == None: return path
  var = m.group(1)

  val = getattr (dirs, var, None)
  if val != None:
    return os.path.join(val,m.group(2))
  else:
    abort_prog ("{$" + var + "} is not a valid path expansion in " + path)
 

  
#### parse_action_file #################################################
#
# This option allows creation of the action_plan from a file
# instead of by indivitual arguments.  Think of it as a batch mode.
#
# Figuring out how to mix command lines args and the action_file
# would be tricky since the args are globbed, analyzed and then
# turned into an action plan.
#
# For now, the action file REPLACES the action plan of any other
# command line arguments before --action-file, and no other
# command line arguments are bothered with.
#
# The action file is 3 columns separated by one or more whitepace chars.
#
# If the first column is "att" it's an attach command
# and is parsed the same way as the attach args are parsed
# (Except we don't have a dash.)
#
# Otherwise the 3 columns are:
#
# option     source   destination
#
# option is one of the valid OS/8 file options:
# a, b, i, y, z
#
# Example:
#
# att rk0sbootdisk.rk05
# att td0 boing.tu56
# a pidp8i.in DTA0:
# b ac-mq-blinker.pal.pt DTA0:
#
# A dollar sign appearing in a POSIX pathname is expanded with substitutions
# from dirs.py.

def parse_action_file(fname):
  try:
    manifest = open(fname, "r")
  except IOError:
    print fname + " not found. Skipping."
    return None

  ioline_re = re.compile("(\S+)\s+(\S+)\s+(\S+)")

  action_plan = {}
  action_plan["sys"] = None
  action_plan["mount"] = []
  action_plan["copy"] = []

  for line in manifest:
    ioline = line.strip()
    if DEBUG: print "parse_action_file: ioline: " + ioline
    if ioline == "": continue
    if ioline[0] == '#': continue                  # Allow comments

    m=re.match(ioline_re, ioline)
    if m== None: 
      print "Ignoring line: " + ioline
      continue

    option = m.group(1)
    source = m.group(2)
    destination = m.group(3)
    
    if option == "att":
      m = re.match(_dev_actfile_re, source)
      if m== None:
        abort_prog ("Could not parse attach spec: " + source)
      parse_attach (action_plan, m, path_expand(destination))
    else:
      if len(option) != 1:
        print "Format options are only 1 letter in size. Ignoring line: " + ioline
      elif option[0] not in _valid_pip_options:
        print "Unrecognize option in line: " + ioline
      elif source == None:
        print "Null value of source. Ignoring line: " + ioline
      elif destination == None:
        print "Null value of destination. Ignoring line: " + ioline
      else:
        append_copy(action_plan, option, source, destination)

  return action_plan


#### is_directory ######################################################
#
# Returns True if the passed path looks like a directory.
#
# This is used at a level where we may still be unsure whether the given
# path refers to something on the OS/8 or the host side, so we first
# determine whether the path looks like an OS/8 or host-side path.  If
# it looks like an OS/8 path, we consider it a "directory" if it names a
# device name, lacking a file name part after it.  Otherwise, we use the
# local OS's "is a directory" path check.

def is_directory(path):
  if DEBUG: "is_directory (" + path + ")"
  m = re.match(_os8_file_re, path)
  if m != None:
    if DEBUG: print "OS/8 Match: DEV: " + m.group(1) + ", File: " + str(m.group(2))
    if m.group(2) == None or m.group(2) == "": 
      return True     # Just a device so yes it's a directory.
    else: return False
  if has_os8_wildcards(path):
    if DEBUG: print "Has wildcards."
    return False
  return os.path.isdir(path)


#### has_os8_wildcards #################################################
# Returns True if the passed file name has OS/8 style wildcards.

def has_os8_wildcards (filename):
  os8_wild_cards = "*?"
  for char in os8_wild_cards:
    if char in filename: return True
  return False


#### file_list_from_expect #############################################
# Given a block of text output by the Python Expect module used by class
# simh, parse it with the assumption that it contains OS/8 DIR output.

def file_list_from_expect(before):
  file_list = []
  lines = before.split("\r")
  for line in lines[1:]:    # First line is our command. Skip it.
    line = line.strip()
    if line == "": continue
    m = re.match("(\S+)\s*\.(\S+)", line)
    if m == None: continue
    # if DEBUG: print "file_list_from_expect: group 1: " + m.group(1) + ", group 2: " + m.group(2)
    fname = m.group(1) + "." + m.group(2)
    file_list.append(fname)
  return file_list


#### append_copy #######################################################
# Append a copy control array to the action_plan

def append_copy(action_plan, mode, source, destination):
  copy_type = ""
  if ":" in source:
    copy_type = "from"
    if "/" in source:
      abort_prog ("append_copy, out: Illegal OS/8 file spec containing a slash:" + source)
    source = source.upper()
  else: source = path_expand(source)

  if ":" in destination:
    if copy_type == "from":
      copy_type = "within"
    else:
      copy_type = "into"
    if "/" in destination:
      print "append_copy, into: Illegal OS/8 file spec containing a slash:" + destination
      sys.exit(-1)
    destination = destination.upper()
    
    if copy_type == "":
      abort_prog ("append_copy: No OS/8 file spec found with source: " + source + ", destination: " + destination)
  else: destination = path_expand(destination)

  copyspec = [mode, source, destination, copy_type]
  action_plan["copy"].append (copyspec)
  

#### parse_args ########################################################
#
# Builds the action plan from the command line arguments and executes it
#
# Note that if we specify the --action-file, the
# contents of that file REPLACE any command line arguments.
#
# An element of the action_plan["copy"] array is itself an array
# that names a file format, a source, a destination, and operation type.
#
#    [<format>, <source>, <destination>, <type>]
#
# type is one of:
#      "from" if we are transferring *from* OS/8 to POSIX
#      "to"   if we are transferring *to* OS/8 to POSIX
#      "on"   if we are transferring files within -- *on* OS/8
#
# The source and destination file specifications are interpreted as in
# the USAGE message below.  (Look for "colon".)

TERSE_USAGE = 'usage: ' + os.path.basename (__file__) + \
              " [-dhvq] [-<dev><unit>[s] image] ... [[-abiyz] <src>] ... <dest>\n" + \
              "       " + os.path.basename (__file__) + " [-dhvq] [--action-file action-file]" + \
"""

    <dev> is one of rk, td, dt, rx, corresponding to SIMH PDP-8 devices
    <unit> must be a valid unit number for the device in both SIMH and
           the booted OS/8 system. A unit number is required.  Following
           the unit with an "s" names the system device to boot.  The
           system image file must exist, and contain a working boot
           image.  Only one designated system device is allowed.
    <src>  is a source file or wild card specification.
    <dest> is a destination file if a single src file is specified; if
           multiple <src> files are given, it is either a POSIX
           directory or an OS/8 device name.

    Specifying an action file overrides any device or file argument
    previously specified on the command line.

    Example: 
    """ + \
      os.path.basename (__file__) + " -rk0s os8v3d-patched.rk05 -dt0 scratch.tu56 -a prog.pa DTA0:PROG.PA "

USAGE = TERSE_USAGE + """
    To see more detailed documentation specify -v -h
"""
        
VERBOSE_USAGE = TERSE_USAGE + """

    This program boots an OS/8 environment in the SIMH PDP-8 simulator
    then tries to behave like the POSIX program it is named after --
    copying files between the POSIX (host) side and the OS/8
    environment or under our control within the OS/8 environment.

    The copying direction is determined by which file name arguments
    have a colon in them:

    *   copy-within: The source and destination file arguments have
        colons, so copy within the OS/8 environment from one volume to
        another.

    *   copy-into: Only the dest argument has a colon, so assume the
        source file names are POSIX-side and copy those files into the
        simulated OS/8 environment.

    *   copy-from: The dest argument has no colon but the source file
        names do, so copy the named OS/8 files out from the simulation.

    If none of the file arguments has a colon in it and you give exactly
    two such arguments, we operate in a special case of copy-within
    mode: the source and destination volumes are assumed to be DSK:, so
    the file is simply copied within the OS/8 DSK: volume from one name
    to the other.  If you give greater than two file name arguments
    without a colon in any of them, it is not possible to make sense of
    the command since we do not intend to try and replace your perfectly
    good POSIX cp implementation, so it errors out.

    If you give only one file name argument, the program always errors
    out: it requires at least one source and one destination.

    The -a, -b, -i, -y, and -z flags correspond to the OS/8 PIP options:

        /A    ASCII format.  OS/8 and POSIX newlines are translated.
              Such transfers are lossless if line endings are  well-formed.
        /B    Binary OS/8 ABSLDR format with leader/trailer and other
              specific formatting that is detected and enforced by PIP.
        /I    Image mode.  Files are copied byte for byte verbatim.
        /Z    ZERO directory of destination OS/8 device.
        /Y    Yank system area from source to destination.

    If no format flag is set, the default transfer format is /I.

    (This priogram currently uses PIP as its primary handler for the
    OS/8 side of the work.)  They must be followed by at least one source
    file name, and they affect all subsequent source file names until
    another such option is found.  For example:

        $ os8-cp -a foo bar -b qux sys:

    Files foo and bar are copied to SYS: in ASCII mode, overriding the
    default binary mode, then binary mode is restored for the copy of
    file qux to the SYS: volume.

    Beware that -i means something very different to this program than
    it means to POSIX cp: destination files will be unceremoniously
    overwritten!

    More about image file mounts:

    image files for non-boot dev specifications, if they do not
    already exist, are created. Their directories are initalized
    with the ZERO command. Multi-partition devices initialize all.

    A future version will include a default system device if
    no dev system mount is made.

    Examples:

        $ os8-cp -td0s my.tu56 -rk0 my.rk05 foo DSK:

    ...will boot from my.tu56, which is presumed to be a bootable OS/8
    DECtape attached to SIMH device TD0.  The RK05 disk image my.rk05
    will be attached to RK0, since the default boot disk is not attached
    there in this example.  It will copy POSIX-side file foo to DSK:FOO
    which will probably be interpreted as DTA0:FOO by the typical BUILD
    options for a bootable OS/8 TU56 DECtape.  Beware therefore of using
    the generic SYS: and DSK: device names!  You would be better advised
    to use DTA0:, RKA0: or RKB0: as the destination in this example.

        $ os8-cp -td0s my.tu56 -rx1 my.rx01 foo RXA1:

    This fixes the almost-certainly incorrect use of DSK: in the prior 
    example.

    The -dt and -td options are handled similarly to the -r* options,
    differing only in whether we use the SIMH DT or TD PDP-8 devices,
    which correspond to the TC08 or TD8E DECtape controllers.  Which one
    you give depends on the device support built into the OS/8 media
    you've booted from.

    More about src and dest specifications:

    When only a destination device, directory, or volume name is given,
    file names are normalized when coping between POSIX and OS/8
    systems.  File names are uppercased and truncated to 6.2 limits when
    copying into OS/8.  File names are lowercased on copying from OS/8
    unless you give the *source* file name in all-uppercase.
    Then file name case is preserved.  This behavior is overridden
    if you give a complete file name for the destination:

        $ os8-cp my-long-file-name.txt DSK:MLF.FD

    If you gave "DSK:" as the destination instead, you would have gotten
    "MY-LON.TX" as the desintation file name instead.

    Give -d to run in debug mode.

    Give -h -v to print this message.

    Give -v to enable verbose status reporting.
"""

def parse_args ():
  global DEBUG
  global VERBOSE
  global QUIET

  action_plan = {}
  action_plan["sys"] = None
  action_plan["mount"] = []
  action_plan["copy"] = []

  idx = 1
  numargs = len(sys.argv)

  filespec_seen = 0
  mode_opt = "i"                              # start of with default of binary.
  first_mode = mode_opt
  source = ""
  destination = ""
  # Keep file_list and mode_list in sync.
  file_and_mode_list = []
  
  while idx < numargs:
    arg = sys.argv[idx]

    # First the simple bit set options
    if arg == "-d":
      DEBUG = True
    elif arg == "-h":
      if VERBOSE:
        print VERBOSE_USAGE
      else:
        print USAGE
      sys.exit(0)
    elif arg == "-q":
      QUIET = True
    elif arg == "-v":
      VERBOSE = 1

    # look for option args.
    elif arg in _arg_to_option:
      new_opt = _arg_to_option[arg]
      if mode_opt == new_opt:
        print "Warning redundant reset of mode option to " + \
          _pip_option_info[new_opt]
      mode_opt = new_opt

    # Not a simple bit set option.
    
    elif arg == "--action-file":
      if idx + 1 == numargs:             # Need filename, but no args left.
        abort_prog ("No action file name.")
      argfilename = sys.argv[idx + 1]
      retval = parse_action_file(argfilename)
      if retval == None:
        abort_prog ("No action plan could be made from " + argfilename + ".")
      else: return retval
      
    else:
      # Parser for OS/8 attach spec.
      m = re.match(_dev_arg_re, arg)
      if m != None:
        if idx + 1 == numargs:             # Need filename, but no args left.
          abort_prog ("No image file name.")
        idx +=1
        parse_attach (action_plan, m, sys.argv[idx])

      # Do file parser if we didn't get an OS/8 attach spec.
      else:

        if DEBUG: print "File parsing of: " + arg
        
        # Need to know if arg is Linux. If so, we need to do globbing.
        # If you want OS/8 globbing, specify a device to prevent globbing
        # from being run.
        m = re.match(_os8_file_re, arg)
        if m == None:          # Yup, it's POSIX.  Glob it.
          if DEBUG: print arg + " is POSIX."
          more_files = glob.glob(arg)
          if more_files == []:
            if DEBUG: print "No more files in POSIX Glob. Our file is: " + arg
            more_files.append(arg)  # If file not found may be an OS/8 internal xfer.
          for new_file in more_files:
            if filespec_seen == 0:
              source = new_file
              first_mode = mode_opt
              if DEBUG: print "Globber: Setting initial source: " + source + " and mode: " + first_mode
            elif filespec_seen == 1:
              if DEBUG: print "Globber: Setting initial destination: " + destination
              destination = new_file  
            else:
              if DEBUG: "Globber: Appending destination to list. New file is: " + new_file
              file_and_mode_list.append([mode_opt,destination])
              destination = new_file
            filespec_seen += 1
        else:
          if filespec_seen == 0:
            source = arg
            first_mode = mode_opt
            if DEBUG: print "Setting initial source: " + source + " and mode: " + first_mode
          elif filespec_seen == 1:
            destination = arg
            if DEBUG: print "Setting initial destination: " + destination
          else:
            file_and_mode_list.append([mode_opt, destination])
            destination = arg
            if DEBUG: "Appending destination to list. New file is: " + new_file
          filespec_seen += 1

    idx +=1        # Bottom of the while loop. Increment.

  if filespec_seen == 0:
    abort_prog ("No file specs seen.  Nothing to do.")
  elif filespec_seen == 1:
    abort_prog ("Only 1 file spec found. Nothing to do.")
  # Now it gets a little complicated...
  # If neither source nor destination is OS/8, pretend they both were OS/8 "DSK:"
  # If source is OS/8, and has OS/8 wild cards, the destination must be a directory.
  else:
    # If more than 2 files, the destination must be either an OS/8 device or a Linux directory.
    if DEBUG: print "Destination: " + destination
    if filespec_seen > 2 and is_directory(destination) == False:
      abort_prog ("Destination must be a Linux directory or OS/8 device for multiple source files.")

    m1 = re.match(_os8_file_re, source)
    m2 = re.match(_os8_file_re, destination)

    # If source is OS/8 and it has wild cards, but destination is a file, not a device,
    # it's a fatal error.
    if m1 != None and has_os8_wildcards(source) and is_directory (destination) == False:
      abort_prog ("Not going to concatinate multiple OS/8 files into: " + destination + ".")

    if m1 == None and m2 == None and filespec_seen == 2:      # No OS/8 dev on two names, local DSK: copy.
      source = "DSK:" + source
      destination = "DSK:" + destination
      
    append_copy(action_plan, first_mode, source, destination)
    
    for mode_and_file in file_and_mode_list:
      filename = mode_and_file[1]
      m3 = re.match(_os8_file_re, filename)
      if m3 != None and has_os8_wildcards(filename) and is_directory (destination) == False:
        abort_prog ("Not going to concatinate multiple OS/8 files into: " + destination + ".")
      append_copy(action_plan, mode_and_file[0], filename, destination)

  return action_plan
  

#### main ##############################################################

def main ():

  action_plan = parse_args()
  if action_plan == None:
    abort_prog ("No action plan was parsed.")
  if DEBUG: print str(action_plan)

  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build, True)
  except (RuntimeError) as e:
    print "Could not start simulator: " + e.message + '!'
    exit (1)
  # s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))
  s.set_logfile (open ("logfile.txt", 'w'))
  if VERBOSE: s.verbose = True
  
  # Perform sys attach
  att_spec = action_plan["sys"]
  if att_spec == None: att_spec = _default_att_spec
  simh_boot_dev = att_spec[0] + att_spec[1]     # Compose simh dev from name and unit.
  imagename = att_spec[2]
  if not os.path.exists (imagename):
    abort_prog ("Requested boot image file: " + imagename + " not found.")
  if VERBOSE or DEBUG:
    print "Attaching " + simh_boot_dev + " to " + imagename
  s.send_cmd ("att " + simh_boot_dev + " " + imagename)

  images_to_zero = []
  
  # Attach other mounts
  for att_spec in action_plan["mount"]:
    simh_dev = att_spec[0] + att_spec[1]     # Compose simh dev from name and unit.
    imagename = att_spec[2]
    if os.path.exists (imagename):
      if VERBOSE or DEBUG: print "Modifying existing " + simh_dev + " image " + imagename
    else:
      if VERBOSE or DEBUG: print "Will create a new image file named: " + imagename
      # Save this att_spec so we can zero it later.
      images_to_zero.append (att_spec)
    if VERBOSE or DEBUG:
      print "Attaching " + simh_dev + " to " + imagename      
    s.send_cmd ("att " + simh_dev + " " + imagename)

  if VERBOSE or DEBUG: print "Booting " + simh_boot_dev + "..."
  s.send_cmd ("boot " + simh_boot_dev)

  for att_spec in images_to_zero:
    os8dev = _os8_from_simh_dev[att_spec[0]]
    if os8dev in _os8_partitions:
      for partition in _os8_partitions[os8dev]:
        os8name = os8dev + partition + att_spec[1] + ":"
        if VERBOSE or DEBUG: print "Initializing directory of " + os8name + " in " + imagename
        s.os8_send_cmd ('\\.', "ZERO " + os8name)
    else:
      os8name = os8dev + att_spec[1] + ":"
      if VERBOSE or DEBUG: print "Initializing directory of " + os8name + " in " + imagename
      s.os8_send_cmd ('\\.', "ZERO " + os8name)

  # Perform copy operations
  for do_copy in action_plan["copy"]:
    mode_opt = do_copy[0]
    source = do_copy[1]
    destination = do_copy[2]
    copy_type = do_copy[3]
    if mode_opt in _option_to_pip:
      pip_option = _option_to_pip[mode_opt]
    else:
      abort_prog ("Unrecognized mode option: " + mode_opt)

    if DEBUG: print "Source: " + source + ", Destination: " + destination + ", Mode: " + mode_opt + "."
    # Is this "from" OS/8 to POSIX, "into" OS/8 from POSIX or "within" OS/8?
    # "into" -- Attach source to simh ptr
    # If we are operating "from" and source has wild cards,
    # Use DIRECT to create list of files.
    # "from" -- Attach destination to ptp. We've already done POSIX globing.
    # "within" -- Use COPY.
    
    if copy_type == "into":
      s.os8_pip_to(source, destination, pip_option)
    elif copy_type == "from":
      if has_os8_wildcards(source):
        # Split off device from source:
        os8dev = source[0:source.index(":")+1]
        if DEBUG: print "Wild card dev: " + os8dev
        # Use OS/8 Direct to enumerate our input files.
        if DEBUG: print "Calling OS/8 DIRECT on wild card filespec: " + source
        s.os8_send_cmd ('\\.', "DIR " + source + "/F=1")
        # Now harvest direct output.  One file per line.  Ignore blank lines.
        # Maybe parse the FREE BLOCKS Output.
        # Done when we see a dot.
        s._child.expect("\d+\s+FREE BLOCKS")
        files = file_list_from_expect(s._child.before)
        for filename in files:
          if VERBOSE or DEBUG:
            print "Wildcard call os8_pip_from: copy from: {" + os8dev + "}{" + filename + "}" + \
              " to: " + destination + ", mode: " + pip_option 
          s.os8_pip_from(os8dev + filename, destination, pip_option)
      else:
        if VERBOSE or DEBUG:
          print "Call os8_pip_from: copy from: " + source + " to " + destination + \
            ", mode: " + pip_option 
        s.os8_pip_from(source, destination, pip_option)
    elif copy_type == "within":
      if VERBOSE or DEBUG:
        print "Call COPY of: " + source + " to " + destination
      s.os8_send_cmd ('\\.', "COPY " + destination + "< " + source)
    else:
      abort_prog ("Unrecognized copy type: " + copy_type)  # Should never happen.
      
  # Detach all mounts and then sys.
  s.back_to_cmd ('\\.')
  for att_spec in action_plan["mount"]:
    simh_dev = att_spec[0] + att_spec[1]     # Compose simh dev from name and unit.
    if VERBOSE or DEBUG:
      print "Detaching " + simh_dev
    s.send_cmd ("det " + simh_dev)
  if VERBOSE or DEBUG:
    print "Detaching " + simh_boot_dev
  s.send_cmd ("det " + simh_boot_dev)

  # And shut down the simulator.
  if VERBOSE or DEBUG:
    print "Quitting simh."
  s.send_cmd ('quit')

if __name__ == "__main__": main()

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# Script runner for OS/8 under SIMH.
# The library module os8script.py does the heavy lifting.
#
# See USAGE message below for details.
#
# Copyright © 2018 by Bill Cattey and Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys

sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Remaining Python core modules
import subprocess
import string
import re
import shutil
import argparse
from itertools import chain

# Our local modules
from pidp8i    import *
from simh      import *
from os8script import *


#### GLOBALS AND CONSTANTS #############################################

DEBUG = False
VERBOSE = False
VERY_VERBOSE = False
QUIET = False
SCRIPT_FILE = ""

USAGE = "usage: "  + os.path.basename (__file__) + \
       " [-h] [-d] [-v] [-vv] [--enable enable_option] ... \n\t[--disable disable_option] ... " + \
       "\n \tscript [script] ... "

_en_dis_arg_re = re.compile("^(enable|disable)_(\S+)$")


def opt_set(en_dis, option, options_enabled, options_disabled):
  if option == None or en_dis == None: return
  # print en_dis + " " + option
  if en_dis == "enable":
    if option not in options_enabled:
      options_enabled.append(option)
    if option in options_disabled:
        options_disabled.remove(option)
  elif en_dis == "disable":
    if option not in options_disabled:
      options_disabled.append(option)
    if option in options_enabled:
        options_enabled.remove(option)
  else: return


def add_bool (self, *args, **kwargs):
  kwargs['action']  = 'store_true'
  kwargs['default'] = False
  self.add_argument (*args, **kwargs)
  

#### parse_args ########################################################
    
def parse_args (script_files, options_enabled, options_disabled):
  global DEBUG
  global VERBOSE
  global VERY_VERBOSE
  global USAGE

  enable_usage = ""
  disable_usage = ""

  idx = 1
  numargs = len(sys.argv)

  if numargs < 2:
    print USAGE
    sys.exit(-1)

  # Add arguments corresponding to --*-os8-* configure script options
  max_obn_len = 0
  for obn, vals in os8opts.opts.iteritems():
    max_obn_len = max(max_obn_len, len(obn))
  for obn, vals in os8opts.opts.iteritems():
    if vals[0]:
      # Enable option
      pad_str = (max_obn_len - len (obn)) * " "
      new_usage = "    " + obn + ": " + pad_str + vals[1] + "\n"
      disable_usage += new_usage
    else:
      # Disable option
      pad_str = (max_obn_len - len (obn)) * " "
      new_usage = "    " + obn + ": " + pad_str + vals[1] + "\n"
      enable_usage += new_usage

  if enable_usage != "":
    USAGE += "\n  Known enable options: \n"
    USAGE += enable_usage

  if disable_usage != "":
    USAGE += "\n  Known disable options: \n"
    USAGE += disable_usage
    
  while idx < numargs:
    arg = sys.argv[idx]
    # print "idx: " + str(idx) + ", arg: " + arg
    # print "Files: " + str(script_files)
    # print "Options: " + str(options_enabled)
    if arg == "-d" or arg == "--debug":
      DEBUG = True
    elif arg == "-h" or arg == "--help":
      print USAGE
      sys.exit(0)
    elif arg == "-v" or arg == "--verbose":
      VERBOSE = 1
    elif arg == "-vv" or arg == "--very-verbose":
      VERY_VERBOSE = 1
    elif arg == "--enable":
      idx +=1
      if idx == numargs:
        print "expecting an option but got none."
      else:
        option = sys.argv[idx]
        # Only add the option once
        if option not in options_enabled: options_enabled.append(option)
    elif arg == "--disable":
      idx +=1
      if idx == numargs:
        print "expecting an option but got none."
      else:
        option = sys.argv[idx]
        # Only add the option once
        if option not in options_disabled: options_disabled.append(option)
    else:
      script_files.append(arg)
    idx += 1
      


#### main ##############################################################
# Program entry point.  Parses the command line and drives the above.

def main ():
  script_files = []
  options_enabled = []
  options_disabled = []

  parse_args (script_files, options_enabled, options_disabled)
  if len(script_files) == 0:
    print "Need a script file to run."
    sys.exit(-1)

  if VERBOSE:
    print "script_files: " + str(script_files)
  if DEBUG:
    print "options_enabled" + str(options_enabled)
    print "options_disabled" + str(options_disabled)
  
  # Log SIMH and OS/8 output to a file by default, but send it to the
  # console instead of the progress messages if -v was given using the
  # trick from https://stackoverflow.com/questions/21239338
  s = simh (dirs.build, True)
  if VERBOSE: s.verbose = True
  s.set_logfile (open (dirs.log + 'os8-run' + '.log', 'w') \
      if not VERY_VERBOSE else os.fdopen (sys.stdout.fileno (), 'w', 0))

  os8 = os8script (s, options_enabled, options_disabled, verbose=VERBOSE, debug=DEBUG)

  for script_file in script_files:
    if VERBOSE:
      print os.path.basename (__file__) + " -- Language Version: " + os8.lang_version

    print "Running script file: " + script_file
    os8.run_script_file (script_file)

  # After all scripts are done, we remove any scratch files,
  # detach any mounted devices, and shut down simh gracefully.

  for filename in os8.scratch_list:
    if os8.verbose: print "Deleting scratch_copy: " + filename
    os.remove(filename)
    
  s.send_cmd ("detach all")

  s.quit ()
  if VERBOSE: print "Done!"

  
if __name__ == "__main__":
    main()

  if benchmark:
    # Run demo long enough to get a good sense of the simulator's
    # execution rate while unthrottled on this host hardware.  If
    # you don't run it long enough, the IPS value is untrustworthy.
    try:
      s.spin (10)
    except pexpect.TIMEOUT:
      # Explicitly shift back from OS/8 context to SIMH command context.
      # We cannot rely on class simh to do this automatically because it
      # expects to see a . prompt from the prior command, but we're
      # still in TECO here, so we must be explicit.
      s.os8_send_ctrl ('e')

      # Ask the simulator what IPS rate we ran that benchmark at.
      s.send_cmd ('show clocks')
      line = s.read_tail ('Execution Rate:')
      curr_ips = int (line.strip().replace(',', '').split(' ')[0])
      pf = open ('lib/pidp8i/ips.py', 'a')
      pf.write ('current = ' + str (curr_ips) + '    # ' + \
            str (datetime.today ()) + '\n')
      pf.close ()
      s.send_cmd ('quit')
      pdp_ratio = float (curr_ips) / ips.pdp8i
      rpi_ratio = float (curr_ips) / ips.raspberry_pi_b_plus
      print "\nYour system is " + format (rpi_ratio, '.1f') + \
          " times faster than a Raspberry Pi Model B+"
      print "or " + format (pdp_ratio, '.1f') + \
          " times faster than a PDP-8/I.\n"
  else:
    # Normal mode.  Tell SIMH and throttle down to a rate suitable for a
    # blinkenlights demo.  1/17 means SIMH runs one instruction then
    # waits for 17ms, yielding ~59 IPS.
    time.sleep (0.02)       # FIXME: simulator chokes on 'cont' without this
    s.os8_send_ctrl ('e')   # same justification as above
    s.send_cmd ('set throttle 1/17')

    # You can't hit Ctrl-E while running this script in the foreground
    # since pexpect takes over stdio.  Therefore, if you want to be able
    # to send commands to the simulator while the demo is running,
    # uncomment the line below, which will let you send commands to the
    # simulator via telnet.  From another terminal or SSH session:

; Loads OS/8 from DECtape, as opposed to the RK05 based environment
; in 0.script.
;
echo Loading OS/8 from DECtape type @OS8_TAPE_DEVICE@...
set df disabled


set cpu noidle
@SET_THROTTLE@
deposit int-throttle THROT_DELAY 3

@if SIMH_TAPE_DEVICE == td
set dt disabled
set td enabled
; else, default is correct, per p.4 in SIMH's pdp8_doc.doc.
@endif

@if SIMH_PASS_LOWERCASE
; The software was configured with either --lowercase=auto or =pass,
; so send all text input to the simulator as 7-bit ASCII, including
; lowercase.  Lowercase output from the simulator will be sent to the
; console unchanged, as will non-printing chars.
set tti 7b
@else
; The software was configured with --lowercase=upper, meaning the user
; wants lowercase text to be forced to uppercase.  This is bidirectional,
; affecting both input to the simulated PDP-8 and output from it.
set tti ksr
@endif

attach @SIMH_TAPE_DEVICE@0 @MEDIADIR@/os8/@OS8_BOOT_TAPE@
boot @SIMH_TAPE_DEVICE@0

; Loads OS/8 V3F from DECtape, as opposed to the RK05 based environment
; in 0.script.  Based on 3.script.in, which differs by being conditional
; based on whether the user chooses at configure time whether to boot
; OS/8 V3F or V3D.  This script also runs the tape image from the build
; directory, rather than from the installation directory, since it's
; normally run as "make run-v3f".
;
echo Loading OS/8 from DECtape type @OS8_TAPE_DEVICE@...
set df disabled
set cpu noidle
@SET_THROTTLE@
deposit int-throttle THROT_DELAY 3

@if SIMH_TAPE_DEVICE == td
set dt disabled
set td enabled
; else, default is correct, per p.4 in SIMH's pdp8_doc.doc.
@endif

@if SIMH_PASS_LOWERCASE
; The software was configured with either --lowercase=auto or =pass,
; so send all text input to the simulator as 7-bit ASCII, including
; lowercase.  Lowercase output from the simulator will be sent to the
; console unchanged, as will non-printing chars.
set tti 7b
@else
; The software was configured with --lowercase=upper, meaning the user
; wants lowercase text to be forced to uppercase.  This is bidirectional,
; affecting both input to the simulated PDP-8 and output from it.
set tti ksr
@endif

attach @SIMH_TAPE_DEVICE@0 bin/v3f-@OS8_TAPE_DEVICE@.tu56
boot @SIMH_TAPE_DEVICE@0

requires 'inc::Module::Install';
requires 'Math::Subsets::List';
requires 'Parallel::Loops';

# os8-cp: A tool to copy files to and from OS/8 running in SIMH

## Motivation

There have been various tools for copying files between OS/8
device image files and the platform hosting those image files.
For example, the graphical [OS8View by Ian Schofield][os8view-forum].

This tool was designed to be called from the command line in the POSIX
environment, and to interface between the POSIX filesystem and OS/8
running underi SIMH.

The semantics are like the POSIX `cp` program, except that a source or
destination containing a colon is interpreted to refer to files within
OS/8.

Additional arguments allow for specifying how the simulation is configured
and booted. I.E. various POSIX files containing OS/8 device images are
attached to SIMH.

The reason why direct copy into and out of image files was not pursued
was that is seemed easier to use OS/8 and SIMH tools to copy files around
rather than learning the low level directory formats and binary data
representations for the various OS/8 image files.  Anything that can
be moved around by `PIP` under OS/8 is fair game for `os8-cp`.

The tool is written in Python and utilizes the pexpect library for
starting up and communication with SIMH.

## Capabilities

* Copy files from and to OS/8 booted up under SIMH.
* In ASCII text mode, convert between OS/8 and POSIX newline codings.
* Allow attaching of arbitrary image files to arbitrary devices.
* Copy files within OS/8 if both source and destination specify OS/8 rather than POSIX names.
* For POSIX file specifications expand directories to lists of files, and use POSIX
style globbing to expand wild cards.
* For OS/8 file specificaitons, allow appropriate wild carding as well.

## Limitations

The architecture of OS/8 makes it impossible to operate with a write-locked
boot device.  (Many would argue that this is a serious defect, and I agree.
However this is the reality we are dealing with.)

This means that there really should only be one instance of `os8-cp`
manipulating a particular bootable image at a time.

When this tool was used in a Makefile, care had to be taken with dependencies
so that a parallel make would never run more than a single instance of
`os8-cp`.

There are a couple ways that this could be dealt with:

* Create a scratch image for the running boot image:  The problem with this
is that often os8-cp is used in the manipulation of a boot image to be used
later by others.  A scratch image would carefully throw away any such work.

* Manage a lock file that would be checked at run-time: This would actually work.
Indeed a lock file with a name based on the path to the boot image would allow
multiple instances of os8-cp acting on different boot images to run simultaneously.
The downside is complexity.  Lock files in Python are platform specific, so
Linux, Windows, BSD, etc platforms might require specific code.  Cleanup of
the lock file on any kind of abnormal exit would have to be managed.  And
design of what to do when waiting for the lock.

Ultimately the implementation decision was:  Be careful not to run
multiple instances os8-cp in parallel against the same boot image file.

## Usage

> `os8-cp` [`-dhvq`] [-<_dev_><_unit_>[`s`] _image_] ... [[`-abiyz`] <_src_>] ... <_dest_>
> `os8-cp` [`-dhvq`] [`--action-file` _action-file_]

| <_dev_>   | **Device**: one of `rk`, `td`, `dt`, `rx`, corresponding to SIMH PDP-8 devices
| <_unit_>  | **Unit**: must be a valid unit number for the device in both SIMH and
|           | the booted OS/8 system. A unit number is required.  Following
|           | the unit with an "s" names the system device to boot.  The
|           | system image file must exist, and contain a working boot
|           | image.  Only one designated system device is allowed.
| <_src_>   | **Source**: is a source file or wild card specification.
| <_dest_>  | **Destination**: is a destination file if a single _src_ file is specified;
|           | if multiple <_src_> files are given, it is either a POSIX
|           | directory or an OS/8 device name.

 Specifying an action file overrides any device or file argument
 previously specified on the command line.

 Example:
 
    os8-cp -rk0s os8v3d-patched.rk05 -dt0 scratch.tu56 -a prog.pa DTA0:PROG.PA 

### Further Details

The copying direction is determined by which file name arguments have a colon in them:

* copy-within: The source and destination file arguments have
colons, so copy within the OS/8 environment from one volume to
another.

* copy-into: Only the dest argument has a colon, so assume the
source file names are POSIX-side and copy those files into the
SIMH OS/8 environment.

* copy-from: The dest argument has no colon but the source file
names do, so copy the named OS/8 files out from the simulation.

If none of the file arguments has a colon in it and you give exactly
two such arguments, we operate in a special case of copy-within
mode: the source and destination volumes are assumed to be DSK:, so
the file is simply copied within the OS/8 DSK: volume from one name
to the other.  If you give greater than two file name arguments
without a colon in any of them, it is not possible to make sense of
the command since we do not intend to try and replace your perfectly
good POSIX cp implementation, so it errors out.

If you give only one file name argument, the program always errors
out: it requires at least one source and one destination.

The `-a`, `-b`, `-i`, `-y`, and `-z` flags correspond to the OS/8 PIP options:

| flag | `PIP` | Description
|------|-------|----------------------------------------------------------
| `-a` | `/A` | ASCII format.  OS/8 and POSIX newlines are translated.
|      |      | Such transfers are lossless if line endings are  well-formed.
| `-b` | `/B` | Binary OS/8 ABSLDR format with leader/trailer and other
|      |      | specific formatting that is detected and enforced by PIP.
| `-i` | `/I` | Image mode.  Files are copied byte for byte verbatim.
| `-z` | `/Z` | ZERO directory of destination OS/8 device.
| `-y` | `/Y` | Yank system area from source to destination.

If no format flag is set, the default transfer format is `/I`.

(This priogram currently uses PIP as its primary handler for the
OS/8 side of the work.)  They must be followed by at least one source
file name, and they affect all subsequent source file names until
another such option is found.  For example:

    $ os8-cp -a foo bar -b qux sys:

Files foo and bar are copied to SYS: in ASCII mode, overriding the
default binary mode, then binary mode is restored for the copy of
file qux to the SYS: volume.

Beware that -i means something very different to this program than
it means to POSIX cp: destination files will be unceremoniously
overwritten!

More about image file mounts:

image files for non-boot dev specifications, if they do not
already exist, are created. Their directories are initalized
with the ZERO command. Multi-partition devices initialize all.

A future version will include a default system device if
no dev system mount is made.

Examples:

    $ os8-cp -td0s my.tu56 -rk0 my.rk05 foo DSK:

...will boot from my.tu56, which is presumed to be a bootable OS/8
DECtape attached to SIMH device TD0.  The RK05 disk image my.rk05
will be attached to RK0, since the default boot disk is not attached
there in this example.  It will copy POSIX-side file foo to DSK:FOO
which will probably be interpreted as DTA0:FOO by the typical BUILD
options for a bootable OS/8 TU56 DECtape.  Beware therefore of using
the generic SYS: and DSK: device names!  You would be better advised
to use DTA0:, RKA0: or RKB0: as the destination in this example.

    $ os8-cp -td0s my.tu56 -rx1 my.rx01 foo RXA1:

This fixes the almost-certainly incorrect use of DSK: in the prior 
example.

The -dt and -td options are handled similarly to the -r* options,
differing only in whether we use the SIMH DT or TD PDP-8 devices,
which correspond to the TC08 or TD8E DECtape controllers.  Which one
you give depends on the device support built into the OS/8 media
you've booted from.

### More about _src_ and _dest_ specifications:

When only a destination device, directory, or volume name is given,
file names are normalized when coping between POSIX and OS/8
systems.  File names are uppercased and truncated to 6.2 limits when
copying into OS/8.  File names are lowercased on copying from OS/8
unless you give the *source* file name in all-uppercase.
Then file name case is preserved.  This behavior is overridden
if you give a complete file name for the destination:

    $ os8-cp my-long-file-name.txt DSK:MLF.FD

If you gave "DSK:" as the destination instead, you would have gotten
"MY-LON.TX" as the desintation file name instead.

### Run-time Options:

| `-d`    | run in debug mode.
| `-v`    | enable verbose status reporting.
| `-h -v` | print detailed usage message.


[os8view-forum]: http://groups.google.com/forum/#!topic/pidp-8/1hojqAATum4

## TODOs

* No TODOs as of yet.

## Notes

* No notes as of yet.

### <a id="license"></a>License

Copyright © 2018 by Bill Cattey and Warren Young. Licensed under the
terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

Then I enhanced our `mkos8` script to apply the patches in an
automated way.  Most of the patches were for programs available
in source form, so I built the programs from source, and then bench
checked the patch against the source.  In a few cases the code was too
obscure, and I marked the patch as "plausable" rather than "verified"
in my spreadsheet.

The file [`patch-list.txt`][pl] lists all of the patch files in
`media/os8/patches`.  Comments in that file begin with `#` and are
used to disable patches we have rejected for one reason or another.
Each rejected patch also has a comment that explains why that
particular patch was rejected from the default set.  Typical reasons
are:

*   The patch requires hardware our simulator doesn't have.
*   The patch conflicts with another patch we deem more important.
*   The patch changes some behavior, and we prefer that the unpatched
    behavior be the default.

You may want to examine this file to see if there are any decisions you
would reverse.  After modifying that file, say "`make`" to rebuild the
OS/8 binary RK05 disk image file with your choice of patches.




[dsn]:     http://bitsavers.org/pdf/dec/pdp8/softwarenews/
[dsn8010]: http://bitsavers.org/pdf/dec/pdp8/softwarenews/198010_PDP8swNews_AA-K629A-BA.pdf
[pl]:      https://tangentsoft.com/pidp8i/doc/trunk/media/os8/patches/patch-list.txt


## Review of Recommendations

`BRTS 31.11.2O` is an optional patch which disables 8th bit parity. It
is recommended because sometimes we may want to allow output that
does not force the 8th bit.

support.  But if you happen to be using this setup under `TD8E` and
`FRTS` doesn't work, then back out this patch.


## Patch Application Order

The `patch` routine in `mkos8` applies the patches in the order they
appear in [`patch-list.txt`][pl].  That list is currently in
alphabetical order.  However, there may in future emerge patches that
impose an order.

For example, if the `ABSLDR` patch actually did work, it needs the
`FUTIL 31.21.2 M` in order to patch into the `ABSLDR` overlay bits.

I was skeptical of `FUTIL 31.21.2M` because, when I

### <a id="license"></a>License

Copyright © 2017 by Bill Cattey. Licensed under the terms of
[the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[os8ext]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-v3d-device-extensions.md

# os8-run: A Scripting Language for Driving OS/8

## History and Motivation

In the beginning, the PiDP-8/I project shipped a hand-made and
hand-maintained OS/8 disk image. This image had multiple problems, and
sometimes the by-hand fixes to those problems caused other problems.

For the 2017.12.22 release, [we][auth] created a tool called `mkos8`
which creates this disk programmatically based on the user's configuration
choices. This has many virtues:

*   The OS/8 system media is created from pristine distribution media,
    rather than being built up in an undocumented *ad hoc* fashion.
    
*   The build sequence is documented in the source code of `mkos8`,
    rather than being a mysterious product of history, most of which
    happened before the OS/8 media came under version control.

*   The build products can be [tested][tm], because the process is
    purposefully done in a way that it is [reproducible][rb].

*   Because `mkos8` is written in Python, we have a full-strength
    scripting language for making the build conditional.  As of the
    2017.12.22 release, there are potentially 65536 different build
    configurations, whereas the old manual process produced just one
    OS/8 system disk image.

That process worked fine for the limited scope of problem it was meant to
cover: creation of an OS/8 V3D RK05 image meant for use with SIMH's PDP-8
simulator, which was configured in a very particular way. It doesn't solve
a number of related problems that should be simple extensions to the idea:

*   What if we want a different version of OS/8, such as V3F?

*   When running under SIMH, there is little practical difference between
    its `DT` and `TD` devices for driving an emulated TU56 tape drive:
    the default is almost certainly fine, since it's compatible with
    the whole range of PDP-8 computers, and thus software for PDP-8
    computers.  But, what if you've got a real PDP-8/e computer with a
    real TU56 tape drive, which means you're using the TD8E interface, not
    the TC08 that SIMH's PDP-8 simulator defaults to using?  That `BUILD`
    output will not work on your hardware.

*   The same basic problem has additional complications when what's
    changed in the `BUILD` is the system device type, such as from an
    RK05 to an RL01 or RX02.

*   How do we make it drive other tools not already hard-coded into
    `mkos8` or its underlying helper library?

Shortly after release 2017.12.22 came out, Bill Cattey began work on
`os8-run` to solve these problems. This new tool implements a scripting
language and a lot of new underlying functionality so that we can not
only implement all of what `mkos8` did, we can now write scripts to do
much more.

The goals of the project are:

*   Entirely replace `mkos8`, in that `os8-run` plus a suitable script
    should be able to do everything that `mkos8` currently does.

*   Provide a suite of scripts and documentation support for creating
    one's own scripts to solve problems we haven't even anticipated.

*   Make it flexible enough to build media images suitable for arbitrary
    real PDP-8 hardware.


[auth]: https://tangentsoft.com/pidp8i/doc/trunk/AUTHORS.md
[rb]:   https://reproducible-builds.org/
[tm]:   https://tangentsoft.com/pidp8i/doc/trunk/tools/test-os8-run


## <a id="capabilities"></a>Capabilities

`os8-run` is a general script running facility that can:

* attach device image files with options that include but also go beyond what SIMH offers:
    * Protect image by attaching it read-only.
    * Recognize the use case of working with a pre-existing image, and abort the script if the image is not found, rather than creating a new, blank image.
    * Protect a master boot image that will not boot read-only by creating a scratch copy and booting the copy instead.
    * Recognize the use case of creating a new, blank image, but preserving any pre-existing image files of the same name.
* boot OS/8 on an arbitrary attached device image.
* create a duplicate of an existing file. This is the use case of building new image files from an existing baseline while preserving the baseline image file.
* copy files from the running OS/8 environment into the POSIX environment
* copy files to the running OS/8 from the POSIX environment running SIMH.
running SIMH.
* run any OS/8 command as long as it returns immediately to the OS/8 Keyboard
Monitor. This includes BATCH scripts.
* run `ABSLDR` and `FOTP`, cycling an arbitrary number of times through the OS/8
Command Decoder.
* run `PAL8` with either a 3 argument form that produces a listing file,
or a 2 argument form that does not.
* run `BUILD` with arbitrarily complex configuration scripts, including
the `BUILD` of a system head that inputs `OS8.BN` and `CD.BN`.
* configure the `tti`, `rx`, `td`, and `dt` devices at run time to allow
shifting between otherwise incompatible configurations of SIMH and OS/8
device drivers.
* run included script files so that common code blocks can be written once
in an external included script.
* run of patch scripts that will use `ODT` or `FUTIL` to patch files in
the booted system image.
* perform actions in a script conditionally on feature enablement matching
an arbitrary keyword.
* perform actions in a script unless a disablement keyword has been specified.
* set enable or disable keywords anywhere in the execution of a script.


## <a id="expect"></a>Key Implementation Detail: Pexpect

Under the covers, `run-os8` is a Python script that uses the [Python
`pexpect` library][pex] to interact programmatically with SIMH and OS/8.
In principle, there is no limit to the complexity of the dialogs we can
script with this.

In practice, the major difficulty in constructing correct Pexpect
scripts is that if you fall out of step with what is "expect"ed, the
expect engine can get into a state where it is blocked waiting for
input that either never will arrive or that already passed by and now
can no longer be matched.  To avoid blocking forever in such situations,
`os8-run` configures Pexpect to time out eventually, resulting in a big
ugly Python backtrace.  The `os8-run` scripts that ship with the
PiDP-8/I software distribution should never do this, but as you write
your own, you may find yourself having to debug such problems.

Running `os8-run` with the `-v` option gives verbose output that
enables you to watch every step of the script as it runs.

[pex]: https://pexpect.readthedocs.io/


## <a id="conventions"></a>Conventions

In the documentation below, we use the term "POSIX" to refer to the
host side of the conversation or to resources available on that side.
We use this generic term because the PiDP-8/I software runs on [many
different platforms][osc], currently limited only to those that are either
POSIX-compliant (e.g. macOS) or those sufficiently close (e.g. Linux).
Thus, a "file from POSIX" refers to a file being copied from the host
system running `os8-run` and SIMH's PDP-8 simulator into the simulated
environment.

Very few script language commands fail fatally.  The design principle
was to ask, "Is the primary use case of this command a prerequisite
for other work that would make no sense if this command failed?"  If
the answer is, "yes", then the failure of command kills the execution
of the whole script and aborts `os8-run`.  Commands that have fatal
exits are mentioned specifically in the [command reference
section](#scripting) below.

### Case Sensitivity -- a tricky issue

It is expected that scripts will be written on the POSIX platform with
a case-sensitive text editor.  `os8-run` should be considered
case-sensitive as well. Scripts should specify the `os8-run` commands
and options in lower case, and the OS/8 commands, options, and
filenames in upper case.

POSIX is ostensibly a case-sensitive platform, filenames, commands
and command arguments are always case sensitive. This was a basic
design decision from the earliest days of ancestral Multics.

The OS/8 platform began as an upper-case only environment.  Only late in
the evolution of the PDP-8 as a word processing platform, did lower
case even exist on OS/8.  SIMH addresses this reality with two different
console device setups, `KSR` and `7b`.

In `KSR` mode, typed lower case characters are upcased automatically before
being sent to the running system.

In `7b` mode, all characters are passed to OS/8 without case conversion.

The current OS/8 default OS/8 system image run with this software distribution
is called `os8v3d-patched.rk05`. It is configured to be as modern as possible.
It contains patches to force lower case characters typed to the Keyboard Monitor
to upper case so they will be understood.  A patch is made to OS/8
BASIC to do the same thing.  However many programs available for use under
OS/8 are upper case only, and get confused unless you set `CAPS LOCK` on
your keyboard.

All of the example scripts specify OS/8 commands in upper case.  Such
commands could have been specified in lower case, and would work just
fine if run in the default `os8v3d-patched.rk05` system image.
However, since a basic use case of `os8-run` is to be able to run
scripts against arbitrary system images (which probably will not have
patches to deal with lower case), use of lower case for OS/8 commands,
arguments, or filenames is discouraged.

`os8-run` does not get involved with forcing OS/8 commands or filenames
to upper case if they appear as lower case in scripts. `os8-run` does
offer commands to toggle the SIMH console support between `KSR` and `7b`.
See the [`configure`](#configure-comm) command.

Although the `os8-run` commands and options could have been made case
insensitive, and the OS/8 commands, options, and filenames could have
been forced to upper case, rendering them case insensitive, there would
still be that aspect where the script developer would have to deal with
establishing case-sensitive POSIX filename conventions that would fit
with OS/8's upper case only filenames.  The decision was made to have
the scripting language require, mindfulness of case, where the developer
adopts a discipline to use lower case for scripting commands, and upper
case when dealing with OS/8.

Apologies in advance for the inconvenience of having to do that. Time
will tell if it was or was not the right decision to have been made.

[osc]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility


## <a id="first"></a>An Illustrative First Example

Here are some example `os8-run` scripts:

Example 1: Begin work on a new RK05 image that gets an updated version
of the OS/8 `BUILD` utility from POSIX source. (Perhaps it was found
on the net.)

    mount rk0 $bin/os8v3d-patched.rk05 required
    mount rk1 $bin/os8-v3f-build.rk05 preserve
    
    cpto $src/os8/v3f/BUILD.PA RKA1:BUILD.PA
    
    boot rk0
    
    pal8 RKB1:BUILD.BN<RKA1:BUILD.PA
    
    begin cdprog SYS:ABSLDR.SV
    RKB1:BUILD.BN
    end cdprog SYS:ABSLDR.SV
    
    os8 SAVE RKB1:BUILD.SV

The above script does the following:

* Attach the system that will do the work on rk0. It must exist.
* Create a new rk05 image, `os8-v3f-build.rk05` but preserve pre-exising versions of the same image.
* Copy the source `BUILD.PA` from the POSIX environment to the OS/8 environment.
* Run `PAL8` to assemble `BUILD.PA` into `BUILD.BN`.
* Run `ABSLDR` to load `BUILD.PA` into memory.
* Save the run image of `BUILD` as an executable on `RKB1:` of the new rk05 image.


## <a id="paths"></a>POSIX Path Expansions

Notice in the [above example](#first) the use of the variables `$bin/`
and `$src/` in the POSIX path specifications.  These refer to particular
directories which vary depending on whether you run this script from
the PiDP-8/I source tree or from the installation tree.  Not only does
using these variables allow the same script to work in both trees, it
allows your script to run regardless of where those source and
installation trees are on any given system.

The scheme works much like predefined POSIX shell variables, but the
underlying mechanism is currently very limited.  First, the substitution
can only occur at the very beginning of a POSIX file specification.
Second, the only values currently defined are:

| $build/   | The absolute path to the root of the build.
| $src/     | The absolute path to the root of the source.
| $bin/     | The directory where executables and runable image files are installed at build time
| $media/   | The absolute path to OS/8 media files
| $os8mi/   | The absolute path to OS/8 media files used as input at build time
| $os8mo/   | The absolute path to OS/8 media files produced as output at build time

To add new values, modify `.../lib/pidp8i/dirs.py.in` and rebuild the
PiDP-8/I software.  Beware that changing this generates the `dirs.py`
file, which is a very deep dependency.  Touching this file will cause
all the OS/8 bootable system image files to be rebuilt, which can take
quite some time even on a fast host computer.


## <a id="contexts"></a>Execution Contexts

It is important to be mindful of the different command contexts when
running scripts under `os8-run`:

* __SIMH context:__  Commands are interpreted by SIMH command processor.
* __OS/8 context:__  Commands are interpreted by the OS/8 Keyboard Monitor.
* __`begin` / `end` blocks:__  These create special interpreter loops with their
own rules.

Examples of `begin` / `end` blocks:

* __Command Decoder:__  Programs like `ABSLDR` and `FOTP` call the OS/8 Command Decoder
to get file specifications and operate on them. `os8-run` uses a `begin` / `end` block to
define set of files to feed to the Command Decoder and to indicate the last file, and
a return to the OS/8 context.
* __OS/8 `BUILD`:__ Commands are passed to `BUILD` and output is interpreted.  The `end`
of the block signifies the end of the `BUILD` program and a return to the OS/8 context.
* __Conditional Execution:__ Blocks of script code, delimited by a `begin` / `block` can be
either executed or ignored depending on the key word that is enabled when that block
is encountered.  This context is very interesting and is more fully documented below.

The commands that execute in the OS/8 environment require a system image
to be attached and booted.  Attempts to run OS/8 commands without having
booted OS/8 kill the script.

Scripting commands such as `mount`, `umount`, and `configure` execute
in the SIMH context. OS/8 is suspended for these commands.

Ideally we would just resume OS/8 with a SIMH continue command when we are
finished running SIMH commands. Unfortunately this does not work under Python
expect.  The expect engine needs a command prompt.

Although hitting the erase character (`RUBOUT`) or the line kill character
(`CTRL/U`) to a terminal-connected SIMH OS/8 session gives a command prompt,
these actions don't work under Python expect. We don't know why.

Booting OS/8 gives a fresh prompt.

Restarting the OS/8 Monitor with a SIMH command line of \"`go 7600`\"
works.

The least disruptive way we have found to resume OS/8 under Python expect
after having escaped to SIMH is to issue the SIMH `continue` command, then
pause for an keyboard delay, then send `CTRL/C` then pause again, then send
`\r\n`.  That wakes OS/8 back up and produces a Keyboard Monitor prompt.

The simh.py code that underlies all this keeps track of the switch
between the SIMH and OS/8 contexts.  However it does not presume to
do this resumption because the `CTRL/C` will quit out of any program
being run under OS/8, and return to the keyboard monitor level.

Because `os8-run` creates the `begin` / `end` blocks with their own
interpreter loops, around commands with complex command structures,
it guarantees that the switch into SIMH context will only happen
when OS/8 is quiescent in the Keyboard Monitor.

Although `os8-run` provides a `resume` command that can appear in
scripts after the commands that escape out to SIMH, using it is optional.
`os8-run` checks the context and issues its own resume call if needed.


## <a id="usage"></a>Usage

> `os8-run` [`-h`] [`-d`] [`-v`] [`-vv`] [`--enable` _enable_option_] ... [`--disable` _disable_option_] ... _script-file_ ...

|                           | **Positional Arguments**
| _script-file_   | One or more script files to run
|                 | **Optional Arguments**
| `-h`            | show this help message and exit
| `-d`            | add extra debugging output, normally suppressed
| `-v`            | verbose script status output instead of the usual few progress messages
| `-vv`           | very verbose: Includes SIMH expect output with the verbose output.
|                 | **Known Enable Options**
| `focal69`       | Add `FOCAL69` to the built OS/8 RK05 image
| `music`         | Add *.MU files to the built OS/8 RK05 image
| `vtedit`        | Add the TECO VTEDIT setup to the built OS/8 RK05 image
|                 | **Known Disable Options**
| `ba`            | Leave *.BA `BASIC` games and demos off the built OS/8 RK05 image
| `uwfocal`       | Leave U/W FOCAL (only) off the built OS/8 RK05 image
| `macrel`        | Leave the `MACREL` assembler off the built OS/8 RK05 image
| `dcp`           | Leave the `DCP` disassembler off the built OS/8 RK05 image
| `k12`           | Leave 12-bit Kermit off the built OS/8 RK05 image
| `cc8`           | Leave the native OS/8 CC8 compiler off the built OS/8 RK05 image
| `crt`           | Leave CRT-style rubout processing off the built OS/8 RK05 image
| `advent`        | Leave Adventure off the built OS/8 RK05 image
| `fortran-ii`    | Leave FORTRAN II off the built OS/8 RK05 image
| `fortran-iv`    | Leave FORTRAN IV off the built OS/8 RK05 image
| `init`          | Leave the OS/8 INIT message off the built OS/8 RK05 image
| `chess`         | Leave the CHECKMO-II game of chess off the built OS/8 RK05 image
| `lcmod`         | Disable the OS/8 command upcasing patch. Used when SIMH has `tti ksr` set.


## Script Language Command Inventory

Here is a list of the `os8-run` scripting language commands in alphabetical order.


| [`boot`](#boot-comm)           | Boot the named SIMH device.                      |
| [`begin`](#begin-end-comm)     | Begin complex conditional or sub-command block.  |
| [`configure`](#configure-comm) | Perform specific SIMH configuration activities.  |
| [`copy`](#copy-com)            | Make a copy of a POSIX file.                     |
| [`cpfrom`](#copy-from-comm) | Copy *from* OS/8 into a file in POSIX environment.  |
| [`cpto`](#copy-to-comm)     | Copy POSIX file *to* OS/8 environment.              |
| [`disable`](#en-dis-comm)      | Set disablement of a feature by keyword.         |
| [`enable`](#en-dis-comm)       | Set enablement of a feature by keyword.          |
| [`end`](#begin-end-comm)       | End complex conditional or sub-command block.    |
| [`exit`](#exit-comm)           | Exit os8-run and send status                     |
| [`include`](#include-comm)     | Execute a subordinate script file.               |
| [`mount`](#mount-comm)         | Mount an image file as a SIMH attached device.   |
| [`os8`](#os8-comm)             | Run arbitrary OS/8 command.                      |
| [`pal8`](#pal8-comm)           | Run OS/8 `PAL8` assembler.                       |
| [`patch`](#patch-comm)         | Run a patch file.                                |
| [`print`](#print-comm)         | Print information from running script.           |
| [`resume`](#resume-comm)       | Resume OS/8 at Keyboard Monitor command level.   |
| [`restart`](#restart-comm)     | Restart OS/8.                                    |
| [`umount`](#umount-comm)       | Unmount a SIMH attached device image.            |

These commands are described in subsections of [Script Language
Command Reference](#scripting) below. That section presents commands
in an order appropriate to building up an understanding of making
first simple and then complex scripts with `os8-run`.


## <a id="scripting"></a>Script Language Command Reference

### <a id="print-comm"></a>`print` - Print information from a running script.

`print` _output_

The simplest script command is `print` which allows display of status
information from the running script.  _output_ is simply displayed.
If the `verbose` option to `os8-run` is set, the line number of the 
print command is included in the output.


### <a id="exit-comm"></a>`exit` - Exit `os8-run` and send status.

`exit` [_status_]

The `exit` command allows immediate termination of the `os8-run` script.   

The _status_ argument is optional.  If the argument is an integer, `os8-run`
will return that status to the calling command shell.  This enables rich
signalling of status when `os8-run` itself is run as a script.

The _status_ argument can also be a string.  If a string is specified,
the status returned by `os8-run` to the command shell is 1, and the
string is printed on exit.  (This is the default behavior of the python
`sys.exit()` procedure.)


### <a id="include-comm"></a>`include` — Execute a subordinate script file.

`include` _script-file-path_

The script file named in _script-file-path_ is executed.  If no fatal
errors are encountered during that execution, then the main script
continues on.

A fatal error in an included script kills the whole execution of
`os8-run`.


### <a id="mount-comm"></a>`mount` — Mount an image file as a SIMH attached device.

`mount` _simh-dev_ _image-file_ [_option_ ...]

Because the primary expectation with `os8-run` scripts is that image
files are mounted, booted and operated on, the failure of a `mount`
command is fatal.


#### `mount` Options

| `new`      | If there is an existing file, rename it with a `.save` extension
|            | because we want to create a new empty image file. If there is
|            | already an existing `.save` version, the existing `.save` version is lost.
| `required` | _image-file_ is required to exist, otherwise abort the script.
| `preserve` | If _image-file_ already exists, create a copy with a version number suffix.
|            | This is useful when you want to prevent overwrites of a good image file
|            | with changes that might not work.  `os8-run` preserves all versions seen
|            | and creates new version that doesn't overwrite any of the previous ones.
| `readonly` | Passes the `-r` option to SIMH attach to mount the device in read only mode.
| `ro`       | Abbreviation for `readonly`.
| `scratch`  | Create a writeable scratch version of the named image file and mount it.
|            | This is helpful when you are booting a distribution DECtape.
|            | Booted DECtape images must be writeable. To protect a distribution DECtape,
|            | use the `scratch` option.  When all script runs are done, the scratch version
|            | is deleted.

Note that the `preserve` and `new` options approach preservation in fundamentally
different ways: `preserve` keeps all old copies, but `new` only keeps the most recent
copy.  This is because it is expected that the `new` option is used with the expectation
that old content is not precious, but that we have a backstop.  Whereas the expectation
of the use of `preserve` is that any and all old versions are precious and should be left
to a person explicitly to delete.

When new image files are created, some sort of initialization is necessary before
files can be written to them.  Although the `new` and `preserve` options could have
performed an OS/8 `ZERO` command to initialize the directories, it was decided
not to do so because in some cases, the OS/8 device drivers required to perform
such actions might not be active until farther down in a complex script.

 
#### `mount` Examples

Mount the `os8v3d-patched.rk05` image, to be found in in the install directory
for runable image files, which must exist, on SIMH `rk0`.

    mount rk0 $bin/os8v3d-patched.rk05 required

Mount the `advent.tu56` image, to be found in the media input directory,
which must exist, on SIMH `dt1` in read only mode, which will protect
it from inadvertent modification.

    mount dt1 $os8mi/subsys/advent.tu56 readonly required

Create a new image file in the media output directory, and mount it on
the SIMH `dt0` device.

    mount dt0 $os8mo/test_copy.tu56 new

Create a writeable copy of the distribution DECtape,
`al-4711c-ba-os8-v3d-1.1978.tu56`, to be found in the media input directory,
which must exist.  Mount it on SIMH dt0 ready for for a read/write boot.
Delete the copy when the script is done.

     mount dt0 $os8mi/al-4711c-ba-os8-v3d-1.1978.tu56 required scratch

Create a new image file `system.tu56` in the install director for
runable image files.  If the file already exists, create a new
version.  If the numbered version file exists, keep incrementing the
version number for the new file until a pre-existing file is not
found.

For example, if `system.tu56` was not found, the new file would be
called `system.tu56`.  If it was found the next version would be
called `system_1.tu56`.  If `system_1.tu56` and `system_2.tu56` were
found the new file would be called `system_3.tu56`, and so on.

     mount dt0 $bin/system.tu56 preserve

The `preserve` option is helpful when experimenting with scripts that may
not work the first time.


### <a id="umount-comm"></a>umount — Unmount a SIMH attached device image.

`umount` _simh-device_

This is just a wrapper for the SIMH `detach` command.

Here is the rationale for having added a `umount` command instead of
just calling the `detach` command from SIMH by its own same name:

Starting from the idea of providing some abstract but useful actions
to take around the SIMH `attach` command, the decision was made to
lean on the POSIX  `mount` command because people familiar with
`mount` were used to hanging lots of different abstract but useful
actions off of it.

`umount` was adopted as _what people familiar with `mount` would
expect as the command to undo what `mount` had done_. This seemed
preferable to inventing _`attach` with more features_ as a wholly
new syntactic/semantic design.


### <a id="boot-comm"></a>`boot` — Boot the named SIMH device.

`boot` _simh-device_

Boot OS/8 on the named _simh-device_ and enter the OS/8 run-time context.

The `boot` command tests to see if something is attached to the
SIMH being booted.  If nothing is attached, the command fails with a
fatal error.

This test does not protect against trying to boot an image lacking a
system area and thus not bootable.  This can't be tested in advance
because booting a non-bootable image simply hangs the virtual machine.
Heroic measures, like looking for magic system area bits in the image
file were deemed too much work.

If an attempt is made to boot an image with no system area, `os8-run`
hangs for a while and then gives a timeout backtrace.


### <a id="resume-comm"></a>`resume` — Resume OS/8 at Keyboard Monitor command level.

`resume`

As explained above in the [Execution contexts](#contexts) section, we
can't just issue a SIMH `continue` command because we need some output
from OS/8 running within SIMH to re-synchronize Python expect to.

After trying several different things that did not work, the least
disruptive action is to send `CTRL/C` and a newline with some keyboard
delays. The `resume` command does this.

However, because the context switches are well-defined, the `resume`
command is completely optional in scripts.  Instead `os8-run`, when it
detects the need to return to OS/8 from SIMH command level, will issue
a `resume` command to force a context switch. 


### <a id="restart-comm"></a>`restart` — Restart OS/8.

`restart`

Equivalent to the SIMH command line of \"`go 7600`\".

Before `resume` was developed, the next less disruptive way to get an
OS/8 Keyboard Monitor prompt was to restart SIMH at address 07600.
This is considered a soft-restart of OS/8.  It is less disruptive than
a `boot` command, because the `boot` command loads OS/8 into main
memory from the boot device, whereas restarting at location 07600 is
just a resart without a reload.

The restart does re-initilaize some state so it is more disruptive
than the `CTRL/C` resume documented above.


### <a id="copy-comm"></a>`copy` — Make a copy of a POSIX file.

`copy` _source-path_ _destination-path_

The most common activity for `os8-run` is to modify a system image.

However, we often want to keep the original and modify a copy.
For example, `os8v3d-patched.rk05`, a commonly used system image comes
from modifying `os8v3d-bin.rk05`.  We keep the latter around so we
don't have to keep rebuilding the baseline.

Instead of requiring some external caller to carefully preserve the
old file, the "make a copy with arbitrary name" functionality was
added by way of this command.

Adding an option to `mount` was considered, but in the interests
of allowing an arbitrary name for the modified image, a separate
command was created.


### <a id="copy-to-comm"></a>`cpto` — Copy POSIX file *to* OS/8 environment.

`cpto` _posix-path_ [_option_]

`cpto` _posix-path_ _os8-filespec_ [_option_]

The option is either empty or exactly one of

| `/A` | OS/8 `PIP` ASCII format. POSIX newlines are converted to OS/8 newlines.
| `/B` | OS/8 `PIP` `BIN` format. Paper tape leader/trailer may be added.
| `/I` | OS/8 `PIP` image format. Bit for Bit copy.

If no option is specified, `/A` is assumed.

In the first form of the command, the OS/8 file specification is left
out, and one is synthesized from the file component of the _posix-path_.

This is how you get files *to* OS/8 from the outside world.  For
example, this enables source code management using modern tools.  The
builder script would check out the latest source and use an `os8-run`
script beginning with a `cpto` command to send it to OS/8 for
assembly, linking, installation, etc.

Example:

Copy a POSIX file init.cm onto the default OS/8 device `DSK:` under the name `INIT.CM`:

     cpto ../media/os8/init.cm


### <a id="copy-from-comm"></a>`cpfrom` — Copy *from* OS/8 to a file in POSIX environment. 

`cpfrom`_os8-filespec_ _posix-path_ [_option_]

The option is either empty or exactly one of

| `/A` | OS/8 `PIP` ASCII format. POSIX newlines are converted to OS/8 newlines.
| `/B` | OS/8 `PIP` `BIN` format. Paper tape leader/trailer may be added.
| `/I` | OS/8 `PIP` image format. Bit for Bit copy.

If no option is specified, `/A` is assumed.

Unlike `cpto` there is only one form of the command.  Both the
_os8-filespec_ and the _posix-path_ must be specified.  The options
are the same for both `cpfrom` and `cpto`.

Copy files from the running OS/8 environment to the POSIX environment running SIMH.

Example:

Copy a listing file into the current working directory of the
executing `os8-run`:

    cpfrom DSK:OS8.LS ./os8.ls /A


### <a id="os8-comm"></a>`os8` — Run arbitrary OS/8 command.

`os8` _os8-command-line_

Everything on the script command line after \"os8 \" is passed,
uninterpreted, to the OS/8 keyboard monitor with the expectation that
the command will return to the monitor command level and the command
prompt, "`.`" will be produced.

This command should be used ONLY for OS/8 commands that return
immediately to command level.  `BATCH` scripts do this, and they can
be run from here.


### <a id="pal8-comm"></a>`pal8` — Run OS/8 `PAL8` assembler.

Run `PAL8` with either a 3 argument form that produces a listing file,
or a 2 argument form that does not.

Actually, the `PAL8` assembler can be called just fine
by using the `os8` command, for example:

    os8 PAL8 RKB1:RL0.BN<RKA1:RL0.PA
   
However, an separate pal8 command was created to enable richer parsing
of errors when no listing file is created.  This decision is currently
under review, and the `pal8` command may go away in a subsequent version
of `os8-run`.  For now, two forms of the `pal8` command are supported with
an unreasonable number of limitations:

`pal8` _os8-bn-spec_ `<` _os8-pa-spec_

`pal8` _os8-bn-spec_ `,` _os8-ls-spec_ `<` _os8-pa-spec_

Note that the parser for this wrapper for `PAL8` is much too
conservative in what it allows:

* No `PAL8` options are allowed.
* Only two ways to call `PAL8`:
    * two argument form with binary and source or
    * three argument form with binary, listing, and source.
* _os8-bn-spec_ must specify a binary filename ending in `.BN`
* _os8-ls-spec_ must specify a listing filename ending in `.LS`
* _os8-pa-spec_ must specify a source filename ending in `.PA`

This should be improved.  The reason why this wrapper is so
constrained is that it evolved from extremely rudimentary, hard-coded
scripts, and hasn't been worked on since reaching minimum necessary
functionality.

The three file name specifiers can include an OS/8 device specification.

Examples:

Create a binary `OS8.BN` on partition B of rk05 drive 1 from `OS8.PA`
source file found on partition A of rk05 drive 1.

    pal8 RKB1:OS8.BN<RKA1:OS8.PA

Create a binary `OS8.BN` on partition B of rk05 drive 1 and a listing
file `OS8.LS` on the default device `DSK:` from `OS8.PA` source file
found on partition A of rk05 drive 1.

    pal8 RKB1:OS8.BN,OS8.LS<RKA1:OS8.PA


### <a id="begin-end-comm"></a>`begin` / `end` — Complex conditionals and sub-command blocks.

`begin` _keyword_ _argument_

`end` _keyword_

_keyword_ is either one of the following:

| `cdprog`  | Command loop through OS/8 Command Decoder with _argument_ specifying |
|           | an OS/8 executable program by name and (optionally) device.|
| `build`        | `BUILD` command interpreter with dialogs manged with Python expect.    |
| `enabled`      | Execution block only if _argument_ is enabled. (See the [`enable` \ `disable`](#en-dis-comm)) section below. |
| `default` | Execution block that runs by default but is ignored if _argument_ is disabled. |
|           | (See the [`enable` \ `disable`](#en-dis-comm) section below.) |
| `version` | Execution block that runs if the current version of the `os8-run` |
|           | scripting language is equal to or greater than the specified version string. |
|           | (See [version test](#vers-test) below.)|

For `cdprog`, and `build`, _argument_ is passed uninterpreted to the
OS/8 `RUN` command.  It is expected that _argument_ will be the name
of an executable, optionally prefixed by a device specification. This
enables running the OS/8 command from specific devices. This is
necessary for running specific `BUILD` command for construction of
system images for specific versions of OS/8 that are __different__
from the default run image.

Example:

Run `FOTP.SV` from device `RKA0` and cycle through the command decoder
to copy files onto a DECtape under construction from two different
places: the old system on `RKA0:` and the newly built components from
`RKB1:`.

    begin cdprog RKA0:FOTP.SV
    DTA0:<RKA0:FOTP.SV
    DTA0:<RKA0:DIRECT.SV
    DTA0:<RKB1:CCL.SV
    DTA0:<RKB1:RESORC.SV
    end cdprog RKA0:FOTP.SV

The `build` command has had a lot of work put into parsing dialogs.
This enables not only device driver related `BUILD` commands of
`LOAD`, `UNLOAD`, `ENABLE` and `DISABLE`, but also answers "yes" to
the "ZERO SYS" question when the `BOOT` command is issued on a brand
new image file.

Example:

Build a rudimentary system for a TC08 DECtape.

    begin build SYS:BUILD
    DELETE SYS,RKA0,RKB0
    DELETE RXA0
    INSERT RK05,RKA0,RKB0
    SYSTEM TC08
    INSERT TC08,DTA0
    INSERT TC,DTA1
    DSK TC08:DTA0
    BOOT
    end build


Most importantly there is full support for the dialog with the `BUILD`
command within the `BUILD` program to create a new OS/8 system head
with new versions of `OS8.BN` and `CD.BN` assembled from source.

Example:

To create a system tape with new OS/8 Keyboard Monitor and Command
Decoder, the above example would add the following just before the
`BOOT` line:

    BUILD DSK:OS8.BN DSK:CD.BN

Note: OS/8 disables the `BUILD` command within the `BUILD`
program after it has been issued during a run.  Traditionally, the
first action after a `BOOT` of a newly built system is to `SAVE` the
just executed memory image of `BUILD`.  That saves all the device
configurations, but also saves a version with the `BUILD` command
within the `BUILD` program disabled.

For this reason, you have to run a fresh version of `BUILD` from
distribution media rather than one saved from a previous run.  This
situation is what drove support for the _argument_ specifier to name
the location of the program to run rather than always running from a
default location.

Also, `BUILD` is too sensitive to the location of the `OS8.BN` and
`CD.BN` files. It pretty much only works if you use `PTR:` or `DSK:`.
Anything else seems to just hang.  I believe the root cause is that,
although the device and file are parsed, the actual device has to be
either `PTR:` or the active system device.

`os8-run` contains two lists of keywords that have been set as enabled
or disabled.  The setting is done either with `os8-run` command line
arguments or with the `enable` and `disable` commands (documented
below.)

Two lists are required because default behavior is different for
enablement versus disablement.

The `begin enabled` block is only executed if the `enabled` list
contains the keyword. If no such keyword is found, the block is ignored.

The `begin default` block is executed by default unless the `disabled`
list contains the keyword. If such a keyword is found, the block is ignored.

The `default` construct allows creation of scripts with conditional
execution  without worrying about informing the build system about new
enablement keywords.
 
All these conditional and sub-command blocks must terminate with an
`end` command.  The _keyword_ of the end command must always match the
_begin_ command.  The argument of `enabled` and `default` blocks
must also match. Nesting is possible, but care should be exercised to
avoid crossing nesting boundaries.

For example:

    begin enabled outer
    begin enabled inner
    end enabled inner
    end enabled outer

is correct, but:

    begin enabled first
    begin enabled second
    end enabled first
    end enabled second

is an error.


### <a id="en-dis-comm"></a>`enable` / `disable` — Set an enablement or disablement.

`enable` _keyword_

`disable` _keyword_

The `enable` and `disable` commands are used within scripts to
dynamically set enablement and disablement.  This expands the scope of
conditional execution beyond setting passed in from the `os8-run`
command line.

As mentioned above, there are two lists of keywords, one for `enabled`
keywords and one for `disabled` keywords.

The `enable` command not only adds the keyword to the `enabled`
list. It also looks for the keyword on the `disabled` list.  If the
keyword is found on the `disabled` list, it is **removed**.

Similarly, the `disable` command adds the keyword to the `disabled`
list, and searches the `enabled` list for the keyword.  If it is found
on the `enabled` list, it is removed.

A keyword, will appear only once, if present at all, and will be on
only one of the two lists.

The rule is: Last action wins.

Why all this complexity? Here is an example we tripped over and had to
implement:  We normally apply patches to the version of `FUTIL` that
came on the OS/8 v3d distribution DECtapes.  We also have an add-on
for the `MACREL` assembler.  That add-on contains a version of `FUTIL`
with updates required to work with binaries assembled with `MACREL` v2.
The `os8v3d-patch.mkos8` script needed to either avoid trying to
patch an updated `FUTIL` if `MACREL` was present, or to perform the
patching action if `MACREL` was not present.

A further complication is that we opt in to including the `MACREL`
add-on by default.  We deal with this triple negative by setting
`disable futil_patch` by default, unless `macrel` gets disabled:

    # MACREL is enabled by default with no settings.
    # We need to avoid patching FUTIL in that default case
    # So we have to set a disablement of that action by
    # default as well.
    
    begin default macrel
    disable futil_patch
    end default macrel
    
    begin default futil_patch
    # The two FUTIL patches only get applied to FUTIL V7 which comes with
    # OS/8 V3D to bring it up to V7D.  MACREL V2 comes with FUTIL V8B, so
    # these patches are skipped by mkos8 using an RE match on the file name
    # when the user does not pass --disable os8-macrel to configure.
    patch ../media/os8/patches/FUTIL-31.21.1M-v7B.patch8
    patch ../media/os8/patches/FUTIL-31.21.2M-v7D.patch8
    end default futil_patch


### <a id="vers-test"></a> version test

The `os8-run` scripting language is expected to evolve over time.  An internal
language version number is kept, and incremented when major or minor changes
are made to the language.

This version numbering scheme can be detected and acted upon within a script
by specifying a `version` match string in a `begin` / `end` block.

The language version string is sequence of numerical sub version numbers of arbitrary
depth separated by periods. Examples of valid language version strings:

    3
    3.1
    3.10
    3.10.1

Each sub version is an integer of arbitrary precision.

Clarifying exmple:  3.10 is higher than 3.1.0.

No whitespace is allowed within a version match string.


Therefore a conditional block requiring language version 2.0 and higher
would look like this:

    begin version 2.0
    # The symprini command exists only in version 2 and above.
    symprini
    end version 2.0


### <a id="patch-comm"></a>`patch` — Run a patch file.

`patch` _patch-file-path_

Run _patch-file-path_ file as a script that uses `ODT` or `FUTIL` to
patch the booted system image.


### `configure` — Perform specific SIMH configuration activities.

`configure` _device_ _setting_

The settings are device specific:

| -------- | --------------------------------------------------------------- |
| **tape** | **DECtape device settings**                                |
| `dt`     | Set TC08 operation by enabling `dt` as the SIMH DECtape device. |
| `td`     | Set TD8e operation by enabling `td` as the SIMH DECTape device. |
| -------- | --------------------------------------------------------------- |
| **tti**  | **Console terminal input device settings**               |
| `KSR`    | Upper case only operation. Typed lower case characters    |
|          | are upcased automatically before being sent to OS/8      |
| `7b`     | SIMH 7bit mode.  All characters are passed to OS/8       |
|          | without case conversion.                                 |
| -------- | --------------------------------------------------------------- |
| **rx**   | **Floppy Disk device settings**                          |
| `RX8E`   | Set the SIMH `rx` to `RX8E` mode compatible with RX01    |
|          | Floppy Disk Drives.                                      |
| `RX28`   | Set the SIMH `rx` to `RX28` mode compatible with RX02    |
|          | Floppy Disk Drives.                                      |
| `rx01`   | Synonym for the `RX8E` option. Compatible with RX01.     |
| `rx02`   | Synonym for the `RX28` option. Compatible with RX02.     |
| -------- | --------------------------------------------------------------- |

This command allows reconfiguration of the SIMH devices during the
execution of a `os8-run` script.  This command makes it possible to
create system images for hardware configurations that are not what are
commony used for OS/8 operation under SIMH.

The best example is the dichotomy between TD8e and TC08 DECTape.

TC08 is a DMA device. It is trivial to emulate. The SIMH device driver
simply copies blocks around in the .tu56 DECtape image.

TD8e is an inexpensive, DECtape interface on a single hex width card
for PDP8 hardware supporting the Omnibus&tm.  The CPU does most of the
work. Although a SIMH emulation is available for TD8e, it runs
perceptably and often unacceptably more slowly than the simple TC08
emulation.

However, hardware in the field most often has the TD8e DECtape because
it was inexpensive.

By allowing reconfiguration inside a script, we can use TC08 by
default, switch to TD8e to run `BUILD` and create .tu55 tape images
suitable for deployment on commonly found hardware out in the real
world. 


## TODOs

* Allow passing in of arguments to PAL8.
* Add sanity check parse of sub-commands to confirm command. **OR** Change the 
begin command to treat _argument_ not as a full command, but merely
a device from which to fetch the command.  Maybe make _argument_ optional.


## Notes

* No notes as of yet.

### <a id="license"></a>License

Copyright © 2018 by Bill Cattey and Warren Young. Licensed under the
terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# simh-os8-script.py Library for scripting OS/8 under SIMH
# Contains validators and callers for os8 and simh commands to make
# it easier to create scripts.
#
# Copyright © 2017 by Jonathan Trites, William Cattey, and Warren Young.
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys
import tempfile
sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Python core modules we use
import re
from string import Template
import shutil
import subprocess

# Our local modules
from pidp8i import *
from simh import *

# Script Language Version
# Update this version number as the language evolves.
# Version 1.0 is the first public version.
LANG_VERSION = "1.0"

# Error Class Definitions ##############################################
# Enables us to use exceptions from within this module.

class Error(Exception):
  """Base Class for exceptions in this module."""
  pass

class InputError(Error):
  """Exception raised for errors in the input.

  Attributes:
  expr -- input expression in which the error occurred
  msg  -- explanation of the error
  """

  def __init__(self, msg):
    self.msg = msg

  def __str__(self):
    return self.msg

      
# Private globals ######################################################
# Visible within this file, but not to the outside.

# Identify a begin enabled/not_disabled command. group(1) contains either the enabled or
# disabled flag. Put the rest of the line in group(2)
_begin_en_dis_comm_re = re.compile ("^begin\s+(enabled|default|version)\s+(.+)$")
  
# Identify an end enabled/not_disabled command. group(1) contains either the enabled or
# disabled flag. Put the rest of the line in group(2)
_end_en_dis_comm_re = re.compile ("^end\s+(enabled|default|version)\s+(.+)$")
  
# Identify an end comm and put the rest of the line in group(1)
_end_comm_re = re.compile ("^end\s+(.+)?$")
  
# Identify an end option command and put the rest of the line in group(1)
_end_option_comm_re = re.compile ("^end\s+option\s+(.+)$")

# A valid version spec
_version_parse_re = re.compile ("^((\d+\.)*)?(\d+)?$")
  
# Name of the DECtape image file we create
_new_sys_tape_prefix = "system"

# Parser regexps used in patcher
_com_os8_parse_str = "^\.([a-zA-Z]+)\s*(.*)$"
_com_os8_parse = re.compile(_com_os8_parse_str)
_com_split_str = "^([a-zA-Z]+)\s*(.*)$"
_com_split_parse = re.compile(_com_split_str)
_odt_parse_str = "^([0-7]+)\s*/\s*(\S+)\s+([0-7;]+)"
_odt_parse = re.compile(_odt_parse_str)

# Put command keyword in group(1) and the rest is in group(3)
_comm_re_str = "^(\S+)(\s+(.+))?$"
_comm_re = re.compile(_comm_re_str)

# Identify an end comm and put the rest of the line in group(1)
_end_comm_re = re.compile ("^end\s+(.+)?$")

# Identify an end option command and put the rest of the line in group(1)
_end_option_comm_re = re.compile ("^end\s+option\s+(.+)$")

# Identify a begin command and put the rest of the line in group(1)
_begin_option_comm_re = re.compile ("^begin\s+option\s+(.+)$")

# Parse an argument string into a sys device with
# device name in group(1), unit number in group(2)
# We put all bootable devices into this string so that when
# we add more devices, for example rl for RL01, we change one
# string not many.
_simh_boot_dev_str = "(rk|td|dt|rx)(\d*)"
_simh_boot_re = re.compile("^" + _simh_boot_dev_str + "$")

# Parse an argument string for mount into SIMH device
# device name in group(1), unit number in group(2)
# And the rest in group (3)
_mount_regex_str = "^" + _simh_boot_dev_str + "\s+(.+)$"
_mount_re = re.compile(_mount_regex_str)

# Map of SIMH device names to OS/8 device name prefixes.
_os8_from_simh_dev = {"rk" : "RK", "td" : "DTA", "dt" : "DTA", "rx" : "RX"}

_os8_partitions = {"RK": ["A", "B"]}

# OS/8 file name matching regex
_os8_file_re = re.compile("(\S+):(\S+)?")

# Regular expression for syntax checking inside FOTP
# Destination is in group(1), Source is in group(3)
_fotp_re = re.compile ("^((\S+:)?\S+)<((\S+:)?\S+)$")

# Regular expression for detecting the 2 arg and 3 arg forms
# of the "pal8" script command.

# OS/8 name regex template:
# Optional device spec, i.e. DTA0:
# File spec with a specific extension or no extension.

_os8_fspec = Template ("((\S+:)?([A-Z0-9]{1,6}|[A-Z0-9]{1,6}\.$ext))")
_os8_BN_fspec = _os8_fspec.substitute(ext="BN")
_os8_PA_fspec = _os8_fspec.substitute(ext="PA")
_os8_LS_fspec = _os8_fspec.substitute(ext="LS")

# For the two arg form:
# The full destination spec is in group(1), The full source spec is in group(4).
# The device components, if any, are in group(2) for destination, and
# group(5) for source.
# The file components are in group(3) for destination, and group (6) for source.
# The destination file must either end in ".BN" or have no extension.
# The source must file either end in ".PA" or have no extension.
_two_arg_pal_re = re.compile ("^" + _os8_BN_fspec + "\s*<\s*" + _os8_PA_fspec + "$")

# For the 3 arg form:
# The full destination spec is in group(1), The full source spec is in group(7).
# The full listing spec is in group(4)
# The device components, if any, are in group(2) for destination, group(5)
# for listing, and group(8) for source.
# The file components are in group(3) for destination, and group(9) for source,
# and group(6) for listing.
# The destination file must either end in ".BN" or have no extension.
# The source must file either end in ".PA" or have no extension.
# The listing must either end in "LS" or have no extension.

_three_arg_pal_re = re.compile ("^" + _os8_BN_fspec + "\s*,\s*" + _os8_LS_fspec + "\s*<\s*" + _os8_PA_fspec + "$")

# Regular expression for syntax checking inside ABSLDR
# One or more OS/8 binary files and optional args beginning with a slash.

_absldr_re = re.compile ("^" + _os8_BN_fspec + "(," + _os8_BN_fspec + ")*(/\S)*$")

# Regular expressions for syntax checking for cpto and cpfrom.
# May be <source> where destination and default option /A is implied.
# Or <source> <option> where destination is implied and option is set.
# Or <source> <destination> where option /A is implied.
# Or <source> <destination> <option> are explicit.
# Valid options are "/A", "/I", and "/B"
# Use two regex's in order:
# <source> in group 1, <dest> in group 2.
# Option is one of /I /B /A in group 4.

# source in group 1, option in group 3.
_from_to_re_1 = re.compile ("^(\S+)(\s+(/[AIB]))?$")
# source in group 1, destination in group 2, option in group 4.
_from_to_re_2 = re.compile ("^(\S+)\s+(\S+)(\s+(/[AIB]))?$")

# Array of regular expressions for syntax checking inside BUILD
_build_comm_regs = {"LOAD"  : re.compile("^(\S+:)?\S+(.BN)?$"),
                    "UNLOAD": re.compile("^\S+(,\S+)?$"),
                    "INSERT": re.compile("^\S+,\S+(,\S+)?$"),
                    "DELETE": re.compile("^\S+(,\S+)?$"),
                    "SYSTEM": re.compile("^\S+$"),
                    "DSK"   : re.compile("^(\S+:)?\S+$"),
                    "BUILD" : re.compile("^(\S+(.BN)?)\s+(\S+(.BN)?)$"),
                    "PRINT" : None,
                    "BOOT"  : None,
                    "end"   : None}

_build_replies = ["\\$", "SYS BUILT", "WRITE ZERO DIRECT\\?", "\\?BAD ARG",
                  "\\?BAD INPUT", "\\?BAD LOAD",
                  "\\?BAD ORIGIN", "\\?CORE", "\\?DSK", "\\?HANDLERS",
                  "I/O ERR", "\\?NAME", "NO ROOM", "SYS NOT FOUND",
                  "\\?PLAT", "\\?SYNTAX", "\\?SYS", "SYS ERR",
                  "\S+ NOT FOUND"]

# Parse two whitspace separated arguments into group(1) and group(2)
_two_args_re = re.compile("^(\S+)\s+(\S+)$")

_rx_settings = ["rx01", "rx02", "RX8E", "RX28"]
_tape_settings = ["td", "dt"]
_tti_settings = ["KSR", "7b"]
_configurables = {"rx": _rx_settings, "tape": _tape_settings,
                  "tti": _tti_settings}

# Matches if the string begins with a dollar sign, and has at least
# one slash, returning the string between the dollar sign and the
# first slash in group 1 and the rest in group 2.
# No whitespace in the string.
_expandable_re = re.compile ("^\$([^/\s]+)/(\S*)$")

# Parse an exit arg for an integer or an integer in parentheses
_exit_arg_re = re.compile ("^(\s*[+-]?\s*\d+)|\s*\(\s*([+-]?\s*\d+)\s*\)\s*$")

# Options enabled/not_disabled for conditional execution in scripts.
#
# Earlier code allowed --enable and --disable. We interface to it.
# We maintain two arrays: options_enable and options_disabled for those
# two argument constructs.
#
# Argument parsing of repeated enable and disable arguments is as follows:
# --enable looks on options_disabled and if present removes it, then adds
# to options_enabled.
# --disable looks on options_enabled and if present removes it, then adds
# to options_enabled.
#
# Last seen enable/disable command line or executed command for a
# particular option wins.
#
# Scripts have enable/disable commands that are run-time
# changers of the contents of options_enabled and options_disabled.
#
# When we run a script we have begin/end blocks for enabled/not_disabled options:
# "begin enabled <option name>" ... "end enabled <option name>
# "begin not_disabled <option name>" ... "end not_disabled <option name>
#
# The enabled block looks for an explicit enablement on the options_enabled
# list. If none is found we default to ignoring the contents of the block.
#
# The not_disabled block looks for an explicit disablement on the
# options_disabled lis.  If found, the block is ignored. Otherwise
# the block defaults to being executed.
#
# begin/end blocks can be nested.  We track the nesting with options_stack.
# Testing for options happens when the begin command is evaluated.
# So changing an enable/disable option inside a begin/end block
# takes effect at the next begin statement. 
# You can write a script as follows:
# enable foo
# begin enabled foo
# # Commands to executed
# disable foo
# # Commands still being executed.
# begin enabled foo
# # Commands to ignore
# end enabled foo
# end enabled foo

# Local routine to perform a save of a pre-existing file
# because we do this in a couple places

def save_if_needed(path):
  if os.path.isfile(path):
    save_path = path + ".save"
    print "Pre-existing " + path + " found.  Saving as " + path + ".save"
    if os.path.isfile(save_path):
      print "Overwriting old " + path + ".save"
      os.remove(save_path)
    os.rename(path, save_path)
  
def version_to_array (version):
  vers_array = []
  this_str = ""

  for c in version:
    if c != ".":
      this_str += c
    else:
      vers_array.append(this_str)
      this_str = ""
  if this_str != "": vers_array.append(this_str)
  return vers_array


class os8script:
  # Contains a simh object, other global state and methods
  # for running OS/8 scripts under simh.
  #### globals and constants ###########################################
  
  
  def __init__ (self, simh, enabled_options, disabled_options, verbose=False, debug=True):
    self.lang_version = LANG_VERSION
    self.verbose = verbose
    self.debug = debug
    self.simh = simh
    self.options_enabled = enabled_options
    self.options_disabled = disabled_options
    # Do we need separate stacks for enabled/disabled options?
    self.options_stack = []
    # List of scratch files to delete when we are done with all script runs.
    self.scratch_list = []
    self.booted = False
    self.line_ct_stack = []


  #### path_expand #######################################################
  # Simple minded variable substitution in a path.
  # A path beginning with a dollar sign parses the characters between
  # the dollar sign and the first slash seen becomes a name to
  # expand with a couple local names: $home and the anchor directories
  # defined in lib/pidp8i/dirs.py.
  # Returns None if the expansion fails.  That signals the caller to fail.

  def path_expand (self, path):
    m = re.match(_expandable_re, path)
    if m == None: return path
    var = m.group(1)

    val = getattr (dirs, var, None)
    if val != None:
      return os.path.join(val,m.group(2))
    else:
      print "At line " + str(self.line_ct_stack[0]) + \
        ": {$" + var + "} is not a valid path expansion in " + path
      return None
    

  #### print_expand ######################################################
  # Close kin to path_expand.  Takes a string that may name a path
  # substitution or the magic $version value and performs the appropriate
  # value substitution.

  def print_expand (self,str):
    end = str.find("$")
    if end == -1: return str

    m = re.findall("\$\S+",str)
    if m == None: return str

    outstr = ""
    start = 0

    for name in m:
      end = str.index(name, start)
      outstr += str[start:end]

      sub = getattr (dirs, name[1:], None)
      if sub == None:
        if name == "$version": sub = self.lang_version
        else: sub = name

      outstr += sub
      start = end + len(name)

    return outstr
      

  #### version_test ######################################################
  # Compare each component of the version test agains the actual version
  # Return true if actual version is greater than or equal to the test
  # version.
  # Caller validates test with _version_parse_re so we only
  # need to return True or False, not error.
  
  def version_test (self, test):
    test_array = version_to_array(test)
    version_array = version_to_array(self.lang_version)
    
    idx = 0
    endpoint = len(test_array)

    while idx < endpoint:
      # If version has more digits than test, the greater than test succeeds.
      if idx >= len(version_array):
           vers_item = "0"
      else:
         vers_item = version_array[idx]
      test_item = test_array[idx]
      if self.debug: print  "version_test: vers_item: " + vers_item + \
         ", test_item: " + test_item

      vers_num = int(vers_item)
      test_num = int(test_item)

      # First time version componet greater than test -> success.
      if vers_num > test_num:
        if self.debug: print "version_test: Success: version greater than test."
        return True
      # First time version component less than test -> failure.
      elif test_num > vers_num:
        if self.debug: print "version_test: Fails on sub compare."
        return False
      #Otherwise is equal. Keep going.

      idx += 1
    # Made it all the way through. Test succeeds.
    if self.debug: print "version_test: Success. Made it thru test string."
    return True

          
  #### basic_line_parse ################################################
  # Returns stripped line and any other cleanup we want.
  # Returns None if we should just 'continue' on to the next line.
  # Filters out comments.
  # Processes the option begin/end blocks.
  
  def basic_line_parse (self, line, script_file):
    self.line_ct_stack[0] += 1
    retval = line.strip()
    if retval == "": return None
    elif retval[0] == "#": return None
    # First test if we are in a begin option block
    m = re.match (_begin_en_dis_comm_re, retval)
    if m != None:
      en_dis = m.group(1)
      rest = m.group(2)
      if self.verbose: print "Line " + str(self.line_ct_stack[0]) + \
         ": doing_begin_option: " + en_dis + " " + rest
      if self.debug: print "options_enabled: " + str (self.options_enabled)
      if self.debug: print "options_disabled: " + str (self.options_disabled)
      if self.debug: print "options_stack: " + str(self.options_stack)

      vers_match = False
      if en_dis == "version":
        # Check for mal-formed version match first
        if re.match (_version_parse_re, rest) == None:
          print "Mal-formed version match string {" + rest + "} at line " + \
            str(self.line_ct_stack[0]) + ". Ignoring this block."
          self.ignore_to_subcomm_end (retval, script_file, en_dis + " " + rest)
          return None
        vers_match = self.version_test (rest)
        if vers_match:
          # Block is active. We push it onto the stack
          if self.debug: print "Pushing version enabled block " + rest + " onto options_stack"
          self.options_stack.insert(0, rest)
          if self.debug: print " new options_stack: " + str(self.options_stack)
        else:
          # Option is inactive.  Ignore all subseqent lines
          # until we get to an end command that matches our option.
          self.ignore_to_subcomm_end (retval, script_file, en_dis + " " + rest)
        return None
        
      elif en_dis == "enabled":
        if rest in self.options_enabled:
          # Block is active. We push it onto the stack
          if self.debug: print "Pushing enabled block " + rest + " onto options_stack"
          self.options_stack.insert(0, rest)
          if self.debug: print "new options_stack: " + str(self.options_stack)
        else:
          # Option is inactive.  Ignore all subseqent lines
          # until we get to an end command that matches our option.
          self.ignore_to_subcomm_end (retval, script_file, en_dis + " " + rest)

        return None
      # only other choice is disabled because of our regex.
      else:
        if rest not in self.options_disabled:
          # Block defaults to active. We push it onto the stack
          if self.debug: print "Pushing not_disabled block " + rest + " onto options_stack"
          self.options_stack.insert(0, rest)
          if self.debug: print "new options_stack: " + str(self.options_stack)
        else:
          # Block is inactive.  Ignore all subseqent lines
          # until we get to an end command that matches our option.
          self.ignore_to_subcomm_end (retval, script_file, en_dis + " " + rest)
        return None
  
    m = re.match(_end_en_dis_comm_re, retval)
    if m != None:
      rest = m.group(2)
      if self.verbose: print "Line " + str(self.line_ct_stack[0]) + ": end rest = " + rest
      if (rest == None or rest == ""):
        print "Warning! option end statement at line " + str(self.line_ct_stack[0]) + \
          " encountered with no argument."
        return None
      if len(self.options_stack) == 0:
        print "Warning! option end statement at line " + str(self.line_ct_stack[0]) + \
          " found with no matching begin for option: " + rest
        return None
      if rest != self.options_stack[0]:
        print "Warning! Mismatched option begin/end group at line " + \
          str(self.line_ct_stack[0]) + ". Currently inside option: " + \
          self.options_stack[0] + " not " + rest
        return None
      else:
        if self.debug: print "Popping " + self.options_stack[0]
        self.options_stack.pop(0)
        if self.debug: print "new options_stack: " + str(self.options_stack)
        return None
  
    return retval
  
  
  #### ignore_to_subcomm_end ###########################################
  
  def ignore_to_subcomm_end (self, old_line, script_file, end_str):
    if self.debug: print "ignore to: " + end_str
    for line in script_file:
      self.line_ct_stack[0] += 1
      line = line.strip()
      if self.verbose: print "Ignore line " + str(self.line_ct_stack[0]) + ": " + line
      
      m = re.match(_end_comm_re, line)
      if m == None: continue
  
      rest = m.group(1)
      if rest == None: rest = ""
      
      if rest == end_str: return
  
  
  #### include_command #################################################
  # Call run_system_script recursively on the file path provided.
  
  def include_command (self, line, script_file):
    path = self.path_expand(line)
    if path == None:
      print "Ignoring: \n\tinclude " + line
      return "fail"

    if not os.path.isfile(path):
      print "Line " + str(self.line_ct_stack[0]) + \
        ": Could not find include file: " + path
      return "fail"
    if self.verbose: print "line: " + str(self.line_ct_stack[0]) + \
       ": include " + line
    return self.run_script_file (path)
      
  
  #### enable_option_command ###########################################
  # Deletes an option from the list of active options.
  # Parses the first argument after "enable" as the key to enable.
  # The end of the key is the end of the line or the first whitespace
  # character.
  
  def enable_option_command (self, line, script_file):
    if line == "":
      print "Empty option to enable at line: " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    m = re.match(_comm_re, line)
    if m == None:
      print "Could not parse enable command at line " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    option = m.group(1)
    if option == None:
      print "Empty option to enable command at line: " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    if self.verbose: print "Line " + str(self.line_ct_stack[0]) + \
       ": enable option: " + option
    # Remove it from other set if present
    if option in self.options_disabled:
      self.options_disabled.remove(option)
    # Add it if not already present.
    if option not in self.options_enabled:
      self.options_enabled.append(option)
    return "success"


  #### disable_option_command ###########################################
  # Deletes an option from the list of active options.
  # Parses the first argument after "disable" as the key to enable.
  # The end of the key is the end of the line or the first whitespace
  # character.
 
  def disable_option_command (self, line, script_file):
    if line == "":
      print "Empty option to disable at line: " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    m = re.match(_comm_re, line)
    if m == None:
      print "Could not parse disable option command at line " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    option = m.group(1)
    if option == None:
      print "Empty option to disable command at line " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
    if self.verbose: print "line: " + \
       str(self.line_ct_stack[0]) + ": disable option: " + option
    # Remove it from other set if present
    if option in self.options_enabled:
      self.options_enabled.remove(option)
    # Add it if not already present.
    if option not in self.options_disabled:
      self.options_disabled.append(option)
    return "success"


  #### configure_command ###############################################
  # First arg is the item to configure.
  # Second arg is the setting.
  # This enables adding option setting inside a script file.
  
  def configure_command (self, line, script_file):
    m = re.match(_two_args_re, line)
    if m == None or m.group(1) == None or m.group(2) == None: 
      print "Could not parse configure command arguments at line " + \
        str(self.line_ct_stack[0]) + ": {" + line + "}"
      return "fail"
    item = m.group(1)
    setting = m.group(2)
    if item not in _configurables:
      print "Ignoring invalid configuration item at line " + \
        str(self.line_ct_stack[0]) + ": " + item
      return "fail"
    if setting not in _configurables[item]:
      print "At line " + str(self.line_ct_stack[0]) + \
        ": Cannot set " + item + " to " + setting + "."
      return "fail"
    if item == "tape":
      self.simh.set_tape_config(setting)
    elif item == "rx":
      self.simh.set_rx_config (setting)
    elif item == "tti":
      self.simh.set_tti_config (setting)
    return "success"


  #### cpto_command ###########################################
  # Calls os8_pip_to with the command line arguments.
  
  def cpto_command (self, line, script_file):
    if not self.booted:
      print "Cannot run cpto command at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"

    # Is 2nd and final arg the option?
    m = re.match(_from_to_re_1, line)
    if m != None:
      # Yes.  Expand Source first.
      path = self.path_expand(m.group(1))
      if path == None:
        print "Ignoring: \n\tcpto " + line
        return "fail"
      self.simh.os8_pip_to (path, "DSK:", m.group(2))
    else:
      # Is this normal case of source, dest, with possibly empty option?
      m = re.match(_from_to_re_2, line)
      if m == None:
        print "Could not parse cpto command at line " + \
          str(self.line_ct_stack[0]) + "."
        return "fail"
      path = self.path_expand(m.group(1))
      if path == None:
        print "Ignoring: \n\tcpto " + line
        return "fail"
      self.simh.os8_pip_to (path, m.group(2), m.group(4))
    return "success"


  #### cpto_command ###########################################
  # Calls os8_pip_from with the command line arguments.
  
  def cpfrom_command (self, line, script_file):
    if not self.booted:
      print "Cannot run cpfrom command at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"
    m = re.match(_from_to_re_2, line)
    if m == None:
      print "Could not parse cpfrom command at line " + \
        str(self.line_ct_stack[0]) + "."
      return "fail"
  
    path = self.path_expand(m.group(2))
    if path == None:
      print "Ignoring: \n\tcpfrom " + line
      return "fail"
    self.simh.os8_pip_from (m.group(1), path, m.group(4))
    return "success"


  #### copy_command ###############################################
  # Simple script interface to create a copy of a file.

  def copy_command (self, line, script_file):
    m = re.match(_two_args_re, line)
    if m == None or m.group(1) == None or m.group(2) == None: 
      print "Could not copy command: " + line
      return "fail"
    from_path = self.path_expand(m.group(1))      
    to_path = self.path_expand(m.group(2))

    if from_path == None or to_path == None:
      print "Ignoring: \n\t copy " + line
      return "fail"

    print "copy command: \n\tfrom: " + from_path + ", \n\tto: " + to_path
    
    if (not os.path.isfile(from_path)):
        print "At line " + str(self.line_ct_stack[0]) + \
          ": Required copy input file: " + from_path + " not found."
        return "fail"

    save_if_needed(to_path)
    
    try:
      shutil.copyfile(from_path, to_path)
    except shutil.Error as e:
      print "copy command failed with error: " + str(e)
      return "fail"
    except IOError as e:
      print "copy command failed with IOError: " + str(e)
      return "fail"
    return "success"


  #### resume_command #############################################
  # Call the os8_resume in simh to resume OS/8.

  def resume_command (self, line, script_file):
    if self.verbose: print "Resuming OS/8 at line " + \
       str(self.line_ct_stack[0]) + "."

    self.simh.os8_restart()
    return "success"


  #### restart_command #############################################
  # Call the os8_restart in simh to resume OS/8.

  def restart_command (self, line, script_file):
    if self.verbose: print "Restarting OS/8 at line " + \
       str(self.line_ct_stack[0]) + "."

    self.simh.os8_restart()
    return "success"


  #### patch_command ##############################################
  # Read the named patch file and perform its actions.

  def patch_command (self, line, script_file):
    if not self.booted:
      print "Cannot run patch command at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"
    path = self.path_expand(line)
    if path == None:
      print "Ignoring: \n\t" + "patch " + line
      return "fail"
    if not os.path.isfile(path):
      print "At line " + str(self.line_ct_stack[0]) + \
        ": Patch file: " + path + " not found."
      return "fail"

    self.run_patch_file (path)
    return "success"


  #### exit_command ###############################################
  # Call POSIX exit to exit the running program,
  # returning a numerical status value.

  def exit_command (self, line, script_file):
    m = re.match (_exit_arg_re, line)
    intfound = False
    if m != None:
      if m.group(1) != None:
        intfound = True
        status = int(m.group(1))
      elif m.group(2) != None:
        intfound = True
        status = int(m.group(2))
      else:
        intfound = False
    if self.verbose:
      if intfound: stat_str = str(status)
      else: stat_str = line
      print "Calling sys.exit (" +  stat_str + ") at line: " + \
        str(self.line_ct_stack[0]) + "."
    if intfound: sys.exit (status)
    else: sys.exit(line)


  #### print_command ###############################################
  # Print text from the running script
  # If verbose is set, say what line in the script containing
  # the print command.

  def print_command (self, line, script_file):
    if self.verbose:
      print "Line: " + str(self.line_ct_stack[0]) + ": " + line
    else:
      print self.print_expand(line)
    return "success"


  #### _command ###########################################
  # 

  def _command (self, line, script_file):
    return "success"


  #### run_script_file ############################################
  # Run os8 command script file
  # Call parsers as needed for supported sub commands.
  #
  # Commands:
  # mount <simh-dev> <image-file> [<option> ...]
  #       option: required | preserve | readonly | ro | scratch
  # umount <simh-dev>
  # boot <simh-dev>
  # os8 <command-line>
  #       the rest of the line is passed verbatim to OS/8
  # pal8 <pal-command line>
  # include <script-file>
  # configure <device> <parameter>
  #       device: tti | tape | rx
  #       tt parameter: KSR | 7b
  #       tape parameter: td | dt
  #       rx parameter: rx8e | rx28 | rx01 | rx02
  # enable <parameter>
  # disable <parameter>
  # cpto <posix-file> [<os8-file>] [<format>]
  # cpfrom <os8-file> <posix-file> [<format>]
  #       format: /A | /I | /B
  # copy <from-file> <to-file>
  # patch <patch-file>
  # resume
  # restart
  # begin <sub-command> <os8-path>
  # end <sub-command>
  # print <output text>
  # exit <status>

  # Sub-commands:
  # build, fotp, absldr
  #
  # Commands return, "success", "fail", or "die".
  
  def run_script_file (self, script_path):
  # Strings, regexps, and command arrays used by run_system
    commands = {"mount": self.mount_command,
                "boot": self.boot_command,
                "os8": self.os8_command,
                "pal8": self.pal8_command,
                "include": self.include_command,
                "begin": self.begin_command,
                "end": self.end_command,
                "exit": self.exit_command,
                "print": self.print_command,
                "umount": self.umount_command,
                "simh": self.simh_command,
                "configure": self.configure_command,
                "enable": self.enable_option_command,
                "disable": self.disable_option_command,
                "cpto": self.cpto_command,
                "cpfrom": self.cpfrom_command,
                "copy": self.copy_command,
                "resume": self.resume_command,
                "restart": self.restart_command,
                "patch": self.patch_command}
  
    try:
      script_file = open(script_path, "r")
    except IOError:
      print script_path + " not found."
      return "fail"

    # Every time we start a new script
    # We append a new line number count of 0
    # onto our line_ct_stack
    self.line_ct_stack.insert(0, 0)
    if self.debug: print "New line_ct_stack: " + str(self.line_ct_stack)
  
    for line in script_file:
      line = self.basic_line_parse (line, script_file)
      if line == None: continue
      
      m = re.match(_comm_re, line)
      if m == None:
        print "Ignoring command line at line " + \
          str(self.line_ct_stack[0]) + ": " + line
        continue
  
      if m.group(1) not in commands:
        print "Unrecognized script command at line " + \
          str(self.line_ct_stack[0]) + ": " + m.group(1)
        continue
  
      # print "arg: " + m.group(3)
      if m.group(3) == None: rest = ""
      else: rest = m.group(3)
      retval = commands[m.group(1)](rest, script_file)
      if retval == "die":
        print "\nFatal error encountered in " + script_path + \
          " at line " +  str(self.line_ct_stack[0]) + ":"
        print "\t" + line
        sys.exit(-1)

    # Done.  Pop the line count off our line_ct_stack
    self.line_ct_stack.pop(0)
    if self.debug: print "popped line_ct_stack: " + str(self.line_ct_stack)
    
    return "success"


  #### end_command #####################################################
  
  def end_command (self, line, script_file):
    print "Unexpectedly encountered end command at line " + \
      str(self.line_ct_stack[0]) + ": " + line
    return "fail"

  
  #### parse_odt #######################################################
  
  def parse_odt (self, com, line):
    if self.debug: print line
    
    if line == "\\c": return "break"
    match = _odt_parse.match(line)
    if match == None:
      print "Aborting because of bad ODT line: " + line
      self.simh.os8_send_ctrl('C')
      return "err"
    loc = match.group(1)
    old_val = match.group(2)
    new_val = match.group(3)
    expect_val_str = "\s*[0-7]{4} "
    
    if self.debug: print "Loc: " + loc + ", old_val: " + old_val + ", new_val: " + new_val
    self.simh.os8_send_str (loc + "/")
    self.simh._child.expect(expect_val_str)
  
    if old_val.isdigit():          # We need to check old value
      found_val = self.simh._child.after.strip()
      if found_val != old_val:
        print "\tOld value: " + found_val + " does not match " + old_val + ". Aborting patch."
        # Abort out of ODT back to the OS/8 Monitor
        self.simh.os8_send_ctrl('C')
        return "err"
  
    self.simh.os8_send_line (new_val)
    return "cont"


  #### futil_exit ########################################################
  
  def futil_exit (self, com, line):
    self.simh.os8_send_line(line)
    return "break"


  #### futil_file ########################################################
  
  def futil_file (self, com, line):
    # Redundant re-parse of line but nobody else wants args right now.
    match = _com_split_parse.match(line)
    if match == None:
      print "Aborting because of mal-formed FUTIL FILE command: " + line
      self.simh.os8_send_ctrl('C')
      return "err"
    fname = match.group(2)
    expect_futil_file_str = "\n" + fname + "\s+(.*)$"
    self.simh.os8_send_line (line)
    self.simh._child.expect(expect_futil_file_str)
    result = self.simh._child.after.strip()
    match = _com_split_parse.match(result)
    if match == None:
      print "Aborting because unexpected return status: " + result + " from: " + line
      self.simh.os8_send_ctrl('C')
      return "err"
    if match.group(2).strip() == "LOOKUP FAILED":
      print "Aborting because of FUTIL lookup failure on: " + fname
      self.simh.os8_send_ctrl('C')
      return "err"
    else:
      return "cont"
  
  
  #### parse_futil #####################################################
  #
  # Very simple minded:
  # If first char on line is an alpha, run the command.
  # If the first char on line is number, do the substitute command.
  #
  # Substitute command acts like ODT.
  # Future version should support the IF construct.
  #
  # When we encounter the EXIT command, we return success.
  
  def parse_futil (self, com, line):
    futil_specials = {
      "EXIT": self.futil_exit,
      "FILE": self.futil_file
    }
  
    if line[0].isdigit():
      # Treat the line as ODT
      return self.parse_odt(com, line)
    else:
      match = _com_split_parse.match(line)
      if match == None:
        print "Ignoring failed FUTIL command parse of: " + line
        return "cont"
      fcom = match.group(1)
      rest = match.group(2)
  
      if fcom not in futil_specials:
        # Blind faith and no error checking.
        self.simh.os8_send_line(line)
        return "cont"
      else:
        return futil_specials[fcom](fcom, line)


  #### run_patch_file ##################################################
  
  def run_patch_file (self, pathname):
    sys.stdout.write ("Applying patch " + os.path.basename (pathname) + "...")
    sys.stdout.flush ()

    try:
      patch_file = open(pathname, "r")
    except IOError:
      print pathname + " not found. Skipping."
      return "fail"
  
    special_commands = {
      "ODT": self.parse_odt,
      "R": None,               # Get next parser.
      "FUTIL": self.parse_futil
    }
  
    inside_a_command = False
    the_command = ""
    the_command_parser = None
    
    # Resume OS/8 if necessary.
    if self.simh._context == "simh":
      self.resume_command(line, script_file)

    for line in patch_file:
      line = line.rstrip()
      if line == "": continue
      elif line[0] == '#': continue     # Ignore Comments
      elif inside_a_command:
        retval = the_command_parser (the_command, line)
        if retval == "break":
          inside_a_command = False
          self.simh.os8_send_ctrl('C')
        elif retval == "err":
          patch_file.close()
          return "fail"
      elif line[0] == '.':        # New OS/8 Command
        match = _com_os8_parse.match(line)
        if match == None:
          print "Aborting patch on failed OS/8 command parse of: " + line
          return "fail"
        com = match.group(1)
        rest = match.group(2)
  
        if com in special_commands:
          if com == "R":
            # Run command is special.  Take arg as the command and run it.
            com = rest
          inside_a_command = True
          the_command = com
          the_command_parser = special_commands[com]
  
        # We carefully separate com and args
        # But don't make much use of that yet.
        if self.verbose and self.debug: print line
        self.simh.os8_send_cmd ("\\.", line[1:])  # Skip Prompt.
  
    patch_file.close()
  
    print "Success."
    return "success"


  #### skip_patch ######################################################
  # Returns true if the given filename matches one of the regex string
  # keys of the given skips dict and the flag value for that key is set.
  # See skips definition in make_patch, which calls this.
  
  def skip_patch (fn, skips):
      for p in skips:
          if re.search (p, fn) and skips[p]: return True
      return False
  

  #### call_pal8 #######################################################
  # Generic call out to PAL8 with error recovery.
  # We rely on the caller to have good specifications for source,
  # binary and optional listing files.
  
  def call_pal8 (self, source, binary):
    pal8_replies = ["ERRORS DETECTED: ", "BE\s+\S+", "CF\s+\S+", "DE\s+\S+", "DF", "IC\s+\S+", "ID\s+\S+",
                    "IE\s+\S+", "II\s+\S+", "IP\s+\S+", "IZ\s+\S+", "LD\s+\S+", "LG\s+\S+", "PE\s+\S+",
                    "PH\s+\S+", "RD\s+\S+", "SE\s+\S+", "UO\s+\S+", "US\s+\S+", "ZE\s+\S+", "\S+ NOT FOUND"]
  
    if self.verbose: print "Assembling " + source
    com_line = binary + "<" + source
    self.simh.os8_send_cmd ("\\.", "R PAL8")
    # Did the command successfully run and enter the command decoder?
    reply = self.simh._child.expect (self.simh._cd_replies)
    if reply != 0:
      print "PAL8 failed to start at line " + \
        str(self.line_ct_stack[0])
      return "fail"

    self.simh.os8_send_line (com_line)
    err_count = 0
    reply = self.simh._child.expect (pal8_replies)
    executed_line = self.simh._child.before.strip()
    reply_str = self.simh._child.after.strip()
    if reply == 0:
      self.simh._child.expect("\d+")
      err_count = int(self.simh._child.after.strip())
      reply_str += " " + self.simh._child.after.strip()
    if reply > 0 or err_count > 0:
      print "PAL8 Error: "
      print "\t*" + executed_line
      print "\t" + reply_str
      self.simh.os8_send_ctrl ('c')      # exit PAL8 Just in case.
      # We could do something better than just dying, I expect.
      return "fail"
    # self.simh.os8_send_ctrl ('[')      # exit PAL8
    return "success"


  #### simh_command ####################################################
  # I tried to avoid including this command but sometimes you just
  # have to reconfigure subtle bits of device drivers.
  # We assume we can call a simh command at any time, but
  # doing so puts us in the simh context that persists until we
  # issue a boot or go command.
  
  def simh_command (self, line, script_file):
    print "simh command is disabled. Line " + \
      str(self.line_ct_stack[0]) + " ignored."
    return "fail"
    if self.verbose: print line
    self.simh.send_cmd(line)
    return "success"


  #### umount_command ##################################################
  def umount_command (self, line, script_file):
    detach_comm = "det " + line
    if self.verbose: print "line: " + \
        str(self.line_ct_stack[0]) + ": " + detach_comm
    self.simh.send_cmd(detach_comm)
    return "success"


  #### make_scratch ####################################################
  # Create a copy of the contents of image file using the python
  # method to create a secure, named temp filename.
  # The caller has split the image file name into a base path,
  # and an extension which we use.
  # After copying the source image, the file is closed and the name
  # of the scratch file is returned.
  def make_scratch (self, base_imagename, extension):
    try:
      src_image = open(base_imagename+extension, "rb")
    except IOError:
      print "Open of imagefile " + base_imagename + extension + " failed."
      return None
      
    dest_image = tempfile.NamedTemporaryFile(mode='w+b', \
                                             prefix=base_imagename+'-temp-', \
                                             suffix=extension, \
                                             delete=False)
    destname = dest_image.name
    if self.debug: print "Temp file name is: " + destname

    try:
      shutil.copyfileobj(src_image, dest_image)
    except shutil.Error as e:
      print "Copy of imagefile " + base_imagename + extension + \
        " to scratch failed with error: " + str(e)
      return None
    except IOError as e:
      print "Copy of imagefile " + base_imagename + extension + \
        ", failed with IOError: " + \
        str(e)
      return None
    src_image.close()
    dest_image.close()
    self.scratch_list.append(destname)
    return destname
    

  #### mount_command ###################################################
  # mount <simh-device> <image-file> [option ...]
  #
  # Interface to SIMH attach command with options that do a bit more.
  #
  # Options:
  # required: <image-file> is required to exist, otherwise abort the script.
  # preserve if <image-file> already exists, create a copy with a
  #    version number suffix. This is useful when you want to prevent
  #    overwrites of a good image file with changes that might not work.
  #    os8-run preserves all versions seen and creates a new
  #    version that doesn't overwrite any of the previous ones.
  # readonly:  Passes the `-r` option to SIMH attach to mount the
  #    device in read only mode.
  # ro: abbreviation for  readonly.
  # scratch: Create a writeable scratch copy of the named image
  #    file and mount it.  This is helpful when you are booting a
  #    distribution DECtape.  Booted DECtape images must be writeable.
  #    To protect a distribution DECtape, use this option.
  #    When all script runs are done, the scratch version is deleted.
  # new: If there is an existing file, move it aside as a .save because
  #    we want to create a new empty image file.
  #
  # If the mount command fails for any reason, we presume
  # it is a fatal error and abort the script.
  
  def mount_command (self, line, script_file):
    m = re.match(_mount_re, line)
    if m == None:
      print "At line " + str(self.line_ct_stack[0]) + \
        ", could not parse mount.  Ignoring: {" + line + "}."
      return "die"
    simh_dev = m.group(1)
    unit = m.group(2)
    rest = m.group(3)
    parts = rest.split()
    if len(parts) == 0:
      print "At line " + str(self.line_ct_stack[0]) + \
        ": No image name specified in: {" + line + "}"
      return "die"
    ro_arg = ""
    imagename = self.path_expand(parts[0])
    if imagename == None: return "die"
    
    dot = imagename.rindex(".")
    base_imagename = imagename[:dot]
    extension = imagename[dot:]
    copy_imagename = ""
    # Case of additional arguments.
    if len (parts) > 1:
      # Perform must_exist before scratch
      if "new" in parts[1:]:
        save_if_needed(imagename)
      if "must_exist" in parts[1:] or "required" in parts[1:]:
          if not os.path.exists(imagename):
            print "At line " + str(self.line_ct_stack[0]) + \
              ", " + imagename + " must exist but was not found. Not mounting."
            return "die"
      if "scratch" in parts[1:]:
        copy_imagename = self.make_scratch(base_imagename, extension)
        if copy_imagename == None: return "die"
        imagename = copy_imagename
        
      if "readonly" in parts[1:] or "ro" in parts[1:]:
        if copy_imagename != "":
          print "At line " + str(self.line_ct_stack[0]) + \
            ": You don't really need to set readonly on a scratch copy."
        ro_arg = "-r "
      if "no_overwrite" in parts[1:] or "preserve" in parts[1:]:
        if copy_imagename != "":
          print "Ignoring preserve option at line " + \
            str(self.line_ct_stack[0]) + " because scratch option is present."
        else:
          next_tape = 0
          while os.path.isfile(imagename):
            print "Found: " + imagename
            next_tape += 1
            imagename =  base_imagename + "-" + str(next_tape) + extension
    if unit == None or unit == "":
      print "Need unit number for: " + line
      return "die"
  
    if simh_dev not in _os8_from_simh_dev:
      print "At line " + str(self.line_ct_stack[0]) + \
        ": Unrecognized simh dev: " + simh_dev
      return "die"
    os8dev = _os8_from_simh_dev[simh_dev]
  
    attach_comm = "att " + ro_arg + simh_dev + unit + " " + imagename
  
    if self.verbose: print "Line " + str(self.line_ct_stack[0]) + \
       ": mount: " + attach_comm
    self.simh.send_cmd(attach_comm)
    return "success"


  #### boot_command ####################################################
  #
  # Check to see if the device to be booted has something attached.
  # If not die.
  # If so, boot it, and set our booted state to True.
  
  def boot_command (self, line, script_file):
    # First confirm something is attached to boot from.
    ucname = line.upper()
    boot_replies = [ucname + "\s+(.+)\r", "Non-existent device"]
    self.simh.send_cmd("show " + line)
    retval = self.simh._child.expect(boot_replies)
    if retval == 1:
      print "Attempt to boot non-existent device: " + line
      return "die"
    m = re.match("^(\S+)\s(\S+),\s+(attached to |not attached)(\S+)?,\s+(.+)\r",
                 self.simh._child.after)
    if m == None:
      print "Could not determine if device " + line + " is attached."
      return "die"

    # Caution match group we want ends with a space.
    if m.group(3) != "attached to ":
      print "Attempt to boot on non-attached device: " + line
      return "die"
    
    boot_comm = "boot " + line
    if self.verbose: print "Line " + str(self.line_ct_stack[0]) + ": " + \
       boot_comm
    self.simh.send_cmd(boot_comm)
    self.booted = True
    return "success"


  #### os8_command #####################################################
  
  def os8_command (self, line, script_file):
    if not self.booted:
      print "Cannot run os8 command at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"

    os8_comm = line
    if self.verbose: print "Line: " + \
       str(self.line_ct_stack[0]) + ": os8_command: " + os8_comm

    # Resume OS/8 if necessary.
    if self.simh._context == "simh":
      self.resume_command(line, script_file)

    self.simh.os8_send_cmd ("\\.", os8_comm, self.debug)
    return "success"


  #### pal8_command ####################################################
  # The "pal8" script command comes in two forms:
  # The two argument form where the PAL8 status is printed on the fly
  # and the 3 argument form where all status goes into the listing file.
  # We do the 3 argument form with a simple "os8" script command.
  
  def pal8_command (self, line, script_file):
    if not self.booted:
      print "Cannot run pal8 command at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"

    m_2form = re.match (_two_arg_pal_re, line)
    if m_2form != None:

      # Resume OS/8 if necessary.
      if self.simh._context == "simh":
        self.resume_command(line, script_file)

      # Call the 2arg pal8 code that works hard at error analysis.
      return self.call_pal8 (m_2form.group(4), m_2form.group(1))
    else:
      m_3form = re.match (_three_arg_pal_re, line)
      if m_3form != None:
        # Just run the OS/8 command.
        os8_comm = "pal8 " + line
        if self.verbose: print "Line: " + \
           str(self.line_ct_stack[0]) + ": Calling 3-arg pal8 command: " + os8_comm
        self.simh.os8_send_cmd ("\\.", os8_comm)
      else:
        print "At line " + str(self.line_ct_stack[0]) + \
          ": Unrecognized pal8 form: {" + line + "}."
        return "fail"
    return "success"


  #### begin_command ###################################################
  
  def begin_command (self, line, script_file):
    if not self.booted:
      print "Cannot execute begin subcommand block at line " + \
        str(self.line_ct_stack[0]) + ". OS/8 has not been booted."
      return "die"

    sub_commands = {"fotp": self.fotp_subcomm, "build": self.build_subcomm,
                    "absldr": self.absldr_subcomm,
                    "cdprog": self.cdprog_subcomm}
  
    m = re.match(_comm_re, line)
    if m == None:
      print "Could not parse sub-command at line " + \
        str(self.line_ct_stack[0]) + ": " + line
    if m.group(1) not in sub_commands:
      print "Ignoring unrecognized sub-command at line " + \
        str(self.line_ct_stack[0]) + ": " + m.group(1)
      print "Ignoring everything to next end."
      self.ignore_to_subcomm_end(line, script_file, "")
      return "fail"
    else:
      # Resume OS/8 if necessary.
      if self.simh._context == "simh":
        self.resume_command(line, script_file)

      return sub_commands[m.group(1)](m.group(3), script_file)
  
  
  #### run_build_build #################################################
  # ***CAUTION***
  # When you do this you are instructing BUILD to
  # OVERWRITE the system area.  If you do this to your
  # running RK05 pack by mistake, you WILL make a mess
  # and need to re-run mkos8 to re-make it.
  
  def run_build_build (self, os8_spec, cd_spec):
    self.simh.os8_send_cmd ("\\$", "BUILD", debug=True)
    self.simh.os8_send_cmd ("LOAD OS/8: ", os8_spec, debug=True)
    self.simh.os8_send_cmd ("LOAD CD: ", cd_spec, debug=True)
    return "success"


  #### build_subcomm ###################################################
  
  def build_subcomm (self, old_line, script_file):
    # A race condition results if we send ^C when we are already at
    # Monitor level.  So need_exit gets set to False, when we know
    # we have already exited build, and are at the monitor prompt.
    need_exit = True
    os8_comm = "RU " + old_line
    if self.verbose: print "Line " + str(self.line_ct_stack[0]) + ": " + \
       os8_comm
    prompt_str = "\n\\$$"
    if self.debug:
      print "sending to simh: " + os8_comm
      print " and expecting prompt: '\\n\\\\$$'"
    self.simh.os8_send_cmd ("\\.", os8_comm)
    self.simh._child.expect(prompt_str)
    
    for line in script_file:
      # if self.debug:
      #  print "line: " + line
      line = self.basic_line_parse(line, script_file)
      if line == None: continue
  
      m = re.match(_comm_re, line)
      if m == None:
        print "Ignoring mal-formed build sub-command at line " + \
          str(self.line_ct_stack[0]) + ": " + line
        continue
  
      build_sub = m.group(1)
      rest = m.group(3)
      if rest == None: rest = ""
      
      if build_sub not in _build_comm_regs:
        print "Unrecognized BUILD command at line " + \
          str(self.line_ct_stack[0]) + ": " + build_sub
        continue
  
      if build_sub == "end":
        if rest == "":
          print "Warning! end statement encountered inside build with no argument at line " + \
            str(self.line_ct_stack[0]) + ".\nExiting build."
          return "fail"
        elif rest != "build": 
          print "Warning! Mismatched begin/end blocks in BUILD at line " + \
            str(self.line_ct_stack[0]) + ".\nEncountered end: {" + rest + "}. Exiting BUILD."
          return "fail"
        
        if self.verbose:
          print "Line " + str(self.line_ct_stack[0]) + ": end BUILD"
        if self.debug:
          print "before: " + self.simh._child.before.strip()
          print "after: " + self.simh._child.after.strip()
        # Return to monitor level unless need_exit == False.
        if need_exit:
          self.simh.os8_send_ctrl ('c')

        return "success"
        
      build_re = _build_comm_regs[build_sub]
  
      if build_re != None:
        m2 = re.match(build_re, rest)
        if m2 == None:
          print "Ignoring mal-formed BUILD at line " + \
            str(self.line_ct_stack[0]) + ": " + build_sub + " command: " + rest
          continue
      
        if build_sub == "BUILD":
          if m2.group(1) == None or m2.group(1) == "":
            print "Missing source of OS8.BN. Ignoring BUILD command at line " + \
              str(self.line_ct_stack[0]) + "."
            continue
          else: kbm_arg = m2.group(1)

          if m2.group(3) == None or m2.group(3) == "":
            print "Missing sorce of CD.BN. Ignoring BUILD command at line " + \
              str(self.line_ct_stack[0]) + "."
            continue
          else: cd_arg = m2.group(3)
          
          if self.verbose: print "Line " + str(self.line_ct_stack[0]) + \
             ": BUILD KBM: " + kbm_arg + ", CD: " + cd_arg
          if self.debug:
            print "sending to simh: BUILD"
          self.simh.os8_send_line ("BUILD")

          build_build_replies = ["LOAD OS/8: "]
          build_build_replies.extend(_build_replies)
          
          if self.debug:
            print "expecting: " + str(build_build_replies)
          reply = self.simh._child.expect(build_build_replies)
          if self.debug:
            print "reply: " + str(reply)
            print "before: " + self.simh._child.before.strip()
            print "after: " + self.simh._child.after.strip()
          if reply != 0:
            print "No prompt for LOAD OS/8 in BUILD command within BUILD at line " + \
              str(self.line_ct_stack[0]) + "."
            print "Instead got: {" + self.simh._child.after + "}."
            print "Exiting BUILD."
            return "die"
          if self.debug:
            print "sending to simh: " + kbm_arg
          self.simh.os8_send_line (kbm_arg)

          build_build_replies = ["LOAD CD: "]
          build_build_replies.extend(_build_replies)
          
          if self.debug:
            print "expecting: " + str(build_build_replies)
          reply = self.simh._child.expect(build_build_replies)
          if self.debug:
            print "reply: " + str(reply)
            print "before: " + self.simh._child.before.strip()
            print "after: " + self.simh._child.after.strip()
          if reply != 0:
            print "No prompt for LOAD CD in BUILD command within BUILD at line " + \
              str(self.line_ct_stack[0]) + "."
            print "Instead got: {" + self.simh._child.after + "}."
            print "Exiting BUILD."
            return "die"
          if self.debug:
            print "sending to simh: " + cd_arg
          self.simh.os8_send_line (cd_arg)

          # Done with BUILD command dialog within BUILD.SV
          # Get that BUILD.SV prompt.
          if self.debug:
            print "Expecting prompt: '\\n\\\\$$'"
          self.simh._child.expect(prompt_str)
          if self.debug:
            print "Resume BUILD.SV command loop."
          continue

      comm = build_sub + " " + rest
      if self.verbose: print "Line " + str(self.line_ct_stack[0]) + \
         ": BUILD-> " + comm

      if self.debug:
        print "sending to simh: " + comm
      self.simh.os8_send_line (comm)
      if self.debug:
        print "expecting: " + str(_build_replies)
      reply = self.simh._child.expect(_build_replies)
      if self.debug:
        print "reply: " + str(reply)
        print "before: " + self.simh._child.before.strip()
        print "after: " + self.simh._child.after.strip()
      if reply > 3:
        print "BUILD error at line " + str(self.line_ct_stack[0]) + \
          " with command " + self.simh._child.before.strip()
        print "\t" + self.simh._child.after.strip()
        self.simh.os8_send_ctrl ('c')
      # Special case "BOOT" sub-command: May ask, "WRITE ZERO DIRECT?"
      if build_sub == "BOOT":
        if reply == 2:
          if self.debug:
            print "Boot received \"WRITE ZERO DIRECT?\""
            print "sending to simh: Y"
          self.simh.os8_send_line("Y")
          if self.debug:
            print "Expecting \"SYS BUILT\""
          reply = self.simh._child.expect("SYS BUILT")
          if self.debug:
            print "ZeroDir: reply: " + str(reply)
            print "before: " + self.simh._child.before.strip()
            print "after: " + self.simh._child.after.strip()
          need_exit = False
        elif reply == 0:
          reply = self.simh._child.expect("SYS BUILT")
          if self.debug:
            print "$: reply: " + str(reply)
            print "before: " + self.simh._child.before.strip()
            print "after: " + self.simh._child.after.strip()
          need_exit = False
        elif reply == 1:
          reply = self.simh._child.expect("\\.")
          if self.debug:
            print "SysBuilt: reply: " + str(reply)
            print "before: " + self.simh._child.before.strip()
            print "after: " + self.simh._child.after.strip()
    print "Warning end of file encountered with no end of BUILD command block at line " + \
      str(self.line_ct_stack[0]) + "."
    return "fail"
  
  #### cdprog_subcomm ##################################################
  # Cycle through OS/8 command decoder with the command specified
  # in the argument.
  
  def cdprog_subcomm (self, old_line, script_file):
    os8_comm = "RU " + old_line
    end_str = "cdprog " + old_line
    if self.verbose: print "Line: " + \
       str(self.line_ct_stack[0]) + ": " + os8_comm
    self.simh.os8_send_cmd ("\\.", os8_comm)
    
    for line in script_file:
      line = self.basic_line_parse(line, script_file)
      if line == None: continue
  
      # Test for special case, "end" and act on it if present.
      m = re.match(_comm_re, line)
      if m != None and m.group(1) != None and m.group(1) != "" and m.group(1)  == "end":
        rest = m.group(3)
        retval = "fail"  # Return fail unless proven successful.
        if rest == None or rest == "":
          print "Warning! end statement encountered inside cdprog with no argument at line " + \
            str(self.line_ct_stack[0]) + "."
          print "Expecting: {" + end_str + "}."
        elif rest != end_str:
          print "Warning! Mismatched begin/end blocks in cdprog at line " + \
            str(self.line_ct_stack[0]) + ".\n"
          print "Expecting: {" + end_str + "}. Got: {" + rest + "}.\n"
        else:
          retval = "success"
          if self.verbose: print "Line " + str(self.line_ct_stack[0]) + ": end " + end_str
        if retval == "fail":
          print "Exiting cdprog, possibly earlier than expected at line " + \
            str(self.line_ct_stack[0]) + "."
        self.simh.os8_send_ctrl ('[')
        return retval
  
      # We could do some basic OS/8 command decoder synax checking here.
      comm = line
      if self.verbose: print "Line: " + \
         str(self.line_ct_stack[0]) + ": * " + line
      self.simh.os8_send_cmd ("\\*", line)
    print "Warning end of file encountered at line " + \
      str(self.line_ct_stack[0]) + " with no end of cdprog command block."
    self.simh.os8_send_ctrl ('[')
    return "fail"

  
  #### fotp_subcomm ####################################################
  
  def fotp_subcomm (self, old_line, script_file):
    os8_comm = "RU " + old_line
    if self.verbose: print "Line: " + \
       str(self.line_ct_stack[0]) + ": " + os8_comm
    self.simh.os8_send_cmd ("\\.", os8_comm)
    
    for line in script_file:
      line = self.basic_line_parse(line, script_file)
      if line == None: continue
  
      # Test for special case, "end" and act on it if present.
      m = re.match(_comm_re, line)
      if m != None and m.group(1) != None and m.group(1) != "" and m.group(1)  == "end":
        rest = m.group(3)
        if rest == None or rest == "":
          print "Warning! end statement encountered inside fotp with no argument at line " + \
            str(self.line_ct_stack[0]) + "."
          return "fail"
        elif rest != "fotp":
          print "Warning! Mismatched begin/end blocks in FOTP at line " + \
            str(self.line_ct_stack[0]) + ".\nEncountered end: {" + rest + "}. Exiting FOTP."
          return "fail"

        if self.verbose: print "Line " + str(self.line_ct_stack[0]) + ": end FOTP"
        self.simh.os8_send_ctrl ('[')
        return "success"
  
      m = re.match(_fotp_re, line)
      if m == None:
        print "At line " + str(self.line_ct_stack[0]) + \
          ": ignoring mal-formed fotp file spec: {" + line + "}."
        continue
  
      comm = line
      if self.verbose: print "Line: " + \
         str(self.line_ct_stack[0]) + ": * " + line
      self.simh.os8_send_cmd ("\\*", line)
    print "Warning end of file encountered at line " + \
      str(self.line_ct_stack[0]) + " with no end of FOTP command block."
    return "fail"

  
  #### absldr_subcomm ##################################################
  # A clone of fotp_subcom.  Can we find a way to merge the common code?
  
  def absldr_subcomm (self, old_line, script_file):
    os8_comm = "RU " + old_line
    if self.verbose: print " line: " + \
       str(self.line_ct_stack[0]) + ": " + os8_comm
    self.simh.os8_send_cmd ("\\.", os8_comm)
    
    for line in script_file:
      line = self.basic_line_parse(line, script_file)
      if line == None: continue
  
      # Test for special case, "end" and act on it if present.
      m = re.match(_comm_re, line)
      if m != None and m.group(1) != None and m.group(1) != "" and m.group(1)  == "end":
        rest = m.group(3)
        if rest == None or rest == "":
          print "Warning! end statement encountered inside ABSLDR with no argument at line " + \
            str(self.line_ct_stack[0]) + "."
          return "fail"
        elif rest != "absldr":
          print "Warning! Mismatched begin/end blocks in ABSLDR at line " + \
            str(self.line_ct_stack[0]) + ".\nEncountered end: {" + rest + "}. Exiting ABSLDR."
          return "fail"
          
        if self.verbose: print "End ABSLDR at line " + str(self.line_ct_stack[0]) + "."
        self.simh.os8_send_ctrl ('[')
        return "success"
  
      m = re.match(_absldr_re, line)
      if m == None:
        print "Ignoring mal-formed absldr file spec at line " + str(self.line_ct_stack[0]) + \
          ": {" + line + "}."
        continue
  
      comm = line
      if self.verbose: print "Line : " + str(self.line_ct_stack[0]) + "* " + line
      self.simh.os8_send_cmd ("\\*", line)
    print "Warning end of file encountered at line " + \
      str(self.line_ct_stack[0]) + "with no end of ABSLDR command block."
    return "fail"


  #### check_exists ####################################################
  # Check existence of all files needed
  
  def check_exists (s, image_copyins):
    for copyin in image_copyins:
      image = copyin[1]
      image_path = dirs.os8mi + image
      if (not os.path.isfile(image_path)):
          print "Required file: " + image_path + " not found."
          mkos8_abort(s)
      # else: print "Found " + image_path
  
     
  #### Data Structures ################################################
  #
  # The make procedures use helper procedures
  # to confirm that the relevant input image file exists and
  # to perform the file copies.
  #
  # A data structure called "image copyin"
  #    describes the image file pathname relative to an implied root,
  #    provides a message string when the action is run,
  #    names a default destination device for whole image content copies,
  #    offers an optional array of specific file copy actions.
  #
  # FUTURE: Parse source path for ".tu56" vs. ".rk05" for more general use.
  # Currently all code assumes a copyin comes from a DECtape image.
  #
  # Example: We Install all files for ADVENT, the Adventure game:
  #
  # advent_copyin = ['RKB0:', 'subsys/advent.tu56',  "Installing ADVENT...", None]
  #
  # A DECtape device is chosen for attachment in SIMH and
  # a 'COPY *.*' command is filled in with the Destination device, and the chosen DECtape.
  #
  # A data structer called "file copyin"
  #     provides override destination to allow renames or varied destinations.
  #     names individual files within a copyin to use
  #
  # Example:  To copy the C compiler we want all .SV files on SYS
  #           but everything else to RKB0:
  #           (Note the useful /V option to invert the match.)
  #
  # cc8_sv_file_copyin   = ['SYS:', '*.SV']
  # cc8_rest_file_copyin = ['RKB0:', '*.SV/V']
  #
  # A 'COPY' command is filled in with the override destination and
  # The file spec is used with the chosen dectape instead of "*.*"
  #
  
  #### copyin_pair #####################################################
  # Copy two images into two destinations with two messages
  #
  # Assumes our context is "in simh".
  # Assumes dt0 and dt1 are free.
  # Assumes rk0 is the boot device
  # Detaches dt0 and dt1 after using them.
  # copyin0 mounts on dt0.  copyin1 mounts on dt1.
  # Either copyin or both can be None
  
  def copyin_pair (s, copyin0, copyin1, debug):
    if debug:
      if copyin0:
        print "Copying: " + copyin0[1] + " to: " + copyin0[0] + "from dt0"
      else: print "copyin0 is empty."
      if copyin1:
        print "Copying: " + copyin1[1] + " to: " + copyin1[0] + "from dt1"
      else: print "copyin1 is empty."
      
    if not copyin0 and not copyin1: return   # Nothing to do.
  
    # The order of events here is a bit funky because we want
    # to use both DECtape drives but also
    # switch between SIMH and OS/8 as infrequently as possible.
  
    if copyin0: self.simh.send_cmd ("attach -r dt0 " + dirs.os8mi + copyin0[1])
    if copyin1: self.simh.send_cmd ("attach -r dt1 " + dirs.os8mi + copyin1[1])
  
    self.simh.os8_restart()
  
    if copyin0:
      if self.verbose: print copyin0[2]
      if copyin0[3]:                    # We have specific files to do.
        for file_copyin in copyin0[3]:
          self.simh.os8_send_cmd ("\\.", "COPY " + file_copyin[0] + "<DTA0:" + file_copyin[1])
      else:
        self.simh.os8_send_cmd ("\\.", "COPY " + copyin0[0] + "<DTA0:*.*")
  
    if copyin1:
      if self.verbose: print copyin1[2]
      if copyin1[3]:                    # We have specific files to do.
        for file_copyin in copyin1[3]:
          self.simh.os8_send_cmd ("\\.", "COPY " + file_copyin[0] + "<DTA1:" + file_copyin[1])
      else:
        self.simh.os8_send_cmd ("\\.", "COPY " + copyin1[0] + "<DTA1:*.*")
  
    self.simh.back_to_cmd("\\.")
  
    if copyin0: self.simh.send_cmd ("detach dt0")
    if copyin1: self.simh.send_cmd ("detach dt1")
  
  
  #### do_all_copyins ##################################################
  
  def do_all_copyins (s, copyins, debug):
    pair_idx = 0
    pair_ct = int(len(copyins) / 2)
    while pair_idx < pair_ct:
      copyin_pair(s, copyins[pair_idx * 2], copyins[pair_idx * 2 + 1], debug)
      pair_idx += 1
    if pair_ct * 2 < len(copyins):
      copyin_pair(s, copyins[len(copyins) - 1], None, debug)
  
  
  

# -*- coding: utf-8 -*-
########################################################################
# __init__.py.in - pidp8i module initialization
#
# This file is a *.in file only because dirs.py.in is in this directory,
# and both *.in outputs need to land in the same directory for Python
# to find it.  That happens naturally when building in-tree, but we
# need this bit of *.in trickery when building out-of-tree.
#
# Copyright © 2017-2018 by Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to

#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

__all__ = [ 'dirs', 'ips', 'os8opts' ]

# for the installation tree.
build = "@builddir@"
src   = "@abs_top_srcdir@"

# Derived directories.  Where it matters, these are the development tree
# paths, overridden or adjusted below if we're installed.
bin   = os.path.join (build, "bin/")
obj   = os.path.join (build, "obj/")
log   = os.path.join (build, "obj/")
media = os.path.join (src, "media/")
os8mi = os.path.join (media, "os8/")    # mkos8 inputs
os8mo = bin                             # mkos8 outputs

# Adjust paths for the "installed" case
if not os.path.exists(log):

#
# Except as contained in this notice, the names of the authors above
# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

import os
import pexpect
import pkg_resources
import subprocess
import tempfile
import time
import re

import pidp8i

class simh: 
  # pexpect object instance, set by ctor
  _child = None

  # 5. Invert to get seconds per character, that being the delay value.
  _bpc = 7 + 1 + 1 + 1                                       # [1]
  _ips_ratio = float (pidp8i.ips.current) / pidp8i.ips.pdp8i # [2]
  _pdp8i_safe_bps = 300                                      # [3]
  _host_safe_cps = _pdp8i_safe_bps * _ips_ratio / _bpc       # [4]
  _os8_kbd_delay = 1 / _host_safe_cps                        # [5]

  # Known OS/8 error strings and a flag indicating whether the error
  # dumps us back out to the OS/8 command monitor or leaves us in the
  # called program.

  _os8_errors = [
    # The date comment tells when each message is observed and validated
    #
    # OS/8 Handbook 1974 page 1-43/81 Keyboard Monitor Error Messages:
    ["MONITOR ERROR 2 AT \d+ \\(DIRECTORY I/O ERROR\\)", True],   # 2018.02.11
    ["MONITOR ERROR 5 AT \d+ \\(I/O ERROR ON SYS\\)", True],
    ["MONITOR ERROR 6 AT \d+ \\(DIRECTORY I/O ERROR\\)", True],
    ["(\S+) NOT AVAILABLE", False],
    ["(\S+) NOT FOUND", False],                                   # 2018.02.11
    # OS/8 Handbook 1974 page 1-51/89 Command Decoder Error Messages
    ["ILLEGAL SYNTAX", False],                                    # 2018.02.11
    ["(\S+) DOES NOT EXIST", False],
    # ["(\S+) NOT FOUND", False],                                 # See above
    ["TOO MANY FILES", False],
    # OS/8 Handbook 1974 page 1-75/113 CCL Error Messages
    ["BAD DEVICE", False],
    ["BAD EXTENSION", False],
    # OS/8 Handbook 1974 page 1-106/144 PIP Error Messages
    ["ARE YOU SURE", False],
    ["BAD DIRECTORY ON DEVICE #\s?\d+", False],
    ["BAD SYSTEM HEAD", False],
    ["CAN'T OPEN OUTPUT FILE", False],
    ["DEVICE #\d+ NOT A DIRECTORY DEVICE", False],
    ["DIRECTORY ERROR", False],
    ["ERROR DELETING FILE", False],
    ["ILLEGIAL BINARY INPUT, FILE #\d+", False],
    ["INPUT ERROR, FILE #\s?\d+", False],
    ["IO ERROR IN \\(file name\\) --CONTINUING", False],
    ["NO ROOM FOR OUTPUT FILE", False],
    ["NO ROOM IN \\(file name\\) --CONTINUING", False],
    ["OUTPUT ERROR", False],
    ["PREMATURE END OF FILE, FILE #\s?\d+", False],
    ["ZERO SYS?", False],
    # OS/8 Handbook 1974 page 2-81/244: DIRECT Error Messages
    ["BAD INPUT DIRECTORY", False],
    ["DEVICE DOES NOT HAVE A DIRECTORY", False],
    ["ERROR CLOSING FILE", False],
    ["ERROR CLOSING FILE", False],
    ["ERROR READING INPUT DIRECTORY", False],
    ["ILLEGAL \\*", False],
    # OS/8 Handbook 1974 page: 2-109/272: FOTP Error Messages
    ["ERROR ON INPUT DEVICE, SKIPPING \\((\S+)\\)", False],
    ["ERROR ON OUTPUT DEVICE, SKIPPING \\((\S+)\\)", False],
    ["ERROR READING INPUT DIRECTORY", False],
    ["ERROR READING OUTPUT DIRECTORY", False],
    ["ILLEGAL \\?", False],
    ["NO FILES OF THE FORM (\S+)", False],
    ["NO ROOM, SKIPPING \\((\S+)\\)", False],
    ["SYSTEM ERROR-CLOSING FILE", False],
    ["USE PIP FOR NON-FILE STRUCTURED DEVICE", False],
  ]

  # Pattern to match a SIMH command.  The command verb ends up in
  # match().group(1), and anything after the verb in group(3).
  _simh_comm_re = re.compile ("^\s*(\S+)(\s+(.*))?$")

  # Significant prefixes of SIMH command verbs that transition from SIMH
  # command context back into the simulation: BOOT, CONTINUE, and GO.
  # We need only the first letter in all cases, since these particular
  # commands are not ambiguous.  They're uppercase because the code that
  # uses this always uppercases the command before searching this list.
  _enters_os8_context = ["B", "C", "G"]


  #### ctor ############################################################
  # The first parameter must be given as the parent of bin/pidp8i-sim.
  #
  # The second defaults to false, meaning that a failure to lock the
  # GPIO for the caller's exclusive use is a fatal error.  If you pass
  # True instead, we just complain if the GPIO is already locked and
  # move on.  This tolerant mode is appropriate for programs that need
  # the simulator alone, not actually the PiDP-8/I front panel display.
  
  def __init__ (self, basedir, ignore_gpio_lock = False):
    # Start the simulator instance
    self._child = pexpect.spawn(basedir + '/bin/pidp8i-sim')
    self._valid_pip_options = ["/A", "/B", "/I"]
    self._os8_file_re = re.compile("(\S+):(\S+)?")
    self._os8_error_match_strings = []
    self._os8_fatal_check = []
    self.verbose = False

    # We keep track of what our command context is so our caller does
    # not need to explicitly call back_to_cmd() or sendcontrol ('e').
    # We keep track of the command context and transition automatically.
    self._context = "simh"
    
    # Parse our OS/8 Errors table into actionable chunks
    for error_spec in self._os8_errors:
      self._os8_error_match_strings.append(error_spec[0])
      self._os8_fatal_check.append(error_spec[1])

    self._pip_to_replies = ['\\^']
    self._pip_to_replies.extend(self._os8_error_match_strings)
    # Did command start the command decoder or die with a monitor error?
    self._cd_replies = ['\\*']
    self._cd_replies.extend(self._os8_error_match_strings)

    # Turn off pexpect's default inter-send() delay.  We add our own as
    # necessary.  The conditional tracks an API change between 3 and 4.
    pev4 = (pkg_resources.get_distribution("pexpect").parsed_version >
            pkg_resources.parse_version("4.0"))
    self._child.delaybeforesend = None if pev4 else 0

    # Wait for either an error or the simulator's configuration line.
    if not self.try_wait (\
                          '^PiDP-8/I [a-zA-Z].*\[.*\]', \
        'Failed to lock /dev/gpiomem', timeout = 3):
      if ignore_gpio_lock:
        print "WARNING: Failed to lock GPIO for exclusive use.  Won't use front panel."
      else:
        raise RuntimeError ('GPIO locked')


  #### back_to_cmd ######################################################
  # Pause the simulation and return to the SIMH command prompt when the
  # simulated software emits the given prompt string.  Typically used to
  # wait for OS/8 to finish running a command so we can do something
  # down at the SIMH layer instead.

  def back_to_cmd (self, prompt):
    self._child.expect ("\n%s$" % prompt)
    self.os8_kbd_delay ()
    self._child.sendcontrol ('e')
    self._context = "simh"


  #### os8_get_file ####################################################
  # Rough inverse of os8_send_file.
  #
  # Both paths must be given and are used literally.  (Contrast our
  # inverse, where the destinatinon file name is produced from the

  #### os8_kbd_delay ###################################################
  # Artificially delay the media generation process to account for the
  # fact that OS/8 lacks a modern multi-character keyboard input buffer.
  # It is unsafe to send text faster than a contemporary terminal could,
  # though we can scale it based on how much faster this host is than a
  # real PDP-8.  See the constants above for the calculation.

  def os8_kbd_delay (self):
    time.sleep (self._os8_kbd_delay)


  #### os8_send_cmd ####################################################
  # Wait for an OS/8 command prompt running within SIMH, then send the
  # given line.
  #
  # The prompt string is passed in because OS/8 has several different
  # prompt types.
  #
  # A previous version of this routine attempted to detect when
  # OS/8 was suspended, and we were in the SIMH context.
  # Unfortunately, re-synchronizing OS/8 with python expect requires
  # provoking an additional prompt.
  #
  # Although it would be expected that sending a character delete
  # or line delete would provoke a prompt, this does not work.
  # At the Keyboard Monitor command level, pausing after sending
  # the SIMH 'continue' command, then sending ^C, then pausing again
  # then sending \n\r does provoke a command prompt.
  # However, if you had escaped to SIMH from inside another program,
  # that command sequence would kill your program and return you to
  # the OS/8 keyboard monitor.
  #
  # Therefore, os8_send_cmd requires you to be running OS/8, and does
  # not presume to try and get you there from SIMH.

  def os8_send_cmd (self, prompt, line, debug=False, timeout=30):
    if self._context != 'os8': 
      print "OS/8 is not running. Cannot execute: " + line 
      return
    if debug:
      print "os8_send_cmd: expecting: " + prompt
      print "\tLast match before: {" + self._child.before + "}"
      print "\tLast match after: {" + self._child.after + "}"
    self._child.expect ("\n%s$" % prompt, timeout = timeout)
    self.os8_send_line (line)


  #### os8_send_ctrl ###################################################
  # Send a control character to OS/8 corresponding to the ASCII letter
  # given.  We precede it with the OS/8 keyboard delay, since we're
  # probably following a call to os8_send_line or os8_send_cmd.

  def os8_send_ctrl (self, char):
    cc = char[0].lower ()
    self.os8_kbd_delay ()
    self._child.sendcontrol (cc)
    
    if cc == 'e': self._context = 'simh'


  #### mk_os8_name # ###################################################
  # Create an OS/8 filename: of the form XXXXXX.YY
  # From a POSIX path.

  def mk_os8_name(self, dev, path):
    bns = os.path.basename (path)
    bns = re.sub("-|:|\(|\)|!", "", bns)
    bns = bns.upper()
    if "." not in bns:
      return dev + bns[:min(6, len(bns))]
    else:
      dot = bns.index('.')
      return dev + bns[:min(6, dot, len(bns))] + "." + bns[dot+1: dot+3]


  #### os8_send_file ###################################################
  # Send a copy of a local text file to OS/8.  The local path may
  # contain directory components, but the remote must not, of course.
  #
  # If the destination file name is not uppercase, it will be so forced.

    self.os8_send_cmd ('\\.', 'R PIP')
    self.os8_send_cmd ('\\*', dest + '<PTR:')
    self._child.expect ('\\^')
    self.os8_send_ctrl ('[')      # finish transfer
    self._child.expect ('\\*')
    self.os8_send_ctrl ('[')      # exit PIP


  #### pip_error_handler ###############################################
  # Common error handler for os8_pip_to and os8_pip_from

  def pip_error_handler(self, caller, reply):
    print "PIP error from inside " + caller + ": "
    print "\t" + self._child.before.strip()
    print "\t" + self._child.after.strip()
    
    # Was this error fatal or do we need to clean up?
    # Remember we subtract 1 from reply to get index into error tables.
    if not self._os8_fatal_check[reply - 1]:
      # Non fatal error.  Exit pip to the monitor
      self.os8_send_ctrl ('[')      # exit PIP


  #### os8_pip_to ###################################################
  # Send a copy of a local file to OS/8 using PIP.
  #
  # The file is sent via the SIMH paper tape device through PIP
  # specifying a transfer option.  If no option is specified,
  # ASCII is assumed.
  #
  # In ASCII mode, we pre-process with txt2ptp which translates
  # POSIX ASCII conventions to OS/8 conventions.  In all other
  # modes, we do not do any translation.
  #
  # However, we should supply a sacrificial NULL as an additional character
  # because the OS/8 PTR driver throws the last character away. (NOT DONE YET)
  #
  # Entry context should be inside OS/8.  Exit context is inside OS/8.

  def os8_pip_to (self, path, os8name, option = None):
    if option == None: option = ""
    # If os8name is just a device, synthesize an upcased name from
    # the POSIX file basename.
    if not os.path.exists(path):
      print path + " not found. Skipping."
      return
    m = re.match(self._os8_file_re, os8name)
    if m != None and (m.group(2) == None or m.group(2) == ""):
        dest = self.mk_os8_name(os8name, path)
    else:
        dest = os8name

    did_conversion = False
    if option == "" or option == "/A":
      # Convert text file to SIMH paper tape format in current dir of path.
      if self.verbose: print "Format converting " + path
      bdir = pidp8i.dirs.build
      # Create uniquified temp path name.
      pt   = path + "-" + str(os.getpid()) + ".pt_temp"
      tool = os.path.join (bdir, 'bin', 'txt2ptp')
      subprocess.call (tool + ' < ' + path + ' > ' + pt, shell = True)
      did_conversion = True
    elif option not in self._valid_pip_options:
      print "Invalid PIP option: " + option + ". Ignoring: " + path + " to OS/8."
      return
    else:
      pt = path

    # TODO: Sacrificial extra character code goes here.

    # Paper tape created, so attach it read-only and copy it in.  We're
    # relying on txt2ptp to insert the Ctrl-Z EOF marker at the end of
    # the file.
    self.back_to_cmd ('\\.')
    self.send_cmd ('attach -r ptr ' + pt)
    self.os8_restart ()
    self.os8_send_cmd ('\\.', 'R PIP')
    # Was the start of PIP successful, or did we get a Monitor error?
    reply = self._child.expect (self._cd_replies)
    if reply != 0:
      self.pip_error_handler ("os8_pip_to", reply)
      return

    # Has the read-in been successful?
    self.os8_send_line (dest + '<PTR:' + option)
    reply = self._child.expect (self._pip_to_replies)
    if reply !=0:
      self.pip_error_handler("os8_pip_to", reply)
      if did_conversion:
        os.remove(pt)
      return

    self.os8_send_ctrl ('[')      # finish transfer
    self._child.expect ('\\*')
    self.os8_send_ctrl ('[')      # exit PIP
    # We could detach ptr and restart OS/8 here, but we don't need to.
    # Do remove the temp file if we created one.
    if did_conversion:
      os.remove (pt)


  #### os8_pip_from ###################################################
  # Fetch a file from OS/8 to a local path using PIP.
  #
  # The OS/8 source filename is synthesized from the basename of the path,
  # upcasing if necessary.
  #
  # The file is sent via the SIMH paper tape device through PIP
  # specifying a transfer option.  If no option is specified,
  # ASCII is assumed.
  #
  # In ASCII mode, we post-process with ptp2txt which translates
  # POSIX ASCII conventions to OS/8 conventions.  In all other
  # modes, we do not do any translation.
  #
  # Entry context should be inside OS/8.  Exit context is inside OS/8.

  def os8_pip_from (self, os8name, path, option = None):
    if option == None: option = ""
    # If path is not a file, use the name portion of os8name.
    if os.path.isdir(path):
      colon = os8name.find(':')
      if colon == -1:                # No dev, just a name.
        path = path + "/" + os8name
      else:
        path = path + "/" + os8name[colon+1:]

    if option != "" and option not in self._valid_pip_options:
      print "Invalid PIP option: " + option + ". Ignoring os8_pip_from on: " + path
      return

    self.back_to_cmd ('\\.')
    self.send_cmd ('attach ptp ' + path)
    self.os8_restart ()
    
    self.os8_send_cmd ('\\.', 'R PIP')
    # Was the start of PIP successful or did we get a Monitor error?
    reply = self._child.expect (self._cd_replies)
    if reply != 0:
      self.pip_error_handler ("os8_pip_from", reply)
      return
    
    self.os8_send_line ('PTP:<' + os8name + option)

    reply = self._child.expect (self._cd_replies)
    if reply !=0:
      self.pip_error_handler ("os8_pip_from", reply)
      # There is an empty PTP file we need to remove.
      os.remove(path)
      return

    self.os8_send_ctrl ('[')      # exit PIP
    self.back_to_cmd ('\\.')
    self.send_cmd ('detach ptp')  # Clean flush of buffers.
    self.os8_restart ()

    if option == "" or option == "/A":
      if self.verbose: print "Format converting " + path
      # Convert text file to SIMH paper tape format
      bdir = pidp8i.dirs.build
      # Create uniquified temp path name.
      pf = path + "-" + str(os.getpid()) + ".pf_temp"
      os.rename(path, pf)
      tool = os.path.join (bdir, 'bin', 'ptp2txt')
      subprocess.call (tool + ' < ' + pf + ' > ' + path, shell = True)
      os.remove(pf)


  #### os8_send_line ###################################################
  # Core of os8_send_cmd.  Also used by code that needs to send text
  # "blind" to OS/8, without expecting a prompt, as when driving EDIT.

  def os8_send_line (self, line):
    self.os8_send_str (line)
    self._child.send ("\r")


  #### os8_send_str ########################################################
  # Core of os8_send_line.  Also used by code that needs to send text
  # "blind" to OS/8, without expecting a prompt and without a CR, as
  # when driving TECO.

  def os8_send_str (self, str):
    for i in xrange (0, len (str)):
      self._child.send (str[i])
      self.os8_kbd_delay ()


  #### os8_resume #######################################################
  # Resume OS/8.
  #
  # It would be nice if we could just send  the "cont" command
  # and have python expect and OS/8 synch right up.
  # But so far we have not figured out how to do that.
  # To resume OS/8 from SIMH we need to provoke a prompt.
  # Typing a rubout or ^U at a SIMH terminal session does this.
  # But not when SIMH is run under python expect.
  # We don't know why.
  #
  # boot works
  # go 7600 works
  # ^C <pause> \n\r works.
  #
  # The resume command uses the ^C method as the least disruptive
  # to system state.

  def os8_resume (self):
    if self._context == "os8": return   # Already running.
    
    self.send_cmd("cont")   # sets os8 context for us.

    # Now provoke a keyboard monitor prompt.
    self.os8_send_ctrl('c')
    self.os8_kbd_delay()
    self.os8_send_str('\r\n')
  

  #### os8_restart #######################################################
  # Called while in the SIMH command prompt, this restarts OS/8.
  #
  # This one-line function exists to abstract the method we use and to
  # document the reason we do it this way.
  #

  def read_tail (self, head, timeout = -1):
    self._child.expect_exact ([head], timeout)
    return self._child.readline ()


  #### send_cmd ########################################################
  # Wait for a SIMH command prompt and then send the given command.
  # If we are not in the simh context send ^e and set context "simh".
  # If we are not in simh context, send ^e set context "simh"
  #    and hope for the best.
  # If we issue a command that enters os8 context, set context "os8".
  # Note exiting out of OS/8 into the SIMH context is a bit of a
  # trap door. Resynchronizing with python expect requires provoking
  # a prompt, and prompts are context specific.
  # Perhaps we should require separate and explicit commands to
  # escape to SIMH. But for now, just be careful to use os8_resume
  # after calling send_cmd.
  
  def send_cmd (self, cmd):
    if self._context == "os8":
      self._child.expect ("\n\\.$")
      self._child.sendcontrol ('e')
      self._context = "simh"
    elif self._context != "simh":
      self._child.sendcontrol ('e')
      self._context = "simh"
      
    self._child.expect ("sim> $")
    self._child.sendline (cmd)
    m = re.match (self._simh_comm_re, cmd)
    if m != None and m.group(1)[:1].upper() in self._enters_os8_context:
      self._context = "os8"


  #### send_line #######################################################
  # Sends the given line "blind", without waiting for a prompt.

  def send_line (self, line):
    self._child.sendline (line)

  # memory before initializing it yourself.
  #
  # See os8_zero_core () for a less heavy-handed alternative for use
  # when running under OS/8.

  def zero_core (self):
    self.send_cmd ('de all 0')
  

  #### describe_dev_config #############################################
  # We provide an interface to alter SIMH device configurations for
  # specific parameters and specific devices
  #
  # dev configs supported:  rx, tti, tape
  #
  # rx:     RX8E, RX28   RX8E is the simh name for RX01 support.
  #                      RX28 is the simh name for RX02 support.
  # tti:    KSR, 7b      7b is full keyboard support.
  #                      KSR forces upcase of lower case keys on input.
  # tape:   td, dt       td is the TD8E DECtape device
  #                      dt is the TC08 DECtape device

  def describe_dev_config (self, name):
    if name == "tape":
      lines = self.do_simh_show("dt")
      dev_status = self.parse_show_tape_dev(lines)

      if dev_status == "dt": return "dt"
      else:
        lines = self.do_simh_show("td")
        return self.parse_show_tape_dev(lines)
    elif name == "rx":
      lines = self.do_simh_show("rx")
      return self.parse_show_rx_dev(lines)
    elif name == "tti":
      lines = self.do_simh_show("tti")
      return self.parse_show_tti(lines)
    else: return None

      
  #### do_simh_show  ###################################################
  # Calls show on the device name.
  # Returns array of lines from output.

  def do_simh_show (self, name):
    supported_shows = ["dt", "td", "tti", "rx"]
    if name not in supported_shows: return None
    
    ucname = name.upper()
    self.send_cmd("show " + name)
    self._child.expect(ucname + "\s+(.+)\r")
    lines = self._child.after.split ("\r")
    return lines


  #### parse_show_tape_dev  ############################################
  # Returns current state of DECtape support.
  # One of: disabled, td, dt, or None if parse fails.

  def parse_show_tape_dev (self, lines):
    if lines == None: return None
    is_enabled_re = re.compile("^(TD|DT)\s+(disabled|(devno=\S+,\s(\d)\s+units))$")
    m = re.match(is_enabled_re, lines[0])

    if m == None or m.group(1) == None or m.group(2) == None: return None
    if m.group(2) == "disabled": return "disabled"
    elif m.group(1) == "TD": return "td"
    elif m.group(1) == "DT": return "dt"
    else: return None


  #### parse_show_tape_attached  ########################################
  # Returns an ordered list of files attached or None if disabled.
  def parse_show_tape_attached (self, lines):
    if lines == None: return None
    if len(lines) < 2: return None
    attached = {}
    attachment_re = re.compile("^\s+(((DT|TD)(\d)(.+),\s+(not\s+attached|attached\s+to\s+(\S+)),(.+))|12b)$")
    for line in lines[1:]:
      m = re.match(attachment_re, line)
      if m == None or m.group(1) == None or m.group(1) == "12b": continue
      filename = m.group(7)
      if filename == None: filename = ""
      attached[m.group(4)] = filename
    return attached

  #### do_print_lines ###################################################
  # Debugging aid. Prints what we parsed out of _child.after.
  def do_print_lines (self, lines):
    for line in lines:
      print line

  #### simh_configure routines #########################################
  # These routines affect the state of device configuration in SIMH.
  # They are intended as robust ways to toggle between incompatible
  # configurations of SIMH:
  # Choice of TD8E or TC08 DECtape (SIMH td and dt devices).
  # Choice of RX01 or RX02 Floppy emulation.
  # The SIMH rx device sets RX8E for RX01, and RX28 for RX02.  
  # Choice of KSR or 7bit console configuration.
  #
  # When re-configuring dt, dt, and rx devices, any attached
  # images are detached before reconfiguration is attempted.
  # (SIMH errors out if you don't detach them.)
  #
  # The check to see if the change is unnecessary.
  # For now they return None if no change necessary.
  #
  # After re-configuring the device, the SIMH show command is used
  # to confirm the re-configuration was successful.
  #
  # In future, we should add exception handling for no change necessary.
  # For now, return True if the change was successful and False if not.


  def set_tape_config (self, to_tape):
    if to_tape == "dt": from_tape = "td"
    elif to_tape == "td": from_tape = "dt"
    else:
      print "Cannot set_tape_config for " + to_tape
      return False

    if self.verbose: print "Disable: " + from_tape + ", and enable: " + to_tape
    
    lines = self.do_simh_show(from_tape)
    from_status = self.parse_show_tape_dev(lines)

    if from_status == None:
      print "do_tape_change: Trouble parsing \'show " + from_tape + "\' output from simh. Giving up on:"
      self.do_print_lines (lines)
      return False

    if from_status == "disabled": print from_tape + " already is disabled."
    else:
      attached_from = self.parse_show_tape_attached(lines)
      if attached_from == None:
        print "do_tape_change: Trouble parsing \'show " + from_tape + "\' output from simh. Giving up on:"
        self.do_print_lines (lines)
        return False
      else:
        for unit in attached_from.keys():
          if attached_from[unit] != "":
            det_comm = "det " + from_tape + unit
            if self.verbose: print det_comm + "(Had: " + attached_from[unit] + ")"
            self.send_cmd(det_comm)
        self.send_cmd("set " + from_tape + " disabled")

    lines = self.do_simh_show(to_tape)
    to_status = self.parse_show_tape_dev(lines)

    if to_status == None:
      print "do_tape_change: Trouble parsing \'show " + to_tape + "\' output from simh. Giving up on:"
      self.do_print_lines (lines)
      return False
    elif to_status != "disabled": print to_tape + " already is enabled."
    else:
      self.send_cmd("set " + to_tape + " enabled")    

    # Test to confirm to_tape is now enabled.

    lines = self.do_simh_show(to_tape)
    to_status = self.parse_show_tape_dev(lines)

    if to_status == None:
      print "Failed enable of " + to_tape + ". Parse fail on \'show " + to_tape + "\'. Got:"
      self.do_print_lines (lines)
      return False
    elif to_status == "disabled":
      print "Failed enable of " + to_tape + ". Device still disabled."
      return False
    else: 
      return True


  #### parse_show_rx_dev ###############################################
  # Show the rx device configuration.

  def parse_show_rx_dev (self, lines):
    if lines == None: return None
    is_enabled_re = re.compile("^\s*(RX)\s+(disabled|((RX8E|RX28),\s+devno=\S+,\s+(\d)\s+units))$")
    m = re.match(is_enabled_re, lines[0])
    if m == None or m.group(2) == None: return None
    if m.group(2) == "disabled": return "disabled"
    return m.group(4)


   #### parse_show_rx_attached ##########################################
  # Returns an ordered list of files attached or None if disabled.

  def parse_show_rx_attached (self, lines):
    if len(lines) < 2: return None
    attached = {}
    attachment_re = re.compile("^\s+(((RX)(\d)(.+),\s+(not\s+attached|attached\s+to\s+(\S+)),(.+))|autosize)$")
    for line in lines[1:]:
      m = re.match(attachment_re, line)
      if m == None or m.group(1) == None or m.group(1) == "autosize": continue
      filename = m.group(7)
      if filename == None: filename = ""
      attached[m.group(4)] = filename
    return attached


  #### set_rx_config ####################################################
  
  def set_rx_config (self, to_rx):
    to_rx = to_rx.lower()
    if to_rx == "rx8e": from_rx = "rx28"
    elif to_rx == "rx01":
      to_rx = "rx8e"
      from_rx = "rx28"
    elif to_rx == "rx28": from_rx = "rx8e"
    elif to_rx == "rx02":
      to_rx = "rx28"
      from_rx = "rx8e"
    else:
      print "Cannot set_rx_config for " + to_rx
      return False
      
    if self.verbose: print "Switch rx driver: " + from_rx + ", to: " + to_rx
    lines = self.do_simh_show("rx")

    rx_type = self.parse_show_rx_dev (lines)
    if rx_type == None:
      print "do_rx_change: Trouble parsing \'show rx\' output from simh. Giving up on:"
      self.do_print_lines(lines)
      return False
    elif rx_type == "disabled":
      if self.verbose: print "rx is disabled. Enabling..."
      self.send_cmd("set rx enabled")
      # Retry getting rx info
      lines = self.do_simh_show("rx")
      rx_type = self.parse_show_rx_dev (lines)
      if rx_type == None:
        print "do_rx_change after re-enable: Trouble parsing \`show rx\` output from simh. Giving up on:"
        self.do_print_lines(lines)
        return False
      elif rx_type == "disabled":
        print "do_rx_change re-enable of rx failed. Giving up."
        return False

    if rx_type.lower() == to_rx:
      print "rx device is already set to " + to_rx
      return None
      
    attached_rx= self.parse_show_rx_attached(lines)
    if attached_rx == None:
      print "do_rx_change: Trouble parsing /'show rx\' from simh to find rx attachments. Got:"
      self.do_print_lines(lines)
    else:
      for unit in attached_rx.keys():
        if attached_rx[unit] != "":
          det_comm = "det rx" + unit
          if self.verbose: print det_comm + "(Had: " + attached_rx[unit] + ")"
          self.send_cmd(det_comm)

    self.send_cmd("set rx " + to_rx)

    # Test to confirm new setting of RX
    lines = self.do_simh_show("rx")
    rx_type = self.parse_show_rx_dev (lines)

    if rx_type == None:
      print "Failed change of rx to " + to_rx + ". Parse fail on \'show rx\'."
      return False
    elif rx_type.lower() != to_rx: 
      print "Failed change of rx to " + to_rx + ". Instead got: " + rx_type
      return False
    return True


  #### get_tti ##################################################
  # Returns an ordered list of files attached or None if disabled.
  def parse_show_tti (self, lines):
    if lines == None: return None
    is_enabled_re = re.compile("^(KSR|7b)$")
    if len(lines) < 2: return None

    # That second line of output contains embedded newlines.
    m = re.match(is_enabled_re, lines[1].strip())
    if m == None or m.group(1) == None: return None
    return m.group(1)



  #### do_tti_change ###################################################

  def set_tti_config (self, to_tti):
    if to_tti == "KSR": from_tti = "7b"
    elif to_tti == "7b": from_tti = "KSR"
    else:
      print "Cannot set_tti_config to " + to_tti
      return
    
    if self.verbose: print "Switch tti driver from: " + from_tti + ", to: " + to_tti

    lines = self.do_simh_show("tti")
    tti_type = self.parse_show_tti (lines)
    if tti_type == None:
      print "do_tti_change: Trouble parsing \'show tti\' output from simh. Giving up on:"
      self.do_print_lines(lines)
      return False
    elif tti_type == to_tti:
      print "tti device is already set to " + to_tti
      return None

    self.send_cmd("set tti " + to_tti)

    # Test to confirm new setting of tti
    lines = self.do_simh_show("tti")
    tti_type = self.parse_show_tti (lines)
    
    if tti_type == None:
      print "Failed change of tti to " + to_tti + ". Parse fail on \'show tti\'."
      return False
    elif tti_type != to_tti: 
      print "Failed change of tti to " + to_tti + ". Instead got: " + tti_type
      return False
    else:
      return True

PiDP-8/I @VERSION@ - OS/8 V3F - KBM V3S - CCL V3A
Configured by @BUILDUSER@ on @BUILDTS@

Restart address = 07600

Type:
    .DIR                -  to get a list of files on DSK:
    .DIR SYS:           -  to get a list of files on SYS:
    .R PROGNAME         -  to run a system program
    .HELP FILENAME      -  to type a help file

# OS/8 Media


## Bootable Systems

`os8v3d-bin.rk05` — Bootable OS/8 system made from the binary DECtapes
of OS/8 V3D in the Willem van der Mark Archives described below plus
other tapes in the [`subsys` subdirectory](/file/media/os8/subsys)
during the PiDP-8/I software build process. This is the disk image used
by boot options IF=0 and IF=7. See the [top-level `README.md`
file][tlrm] for instructions on controlling what goes into this image.

`v3*.tu56` — Bootable OS/8 DECtape image used by boot option IF=3.
Primarily intended to demonstrate the uncommon "boot and run from tape"
experience offered by early DEC systems. There will usually be only one
of these files, with its name indicating whether it contains an OS/8 V3D
or V3F operating system image, and whether it is built to expect a TC08
or TD8E tape drive interface. For example, it may be called
`v3f-tc08.tu56`, meaning OS/8 V3F built for a system with a TC08 tape
interface.


## Data Disks

`os8v3d-src.rk05` — OS/8 Source RK05 pack made from the source DECtapes
of OS/8 V3D in the Willem van der Mark Archives, described below. This
is not a bootable OS/8 system. It is merely a convenience for use with a
bootable OS/8 system, so you can avoid mounting the seven "Source"
distribution tapes in succession.

If you give the following command to SIMH:

    att rk1 media/os8/os8v3d-src.rk05
   
...this disk will appear as RKA1: and RKB1: under OS/8.


## Distribution DECtape images

Taken from the Willem van der Mark Archives.

Willem van der Mark wrote a really cool [PDP-8 emulator in Java][vdms].
He has a well organized archive of DEC media.  The following DECtapes
were copied from his [OS8-V3D software archive][vdms].

The OS/8 Binary DECtapes were compared against those in [Dave Gesswein's
Archive][dga] and found to be nearly identical.  Of the three tapes

| `al-4695c-sa-os8-v3d-5.1978.tu56`     | DEC OS/8 V3D **Source** Distribution  5/7
| `al-4696c-sa-os8-v3d-6.1978.tu56`     | DEC OS/8 V3D **Source** Distribution  6/7
| `al-4697c-sa-os8-v3d-7.1978.tu56`     | DEC OS/8 V3D **Source** Distribution  7/7
| `al-4759c-sa-os8-ext-1.1978.tu56`     | DEC OS/8 V3D Extensions **Source** Distribution  1/3
| `al-4760c-sa-os8-ext-2.1978.tu56`     | DEC OS/8 V3D Extensions **Source** Distribution  1/3
| `al-5586c-sa-os8-ext-3.1978.tu56`     | DEC OS/8 V3D Extensions **Source** Distribution  1/3

## Other Master DECtape images

| DECtape Image File Name                       | Content Description
| ----------------------------------------------|------------------------------
| al-5642a-ba-macrel-linker.1978.tu56           | Version 1 MACREL distribution. No longer used.
| al-5642c-ba-macrel-v2-futil-v8b-by-hand.tu56  | Hand patched distribution of MACREL version 2. Contains critical, mandatory patch to FUTIL.

## Subdirectories

| Directory Name  | Content Description
| ----------------|------------------------------------------------------------
| patches     | Contains the OS/8 patch files
| scripts     | Contains scripts fed to os8-run to automate various actions.
| subsys      | Images containing OS/8 subsystems such as Focal, Adventure, etc.

## Other Files

| File Name       | Content Description
| ----------------------------------------------------------------------------
| `LICENSE.md`    | License provided by DEC that makes our use of OS/8 legal
| `init.cm`   | Command to type out the contents of INIT.TX. Used at startup by
|         | various boot images.
| `init.tx.in`    | Baseline text typed out by init.cm.  Configuration in auto.def
|         | establishes parameters that are substituted to create `init.tx`.
| `local.tu56`    | Files created for or vetted by the PiDP-8/I project; used at build time

[dga]:  http://www.pdp8online.com/images/images/misc_dectapes.shtml
[tlrm]: /doc/trunk/README.md
[vdms]: http://vandermark.ch/pdp8/index.php?n=OS8.OS8-V3D
[vdma]: http://vandermark.ch/pdp8/index.php

TYPE INIT.TX

# Most of these patches have been verified
# by reading the source code.
# The patches that remain commented out are not recommended
# and the reason why appears in the line above it.
#
# ABSLDR-21.29.1M is against v6A but we have v4A.
# v6A came with OS/8 Devices Extension kit QF026
# Binary DECtape: AL-H525A-BA, Source not on DECtape
# DO NOT APPLY THIS PATCH.
## ABSLDR-21.29.1M-v6C.patch8
BASIC.UF-31.5.1M-V5B.patch8
BATCH-31.23.1M-v7B.patch8
BLOAD-31.10.1M-v5B.patch8
BRTS-31.11.1M-v5B.patch8
# BRTS 31.11.2O disables 8th bit parity. Recommended.
BRTS-31.11.2-O.patch8
# BRTS 31.11.3O enables 132 column output. Recommended.
BRTS-31.11.3-O.patch8
BRTS-31.11.5-x.patch8
CREF-21.15.1M-v5B.patch8
CREF-21.15.2M-v5C.patch8
EDIT-21.17.1M-v12B.patch8
EDIT-21.17.2M-v12C.patch8
EDIT-21.17.3M-v12D.patch8
# EDIT 21.17.4 overwrites patch in 21.17.2. DO NOT APPLY THIS PATCH
# EDIT-21.17.4M-V12C.patch8
F4-21.1.2M-v4B.patch8
F4-51.3.1M-v4C.patch8
F4-51.3.2M-v4x.patch8
# FORLIB 51.10.1M is hard-coded into mkos8 to copy a new
# FORLIB.RL made with instructions from the patch.
# So the patch will not apply but is listed here for completeness.
## FORLIB-51.10.1M.patch8
FOTP-21.19.1M-V9B.patch8
# FRTS-51.3.3-O is to enable FRTS to work with 2-page system
# handlers.  I've read the code but do not fully understand it.
# It is plausable that it generalizes on the code that makes
# the 2-page TD8E handler work.  But it could also be a
# patch tha tONLY works with the OS/8 Devices Extension kit QF026.
# We are enabling the patch for not.  If further testing shows
# that it breaks TD8E support, we will turn it off.
FRTS-51.3.3-O.patch8
# The two FUTIL patches only get applied to FUTIL V7 which comes with
# OS/8 V3D to bring it up to V7D.  MACREL V2 comes with FUTIL V8B, so
# these patches are skipped by mkos8 using an RE match on the file name
# when the user does not pass --disable-os8-macrel to configure.
FUTIL-31.21.1M-v7B.patch8
FUTIL-31.21.2M-v7D.patch8
# FUTIL 31.21.3O switches XS format. Recommend to leave it out.
# FUTIL-31.21.3O.patch8
# LQP 21.49.1 consists of commands run in BUILD.
# The auto-apply system won't apply it.
# It has not been validated. It uses hardware we don't have.
## LQP-21.49.1M-vB.patch8
MCPIP-21.21M-v6B.patch8
MSBAT-31.22.1M-v3B.patch8
PAL8-21.22.1M-v10B.patch8
PAL8-21.22.2M-v10C.patch8
PAL8-21.22.3M-v10D.patch8
# PAL8 21.22.4M is for V12 PAL8. It BREAKS LS output in V10!
# DO NOT APPLY THIS PATCH!
# PAL8-21.22.4M.patch8
PIP-21.23.1M-v12B.patch8
PIP10-21.24.1M-v3B.patch8
SABR-21.91.1M-v18B.patch8
SET-21.26.1M-v1C.patch8
SET-21.26.2M-v1D.patch8
SET-21.26.3M-v1E.patch8
# TECO 31.20.1 Unconditional no case flagging. Not recommended
# TECO-31.20.01O.patch8
# TECO 31.20.2 Turns off verbose errors. Not recommended.
# TECO-31.20.02O.patch8
# TECO 31.20.3 Turns off Yank overwrite warning. Not recommended.
# TECO-31.20.03O.patch8
# TECO 31.20.4 Special support for VT05. Not recommended.
# TECO-31.20.04O.patch8
TECO-31.20.05M-v5A.patch8
TECO-31.20.06M-v5B.patch8
TECO-31.20.07M.v5C.patch8
TECO-31.20.08M-v5.04.patch8
TECO-31.20.10M-5.05.patch8
TECO-31.20.11M-v5.06.patch8
TECO-31.20.12M-v5.07.patch8
TECO-31.20.13M-v5.08.patch8
#
# MACREL, LINK, and OVDRV patches have not been validated.
# The Version numbers don't all match. Some won't apply.
# More work is needed before they are deemed safe.
# NOT Recommended.
## MACREL-40.5.1M-v1D.patch8
## MACREL-40.5.2M-v1E.patch8
## LINK-40.2.1M-v1D.patch8
## LINK-40.2.2M-v1E.patch8
## LINK-40.2.3M-v1F.patch8
# OVRDRV 40.6.1 is a source level patch
## OVRDRV-40.6.1M-v1B-8srccom

# OS/8 Scripts

This directory contains scripts to be run by the os8-run tool,
which provides a rich language to automate actions of OS/8
under SIMH.  See also the [os8-run documentation][os8-run-doc].

Here is an inventory of the scripts and their actions.

| Script Name        | Function
|--------------------|-------------------------------------------
| v3d-dist-rk05.os8  | Construct an OS/8 v3d rk05 image from
|                    | distribution media, configured by auto.def
| v3d-rk05.os8       | Apply patches to output of v3d-dist.rk05.os8
| 		     | to construct a default OS/8 rk05 boot image.
| v3d-src-rk05.os8   | Construct an OS/8 rk05 image containing souces
| 		     | from distribution media.
| all-tu56.os8	     | Construct 4 tu56 images based on --enable
| 		     | parameters: v3d or v3f with tc08 or td12k
|		     | system heads.
| cusp-copyin.os8    | Include script used by all-tu56.os8 to
| 		     | copy Commonly Used System Programs onto
|		     | the tu56 image under construction.
| v3f-control.os8    | Perform assembly or BATCH operations to produce
| 		     | binaries from v3f sources.

There are also utility/test scripts:

| Script Name        | Function
|--------------------|-------------------------------------------
| version-test.os8   | Test the `begin enabled version` functionality
| 		     | in os8-run.
| copy-test.os8	     | Test the `cpto` and `cpfrom` os8-run commands.
| err-test.os8	     | Used to provoke errors in os8-run and test
| 		     | behavior.
| restart-test.os8   | Test the `restart` os8-run command.
| patch-test.os8     | Test the `patch` os8-run command.
| v3d-reset-tc08.os8 | Utility: re-configure the default OS/8 v3d
| 		     | rk05 boot image to use TC08 DECtape (instead
|		     | of TD8E) drivers.

[os8-run-doc]: /doc/trunk/doc/os8-run.md

## License

Copyright © 2016-2018 by Bill Cattey. This document is licensed under
the terms of [the SIMH license][sl].

# Builds a bootable dectape image for either v3d or v3f.
# Pieces come from, as needed:
# v3d.rk05, the os8v3d device driver distribution DECtape,
# and the os8v3f-build rk05.
# Keep this file in sync with v3d-dist.os8 which determines
# which device drivers are available by default when running
# BUILD.SV from SYS: in the v3d enabled sections below.

# Control: We default to v3d unless externally overridden to enable v3f
enable v3d
begin enabled v3f
  disable v3d
end enabled v3f

begin enabled v3f
  print Building v3f
end enabled v3f

begin enabled v3d
  print Building OS/8 v3d tu56 image
end enabled v3d

mount dt1 $os8mi/al-4712c-ba-os8-v3d-2.1978.tu56 readonly required

begin enabled v3f
  mount rk1 $bin/v3f-made.rk05 required
end enabled v3f

# Control: We default to tc08 unless externally overridden to enable
# Either td12k or tdrom which will enable td8e and disable tc08

enable tc08
begin enabled td12k
  print for td12k configuration of TD8E.
  enable td8e
end enabled td12k

begin enabled tdrom
  print for dtrom configuration of TD8E.
  enable td8e
end enabled tdrom

begin enabled td8e
  disable tc08
end enabled td8e

# This script can be run from a parallel make
# So we create a scratch version of the system rk05 to prevent conflicts.
# We have to do this anyway for TD8E since we change the DECtape configuration.

mount rk0 $bin/v3d.rk05 required scratch
boot rk0

begin enabled td8e
  # For TD8E we run BUILD twice
  # First from SYS to change switch from TC08 to TD8E
  # Then  to build the TD8E head from either RKB1 for v3f or from SYS for v3d.

  os8 SET SYS NO INIT
  
  begin build SYS:BUILD
    # TD8E non-system handler should be present.
    # LOAD DTA1:TD8EA.BN
    DELETE DTA0,DTA1
    INSERT TD8A,DTA0,DTA1
    BOOT
  end build

  configure tape td

  # Now that the system is configured for TD8E build the .tu56
  # Mount the destination image, either v3d or v3f on drive 0.
  begin enabled v3d
    mount td0 $os8mo/v3d-td12k.tu56 new
  end enabled v3d

  begin enabled v3f
    mount td0 $os8mo/v3f-td12k.tu56 new
  end enabled v3f

  mount td1 $os8mi/al-4712c-ba-os8-v3d-2.1978.tu56 readonly required
end enabled td8e

# This is the TC08 path.
# Mount the destination image, either v3d or v3f on drive 0.

begin enabled tc08
  print with TC08 support.

  begin enabled v3d
    mount dt0 $os8mo/v3d-tc08.tu56 new
  end enabled v3d

  begin enabled v3f
    mount dt0 $os8mo/v3f-tc08.tu56 new
  end enabled v3f

end enabled tc08

# Now build the system head.
# v3f is more complicated because it installs a new KBM and CD.
# Additionally that version of BUILD.SV contained NO drivers.

# Be careful with the v3d build. We are using the BUILD.SV
# from the rk05 SYS:. Be careful not to trash it!
# TODO: Change BUILD.SV on our rk05 system packs already to
# have the TD8E Drivers loaded.

boot rk0

begin enabled v3d

  begin build SYS:BUILD
    # TD8EA.BN should already be present.
    # LOAD DTA1:TD8EA.BN

    # The appropriate TD8E System handlers should already be present.
    # begin enabled td12k
    #  LOAD DTA1:TD8ESY.BN
    # end enabled td12k
    # begin enabled tdrom
    #  LOAD DTA1:ROMMSY.BN
    # end enabled tdrom

    # Necessary! Otherwise we mung the RK05 image!
    DELETE SYS
    DELETE RKA0
    DELETE RKB0
    INSERT RK05,RKA0,RKB0

    # Unconditionally delete DTA0 because we shift it
    # from non-system to system.
    DELETE DTA0

    # TD8E also changes non-system DTA1 from TC to TD.
    begin enabled td8e
      DELETE DTA1
    end enabled td8e

    # Configure system for TC08
    begin enabled tc08
      SYSTEM TC08
      INSERT TC08,DTA0
      DSK TC08:DTA0
    end enabled tc08

    # Configure system for td12k
    begin enabled td12k
      SYSTEM TD8E
      INSERT TD8E,DTA0
      INSERT TD8E,DTA1
      DSK TD8E:DTA0
    end enabled td12k
  
    # Or configure system for tdrom
    begin enabled tdrom
      SYSTEM ROM
      INSERT ROM,DTA0
      INSERT ROM,DTA1
      DSK ROM:DTA0
    end enabled tdrom
    
    # That should do it.
    PRINT
    BOOT
    end build

end enabled v3d

begin enabled v3f
  os8 COPY DSK:<RKB1:OS8.BN,CD.BN

  begin build RKB1:BUILD
    LOAD DTA1:RK8ESY.BN
    LOAD DTA1:RK8ENS.BN
    LOAD DTA1:PT8E.BN
    
    # TD8E non-system handler.
    LOAD DTA1:TD8EA.BN
    
    begin enabled tc08
      LOAD DTA1:TC08SY.BN
      LOAD DTA1:TC08NS.BN
    end enabled tc08
    
    # TD8E systems with 12K uncomment next line.
    begin enabled td12k
      LOAD DTA1:TD8ESY.BN
    end enabled td12k
    # TD8E systems with ROM uncomment next line.
    begin enabled tdrom
      LOAD DTA1:ROMMSY.BN
    end enabled tdrom

    begin enabled td8e
      # Additional TD8E non-system devices not on sys by default.
      # But there might not be space. Leave them out for now.
      # Units 2 and 3.
      # LOAD DTA1:TD8EB.BN
      # Units 4 and 5.
      # LOAD DTA1:TD8EC.BN
      # Units 6 and 7.
      # LOAD DTA1:TD8ED.BN
    end enabled td8e
    
    
    # I think we actually want the RKB1 version of KL8E.BN
    LOAD DTA1:KL8E.BN
    LOAD DTA1:LPSV.BN
    LOAD RKB1:RXSY2.BN
    LOAD RKB1:RXNS.BN
    
    INSERT PT8E,PTR
    INSERT PT8E,PTP
    INSERT KL8E,TTY
    INSERT LPSV,LPT
    
    begin enabled tc08
      SYSTEM TC08
      INSERT TC08,DTA0
      INSERT TC,DTA1
      DSK TC08:DTA0
    end enabled tc08
    
    # Un-comment next 4 lines for TD8E 12K System
    begin enabled td12k
      SYSTEM TD8E
      INSERT TD8E,DTA0
      INSERT TD8E,DTA1
      DSK TD8E:DTA0
    end enabled td12k
    
    # Un-comment next 4 lines for TD8E ROM System
    begin enabled tdrom
      SYSTEM ROM
      INSERT ROM,DTA0
      INSERT ROM,DTA1
      DSK ROM:DTA0
    end enabled tdrom
    
    INSERT RX02,RXA0
    
    INSERT RK05,RKA0,RKB0
    INSERT RK05,RKA1,RKB1
    INSERT RK05,RKA2,RKB2
    
    BUILD DSK:OS8.BN DSK:CD.BN
    BOOT
  end build
  
end enabled v3f

os8 SAVE DTA0 BUILD.SV

# cusp-copyin.os8 uses the value of v3d or v3f enablement
# already present in the environment.
include $media/os8/scripts/cusp-copyin.os8

# Lastly copy in the appropriate DECtape utilities.
begin cdprog RKA0:FOTP.SV
  begin enabled tc08
    DTA0:<RKA0:DTCOPY.SV
    DTA0:<RKA0:DTFRMT.SV
  end enabled tc08
  begin enabled td8e
    DTA0:<RKA0:TDCOPY.SV
    DTA0:<RKA0:TDFRMT.SV
  end enabled td8e
end cdprog RKA0:FOTP.SV

# The last thing we do is run CCL on the system tu56 we just made.

begin enabled td8e
  boot td0
end enabled td8e

begin enabled tc08
  boot dt0
end enabled tc08

os8 R CCL

# Further system initialization

os8 SET TTY COL 3

begin default crt
os8 SET TTY SCOPE
end default crt

begin default lcmod
os8 SUBMIT SYS:LCSYS.BI
# os8 SUBMIT SYS:LCBAS.BI
end default lcmod

# INIT message setting stuf goes here
begin enabled v3f
cpto $os8mi/3finit.tx DSK:INIT.TX
end enabled v3f

begin enabled v3d
cpto $os8mi/init.tx
end enabled v3d

cpto $os8mi/init.cm

os8 SET SYS INIT