Mon 16 Mar 11:39:34 CET 2026

doc/net.md

@@ -0,0 +1,76 @@
+# Networking
+
+## Ports
+
+A port is a bidirectional communication point and connects two nodes via a serial link. A port connecting a link is assigned to a specific direction which is either known in advance (static parameter) or dynamically determined by network controll messages (dynamic paramter). There are cartesian directions like North, South, East, or West, and message flow directions like Up and Down. The up direction is commonly used to propagate consoleoutput or data message to a dedicated information sink node (which can be a n external computer), and the down direction is used for the propagation (and broadcasting) of program code and evnts. 
+
+There are physical and logical port numbers. A logical port can be associated by the message source-sink flow  direction (and a cartesian direction), whereas a physical port is assigned to a specific communication device.
+
+A typical assignment of physical ports to the message flow directions and their cartesian direction is shown below.
+
+| #id  | dx,dy | class  |
+|:--|:--|:--|
+|  0 |  -1,0  | UP  |
+|  1 |   1,0  | DOWN  |
+|  2 |   0,1  | DOWN  |
+
+## Message Types
+
+### Network Control Message (NCM)
+
+This is a message that is used for network initialization and routing (as a prefix message to other message pulling them through the network carrying additional network information).
+
+
+| Message Format | Description |
+|:--|:--|
+| `@rRIXY@`    | Multicast in radius R with ID I and current hop count dX,dY |
+| `@1XYIxy@`   | Unicast to rel. position dX,dY with oroginal dx,dy and ID I |
+| `@dxy@`      | Downward distribution of following message (broadcast) |
+
+Numeric valuea in the NCM are always binary (int8\_t).
+
+### Program
+
+A full program (textual code) is send to a node via the down link (and in default case routed downwards). The VM context (commonly root context) is reset, the program code is compiled, and finally started. The program is compiled directly from the link receiver buffer. After compilation the message slot is freed.
+
+A program part is compiled but not executed (incremental program compiling), enabling the partitioning of programs into smaller parts. A single code line is compiled and executed either in the root context (if idle) or in a separate context (used only for single line code). Single code statements should not block the processing and can be used, e.g., to start the root context (go) after compiling a complete program or to reset a context (new).
+```
+[program code]
+[[program part]]
+]single line[
+
+}new(0)[[[part1]][[part2]][[part3]]]go(0)[
+```
+
+
+## Channel IO
+
+### Sending of messages
+
+A message (including delimiters) is send via the channel output operation using a physical (e.g. LINK0) or virtual link descriptor (e.g., LINKUP, ROUTE). a message routing can append a pre-fix NCM message to control message routing (by the current and other nodes) and to transport additional information like the routing history (x- and y-hops).
+
+```
+# Stdout / console
+! a,b,c   => #abc#
+LINK0 ! #",",'!,a,b,c,'!   => !a,b,c!
+ROUTE ! #",",'!,a,b,c,'!   => !a,b,c!
+ROUTE ! #",",'@,'1,dx,dy,'@,'$,a,b,c,'$
+
+LINKUP ! ...
+LINKDOWN ! ...
+  => @1DD000@ $a,b,c$
+```
+
+### Receiving of Messages
+
+
+```
+proc receiver {
+  # we can only receive $$ messages, %%evnets and program cofe ][ is handled by the VM
+  event ? dx,dy,a,b,c
+}
+# events can only be registered on physical links
+on event("LINK",0) call receiver
+on event("LINK",1) call receiver
+on event("LINK",2) call receiver
+```