Gsm migration

docs/services/hal.md

@@ -45,3 +45,70 @@
   - resources
     - bigbox_v1_cm.lua
     - bigbox_ss.lua
+
+## HAl monitor acticheture
+
+```mermaid
+sequenceDiagram
+  participant Config
+  participant Bus
+  participant Core
+  participant Monitors
+  Core->>Core: Init storage driver and cap (for config loading)
+  Config->>Core: Request config blob
+  Core->>StoreCap: Parrot Request
+  StoreCap->>Core: Return blob
+  Core->>Config: Response
+  Config->>Core: Load config
+  Core->>Core: Create monitors
+  Core->>Monitors: op choice over monitors (and bus etc)
+  Monitors->>Core: (UART) use config to build uart driver, return driver in connected event
+  Core->>Core: Init driver and get capabilities
+  Core->>Bus: Broadcast uart device and capability
+```
+
+Monitors are scope protected modules that provide a event based op which returns when a device is either connected or disconnected.
+```lua
+local device_event = perform(uart_monitor:monitor_op())
+if device_event.connected then
+  -- somthing
+else
+  --somthing else
+end
+```
+
+Monitors can scale for complexity, for example the simplest case of a monitor would be uart, where the monitor would recieve a config and build drivers immediately based on that config, the monitor_op would iterate over the drivers and then block forever
+```lua
+function monitor:monitor_op()
+  if self._progress >= #self._drivers then
+    return op.never()
+  end
+  return op.always(
+    -- device connected event goes here
+  )
+end
+```
+
+Some devices are not defined at config time, and appear dynamically. These monitors can return a scope_op which listens to an underlying command to build device events
+```lua
+function monitor.new()
+  return setmetatable({
+    scope = -- child scope to protect HAL from montior based failure
+    cmd = -- monitoring command here
+  }, monitor)
+end
+
+-- A monitor op that is dependant on command line output
+function monitor:monitor_op()
+  return scope:scope_op(function ()
+    return self.cmd:read_line_op():wrap(parser)
+  end)
+end
+```
+
+Both of these examples are fiberless
+
+Monitors may also spawn fibers in the background, although the majority won't need to, to mediate command output between drivers
+
+
+