documentation update [skip ci]

doc/CHANGELOG.md

@@ -30,24 +30,42 @@ The full set of tests is only run for tagged releases.
 ### New features
 ### Changes
 - tools changes
+  - tools/asm-11/lib/push_pop.mac: add push2
   - tools/bin
     - tmuconv: add -t_ru06 and -t_flow
   - tools/tcode
+    - cpu_basics.mac: expanded
     - cpu_details.mac: significantly expanded
     - cpu_mmu.mac: significantly expanded
+  - tools/tbench
+    - /w11a/test_w11a_inst_quick.tcl: use creset option to clr pending traps
+  - tools/tcl
+    - rw11/asm.tcl: asmrun: add creset option (active with ps option)
 - firmware changes
-  - pdp11.vhd: rename, eg srv->ser; drop trap_done; add in_vecysv
+  - pdp11.vhd: rename, eg srv->ser; cpustat_type: drop trap_done, add in_vecysv,
+      treq_tbit,resetcnt; decode_stat_type: op_rti instead of op_rtt
+  - pdp11_decode.vhd: use op_rti instead of op_rtt
   - pdp11_vmbox.vhd: rename some rsv->ser; remove obsolete trap_done
+  - pdp11_sequencer.vhd: tbit logic overhaul; use treq_tbit; cleanups;
+      use resetcnt for 8 cycle RESET wait see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
+  - rtl/sys_gen/w11a/s3board/sys_conf.vhd: disable monitors for timing closure
+  - rtl/sys_gen/w11a/\*/\*.vmfset: drop removed signals
 - general changes
   - rename _gpr to _gr, use 'general registers' not 'general purpose registers'
 ### Bug Fixes
   - rtl/w11a
     - pdp11_sequencer:
-      - BUGFIX: use is_kstackdst1246 also in dstr flow
-      - BUGFIX: correct ysv flow implementation
-      - BUGFIX: correct mmu trap handing in s_idecode
-      - BUGFIX: correct mmu trap vs interrupt priority
-    - pdp11_vmbox: BUGFIX: correct red/yellow zone boundary
+      - BUGFIX: use is_kstackdst1246 also in dstr flow, see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
+      - BUGFIX: correct ysv flow implementation, see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
+      - BUGFIX: correct mmu trap handing in s_idecode, see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
+      - BUGFIX: correct mmu trap vs interrupt priority, see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
+    - pdp11_vmbox: BUGFIX: correct red/yellow zone boundary, see
+      [ECO-035](ECO-035-stklim-tbit-fixes.md)
 
 <!-- --------------------------------------------------------------------- -->
 ---

doc/ECO-035-stklim-tbit-fixes.md

@@ -13,11 +13,11 @@ and T-bit trace trap logic. They caused diagnostic messages in `ekbee1` and
 The 11/70, and also the 11/45, differ from most other PDP-11 models in the
 implementation of the stack protection and trace traps.
 The 11/70 does stack protection checks for write accesses in mode 1,2,4, and 6,
-while for example the J11 only checks for mode 2 and 3.
+while for example the J11 only checks for mode 4 and 5.
 The service order for trap and interrupt processing also differs, on the 11/70
 interrupts have priority over tbit traps, while on the J11 and most other
 models interrupts have lowest priority.
-The SimH simulator uses J11 semantics in both cases, even in 11/70 mode.
+The SimH simulator uses J11 behavior in both cases, even in 11/70 mode.
 In some cases, the w11 implementation followed the SimH implementation, and
 as a result, some J11 behaviors crept into the w11.
 
@@ -42,15 +42,15 @@ as a result, some J11 behaviors crept into the w11.
   - fix: the hack is removed and replaced by proper protection logic.
 - correct mmu trap handing in `s_idecode`
   - issues: in case of register-register operate instructions, like `INC R0`
-      or `ADD R1,R1`, that execute in two cycles, the w11 starts in `s_idecode`
+      or `ADD R1,R2`, that execute in two cycles, the w11 starts in `s_idecode`
       the fetch of the next instruction. That logic checked for interrupts but
       not for MMU traps. MMU traps were therefore only taken at the first
       instruction that was fetch pipelined.
   - fix: correct prefetch logic, suppress prefetch also in case of pending
       traps.
-- correct mmu trap vs interrupt priority
+- correct traps vs interrupt priority
   - issues: the w11 had an incorrect service order, and interrupts had higher
-      precedence than traps.
+      precedence than mmu, ysv and tbit traps.
   - fix: implemented correct 11/70 style precedence, with tbit trap lowest,
       interrupts above tbit traps, and all other traps above interrupts.
 - trace trap logic overhaul

doc/e11_diff_summary.md

@@ -0,0 +1,3 @@
+# Known differences between e11, 11/70, and w11a
+
+_to come_

doc/simh_diff_div_after_v1.md

@@ -0,0 +1,21 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: State of N and Z and registers after a `DIV` abort with `V=1`
+
+The state of the N and Z condition codes is specified as unspecified for
+the `DIV` instruction when V=1 is set after a zero divide or an overflow
+condition.
+See [1979 processor handbook](http://www.bitsavers.org/pdf/dec/pdp11/handbooks/PDP11_Handbook1979.pdf) on page 75.
+
+The 11/70 leaves the N and Z condition codes and the result registers in a
+state depending on the abort point in the microcode state flow. That results
+in sometimes surprising settings.
+
+SimH returns Z=0 and N based on the sign of the full 32-bit result, as can be
+easily determined by xor'ing of the sign bits of dividend and divisor.
+
+xxdp `ekbbf0` test 15 tests the exact 11/70 behavior to verify the
+divide logic and is skipped.
+
+w11 also returns Z=0 and N based on the sign of the full 32-bit result, this
+is documented as [w11 known difference](w11a_diff_70_div_after_v1.md).

doc/simh_diff_instruction_complete.md

@@ -0,0 +1,24 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: The 'instruction completed flag' in `MMR0` is not implemented
+
+All PDP-11 processors with a fully functional MMU (11/45, 11/70, 11/44, and J11)
+support the re-execution of an instruction after an MMU abort.
+`MMR2` holds the virtual address of aborted instruction and `MMR1` holds
+information about register changes. This can be used by a handler to roll back
+the register changes and restart the instruction. This can be used to
+implement demand paging or dynamic extension of stack segments.
+
+The 11/70 and 11/45 are the only PDP-11 processors that also support the
+recovery of an MMU abort of a stack push during trap or interrupt processing.
+To distinguish between an instruction and a trap processing abort the
+`MMR1` has a bit called `instruction completed`. It is will be set to 0
+whenever an instruction is aborted and is 1 after a trap service flow is
+aborted. The `MMR2` contains the vector address in the latter case.
+
+SimH does not support the `MMR0` `instruction completed` flag and the
+associated `MMR2` behavior.
+xxdp `ekbee1` test 67 verifies this behavior and is skipped.
+
+w11 also doesn't support this behavior currently, this is documented as
+[w11 known difference](w11a_diff_70_instruction_complete.md).

doc/simh_diff_mmr1_rts_mtp.md

@@ -1,14 +1,12 @@
-## Known differences between w11a and a SimH 11/70
+## Known differences between SimH, 11/70, and w11a
 
-### SimH: implicit stack pops not recorded in MMR1
+### SimH: implicit stack pops not recorded in `MMR1`
 
 The MMU abort behavior for instructions with implicit stack pops
-(`RTS`, `MTPI`, `MTPD`) differs on SimH from w11 and a real 11/70.
+(`RTS`, `MTPI`, `MTPD`) differs for SimH from a real 11/70 and from w11.
 SimH updates the stack pointer _after_ the stack value has been
 read. If this read is aborted by the MMU, the state is `SP` unchanged
-and `MMR1` zero. w11 and a real 11/70 update `SP` and record that in
+and `MMR1` zero. A real 11/70 and w11 update `SP` and record that in
 `MMR1` before the stack value is accessed and an MMU abort detected.
 In both cases the register change state and the `MMR1` state
 are consistent, so MMU vector 250 handlers will work correctly.
-
-This difference is only detected in test codes.

doc/simh_diff_mmu_nxm_prio.md

@@ -0,0 +1,16 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: MMU aborts have priority over NXM aborts
+
+Let's assume a case where two address errors are present:
+- the MMU rejects the access
+- the MMU translated physical address is located in non-existent memory
+
+In the KB11-C processor, the NXM condition is handled before the MMU condition.
+This leads to the surprising situation that the access is aborted with a
+vector 4 flow rather than a vector 250 flow.
+
+SimH verifies the MMU abort condition first. xxdp `ekbee1` test 122 verifies the 11/70 behavior and is patched.
+
+w11 also doesn't support this behavior, this is documented as
+[w11 known difference](w11a_diff_70_mmu_nxm_prio.md).

doc/simh_diff_mmu_trap_suppression.md

@@ -0,0 +1,13 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: MMU traps not suppressed when MMU register accessed
+
+The 11/70 does not execute an MMU trap and doesn't set A or W bits in `PDR`
+when an MMU register is accessed, thus `MMR0` to `MMR3` and any of the
+`PDR` and `PAR` registers.
+
+SimH doesn't support this behavior.
+xxdp `ekbee1` tests 61 and 63 verify this behavior and are skipped.
+
+w11 also doesn't support this behavior, this is documented as
+[w11 known difference](w11a_diff_70_mmu_trap_suppression.md).

doc/simh_diff_red_psw.md

@@ -0,0 +1,12 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: Red stack zone PSW protection
+
+The 11/70 includes location 177776 in the red stack zone. This is not
+documented in the Processor Handbooks, only mentioned in the Technical
+Manual. It was added to protect the `PSW` in case a further stack push
+is done after an emergency stack was set up, the vector flow of a fatal
+stack errors had concluded, and the handler does a stack push when `SP`
+is still 0.
+
+SimH doesn't support this behavior. W11 does.

doc/simh_diff_service-order.md

@@ -0,0 +1,21 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: trap and interrupt service order has J11 behavior
+
+The 11/70 (and the 11/45) differ from all other PDP-11 models in the order in
+which interrupts and traps are honored after the successful completion of an
+instruction. On the 11/70, interrupts have precedence over T-bit trace traps,
+on all other models interrupts have the lowest priority.
+
+As consequence, `RTI` _can_ be used on an 11/70 to exit from an interrupt driver,
+and exactly one trace trap will happen when an interrupt is honored after
+a traced instruction. On all other models, `RTT` _should_ be used to exit from
+an interrupt driver to prevent a double trace trap, one before the interrupt
+and one after the hander exit.
+
+SimH uses the J11 service order with interrupts having the lowest priority for
+all PDP-11 models.
+
+The w11 implements the proper 11/70 service order.
+
+See also [traced `WAIT`](simh_diff_traced-wait.md).

doc/simh_diff_spl.md

@@ -0,0 +1,16 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: `SPL` doesn't have 11/70 behavior
+
+On an 11/70, the `SPL` instruction in the 11/70 always fetches the next
+instruction regardless of current mode, pending device, or even console
+interrupts. This behavior is used in some xxdp diagnostic codes to prepare
+a situation suitable for interrupt response testing.
+
+SimH does not implement this behavior, `SPL` behaves like all other
+instructions, and interrupts or traps are honored after it completes.
+xxdp `ekbbf0` test 32 depends on the 11/70 behavior and is skipped.
+
+The w11 implements 11/70 behavior for `SPL` in kernel mode only. In supervisor
+or user mode `SPL` is a nop and honors traps and interrupts, see
+[`SPL` on w11](w11a_diff_70_spl_bug.md).

doc/simh_diff_stklim.md

@@ -0,0 +1,29 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: stack limit check uses J11 behavior
+
+The stack limit check is implemented slightly differenly on all models that
+support it. All models check the stack limit only in kernel mode for specifiers
+with `SP` as register and compare the effective address with the stack limit.
+Beyond that, the 11/70 and the J11 logic are very different
+- the 11/70 checks for writes with specifiers with mode 1, 2, 4, or 6, thus for
+  - `clr  (sp)`
+  - `mov  #77,(sp)+`
+  - `mov  #77,(sp)+`
+  - `mov  #77,-(sp)`
+  - `mov  #77,2(sp)`
+- the J11 checks for all accesses with specifiers with mode 4 and 5, thus for
+  - `mov  #77,-(sp)`
+  - `clr @-(sp)`
+  - `tst -(sp)`
+
+The 11/70 logic focuses on that a write was done, while the J11 logic focuses
+on that the `SP` was decremented.
+
+SimH uses the J11 behavior for all models, thus also for an 11/70 simulation.  
+xxdp `ekbbf0` tests 36,40 and 42,
+`ekbee1` tests 122 and 123,
+`eqkce1` tests 41 and 65,
+depend on the 11/70 behavior and are patched or skipped.
+
+The w11 correctly implements the 11/70 behavior.

doc/simh_diff_summary.md

@@ -0,0 +1,22 @@
+# Known differences between SimH, 11/70, and w11a
+
+The SimH simulator focuses on the behavior that is relevant to the normal
+operation of operating systems and user code. Model differences that are
+operation relevant, e.g. in probe routines or model-dependent kernel routines,
+are handled correctly epending on the `set cpu` configuration.
+However, many model variations that do not effect normal operation are not
+modeled for performance reasons. In these cases, the J11 behavior is often used
+for all PDP-11 models, and also when `set cpu 11/70` is configured.
+
+Test codes are sometimes sensitive to those details, so the most relevant
+ones are listed here:
+- [SimH: State of N and Z and registers after a `DIV` abort with `V=1`](simh_diff_div_after_v1.md)
+- [SimH: stack limit check uses J11 behavior](simh_diff_stklim.md)
+- [SimH: Red stack zone PSW protection](simh_diff_red_psw.md)
+- [SimH: trap and interrupt service order has J11 behavior](simh_diff_service-order.md)
+- [SimH: traced `WAIT` has J11 behavior](simh_diff_traced-wait.md)
+- [SimH: `SPL` doesn't have 11/70 behavior](simh_diff_spl.md)
+- [SimH: MMU traps not suppressed when MMU register accessed](simh_diff_mmu_trap_suppression.md)
+- [SimH: implicit stack pops not recorded in `MMR1`](simh_diff_mmr1_rts_mtp.md)
+- [SimH: The 'instruction completed flag' in `MMR0` is not implemented](simh_diff_instruction_complete.md)
+- [SimH: MMU aborts have priority over NXM aborts](simh_diff_mmu_nxm_prio.md)

doc/simh_diff_traced-wait.md

@@ -0,0 +1,20 @@
+## Known differences between SimH, 11/70, and w11a
+
+### SimH: traced `WAIT` has J11 behavior
+
+On an 11/70 (and an 11/45) a traced `WAIT` will wait until an interrupt happens
+and finish without raising a trace trap because the interrupt has higher
+service precedence. The trace trap related to the `WAIT` will happen when the
+interrupt driver exits with an `RTI`.
+See also [trap and interrupt service order](simh_diff_service-order.md).
+
+On a J11 and other PDP-11 models, a traced `WAIT` falls through and raises a
+trace trap immediately. This is consistent with trace traps having higher
+precedence in those models.
+
+SimH uses the J11 service order with interrupts having the lowest priority for
+all PDP-11 models, and consequently, a traced `WAIT` falls through and raises
+a trace trap immediately.
+xxdp `ekbbf0` test 63 verifies the 11/70 behavior and is skipped.
+
+The w11 implements the proper 11/70 service order and `WAIT` behavior.

doc/w11a_diff_70_jsr_sp.md

@@ -29,6 +29,6 @@ EK-KB11C-TM-001_1170procMan.pdf clearly decribes the 11/70 behavior as
 >  JSR.20: decrements SP by 2, new value is stored inb the SP and the DR for  
 >  use in the external data transfer started on JSR.30
 
-`jsr sp` is never used due to its bizarre semantics. The matching `rts sp`
+`jsr sp` is never used due to its bizarre behavior. The matching `rts sp`
 results in a useless `sp` too. Given that, this is considered an
 acceptable deviation from 11/70 behavior.

doc/w11a_diff_70_mmu_trap_suppression.md

@@ -6,7 +6,7 @@ The 11/70 does not execute an MMU trap and doesn't set A or W bits in `PDR`
 when an MMU register is accessed, thus `MMR0` to `MMR3` and any of the
 `PDR` and `PAR` registers.
 
-This causes test 061 of `ekbee1` to fail.
+This causes `ekbee1` tests 61 and 63 to fail.
 
 The w11 doesn't implement this trap suppression (neither does SimH or e11).
 

doc/w11a_diff_70_spl_bug.md

@@ -2,7 +2,7 @@
 
 ### Instruction fetch after `SPL`
 
-The `SPL` instruction in the 11/70 always fetched the next instruction
+The `SPL` instruction in the 11/70 always fetches the next instruction
 regardless of current mode, pending device, or even console interrupts.
 This is known as the infamous _SPL bug_, see
   - https://minnie.tuhs.org/pipermail/tuhs/2006-September/002692.html
@@ -13,7 +13,7 @@ This is known as the infamous _SPL bug_, see
   - https://minnie.tuhs.org/pipermail/tuhs/2006-October/002695.html
   - https://minnie.tuhs.org/pipermail/tuhs/2006-October/002702.html
 
-In the w11a, the `SPL` has 11/70 semantics in kernel mode, thus no 
+In the w11a, the `SPL` has 11/70 behavior in kernel mode, thus no
 traps or interrupts, the instruction after the `SPL` is unconditionally
 executed.
 But in supervisor and user mode `SPL` really acts as `NOOP`, so traps and
@@ -24,7 +24,7 @@ interrupts are taken as for all other instructions.
 Drivers most likely do not depend on this specific `SPL` behavior.
 It is not mentioned in Processor or Architecture Handbooks, only in
 the 11/70 Technical Manual.
-But some `xxdp` test either explicitly check this, like `ekbbf0` test 032,
+But some `xxdp` tests either explicitly check this, like `ekbbf0` test 032,
 or use it to set up an _instruction under test_, like `ekbbf0` tests 035, 047.
 So getting the kernel mode `SPL` behavior right is important for
 passing `ekbbf0`.

doc/w11a_known_differences.md

@@ -25,6 +25,11 @@ the _PDP-11 Family Differences Table_ in
 - [PDP-11 MICRO/PDP-11 Handbook 1983-84](http://www.bitsavers.org/pdf/dec/pdp11/handbooks/EB-24944-18_Micro_PDP-11_Handbook_1983-84.pdf) Appendix G p387
 - and also [PDP-11 family differences appendix](https://gunkies.org/wiki/PDP-11_family_differences_appendix)
 
+Also helpful are the differences sections in the manuals of for processors
+- [T-11 User's Guide 1982](http://www.bitsavers.org/pdf/dec/pdp11/t11/T11_UsersMan.pdf) Appendix B p221
+- [J-11 Programmer's Reference Rev 2.04 1982](http://www.bitsavers.org/pdf/dec/pdp11/j11/J-11_Programmers_Reference_Jan82.pdf) Section 11.0 p37 (focus on registers and instructions)
+- [KD11-E (11/34) Central Processor Manual](http://www.bitsavers.org/pdf/dec/pdp11/1134/EK-KD11E-TM-001_KD11-E_Central_Processor_Maintenance_Manual_Dec76.pdf) Table 2-8 p41
+
 ### Differences in unspecified behavior between w11a and KB11-C (11/70)
 - [State of N and Z and registers after a `DIV` abort with `V=1`](w11a_diff_70_div_after_v1.md)
 
@@ -47,10 +52,11 @@ this is considered as an acceptable implementation difference.
   **--> a 'watch dog' mechanism will be added in a future version which
   suspends the CPU when the server doesn't respond fast enough.**
 
-### Known differences between w11a and a SimH 11/70
-The SimH emulator models only behavior what is relevant for the normal
-operation of operating systems and user code. Many details which do not
-have impact on normal operation are not modeled for performance reasons.
-Test codes are sometimes sensitive to those details, that's why the most
-relevant are listed here.
-- [SimH: implicit stack pops not recorded in MMR1](w11a_diff_simh_mmr1_rts_mtp.md)
+### Known differences between Simh, e11, a real 11/70, and w11a
+The Simh and e11 simulators do not model some 11/70 details that have no
+effect on normal operation for performance reasons. Test codes, like xxdp
+diagostic programs from DEC or the tcodes of the w11 verification suite are
+sometimes sensitive to those details, so the most relevant ones are
+listed under
+- [Known differences between SimH, 11/70, and w11a](simh_diff_summary.md)
+- [Known differences between e11, 11/70, and w11a](e11_diff_summary.md)