SRET: a handler answers the way a subroutine does

CALL saves A, B and Data Pointers 0 to 2 and nothing else, which is exactly
why Q and DP3 are how a subroutine hands something back. An interrupt saves
all of it, so a service with an answer had to reach into its own frame and
un-save two fields by hand:

  MVSD.2
  DPUP.2 0d02           ; the saved Q, by an offset it had to know
  STA.2
  RETI

Thirty places in CosmOS did that. Every one knew the frame's layout by
heart, and all thirty would have gone quietly wrong the day the frame
gained a field - the same duplicated fact this project keeps being bitten
by, except duplicated into thirty places AND into the CPU.

SRET is 0x76, in the seat the block split left for it. It is RETI's frame
with RET's rule applied: A, B and DP0 to DP2 come back, the saved Q and DP3
are dropped, and the Interrupt Flag is restored from the frame - only that
bit, so carry survives a service the way it survives a call, and there is
one rule rather than two. RETI stays exactly as it was: a hardware handler
has nothing to say and must leave no trace.

CosmOS is 10,969 bytes against 11,122, and no handler knows a frame offset.

TWO MISTAKES WORTH RECORDING, both mine, both caught by tests.

The first conversion matched STA.2 with a regular expression that did not
allow a trailing comment, so it ran past the end of one handler and into
the next. The second understood the pattern and still got it wrong: the old
frame write carried the answer from A into the saved Q slot, so simply
deleting the write left Q holding whatever it happened to hold. Services
that answer by calling something were fine - Q already had it - and
services that set A directly silently reported success for every failure.
cosmosCwd is what noticed, by saying "cannot go there" about a directory
that was there. Sixteen handlers move the answer into Q now.

Seven MVQA went with it. They copied Q into A so the frame write could
carry it; SRET puts A back, so they moved a value nobody would ever read.

Programs/testPrograms/serviceReturnTest.asm

@@ -26,6 +26,21 @@
 ;   quiet: 7          a service that says nothing leaves Q as it found it
 ;   answer: 42        one that does, does not
 ;   pointer: ABC      and DP3 comes back the same way
+;   sret: 42          and SRET says the same thing without touching the frame
+;   sretptr: ABC      for a pointer too
+;   sretkept: 7       while everything a RET would restore still comes back
+;
+; ---- The frame editing above is what SRET exists to replace ----
+;
+; Everything between MVSD and RETI in "answer" and "pointer" is a routine reaching into its
+; own frame to un-save two fields, using offsets it has to know by heart. Thirty places in
+; CosmOS did that, and all thirty would have gone quietly wrong the day the frame gained a
+; field. SRET is the same instruction sequence as RETI with the saved Q and DP3 stepped
+; over instead of restored, so a handler answers the way a subroutine does and nothing
+; below has to know what a frame looks like.
+;
+; Both are kept here on purpose. RETI is still how a HARDWARE handler says it was never
+; there, and a service that has nothing to say should still use it.
 
 #Include console.asm
 
@@ -59,6 +74,39 @@ start:
   POPD.0
   CALL printString
   CALL newLine
+
+  ; ---- And the same three answers, given with SRET instead ----
+  SETD.0 SretText
+  CALL printString
+  SWI sretAnswer
+  MVQA
+  CALL printByteDecimal
+  CALL newLine
+
+  SETD.0 SretPtrText
+  CALL printString
+  SWI sretPointer
+  PSHD.3
+  POPD.0
+  CALL printString
+  CALL newLine
+
+  ; What SRET must still put back. A handler that trampled A, B and DP0 to DP2 would break
+  ; every caller, which is exactly why RET restores them - so SRET does too, and the number
+  ; printed here is the caller's own, loaded before the service was asked for anything.
+  INIA 0d7
+  RSTB
+  CCF
+  ADD                   ; Q is the caller's seven,
+  SETD.0 SretKeptText   ; and DP0 names the label, BEFORE the service is asked.
+  SWI sretTrample
+  ; Printed after the call rather than before it, which is the whole of the check: the
+  ; handler pointed DP0 somewhere else, so this says "sretkept" only if SRET brought the
+  ; caller's own pointer back. Printing first would have tested nothing at all.
+  CALL printString
+  MVQA
+  CALL printByteDecimal
+  CALL newLine
   HALT
 
 ; Says nothing, so whatever the caller had in Q is still there afterwards.
@@ -88,6 +136,31 @@ pointer:
   STA.1
   RETI
 
+; ---- The same answers, without the frame ----
+;
+; Q and DP3 are set the way any subroutine sets them, and SRET leaves them alone. There is
+; no MVSD, no offset, and nothing here that would need revisiting if the frame changed.
+sretAnswer:
+  INIA 0d42
+  RSTB
+  CCF
+  ADD
+  SRET
+
+sretPointer:
+  SETD.3 Letters
+  SRET
+
+; Sets everything a RET would restore to something wrong, to show that SRET restores it.
+; If any of these came back, the caller's 7 would not.
+sretTrample:
+  INIA 0d99
+  INIB 0d98
+  SETD.0 Letters
+  SETD.1 Letters
+  SETD.2 Letters
+  SRET
+
 #Data
 
 QuietText:
@@ -96,6 +169,12 @@ AnswerText:
 "answer: "
 PointerText:
 "pointer: "
+SretText:
+"sret: "
+SretPtrText:
+"sretptr: "
+SretKeptText:
+"sretkept: "
 Letters:
 "ABC"
 
@@ -105,3 +184,6 @@ Letters:
   quiet    quiet
   answer   answer
   pointer  pointer
+  sretAnswer   sretAnswer
+  sretPointer  sretPointer
+  sretTrample  sretTrample