docs: add documentation for tty: service option

Author: Ollie-Gutierrez

doc/config/service-opts.md

@@ -46,6 +46,7 @@ Other run/task/service options are:
   * `cgroup.NAME[,opts]` or `cgroup:opts` -- see the [Cgroups](cgroups.md) section
   * `env:[-]/path/to/env` -- see the [Service Environment](service-env.md) section
   * `log:...` -- see [Redirecting Output](logging.md#redirecting-output)
+  * `tty:<dev>` -- see [Controlling TTY](tty.md#controlling-tty)
   * `nowarn` -- see [Conditional Loading](services.md#conditional-loading)
   * `notify:...` -- see [Service Synchronization](service-sync.md)
   * `if:...` -- see [Conditional Execution](services.md#conditional-execution)

doc/config/tty.md

@@ -83,4 +83,31 @@ board bringup and system debugging it can come in handy.
 
 One can also use the `service` stanza to start a stand-alone shell:
 
-    service [12345] /bin/sh -l
+    service [12345] /bin/sh -l
+
+Controlling TTY for Services
+----------------------------
+
+The `tty:<dev>` option gives a `run`, `task`, or `service` a controlling
+terminal on the given device.  The device is opened, set as the
+controlling terminal for the session (after `setsid()`), and connected to
+the process's stdin, stdout, and stderr.  A default `TERM` environment
+variable is set based on the device type: `vt102` for serial lines and
+`linux` for virtual terminals.
+
+`<dev>` may be a device node like `/dev/ttyS0`, or the special keyword
+`@console` (see above).  Note that `@console` expands only to the
+first console, not all.
+
+When `tty:` is combined with `log:`, stdout and stderr are redirected
+to the log sink instead of the TTY, but stdin remains connected to the
+TTY device.
+
+> The `tty:<dev>` option is for `run`, `task`, and `service` stanzas only.
+> The `tty` directive itself (for getty/login) has its own syntax, see
+> above.
+
+**Example:**
+
+    service [2345] tty:/dev/ttyS0 /usr/sbin/foo -- Foo on serial console
+    task [S] tty:@console my-setup-script -- Board bringup on console

man/finit.conf.5

@@ -744,6 +744,37 @@ is
 and the default
 .Cm tag
 identity is the basename of the service or run/task command.
+.It Cm tty:\&<dev>
+Give the
+.Cm run , task ,
+or
+.Cm service
+a controlling terminal on
+.Cm <dev> .
+The device is opened, set as the controlling terminal for the session
+(after
+.Fn setsid ) ,
+and connected to stdin, stdout, and stderr.
+A default
+.Ev TERM
+variable is set based on the device type:
+.Cm vt102
+for serial lines and
+.Cm linux
+for virtual terminals.
+.Cm <dev>
+may be a device node like
+.Pa /dev/ttyS0 ,
+or the special keyword
+.Cm @console
+(see TTYs and Consoles above).
+When combined with
+.Cm log: ,
+stdout and stderr are redirected to the log sink instead, but stdin
+remains connected to the TTY device.
+.Bd -unfilled -offset indent
+service [2345] tty:/dev/ttyS0 /usr/sbin/foo -- Foo on serial console
+.Ed
 .El
 .Sh RESCUE MODE
 Finit supports a rescue mode which is activated by the