8 files changed, 265 insertions, 141 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
deleted file mode 100644
index 5cf30050..00000000
--- a/doc/CMakeLists.txt
+++ /dev/null
@@ -1 +0,0 @@
-add_subdirectory(man)
diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt
deleted file mode 100644
index add68d62..00000000
--- a/doc/man/CMakeLists.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-set(MAN_NAMES
-  # Add man page sources here
-  flow_accept.3
-  flow_alloc.3
-  flow_dealloc.3
-  flow_read.3
-  flow_write.3
-  fccntl.3
-  fqueue.3
-  fqueue_create.3
-  fqueue_destroy.3
-  fqueue_next.3
-  fevent.3
-  fset.3
-  fset_create.3
-  fset_destroy.3
-  fset_zero.3
-  fset_add.3
-  fset_del.3
-  fset_has.3
-  ouroboros-glossary.7
-  ouroboros-tutorial.7
-  ouroboros.8
-  irmd.8
-  irm.8
-  )
-
-macro(INSTALL_MAN __mans)
-  foreach (_man ${ARGV})
-    string(REGEX REPLACE "^.+[.]([1-9]).gz" "\\1" _mansect ${_man})
-    install(FILES ${_man} DESTINATION "${CMAKE_INSTALL_MANDIR}/man${_mansect}")
-  endforeach (_man)
-endmacro(INSTALL_MAN __mans)
-
-find_program(GZIP_EXECUTABLE
-  NAMES gzip
-  DOC "Will gzip the man pages")
-
-mark_as_advanced(GZIP_EXECUTABLE)
-
-if (GZIP_EXECUTABLE)
-  foreach (m ${MAN_NAMES})
-    set(md ${CMAKE_CURRENT_BINARY_DIR}/${m}.gz)
-
-    add_custom_command(
-      OUTPUT ${md}
-      COMMAND ${GZIP_EXECUTABLE}
-      ARGS -c ${CMAKE_CURRENT_SOURCE_DIR}/${m} > ${md}
-      COMMENT "Compressing manpage ${m}"
-      VERBATIM)
-
-    set(MAN_FILES ${MAN_FILES} ${md})
-  endforeach ()
-
-  add_custom_target(man ALL DEPENDS ${MAN_FILES})
-
-  INSTALL_MAN(${MAN_FILES})
-endif ()
diff --git a/doc/man/fccntl.3 b/doc/man/fccntl.3
index 767342b9..3dcfc2d9 100644
--- a/doc/man/fccntl.3
+++ b/doc/man/fccntl.3
@@ -76,6 +76,17 @@ buffer. Takes a \fBsize_t \fIqlen\fR * as third argument.
 \fBFLOWGTXQLEN\fR   - get the current number of packets in the transmit
 buffer. Takes a \fBsize_t \fIqlen\fR * as third argument.
 
+\fBFLOWSTXQDLY\fR   - set the target queueing delay for the transmit
+occupancy limiter. Takes a \fBstruct timespec * \fItimeo\fR as third
+argument. A zero delay leaves the ring unlimited, bounded only by its
+slot count. The build-time default is applied when the flow is
+created. The delay must be a normalised, non-negative timespec no
+longer than the maximum the limiter accepts.
+
+\fBFLOWGTXQDLY\fR   - retrieve the current target queueing delay for
+the transmit occupancy limiter. Takes a \fBstruct timespec * \fItimeo\fR
+as third argument.
+
 \fBFRCTSFLAGS\fR    - set the current flow flags. Takes an \fBuint16_t
 \fIflags\fR as third argument. Supported flags are:
 
@@ -101,12 +112,15 @@ On success, \fBfccntl\fR() returns 0.
 \fBfccntl\fR() can return
 
 .B -EINVAL
-An invalid argument was passed.
+An invalid argument was passed. This is also returned when the delay
+passed to FLOWSTXQDLY is negative, is not normalised, or exceeds the
+maximum the transmit occupancy limiter accepts.
 
 .B -EPERM
 Operation not permitted. This is returned when requesting the value of
 a timeout (FLOWGSNDTIMEO or FLOWGRCVTIMEO) when no such timeout was
-set.
+set, or when FLOWSTXQDLY/FLOWGTXQDLY is used on a flow with no
+transmit occupancy ring.
 
 .B -EBADF
 Invalid flow descriptor passed.
diff --git a/doc/man/flow_alloc.3 b/doc/man/flow_alloc.3
index dbe5323c..8a9b5f5b 100644
--- a/doc/man/flow_alloc.3
+++ b/doc/man/flow_alloc.3
@@ -62,10 +62,60 @@ The \fBflow_dealloc\fR() function will release any resources
 associated with the flow. This call may block and keep reliable flows
 active until all packets are acknowledged.
 
-A \fBqosspec_t\fR specifies the following QoS characteristics of a
-flow:
-
-TODO: specify a qosspec_t
+A \fBqosspec_t\fR specifies the QoS characteristics of a flow.
+The fields are:
+
+.TP
+\fBdelay\fR (ms)
+Maximum one-way delay.
+.TP
+\fBbandwidth\fR (bits/s)
+Minimum bandwidth.
+.TP
+\fBavailability\fR
+Class of 9s (e.g. 5 = 99.999%).
+.TP
+\fBloss\fR
+Tolerated packet loss; 0 selects reliable delivery.
+.TP
+\fBber\fR
+Tolerated bit error rate (errors per billion bits); 0 enables an
+end-to-end integrity check (corrupted packets are dropped).
+.TP
+\fBservice\fR
+Framing / reliability class: \fBSVC_RAW\fR (0) disables FRCT;
+\fBSVC_MESSAGE\fR (1) preserves SDU boundaries; \fBSVC_STREAM\fR (2) is
+a byte stream with no SDU boundaries. \fBSVC_STREAM\fR requires
+\fIloss\fR = 0; otherwise
+\fBflow_alloc\fR()/\fBflow_accept\fR() returns \fB-EINVAL\fR.
+.TP
+\fBmax_gap\fR (ms)
+Maximum tolerated inter-packet gap. Packets exceeding the gap
+budget are dropped under the real-time cubes.
+.TP
+\fBtimeout\fR (ms)
+Peer-liveness timeout; 0 disables. Only applies when FRCT is
+enabled (service > 0).
+
+.PP
+The library provides predefined cubes:
+
+.TP
+\fBqos_raw\fR
+No guarantees, no integrity check.
+.TP
+\fBqos_raw_safe\fR
+Best-effort with end-to-end integrity (ber = 0).
+.TP
+\fBqos_rt\fR / \fBqos_rt_safe\fR
+Real-time messages, optimised for latency over reliability;
+\fBqos_rt_safe\fR adds an end-to-end integrity check.
+.TP
+\fBqos_msg\fR
+Reliable, SDU-preserving delivery.
+.TP
+\fBqos_stream\fR
+Reliable byte stream; no SDU boundaries are preserved.
 
 .SH RETURN VALUE
 
@@ -117,13 +167,39 @@ _
 \fBflow_dealloc\fR() & Thread safety & MT-Safe
 .TE
 
+.SH NOTES
+The returned file descriptor is subject to a single-reader and
+single-writer discipline \(em at most one thread may call
+.BR flow_read ()
+(or monitor the fd via
+.BR fevent ())
+and at most one thread may call
+.BR flow_write ()
+concurrently. See
+.BR flow_read (3),
+.BR flow_write (3),
+and
+.BR fevent (3)
+for details.
+.PP
+.BR flow_dealloc ()
+must not be called concurrently with any thread that is inside
+.BR flow_read (),
+.BR flow_write (),
+.BR fevent (),
+or any other Ouroboros library call on the same fd; the result is
+undefined behaviour. Applications must serialise teardown with
+in-flight use, e.g. by signalling worker threads to drop the fd
+before calling
+.BR flow_dealloc ().
+
 .SH TERMINOLOGY
 Please see \fBouroboros-glossary\fR(7).
 
 .SH SEE ALSO
 
-.BR fccntl "(3), " flow_read "(3), " fqueue "(3), " fset "(3), " \
-ouroboros (8)
+.BR fccntl "(3), " fevent "(3), " flow_read "(3), " flow_write "(3), " \
+fqueue "(3), " fset "(3), " ouroboros (8)
 
 .SH COLOPHON
 This page is part of the Ouroboros project, found at
diff --git a/doc/man/flow_read.3 b/doc/man/flow_read.3
index acc1f61e..d4a5e883 100644
--- a/doc/man/flow_read.3
+++ b/doc/man/flow_read.3
@@ -39,8 +39,7 @@ end of the datagram.
 
 On success, \fBflow_write\fR() returns the number of bytes written. On
 failure, a negative value indicating the error will be returned.
-Partial writes needs to be explicitly enabled. Passing a
-NULL pointer for \fIbuf\fR returns 0 with no other effects.
+Passing a NULL pointer for \fIbuf\fR returns 0 with no other effects.
 
 .SH ERRORS
 .B -EINVAL
@@ -62,7 +61,8 @@ The flow has been reported down.
 The flow's peer is unresponsive (flow timed out).
 
 .B -EMSGSIZE
-The buffer was too large to be written.
+The received packet does not fit in the caller's buffer and partial
+reads are disabled (see \fBfccntl\fR(3), \fBFLOWFRNOPART\fR).
 
 .SH ATTRIBUTES
 
@@ -74,11 +74,47 @@ LB|LB|LB
 L|L|L.
 Interface & Attribute & Value
 _
-\fBflow_read\fR() & Thread safety & MT-Safe
+\fBflow_read\fR() & Thread safety & MT-Safe race:fd
 _
-\fBflow_write\fR() & Thread safety & MT-Safe
+\fBflow_write\fR() & Thread safety & MT-Safe race:fd
 .TE
 
+.SH THREAD SAFETY
+Only one thread may call
+.BR flow_read ()
+on a given file descriptor at any time. Partial-read state kept
+across calls assumes a single logical reader; two threads racing
+.BR flow_read ()
+on the same fd is undefined behaviour. Likewise, only one thread
+may call
+.BR flow_write ()
+on a given fd at a time; two writer threads on the same fd is
+undefined behaviour.
+.PP
+Combining a writer thread with a reader thread (one thread calling
+.BR flow_write (),
+another calling
+.BR flow_read ()
+or
+.BR fevent ())
+is permitted and safe. The writer does not need a dedicated reader
+thread \(em when the FRCT send window fills,
+.BR flow_write ()
+drives its own inbound rx draining internally to process incoming
+ACKs and reopen the window, clamped by the caller's
+.BR fccntl (3)
+send-timeout if any.
+.PP
+Monitoring the same fd via
+.BR fevent ()
+from a different thread is well-defined but races: events reported
+by
+.BR fevent ()
+may already have been consumed by the racing
+.BR flow_read (),
+so the second reader may then block. See
+.BR fevent (3).
+
 .SH TERMINOLOGY
 Please see \fBouroboros-glossary\fR(7).
 
diff --git a/doc/man/fqueue.3 b/doc/man/fqueue.3
index 72a0bc25..f2fb8c9f 100644
--- a/doc/man/fqueue.3
+++ b/doc/man/fqueue.3
@@ -116,6 +116,27 @@ _
 \fBfevent\fR() & Thread safety & MT-Safe
 .TE
 
+.SH THREAD SAFETY
+.BR fevent ()
+and
+.BR flow_read ()
+on the same fd from distinct threads is well-defined but races:
+events reported by
+.BR fevent ()
+may already have been consumed by the racing
+.BR flow_read (),
+so the reader may then block. Same shape as
+.BR select (2)
++
+.BR read (2)
+from distinct threads. The intended pattern is that the thread
+invoking
+.BR fevent ()
+is the same thread that calls
+.BR flow_read ()
+on the fds returned by
+.BR fqueue_next ().
+
 .SH TERMINOLOGY
 Please see \fBouroboros-glossary\fR(7).
 
diff --git a/doc/man/ouroboros-tutorial.7 b/doc/man/ouroboros-tutorial.7
index 1fc02a02..54abba5b 100644
--- a/doc/man/ouroboros-tutorial.7
+++ b/doc/man/ouroboros-tutorial.7
@@ -47,37 +47,56 @@ The output should be
 .SH PINGING A SERVER APPLICATION OVER THE LOOPBACK ADAPTER
 
 With a running irmd, let's create an IPC process. For this tutorial,
-we will create and bootstrap an eth-llc IPCP over the loopback
-interface. To observe what's going on, open another terminal
-window. Note that "ipcp bootstrap" will create an IPCP if an IPCP by
-that name does not yet exist (See \fBouroboros\fR(8)).
+we will create a unicast IPCP, attach it to the loopback interface and
+bootstrap it. To observe what's going on, open another terminal
+window.
 
 .RS 4
-$ irm ipcp bootstrap type eth-llc name llc layer llc if lo
+$ irm ipcp create name lan type unicast
 .RE
 
 .RS 4
 ==23918== irmd(II): Created IPCP 23932.
-.br
-==23932== ipcpd/eth-llc(II): Using raw socket device.
-.br
-==23918== irmd(II): Bootstrapped IPCP 23932 in layer llc.
+.RE
+
+An IPCP needs a \fIpoint of attachment\fR: the transmission technology
+it sends and receives on. Attach it to the loopback interface (See
+\fBouroboros\fR(8)).
+
+.RS 4
+$ irm ipcp poa attach name lan eth dev lo
+.RE
+
+.RS 4
+==23918== irmd(II): Attached IPCP 23932.
+.RE
+
+.RS 4
+$ irm ipcp bootstrap name lan layer lan
+.RE
+
+.RS 4
+==23918== irmd(II): Bootstrapped IPCP 23932.
 .RE
 
 Now that we have the IPCP bootstrapped, it can act as a local network
 layer that can provide full connectivity between all processes in the
 system. Let's test it using the oping application. First, let's choose
-a name for the server ("my.oping.server") and register in the llc
+a name for the server ("my.oping.server") and register it in the lan
 layer.
 
 .RS 4
-$ irm reg name my.oping.server layer llc
+$ irm name create my.oping.server
+.br
+$ irm name register my.oping.server layer lan
 .RE
 
 The IRMd should respond with
 
 .RS 4
-==23918== irmd(II): Registered my.oping.server in llc as 716016b1.
+==23918== irmd(II): Created new name: my.oping.server.
+.br
+==23918== irmd(II): Registered my.oping.server with IPCP 23932 as 716016b1.
 .RE
 
 Now start a server of oping in the background (or in a different
diff --git a/doc/man/ouroboros.8 b/doc/man/ouroboros.8
index df328fcc..4c83e5a9 100644
--- a/doc/man/ouroboros.8
+++ b/doc/man/ouroboros.8
@@ -98,10 +98,13 @@ accessed by other processes.
 In order to enroll an IPC process in a layer, some other member will
 have to be reachable over a lower layer. IPCPs that wrap a legacy
 transmission technology are all bootstrapped and thus need not enroll
-as they work directly over a physical connection. Ouroboros currently
-supports IPCPs over shared memory (local), L2 (eth-llc and eth-dix)
-and L3 (udp). The unicast and broadcast layers require connections to
-be established between IPCP components for its operation.
+as they work directly over a physical connection. A unicast or
+broadcast IPCP attaches to a transmission technology itself, as a
+\fIpoint of attachment\fR (PoA); Ouroboros currently supports PoAs on
+L2 (Ethernet) and L3 (UDP/IPv4 and UDP/IPv6), next to IPCPs over
+shared memory (local). The unicast and broadcast layers require
+connections to be established between IPCP components for its
+operation.
 
 \fBConnecting the management components\fR using \fImanagement
 flows\fR allows management information to be sent between IPCPs so
@@ -123,12 +126,6 @@ creates an IPCP process of type \fItype\fR in the system with name
 .PP
 \fBlocal\fR     - create a loopback IPCP.
 .PP
-\fBeth-llc\fR   - create an IPCP that attaches to Ethernet using LLC frames.
-.PP
-\fBeth-dix\fR   - create an IPCP that attaches to Ethernet using DIX frames.
-.PP
-\fBudp\fR       - create an IPCP that attaches to a UDP socket.
-.PP
 \fBunicast\fR   - create a unicast IPCP that uses lower level layers.
 .PP
 \fBbroadcast\fR - create a broadcast IPCP that uses lower level layers.
@@ -159,53 +156,9 @@ Values for [\fIparam\fR] are dependent on \fItype\fR:
 default: SHA3_256.
 .RE
 
-.PP
-\fBeth-llc\fR
-.RS 4
-.PP
-dev \fIinterface\fR specifies the interface to bind the IPCP to.
-.PP
-[hash \fIpolicy\fR] specifies the hash function used for the directory,
-.br
-\fIpolicy\fR: SHA3_224, SHA3_256, SHA3_384, SHA3_512.
-.br
-default: SHA3_256.
-.RE
 
-.PP
-\fBeth-dix\fR
-.RS 4
-.PP
-dev \fIinterface\fR specifies the interface to bind the IPCP to.
-.PP
-[ethertype \fIethertype\fR] specifies the ethertype used for the layer.
-.br
-default: 0xA000.
-.PP
-[hash \fIpolicy\fR] specifies the hash function used for the directory,
-.br
-\fIpolicy\fR: SHA3_224, SHA3_256, SHA3_384, SHA3_512.
-.br
-default: SHA3_256.
-.RE
 
-.PP
-\fBudp\fR
-.RS 4
-.PP
-ip \fIip\fR specifies the local IP address to bind to
-.PP
-[dns \fIdns\fR] specifies an optional DDNS server that will be used for
-the directory.
-.PP
-[port \fIport\fR] specifies a UDP port that is used for sending and
-receiving ouroboros traffic. This must be the same for the entire UDP
-layer. Parallel UDP layers should use different ports. This UDP port
-needs to be forwarded if the server is behind a NAT and wants to
-receive incoming requests.
-.br
-default: 3435
-.RE
+
 
 .PP
 \fBunicast\fR
@@ -275,6 +228,38 @@ default: SHA3_256.
 .RE
 
 .PP
+\fBirm ipcp poa attach\fR name \fIname\fR \fIpoa\fR
+.RS 4
+attaches the IPCP with name \fIname\fR to a point of attachment.
+Repeat to attach more than one. Exactly one \fIpoa\fR is given:
+.PP
+udp \fIip\fR[:\fIport\fR] attaches to a local IPv4 or IPv6 address.
+IPv6 addresses need brackets when a port is given: [\fIip\fR]:\fIport\fR.
+.br
+default port: 3435.
+.PP
+eth dev \fIdevice\fR [ethertype \fIethertype\fR] attaches to an Ethernet
+device.
+.br
+default: 0xA000.
+.RE
+
+.PP
+\fBirm ipcp poa detach\fR name \fIname\fR \fIpoa\fR
+.RS 4
+releases a point of attachment that the IPCP with name \fIname\fR is
+attached to. Flows over it are brought down first. \fIpoa\fR takes the
+same values as for \fBattach\fR.
+.RE
+
+.PP
+\fBirm ipcp poa list\fR name \fIname\fR
+.RS 4
+lists the points of attachment that the IPCP with name \fIname\fR is
+attached to.
+.RE
+
+.PP
 \fBirm ipcp enroll\fR name \fIname\fR [type \fItype\fR] [dst \fIdst\fR] \
 [layer \fIlayer\fR] [\fIautobind\fR]
 .RS 4
@@ -290,6 +275,15 @@ the layer name is a shorthand for the destination name being the same
 as the layer name.
 .PP
 [autobind] will automatically bind this IPCP to its name and the layer name.
+.PP
+[udp \fIip\fR[:\fIport\fR]] enrols over a point of attachment this
+IPCP is attached to, at a peer reachable at this IPv4 or IPv6 address
+or host name.
+.PP
+[eth [dev \fIdevice\fR] [ethertype \fIethertype\fR]] enrols over a
+point of attachment this IPCP is attached to, resolving the peer by a
+name query over Ethernet. [dev \fIdevice\fR] restricts the query to
+one attached device.
 .RE
 
 \fBirm ipcp connect\fR name \fIname\fR component \fIcomponent\fR dst
@@ -298,6 +292,18 @@ as the layer name.
 connects a \fIcomponent\fR (\fBdt\fR or \fBmgmt\fR) of a unicast or
 broadcast IPCP with name \fIname\fR to that component of the
 destination IPCP within the same layer.
+.PP
+[qos \fIqos\fR] specifies the QoS cube for a \fBdt\fR flow: raw, safe,
+rt, rt-safe or msg.
+.PP
+[udp \fIip\fR[:\fIport\fR]] connects over a point of attachment
+this IPCP is attached to, to a peer reachable at this IPv4 or IPv6
+address or host name.
+.PP
+[eth [dev \fIdevice\fR] [ethertype \fIethertype\fR]] connects over a
+point of attachment this IPCP is attached to, resolving the peer by a
+name query over Ethernet. [dev \fIdevice\fR] restricts the query to
+one attached device.
 .RE
 
 \fBirm ipcp disconnect\fR name \fIname\fR component \fIcomponent\fR dst
@@ -370,12 +376,23 @@ not accept future flow allocation requests for \fIname\fR.
 
 .SH IRM NAME COMMANDS
 .PP
-\fBirm name create \fIname\fR \fIlb\fR policy
+\fBirm name create \fIname\fR lb \fIpolicy\fR
+[sencpath \fI/path/to/server/enc.conf\fR]
+[scrtpath \fI/path/to/server/crt.pem\fR]
+[skeypath \fI/path/to/server/key.pem\fR]
+
+[cencpath \fI/path/to/client/enc.conf\fR]
+[ccrtpath \fI/path/to/client/crt.pem\fR]
+[ckeypath \fI/path/to/client/key.pem\fR]
 .RS 4
-Create a name \fIname\fR with a load-balancing policy
+Create a name \fIname\fR with a load-balancing policy and security credentials
 .br
 \fIpolicy\fR: round-robin, spillover
 .br
+\fI/path/to/enc.conf\fR: The path to the server and client encryption configuration.
+\fI/path/to/pem\fR: The path to the server and client certificates and
+private keys, in pem format.
+.br
 .RE
 
 .PP