9 files changed, 228 insertions, 132 deletions
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 87e23078..767342b9 100644
--- a/doc/man/fccntl.3
+++ b/doc/man/fccntl.3
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH FCCNTL 3 2018-10-04 Ouroboros "Ouroboros Programmer's Manual"
 
@@ -40,8 +40,8 @@ disables the timeout.
 \fBFLOWGQOSSPEC\fR  - retrieve the current QoS specification of the
 flow. Takes a \fBqosspec_t * \fIqs\fR as third argument.
 
-\fBFLOWSFLAGS\fR    - set flow flags. Takes flow flags as third
-argument. Supported flags are:
+\fBFLOWSFLAGS\fR - set flow flags. Takes flow \fBuint32_t\fR
+\fIflags\fR as third argument. Supported flags are:
 
 .RS 8
 \fIFLOWFRDONLY\fR   - set flow to read-only.
@@ -67,25 +67,30 @@ no partial writes).
 
 .RE
 
-\fBFLOWGFLAGS\fR    - get the current flow flags. Takes an \fBuint32_t
+\fBFLOWGFLAGS\fR    - get the current flow flags. Takes an \fBuint32_t *
 \fIflags\fR as third argument.
 
 \fBFLOWGRXQLEN\fR   - get the current number of packets in the receive
-buffer. Takes a \fBsize_t \fIqlen\fR as third argument.
+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.
+buffer. Takes a \fBsize_t \fIqlen\fR * as third argument.
 
-\fBFRCTGFLAGS\fR    - get the current flow flags. Takes an \fBuint16_t
+\fBFRCTSFLAGS\fR    - set the current flow flags. Takes an \fBuint16_t
 \fIflags\fR as third argument. Supported flags are:
 
 .RS 8
-\fIFRCTFRESCNTRL\fR - resource control enabled.
+\fIFRCTFRESCNTL\fR - resource control enabled.
+
+\fIFRCTFRTX\fR      - retransmission enabled. Cannot be modified and will
+be ignored on set.
 
-\fIFRCTFRTX\fR      - retransmission enabled.
+\fIFRCTFLINGER\fR   - finish connection on flow deallocation.
 
 .RE
 
+\fBFRCTGFLAGS\fR    - get the current flow flags. Takes an \fBuint16_t *
+\fIflags\fR as third argument.
 
 .SH RETURN VALUE
 
diff --git a/doc/man/flow_alloc.3 b/doc/man/flow_alloc.3
index 1dfc34fe..8a9b5f5b 100644
--- a/doc/man/flow_alloc.3
+++ b/doc/man/flow_alloc.3
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH FLOW_ALLOC 3 2018-10-05 Ouroboros "Ouroboros Programmer's Manual"
 
@@ -59,12 +59,63 @@ The \fBflow_join\fR() function allows applications to join a broadcast
 flow provided by a broadcast layer. The dst is the layer name.
 
 The \fBflow_dealloc\fR() function will release any resources
-associated with the flow.
-
-A \fBqosspec_t\fR specifies the following QoS characteristics of a
-flow:
-
-TODO: specify a qosspec_t
+associated with the flow. This call may block and keep reliable flows
+active until all packets are acknowledged.
+
+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
 
@@ -116,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 1a6c8eaf..d4a5e883 100644
--- a/doc/man/flow_read.3
+++ b/doc/man/flow_read.3
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH FLOW_READ 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual"
 
@@ -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
@@ -58,8 +57,12 @@ The flow was not allocated.
 .B -EFLOWDOWN
 The flow has been reported down.
 
+.B -EFLOWPEER
+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
 
@@ -71,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 85e12518..f2fb8c9f 100644
--- a/doc/man/fqueue.3
+++ b/doc/man/fqueue.3
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH FQUEUE 3 2017-08-29 Ouroboros "Ouroboros Programmer's Manual"
 
@@ -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/fset.3 b/doc/man/fset.3
index 6d1da6c7..87a7dc87 100644
--- a/doc/man/fset.3
+++ b/doc/man/fset.3
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH FSET 3 2017-04-10 Ouroboros "Ouroboros Programmer's Manual"
 
diff --git a/doc/man/ouroboros-glossary.7 b/doc/man/ouroboros-glossary.7
index 65af7a53..1f7ad882 100644
--- a/doc/man/ouroboros-glossary.7
+++ b/doc/man/ouroboros-glossary.7
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH OUROBOROS-GLOSSARY 7 2017-12-02 Ouroboros "Ouroboros User Manual"
 
diff --git a/doc/man/ouroboros-tutorial.7 b/doc/man/ouroboros-tutorial.7
index 416bf72d..1fc02a02 100644
--- a/doc/man/ouroboros-tutorial.7
+++ b/doc/man/ouroboros-tutorial.7
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH OUROBOROS-TUTORIAL 7 2018-10-05 Ouroboros "Ouroboros User Manual"
 
diff --git a/doc/man/ouroboros.8 b/doc/man/ouroboros.8
index adb652bf..759b1433 100644
--- a/doc/man/ouroboros.8
+++ b/doc/man/ouroboros.8
@@ -1,6 +1,6 @@
-.\" Ouroboros man pages CC-BY 2017 - 2020
-.\" Dimitri Staessens <dimitri.staessens@ugent.be>
-.\" Sander Vrijders <sander.vrijders@ugent.be>
+.\" Ouroboros man pages CC-BY 2017 - 2024
+.\" Dimitri Staessens <dimitri@ouroboros.rocks>
+.\" Sander Vrijders <sander@ouroboros.rocks>
 
 .TH OUROBOROS 8 2020-11-29 Ouroboros "Ouroboros User Manual"
 
@@ -99,10 +99,9 @@ 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), L1 (raptor, experimental),
-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.
+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.
 
 \fBConnecting the management components\fR using \fImanagement
 flows\fR allows management information to be sent between IPCPs so
@@ -124,13 +123,13 @@ creates an IPCP process of type \fItype\fR in the system with name
 .PP
 \fBlocal\fR     - create a loopback IPCP.
 .PP
-\fBraptor\fR    - create an IPCP that attaches to a raptor NetFPGA device.
-.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.
+\fBudp4\fR       - create an IPCP that attaches to a UDP/IPv4 socket.
+.PP
+\fBudp6\fR       - create an IPCP that attaches to a UDP/IPv6 socket.
 .PP
 \fBunicast\fR   - create a unicast IPCP that uses lower level layers.
 .PP
@@ -162,16 +161,6 @@ Values for [\fIparam\fR] are dependent on \fItype\fR:
 default: SHA3_256.
 .RE
 
-\fBraptor\fR
-.RS 4
-.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-llc\fR
 .RS 4
@@ -203,23 +192,35 @@ default: SHA3_256.
 .RE
 
 .PP
-\fBudp\fR
+\fBudp4\fR
 .RS 4
 .PP
-ip \fIip\fR specifies the local IP address to bind to
+ip \fIip\fR specifies the local IPv4 address to bind to
 .PP
-[dns \fdns\fR] specifies an optional DDNS server that will be used for
+[dns \fIdns\fR] specifies an optional DDNS server that will be used for
 the directory.
 .PP
-[cport \fcport\fR] specifies a client UDP port that will be used for
-sending packets.
+[port \fIport\fR] specifies a UDP port that is used for sending and
+receiving ouroboros traffic. This must be the same for the entire UDP4
+layer. Parallel UDP4 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: A random UDP port in the ephemeral range
+default: 3435
+.RE
+
+.PP
+\fBudp6\fR
+.RS 4
 .PP
-[sport \fsport\fR] specifies a server UDP port that is used for
-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.
+ip \fIip\fR specifies the local IPv6 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 UDP6
+layer. Parallel UDP6 layers should use different ports.
 .br
 default: 3435
 .RE
@@ -387,12 +388,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