;;; Commentary:
+;; There are many Z-machine interpreters, but this one is mine.
+;; It only capable of interpreting the subset of Z-code necessary
+;; to run the first Zork game in z3 format.
+;;
+;; It is based entirely on the description of the Z-machine contained
+;; Marnix Klooster's wonderful document, "The Z-machine And How to Emulate It."
+
;;; Code:
;; Utility functions
(defun ez-get-global-var (gvar)
(if (> gvar 239)
(error "Invalid global variable %d" gvar))
- (ez-mem-ref-word (+ (* 2 gvar) ez-globalvartab-addr)))
+ (let ((val
+ (ez-mem-ref-word (+ (* 2 gvar) ez-globalvartab-addr))))
+ (ez-debug-message "\tRetrieved %x from global variable %x" val gvar)
+ val))
(defun ez-set-global-var (gvar val)
- (ez-mem-set-word (+ (* 2 gvar) ez-globalvartab-addr) val))
+ (ez-mem-set-word (+ (* 2 gvar) ez-globalvartab-addr) val)
+ (ez-debug-message "\tSet global variabl %x to %x" gvar val))
;; Object tree
(chars (cdr word-count-and-chars))
(cur 0)
(lock 0)
- (abbrev-char nil)
(s ""))
- (dolist (char chars)
- (cond
- (abbrev-char
- (let ((abbrev-addr
- (* 2 (ez-mem-ref-word (+ ez-abbrevtab-addr
- (* 2 (+ (* (- abbrev-char 1) 32) char)))))))
- (setq s (concat s (cdr (ez-get-zstring-and-length abbrev-addr)))))
- (setq abbrev-char nil))
- ((memq char '(1 2 3)) ;Abbreviation
- (setq abbrev-char char))
- ((= char 4)
- (setq cur (mod (+ cur 1) 3)))
- ((= char 5)
- (setq cur (mod (+ 3 (- cur 1)) 3)))
- (t
- (setq s (concat s (substring (elt ez-zstring-alphabets cur)
- char (+ char 1))))
- (setq cur lock))))
+ (while (> (length chars) 0)
+ (let ((char (pop chars)))
+ (cond
+ ((memq char '(1 2 3)) ;Abbreviation
+ (let* ((abbrev-char char)
+ (abbrev-addr
+ (* 2 (ez-mem-ref-word (+ ez-abbrevtab-addr
+ (* 2 (+ (* (- abbrev-char 1) 32) (pop chars))))))))
+ (setq s (concat s (cdr (ez-get-zstring-and-length abbrev-addr))))))
+ ((= char 4)
+ (setq cur (mod (+ cur 1) 3)))
+ ((= char 5)
+ (setq cur (mod (+ 3 (- cur 1)) 3)))
+ ((and (= cur 2) (= char 6))
+ (setq s (concat s (char-to-string (+ (lsh (pop chars) 5) (pop chars)))))
+ (setq cur lock))
+ (t
+ (setq s (concat s (substring (elt ez-zstring-alphabets cur)
+ char (+ char 1))))
+ (setq cur lock)))))
(cons word-count s)))
(defun ez-get-zstring (base-addr)
(cdr (ez-get-zstring-and-length base-addr)))
+;; Dictionary
+
+(defun ez-get-dictionary ()
+ (let* ((nseps (ez-mem-ref-byte ez-dict-base))
+ (separators
+ (mapcar (lambda (i) (ez-mem-ref-byte (+ ez-dict-base i)))
+ (number-sequence 1 nseps)))
+ (bytes-per-entry (ez-mem-ref-byte (+ ez-dict-base 1 nseps)))
+ (nentries (ez-mem-ref-word (+ ez-dict-base 1 nseps 1)))
+ (entries-base (+ ez-dict-base nseps 4))
+ (entries nil))
+ (dotimes (i nentries)
+ (let ((this-base (+ entries-base (* 7 i))))
+ (setq entries (cons (cons this-base
+ (ez-get-zstring this-base))
+ entries))))
+ (list entries separators entries)))
;; Call stack
(defun ez-routine-stack-push (val)
(let ((frame (car ez-call-stack)))
+ (ez-debug-message "\tPushed %x to stack" val)
(setf (elt frame 1) (cons val (elt frame 1)))))
(defun ez-routine-stack-pop ()
(let* ((frame (car ez-call-stack))
(rs-head (car (elt frame 1))))
(setf (elt frame 1) (cdr (elt frame 1)))
+ (ez-debug-message "\tPopped %x from stack" rs-head)
rs-head))
(defun ez-get-local-var (lvar)
- (let ((frame (car ez-call-stack)))
- (aref (elt frame 2) (- lvar 1))))
+ (let* ((frame (car ez-call-stack))
+ (val (aref (elt frame 2) (- lvar 1))))
+ (ez-debug-message "\tRetrieved value %x from local variable %x" val lvar)
+ val))
(defun ez-set-local-var (lvar val)
(let ((frame (car ez-call-stack)))
+ (ez-debug-message "\tSet local variable %x to %x" lvar val)
(aset (elt frame 2) (- lvar 1) val)))
(defun ez-get-pc ()
(defun ez-set-var (var val)
(cond
((= var 0)
- (message "Pushed %x to stack" val)
(ez-routine-stack-push val))
((< var 16)
- (message "Saved %x to local variable %x" val var)
(ez-set-local-var var val))
(t
- (message "Saved %x to global variable %x" val (- var 16))
(ez-set-global-var (- var 16) val))))
(defun ez-read-pc-var-and-inc ()
(error "Unsupported op PC:%x Optype:%s Opcode:%x Operands:%s Operand-types:%s"
instr-pc optype opcode (ez-list-to-string-hex operands) operand-types))
(let ((mnemonic (elt table-row 1)))
- (message "PC:%x Optype:%s Opcode:%x Mnemonic:%s Operands:%s Operand-types:%s"
+ (ez-debug-message "PC:%x Optype:%s Opcode:%x Mnemonic:%s Operands:%s Operand-types:%s"
instr-pc optype opcode mnemonic
(ez-list-to-string-hex operands) operand-types))
(funcall (elt table-row 2) operands operand-types))))
(if (= type1 #b11)
nil
(cons type1
- (let ((type2 (lsh (logand #b110000 type-byte) -4)))
+ (let ((type2 (mod (lsh type-byte -4) 4)))
(if (= type2 #b11)
nil
(cons type2
- (let ((type3 (lsh (logand #b1100 type-byte) -2)))
+ (let ((type3 (mod (lsh type-byte -2) 4)))
(if (= type3 #b11)
nil
(cons type3
- (let ((type4 (logand #b11)))
+ (let ((type4 (mod type-byte 4)))
(if (= type4 #b11)
nil
(list type4))))))))))))))
((1op #x05) inc ez-op-inc)
((1op #x06) dec ez-op-dec)
((1op #x0B) ret ez-op-ret)
+ ((0op #x08) ret_pulled ez-op-ret-pulled)
((1op #x0C) jump ez-op-jump)
((2op #x05) inc_jg ez-op-inc-jg)
((2op #x04) dec_jg ez-op-dec-jg)
((2op #x10) loadb ez-op-loadb)
((2op #x01) je ez-op-je)
((2op #x02) jl ez-op-jl)
+ ((2op #x03) jg ez-op-jg)
((2op #x06) jin ez-op-jin)
+ ((2op #x07) test ez-op-test)
((2op #x08) or ez-op-or)
((2op #x09) and ez-op-and)
((2op #x14) add ez-op-add)
((2op #x16) mul ez-op-mul)
((2op #x17) div ez-op-div)
((2op #x18) mod ez-op-mod)
- ((var #x00) call_fv ez-op-callf)
+ ((var #x00) call_fv ez-op-callfv)
((1op #x01) get_sibling ez-op-get-sibling)
((1op #x02) get_child ez-op-get-child)
((1op #x03) get_parent ez-op-get-parent)
((0op #x0B) new_line ez-op-new-line)
((var #x06) print_num ez-op-print-num)
((var #x05) print_char ez-op-print-char)
- ((1op #x0A) print_obj ez-op-print-obj)))
+ ((1op #x0A) print_obj ez-op-print-obj)
+ ((var #x04) read ez-op-read)))
(defun ez-op-ret (operands &optional operand-types)
(let ((retval (car operands)))
+ (ez-debug-message "\tReturning value %x" retval)
(ez-pop-call-stack-frame)
(ez-set-var (ez-read-pc-byte-and-inc) retval))
- t)
+ 'run)
+
+(defun ez-op-ret-pulled (operands operand-types)
+ (let ((retval (ez-routine-stack-pop)))
+ (ez-debug-message "\tReturning value %x" retval)
+ (ez-op-ret (list retval)))
+ 'run)
(defun ez-op-rtrue (&optional operands operand-types)
(ez-op-ret (list 1))
- t)
+ 'run)
(defun ez-op-rfalse (&optional operands operand-types)
(ez-op-ret (list 0))
- t)
+ 'run)
(defun ez-op-jz (operands operand-types)
(ez-do-branch (= (car operands) 0))
- t)
+ 'run)
(defun ez-op-je (operands operand-types)
(ez-do-branch (memq (car operands) (cdr operands)))
- t)
+ 'run)
(defun ez-op-jg (operands operand-types)
(let ((s1 (ez-decode-signed-operand (car operands) (car operand-types)))
(s2 (ez-decode-signed-operand (cadr operands) (cadr operand-types))))
(ez-do-branch (> s1 s2)))
- t)
+ 'run)
(defun ez-op-jl (operands operand-types)
(let ((s1 (ez-decode-signed-operand (car operands) (car operand-types)))
(s2 (ez-decode-signed-operand (cadr operands) (cadr operand-types))))
(ez-do-branch (< s1 s2)))
- t)
+ 'run)
(defun ez-op-inc-jg (operands operand-types)
(let ((var (car operands)))
(ez-op-inc (list var))
(ez-op-jg (cons (ez-get-var var) (cdr operands)) (cons 'w (cdr operand-types))))
- t)
+ 'run)
(defun ez-op-dec-jl (operands operand-types)
(let ((var (car operands)))
(ez-op-dec (list var))
(ez-op-jl (cons (ez-get-var var) (cdr operands)) (cons 'w (cdr operand-types))))
- t)
+ 'run)
(defun ez-op-jin (operands operand-types)
(let ((obj (car operands))
(n (cadr operands)))
(ez-do-branch (or (= n 0)
(= n (ez-get-obj-parent obj)))))
- t)
+ 'run)
+
+(defun ez-op-test (operands operand-types)
+ (let ((a (car operands))
+ (b (cadr operands)))
+ (ez-do-branch (= (logand a b) b)))
+ 'run)
(defun ez-op-jump (operands operand-types)
(let ((offset (if (eq (car operand-types) 'b)
(ez-decode-signed-byte (car operands))
(ez-decode-signed-word (car operands)))))
(ez-set-pc (+ (ez-get-pc) offset -2)))
- t)
+ 'run)
(defun ez-op-inc (operands &optional operand-types)
(let ((var (car operands)))
(ez-set-var var (mod (+ 1 (ez-get-var var)) #x10000)))
- t)
+ 'run)
(defun ez-op-dec (operands &optional operand-types)
(let ((var (car operands)))
(ez-set-var var (mod (+ (ez-get-var var) 1) #x10000)))
- t)
+ 'run)
(defun ez-op-store (operands operand-types)
(let ((var (car operands))
(a (cadr operands)))
(ez-set-var var a))
- t)
+ 'run)
(defun ez-op-load (operands operand-types)
(let ((var (car operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (ez-get-var var)))
- t)
+ 'run)
(defun ez-op-storew (operands operand-types)
(let ((baddr (car operands))
(n (cadr operands))
(a (caddr operands)))
(ez-mem-set-word (+ baddr (* 2 n)) a))
- t)
+ 'run)
(defun ez-op-loadw (operands operand-types)
(let ((baddr (car operands))
(n (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (ez-mem-ref-word (+ baddr (* 2 n)))))
- t)
+ 'run)
(defun ez-op-storeb (operands operand-types)
(let ((baddr (car operands))
(n (cadr operands))
(a (caddr operands)))
(ez-mem-set-byte (+ baddr n) a))
- t)
+ 'run)
(defun ez-op-loadb (operands operand-types)
(let ((baddr (car operands))
(n (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (ez-mem-ref-byte (+ baddr n))))
- t)
+ 'run)
(defun ez-op-and (operands operand-types)
(let ((a (car operands))
(b (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (logand a b)))
- t)
+ 'run)
(defun ez-op-or (operands operand-types)
(let ((a (car operands))
(b (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (logior a b)))
- t)
+ 'run)
(defun ez-op-add (operands operand-types)
(let ((a (car operands))
(b (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (mod (+ a b) #x10000)))
- t)
+ 'run)
(defun ez-op-sub (operands operand-types)
(let ((a (car operands))
(b (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (mod (+ (- a b) #x10000) #x10000)))
- t)
+ 'run)
(defun ez-op-mul (a b)
(let ((a (car operands))
(b (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc) (mod (* a b) #x10000)))
- t)
+ 'run)
(defun ez-op-div (a b)
(error "Not implemented"))
(defun ez-op-mod (a b)
(error "Not implemented"))
-(defun ez-op-callf (operands operand-types)
+(defun ez-op-callfv (operands operand-types)
(let* ((raddr (car operands))
(call-operands (cdr operands))
(r (* 2 raddr))
(L (ez-mem-ref-byte r))
(n (length call-operands))
(new-pc (+ r 1 (* L 2))))
- (ez-add-call-stack-frame new-pc)
- (dotimes (i L)
- (if (< i n)
- (ez-set-local-var (+ i 1) (elt call-operands i))
- (ez-set-local-var (+ i 1) (ez-mem-ref-word (+ r 1 (* 2 i)))))))
- t)
+ (if (= raddr 0)
+ (ez-set-var (ez-read-pc-byte-and-inc) 0) ; Simply return 0
+ (ez-add-call-stack-frame new-pc)
+ (dotimes (i L)
+ (if (< i n)
+ (ez-set-local-var (+ i 1) (elt call-operands i))
+ (ez-set-local-var (+ i 1) (ez-mem-ref-word (+ r 1 (* 2 i))))))))
+ 'run)
(defun ez-op-test-attr (operands operand-types)
(let ((obj (car operands))
(attr (cadr operands)))
(ez-do-branch (= 1 (ez-get-obj-attr obj attr)))
- t))
+ 'run))
(defun ez-op-set-attr (operands operand-types)
(let ((obj (car operands))
(attr (cadr operands)))
(ez-set-obj-attr obj attr 1))
- t)
+ 'run)
(defun ez-op-clear-attr (operands operand-types)
(let ((obj (car operands))
(attr (cadr operands)))
(ez-set-obj-attr obj attr 0))
- t)
+ 'run)
(defun ez-op-get-sibling (operands operand-types)
(let ((sib (ez-get-obj-sibling (car operands))))
(ez-set-var (ez-read-pc-byte-and-inc) sib)
(ez-do-branch (> sib 0)))
- t)
+ 'run)
(defun ez-op-get-child (operands operand-types)
(let ((child (ez-get-obj-child (car operands))))
(ez-set-var (ez-read-pc-byte-and-inc) child)
(ez-do-branch (> child 0)))
- t)
+ 'run)
(defun ez-op-get-parent (operands operand-types)
(let ((parent (ez-get-obj-parent (car operands))))
(ez-set-var (ez-read-pc-byte-and-inc) parent))
- t)
+ 'run)
(defun ez-op-remove-obj (operands operand-types)
(let ((obj (car operands)))
(ez-remove-obj obj))
- t)
+ 'run)
(defun ez-op-insert-obj (operands operand-types)
(let ((obj1 (car operands))
(obj2 (cadr operands)))
(ez-insert-obj obj1 obj2))
- t)
+ 'run)
(defun ez-op-put-prop (operands operand-types)
(let* ((obj (car operands))
(prop (cadr operands))
(a (caddr operands)))
(ez-set-obj-prop obj prop a))
- t)
+ 'run)
(defun ez-op-get-prop (operands operand-types)
(let* ((obj (car operands))
(prop (cadr operands)))
(ez-set-var (ez-read-pc-byte-and-inc)
(ez-get-obj-prop obj prop)))
- t)
+ 'run)
(defun ez-op-print (operands operand-types)
(let* ((word-count-and-string (ez-get-zstring-and-length (ez-get-pc)))
(string (cdr word-count-and-string)))
(ez-print string)
(ez-increment-pc (* 2 word-count)))
- t)
+ 'run)
(defun ez-op-new-line (operands operand-types)
(ez-print "\n")
- t)
+ 'run)
(defun ez-op-print-num (operands operand-types)
(let ((s (ez-decode-signed-operand (car operands) (car operand-types))))
(ez-print (number-to-string s)))
- t)
+ 'run)
(defun ez-op-print-char (operands operand-types)
(let ((c (car operands)))
(ez-print (string c)))
- t)
+ 'run)
(defun ez-op-print-obj (operands operand-types)
(let ((obj (car operands)))
(ez-print (ez-get-obj-name obj)))
- t)
+ 'run)
+
+(defvar ez--next-read-args nil)
+(defun ez-op-read (operands operand-types)
+ (let ((baddr1 (car operands))
+ (baddr2 (cadr operands)))
+ (setq ez--next-read-args (list baddr1 baddr2)))
+ 'wait-for-input)
+
+(defun ez-op-read2 (input-string)
+ (let ((baddr1 (car ez--next-read-args))
+ (baddr2 (cadr ez--next-read-args)))
+
+ (dotimes (i (length input-string))
+ (ez-mem-set-byte (+ baddr1 1 i) (downcase (elt input-string i))))
+ (ez-mem-set-byte (+ baddr1 1 (length input-string)) 0)
+
+ ))
;; Execution loop
-(defun ez-run (filename)
+(defun ez-load-and-run (filename)
(ez-load-file filename)
(ez-parse-header)
(setq ez-call-stack (list (ez-make-call-stack-frame ez-start-pc)))
- (while (ez-execute-instr)))
+ (ez-run))
+(defvar ez-machine-state nil
+ "Identifies the current executation state of the Z-machine.")
+
+(defun ez-run ()
+ (setq ez-machine-state 'run)
+ (while (eq ez-machine-state 'run)
+ (setq ez-machine-state (ez-execute-instr))))
;;; Buffer and I/O
;;
-(defun ez-render-prompt ()
- (with-current-buffer "*ez*"
- (let ((update-point (= ez-input-marker (point)))
- (update-window-points (mapcar (lambda (w)
- (list (= (window-point w) ez-input-marker)
- w))
- (get-buffer-window-list nil nil t))))
- (save-excursion
- (set-marker-insertion-type ez-prompt-marker nil)
- (set-marker-insertion-type ez-input-marker t)
- (let ((inhibit-read-only t))
- (delete-region ez-prompt-marker ez-input-marker)
- (goto-char ez-prompt-marker)
- (insert
- ">"
- (propertize " " ; Need this to be separate to mark it as rear-nonsticky
- 'read-only t
- 'rear-nonsticky t)))
- (set-marker-insertion-type ez-input-marker nil))
- (goto-char ez-input-marker))))
-
-(defvar ez-prompt-marker nil
- "Marker for prompt position in buffer.")
-
(defvar ez-input-marker nil
- "Marker for prompt position in buffer.")
+ "Marker for input position in buffer.")
(defun ez-setup-buffer ()
(with-current-buffer (get-buffer-create "*ez*")
+ (ez-mode)
(let ((inhibit-read-only t))
- (delete-region (point-min) (point-max)))
+ (erase-buffer))
(setq-local scroll-conservatively 1)
- (if (markerp ez-prompt-marker)
- (set-marker ez-prompt-marker (point-max))
- (setq ez-prompt-marker (point-max-marker)))
(if (markerp ez-input-marker)
(set-marker ez-input-marker (point-max))
(setq ez-input-marker (point-max-marker)))
- (goto-char (point-max))
- (ez-render-prompt)))
+ (goto-char (point-max))))
(defun ez-print (string)
(with-current-buffer "*ez*"
(save-excursion
- (goto-char ez-prompt-marker)
+ (goto-char ez-input-marker)
(insert-before-markers string))))
+(defun ez-enter ()
+ (interactive)
+ (if (not (eq ez-machine-state 'wait-for-input))
+ (error "Z-machine not ready for input."))
+ (let ((input-string (with-current-buffer "*ez*"
+ (buffer-substring ez-input-marker (point-max)))))
+ (delete-region ez-input-marker (point-max))
+ (ez-print (concat input-string "\n"))
+ (ez-debug-message "\tReceived string \"%s\"" input-string)
+ (ez-op-read2 input-string)
+ (ez-run)))
+
+;; Debugging info
+
+(defun ez-setup-debug-buffer ()
+ (with-current-buffer (get-buffer-create "*ez-debug-trace*")
+ (setq-local buffer-read-only t)
+ (let ((inhibit-read-only t))
+ (erase-buffer)
+ (insert "--- Trace Start ---\n\n"))))
+
+(defun ez-debug-message (&rest strings)
+ (with-current-buffer (get-buffer-create "*ez-debug-trace*")
+ (save-excursion
+ (goto-char (point-max))
+ (let ((inhibit-read-only t))
+ (insert (apply #'format-message strings) "\n")))))
+
+(defun ez-debug-memory ()
+ (interactive)
+ (with-current-buffer (get-buffer-create "*ez-debug-memory*")
+ (setq-local buffer-read-only t)
+ (let ((inhibit-read-only t)
+ (old-point (point)))
+ (hexl-mode-exit)
+ (erase-buffer)
+ (insert ez-memory)
+ (setq-local buffer-undo-list nil)
+ (hexl-mode)
+ (goto-char old-point))))
+
;; Mode
(defvar ez-mode-map
(if (get-buffer "*ez*")
(switch-to-buffer "*ez*")
(switch-to-buffer "*ez*")
- (ez-mode)
(ez-setup-buffer)
- (ez-run zfile))
+ (ez-load-and-run zfile))
"Started EZ.")
(defun ez-debug ()
(interactive)
- (switch-to-buffer "*ez*")
- (ez-mode)
(ez-setup-buffer)
- (ez-run "zork1.z3"))
+ (ez-setup-debug-buffer)
+ (ez-load-and-run "zork1.z3"))
;;; ez.el ends here