From: ian <ian>
Date: Wed, 21 May 2008 16:48:29 +0000 (+0000)
Subject: wip multiplexer spec
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ijackson/git?a=commitdiff_plain;h=9ebc70edf766f67781cc0fef0ed5a534533ac81a;p=trains.git

wip multiplexer spec
---

diff --git a/hostside/README.commands b/hostside/README.commands
index f249a82..fdb6e6c 100644
--- a/hostside/README.commands
+++ b/hostside/README.commands
@@ -1,27 +1,34 @@
 Protocol over new hostside stdin and to multiplexer:
 
+ U< ?...   means realtime prints that message without any ?
+           when reflected by multiplexer, one of - + &
+           is prepended, as follows
+                  -   result of command by another client
+                  +   result of command by us
+                  &   asynchronous
+
 ======================================================================
 
 POSSIBLY-ASYNCHRONOUS REPORTING OF MESSAGES TO/FROM (MASTER) PIC
 
- U< picioh <timestamp> out <byte> [<byte>...]
+ U< ?picioh <timestamp> out <byte> [<byte>...]
 	In principle, all output to PICs, in raw form, but
 	subject to suppression
 
- U< picioh in junk    <byte> [<byte>...]
- U< picioh in aargh   <byte> [<byte>...]
- U< picioh in hello   <byte> [<byte>...]
- U< picioh in off     <byte> [<byte>...]
- U< picioh in toolong <byte> [<byte>...]
- U< picioh in msg     <byte> [<byte>...]
+ U< ?picioh in junk    <byte> [<byte>...]
+ U< ?picioh in aargh   <byte> [<byte>...]
+ U< ?picioh in hello   <byte> [<byte>...]
+ U< ?picioh in off     <byte> [<byte>...]
+ U< ?picioh in toolong <byte> [<byte>...]
+ U< ?picioh in msg     <byte> [<byte>...]
 
- U< picio out polarity <[<segment>[,...]]>	literal < and > bracket segs
- U< picio out unknown				data printed in assoc'd picioh
+ U< ?picio out polarity <[<segment>[,...]]>	literal < and > bracket segs
+ U< ?picio out unknown				data printed in assoc'd picioh
 
- U< picio in <messagename> [<objectnum>]
- U< picio out <messagename> [<objectnum>]
+ U< ?picio in <messagename> [<objectnum>]
+ U< ?picio out <messagename> [<objectnum>]
 
- U< picio in-info detect 0|1 <segment-name>	decoded `picio in detect[01]'
+ U< ?picio in-info detect 0|1 <segment-name>	decoded `picio in detect[01]'
 
  Suppression (see parse-proto-spec and realtime.c:serial_transmit)
 	nmra data	ping/pong	special in	other out
@@ -31,35 +38,37 @@ POSSIBLY-ASYNCHRONOUS REPORTING OF MESSAGES TO/FROM (MASTER) PIC
   -v2	 suppressed	 cooked		 raw with type	 cooked
   -v3	 both		 both		 raw with type	 both
 
- U< resolving <some message about resolution algorithm>
+ U< ?resolving <some message about resolution algorithm>
 
- U< resolution inexplicable <segment>
- U< resolution mispositioned head|tail <train> <crush-ending-seg> <distance>
- U< resolution movpos-change-failed <segment>/<poscombname>
- U< resolution problems <number-of-problems>
+ U< ?resolution inexplicable <segment>
+ U< ?resolution mispositioned head|tail <train> <crush-ending-seg> <distance>
+ U< ?resolution movpos-change-failed <segment>/<poscombname>
+ U< ?resolution problems <number-of-problems>
 
- U< stastate <state>
+ U< ?stastate <state>
 
- U< warning <type>[ <arguments>] :  <warning message>
- U< warning watchdog : PIC watchdog timer triggered
- U< warning spurious <count> : spurious short circuit (fault) etc.
+ U< ?warning <type>[ <arguments>] :  <warning message>
+ U< ?warning watchdog : PIC watchdog timer triggered
+ U< ?warning spurious <count> : spurious short circuit (fault) etc.
 
- U< train <train> signalling-problem ....
- U< train <train> signalling-problem <problematic-segment> : <message>
+ U< ?train <train> signalling-problem ....
+ U< ?train <train> signalling-problem <problematic-segment> : <message>
 
- U< train <train> forwards|backwards at [-]<segment>:<maxinto>+-<uncertainty>
- U< train <train> has <markchar>[-]<segment>[/<movposcomb>]....
+ U< ?train <train> forwards|backwards at [-]<segment>:<maxinto>+-<uncertainty>
+ U< ?train <train> has <markchar>[-]<segment>[/<movposcomb>]....
        <markchar> is * for det_expected
                      ! for foredetect
                      @ for det_ignore
 
- U< movpos <segment> feat <feat><posn> point|relay
- U< movpos <segment> position <overallposn> moving
- U< movpos <segment> position <overallposn> stable
+ U< ?movpos <segment> feat <feat><posn> point|relay
+ U< ?movpos <segment> position <overallposn> moving
+ U< ?movpos <segment> position <overallposn> stable
             <overallposn> may be ? for unknown
 
- U< debug <context> : <debug message>
- U< info : <informational message>
+ U< ?debug <context> : <debug message>
+ U< ?info : <informational message>
+
+MESSAGES TO SIMULATION LOG
 
  S  picioh in suppressed <byte> [<byte>...]
  S  command-in <command> <args>....
@@ -72,15 +81,68 @@ COMMANDS AND RESPONSES
 
  P> <command> [<arguments>...]
   results in:
- R< executing <command> [<arguments>...]
+ R< ?executing <command> [<arguments>...]
   consequential messages including picio, signalling problems etc.
   then one of these
- R< ack <command> ok
- R< ack <command> <errorcode>
- R< ack <command> <errorcode> [<remaining info>] : <remaining error message>...
- R< ack <command> <errorcode> SignallingPredictedProblem \
+ R< ?ack <command> ok
+ R< ?ack <command> <errorcode>
+ R< ?ack <command> <errorcode> [<remaining info>] : <remaining error msg>...
+ R< ?ack <command> <errorcode> SignallingPredictedProblem \
           <problematic-train> <problematic-segment>|? : <error message>...
 
+    when these come through the multiplexer, everything which is a
+    result of _other_ clients' activities, between <executing> and
+    <ack> inclusive, is prefixed with `-' if they are not due to
+    this client or `+' if they are.
+
+    Some commands have ! at the end of their name
+    - that means they are privileged.
+
+======================================================================
+
+MULTIPLEXER FACILITIES
+
+ M< =  indicates messages to and from the multiplexer about this
+ M> =   specific client connection
+
+ M< =connected
+ M< =permission normal|super
+  or
+ M< =denied
+  and later perhaps
+ M< =failing : <message>
+  otherwise there is no need to quit - just send eof
+
+ M< =select [~]<glob-pattern>...
+    first match wins; ~ discards the message; if nothing matches,
+    all are selected; patterns are matched against message with
+    _ replacing spaces and added to the end; patterns which contain
+    no * have _* appended; default is ~debug; total pattern length
+    is limited for safety and if it is too long it is truncated.
+ M> =select 
+
+ M< =replay [~]<glob-pattern>...
+
+broadcast messages start with %
+
+ C> $replay% <selector>[!] 
+
+ M< %<selector>[!] <stuff>...        <stuff> depends on <selector>
+				      <selector> must be [a-z][-0-9a-z]*
+ M> %<selector>[!] <stuff>...        echoed to all clients
+
+
+MULTIPLEXER-IMPLEMENTED FUNCTIONALITY AFFECTING WHOLE SYSTEM
+
+ P> $<command>[!] <args>...
+ R< ?executing $<command>[!]
+ R< ?ack $<command>[!] ok
+
+ C> $realtime! kill|finish|start|start-manual
+ C> $save!
+
+ C> $reserve
+
 ======================================================================
 
 DIRECT NMRA AND PIC INSTRUCTIONS
@@ -106,8 +168,3 @@ DIRECT NMRA AND PIC INSTRUCTIONS
     !pic =<pic-bytes>    and
     !nmra _<pic-bytes>
  do exactly the same.
-
-
-
-ack ok commandname
-ack errorcode commandname