New upstream version 1.19.90 upstream/1.19.90

8 files changed, 328 insertions, 110 deletions

diff --git a/shared/n-acd/src/n-acd-bpf-fallback.c b/shared/n-acd/src/n-acd-bpf-fallback.c
index 7270cfd9..3cf4eb06 100644
--- a/shared/n-acd/src/n-acd-bpf-fallback.c
+++ b/shared/n-acd/src/n-acd-bpf-fallback.c
@@ -7,6 +7,7 @@
  * See n-acd-bpf.c for documentation.
  */
 
+#include <c-stdaux.h>
 #include <stddef.h>
 #include "n-acd-private.h"
 
diff --git a/shared/n-acd/src/n-acd-bpf.c b/shared/n-acd/src/n-acd-bpf.c
index 771a28ee..57b29ddf 100644
--- a/shared/n-acd/src/n-acd-bpf.c
+++ b/shared/n-acd/src/n-acd-bpf.c
@@ -12,6 +12,7 @@
  * that have already been removed.
  */
 
+#include <c-stdaux.h>
 #include <errno.h>
 #include <inttypes.h>
 #include <linux/bpf.h>
diff --git a/shared/n-acd/src/n-acd-private.h b/shared/n-acd/src/n-acd-private.h
index 3f207912..4583c018 100644
--- a/shared/n-acd/src/n-acd-private.h
+++ b/shared/n-acd/src/n-acd-private.h
@@ -2,6 +2,7 @@
 
 #include <c-list.h>
 #include <c-rbtree.h>
+#include <c-stdaux.h>
 #include <errno.h>
 #include <inttypes.h>
 #include <netinet/if_ether.h>
@@ -13,9 +14,6 @@
 
 typedef struct NAcdEventNode NAcdEventNode;
 
-#define _cleanup_(_x) __attribute__((__cleanup__(_x)))
-#define _public_ __attribute__((__visibility__("default")))
-
 /* This augments the error-codes with internal ones that are never exposed. */
 enum {
         _N_ACD_INTERNAL = _N_ACD_E_N,
@@ -150,23 +148,7 @@ int n_acd_bpf_compile(int *progfdp, int mapfd, struct ether_addr *mac);
 
 /* inline helpers */
 
-static inline int n_acd_errno(void) {
-        /*
-         * Compilers continuously warn about uninitialized variables since they
-         * cannot deduce that `return -errno;` will always be negative. This
-         * small wrapper makes sure compilers figure that out. Use it as
-         * replacement for `errno` read access. Yes, it generates worse code,
-         * but only marginally and only affects slow-paths.
-         */
-        return abs(errno) ? : EIO;
-}
-
 static inline void n_acd_event_node_freep(NAcdEventNode **node) {
         if (*node)
                 n_acd_event_node_free(*node);
 }
-
-static inline void n_acd_closep(int *fdp) {
-        if (*fdp >= 0)
-                close(*fdp);
-}
diff --git a/shared/n-acd/src/n-acd-probe.c b/shared/n-acd/src/n-acd-probe.c
index d4da0fd5..43dd344c 100644
--- a/shared/n-acd/src/n-acd-probe.c
+++ b/shared/n-acd/src/n-acd-probe.c
@@ -1,9 +1,14 @@
 /*
  * IPv4 Address Conflict Detection
+ *
+ * This file implements the probe object. A probe is basically the
+ * state-machine of a single ACD run. It takes an address to probe for, checks
+ * for conflicts and then defends it once configured.
  */
 
 #include <assert.h>
 #include <c-rbtree.h>
+#include <c-stdaux.h>
 #include <endian.h>
 #include <errno.h>
 #include <inttypes.h>
@@ -19,8 +24,8 @@
 #include "n-acd-private.h"
 
 /*
- * These parameters and timing intervals specified in RFC-5227. The original
- * values are:
+ * These parameters and timing intervals are specified in RFC-5227. The
+ * original values are:
  *
  *     PROBE_NUM                                3
  *     PROBE_WAIT                               1s
@@ -66,10 +71,19 @@
 #define N_ACD_RFC_DEFEND_INTERVAL_NSEC          (UINT64_C(10000000000)) /* 10s */
 
 /**
- * XXX
+ * n_acd_probe_config_new() - create probe configuration
+ * @configp:                    output argument for new probe configuration
+ *
+ * This creates a new probe configuration. It will be returned in @configp to
+ * the caller, which upon return fully owns the object.
+ *
+ * A probe configuration collects parameters for probes. It never validates the
+ * input, but this is left to the consumer of the configuration to do.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
-_public_ int n_acd_probe_config_new(NAcdProbeConfig **configp) {
-        _cleanup_(n_acd_probe_config_freep) NAcdProbeConfig *config = NULL;
+_c_public_ int n_acd_probe_config_new(NAcdProbeConfig **configp) {
+        _c_cleanup_(n_acd_probe_config_freep) NAcdProbeConfig *config = NULL;
 
         config = malloc(sizeof(*config));
         if (!config)
@@ -83,9 +97,15 @@ _public_ int n_acd_probe_config_new(NAcdProbeConfig **configp) {
 }
 
 /**
- * XXX
+ * n_acd_probe_config_free() - destroy probe configuration
+ * @config:                     configuration to operate on, or NULL
+ *
+ * This destroys the probe configuration and all associated objects. If @config
+ * is NULL, this is a no-op.
+ *
+ * Return: NULL is returned.
  */
-_public_ NAcdProbeConfig *n_acd_probe_config_free(NAcdProbeConfig *config) {
+_c_public_ NAcdProbeConfig *n_acd_probe_config_free(NAcdProbeConfig *config) {
         if (!config)
                 return NULL;
 
@@ -95,16 +115,45 @@ _public_ NAcdProbeConfig *n_acd_probe_config_free(NAcdProbeConfig *config) {
 }
 
 /**
- * XXX
+ * n_acd_probe_config_set_ip() - set ip property
+ * @config:                     configuration to operate on
+ * @ip:                         ip to set
+ *
+ * This sets the IP property to the value `ip`. The address is copied into the
+ * configuration object. No validation is performed.
+ *
+ * The IP property selects the IP address that a probe checks for. It is the
+ * caller's responsibility to guarantee the address is valid and can be used.
  */
-_public_ void n_acd_probe_config_set_ip(NAcdProbeConfig *config, struct in_addr ip) {
+_c_public_ void n_acd_probe_config_set_ip(NAcdProbeConfig *config, struct in_addr ip) {
         config->ip = ip;
 }
 
 /**
- * XXX
+ * n_acd_probe_config_set_timeout() - set timeout property
+ * @config:                     configuration to operate on
+ * @msecs:                      timeout to set, in milliseconds
+ *
+ * This sets the timeout to use for a conflict detection probe. The
+ * specification default is provided as `N_ACD_TIMEOUT_RFC5227` and corresponds
+ * to 9 seconds.
+ *
+ * If set to 0, conflict detection is skipped and the address is immediately
+ * advertised and defended.
+ *
+ * Depending on the transport used, the API user should select a suitable
+ * timeout. Since `ACD` only operates on the link layer, timeouts in the
+ * hundreds of milliseconds range should be more than enough for any modern
+ * network. Note that increasing this value directly affects the time it takes
+ * to connect to a network, since an address should not be used unless conflict
+ * detection finishes.
+ *
+ * Using the specification default is **discouraged**. It is way too slow and
+ * not appropriate for modern networks.
+ *
+ * Default value is `N_ACD_TIMEOUT_RFC5227`.
  */
-_public_ void n_acd_probe_config_set_timeout(NAcdProbeConfig *config, uint64_t msecs) {
+_c_public_ void n_acd_probe_config_set_timeout(NAcdProbeConfig *config, uint64_t msecs) {
         config->timeout_msecs = msecs;
 }
 
@@ -214,15 +263,14 @@ static void n_acd_probe_unlink(NAcdProbe *probe) {
          */
         if (n_acd_probe_is_unique(probe)) {
                 r = n_acd_bpf_map_remove(probe->acd->fd_bpf_map, &probe->ip);
-                assert(r >= 0);
-                (void)r;
+                c_assert(r >= 0);
                 --probe->acd->n_bpf_map;
         }
         c_rbnode_unlink(&probe->ip_node);
 }
 
 int n_acd_probe_new(NAcdProbe **probep, NAcd *acd, NAcdProbeConfig *config) {
-        _cleanup_(n_acd_probe_freep) NAcdProbe *probe = NULL;
+        _c_cleanup_(n_acd_probe_freep) NAcdProbe *probe = NULL;
         int r;
 
         if (!config->ip.s_addr)
@@ -286,9 +334,20 @@ int n_acd_probe_new(NAcdProbe **probep, NAcd *acd, NAcdProbeConfig *config) {
 }
 
 /**
- * XXX
+ * n_acd_probe_free() - destroy a probe
+ * @probe:                      probe to operate on, or NULL
+ *
+ * This destroys the probe specified by @probe. All operations are immediately
+ * ceded and all associated objects are released.
+ *
+ * If @probe is NULL, this is a no-op.
+ *
+ * This function will flush all events associated with @probe from the event
+ * queue. That is, no events will be returned for this @probe anymore.
+ *
+ * Return: NULL is returned.
  */
-_public_ NAcdProbe *n_acd_probe_free(NAcdProbe *probe) {
+_c_public_ NAcdProbe *n_acd_probe_free(NAcdProbe *probe) {
         NAcdEventNode *node, *t_node;
 
         if (!probe)
@@ -306,7 +365,7 @@ _public_ NAcdProbe *n_acd_probe_free(NAcdProbe *probe) {
 }
 
 int n_acd_probe_raise(NAcdProbe *probe, NAcdEventNode **nodep, unsigned int event) {
-        _cleanup_(n_acd_event_node_freep) NAcdEventNode *node = NULL;
+        _c_cleanup_(n_acd_event_node_freep) NAcdEventNode *node = NULL;
         int r;
 
         r = n_acd_raise(probe->acd, &node, event);
@@ -327,8 +386,8 @@ int n_acd_probe_raise(NAcdProbe *probe, NAcdEventNode **nodep, unsigned int even
                 node->event.conflict.probe = probe;
                 break;
         default:
-                assert(0);
-                return -EIO;
+                c_assert(0);
+                return -ENOTRECOVERABLE;
         }
 
         c_list_link_tail(&probe->event_list, &node->probe_link);
@@ -451,8 +510,8 @@ int n_acd_probe_handle_timeout(NAcdProbe *probe) {
                  * There are no timeouts in these states. If we trigger one,
                  * something is fishy.
                  */
-                assert(0);
-                return -EIO;
+                c_assert(0);
+                return -ENOTRECOVERABLE;
         }
 
         return 0;
@@ -583,31 +642,47 @@ int n_acd_probe_handle_packet(NAcdProbe *probe, struct ether_arp *packet, bool h
                  * We are not listening for packets in these states. If we receive one,
                  * something is fishy.
                  */
-                assert(0);
-                return -EIO;
+                c_assert(0);
+                return -ENOTRECOVERABLE;
         }
 
         return 0;
 }
 
 /**
- * n_acd_probe_set_userdata - XXX
+ * n_acd_probe_set_userdata - set userdata
+ * @probe:                      probe to operate on
+ * @userdata:                   userdata pointer
+ *
+ * This can be used to set a caller-controlled user-data pointer on @probe. The
+ * value of the pointer is never inspected or used by `n-acd` and is fully
+ * under control of the caller.
+ *
+ * The default value is NULL.
  */
-_public_ void n_acd_probe_set_userdata(NAcdProbe *probe, void *userdata) {
+_c_public_ void n_acd_probe_set_userdata(NAcdProbe *probe, void *userdata) {
         probe->userdata = userdata;
 }
 
 /**
- * n_acd_probe_get_userdata - XXX
+ * n_acd_probe_get_userdata - get userdata
+ * @probe:                      probe to operate on
+ *
+ * This queries the userdata pointer that was previously set through
+ * n_acd_probe_set_userdata().
+ *
+ * The default value is NULL.
+ *
+ * Return: The stored userdata pointer is returned.
  */
-_public_ void n_acd_probe_get_userdata(NAcdProbe *probe, void **userdatap) {
+_c_public_ void n_acd_probe_get_userdata(NAcdProbe *probe, void **userdatap) {
         *userdatap = probe->userdata;
 }
 
 /**
  * n_acd_probe_announce() - announce the configured IP address
- * @probe:      probe object
- * @defend:     defence policy
+ * @probe:                      probe to operate on
+ * @defend:                     defence policy
  *
  * Announce the IP address on the local link, and start defending it according
  * to the given policy, which mut be one of N_ACD_DEFEND_ONCE,
@@ -619,7 +694,7 @@ _public_ void n_acd_probe_get_userdata(NAcdProbe *probe, void **userdatap) {
  * Return: 0 on success, N_ACD_E_INVALID_ARGUMENT in case the defence policy
  *         is invalid, negative error code on failure.
  */
-_public_ int n_acd_probe_announce(NAcdProbe *probe, unsigned int defend) {
+_c_public_ int n_acd_probe_announce(NAcdProbe *probe, unsigned int defend) {
         if (defend >= _N_ACD_DEFEND_N)
                 return N_ACD_E_INVALID_ARGUMENT;
 
diff --git a/shared/n-acd/src/n-acd.c b/shared/n-acd/src/n-acd.c
index def56a21..a0a48c58 100644
--- a/shared/n-acd/src/n-acd.c
+++ b/shared/n-acd/src/n-acd.c
@@ -1,11 +1,56 @@
 /*
  * IPv4 Address Conflict Detection
+ *
+ * This file contains the main context initialization and management functions,
+ * as well as a bunch of utilities used through the n-acd modules.
+ */
+
+/**
+ * DOC: IPv4 Address Conflict Detection
+ *
+ * The `n-acd` project implements the IPv4 Address Conflict Detection protocol
+ * as defined in RFC-5227. The protocol originates in the IPv4 Link Local
+ * Address selection but was later on generalized and resulted in `ACD`. The
+ * idea is to use `ARP` to query a link for an address to see whether it
+ * already exists on the network, as well as defending an address that is in
+ * use on a network interface. Furthermore, `ACD` provides passive diagnostics
+ * for administrators, as it will detect address conflicts automatically, which
+ * then can be logged or shown to a user.
+ *
+ * The main context object of `n-acd` is the `NAcd` structure. It is a passive
+ * ref-counted context object which drives `ACD` probes running on it. A
+ * context is specific to a linux network device and transport. If multiple
+ * network devices are used, then separate `NAcd` contexts must be deployed.
+ *
+ * The `NAcdProbe` object drives a single `ACD` state-machine. A probe is
+ * created on an `NAcd` context by providing an address to probe for. The probe
+ * will then raise notifications whether the address conflict detection found
+ * something, or whether the address is ready to be used. Optionally, the probe
+ * will then enter into passive mode and defend the address as long as it is
+ * kept active.
+ *
+ * Note that the `n-acd` project only implements the networking protocol. It
+ * never queries or modifies network interfaces. It completely relies on the
+ * API user to react to notifications and update network interfaces
+ * respectively. `n-acd` uses an event-mechanism on every context object. All
+ * events raise by any probe or operation on a given context will queue all
+ * events on that context object. The event-queue can then be drained by the
+ * API user. All events are properly asynchronous and designed in a way that no
+ * synchronous reaction to any event is required. That is, the events are
+ * carefully designed to allow forwarding via IPC (or even networks) to a
+ * controller that handles them and specifies how to react. Furthermore, none
+ * of the function calls of `n-acd` require synchronous error handling.
+ * Instead, functions only ever return values on fatal errors. Everything else
+ * is queued as events, thus guaranteeing that synchronous handling of return
+ * values is not required. Exceptions are functions that do not affect internal
+ * state or do not have an associated context object.
  */
 
 #include <assert.h>
 #include <c-list.h>
 #include <c-rbtree.h>
 #include <c-siphash.h>
+#include <c-stdaux.h>
 #include <endian.h>
 #include <errno.h>
 #include <inttypes.h>
@@ -55,7 +100,7 @@ static int n_acd_get_random(unsigned int *random) {
 
         r = clock_gettime(CLOCK_MONOTONIC, &ts);
         if (r < 0)
-                return -n_acd_errno();
+                return -c_errno();
 
         c_siphash_append(&hash, (const uint8_t *)&ts.tv_sec, sizeof(ts.tv_sec));
         c_siphash_append(&hash, (const uint8_t *)&ts.tv_nsec, sizeof(ts.tv_nsec));
@@ -76,19 +121,19 @@ static int n_acd_socket_new(int *fdp, int fd_bpf_prog, NAcdConfig *config) {
 
         s = socket(PF_PACKET, SOCK_DGRAM | SOCK_CLOEXEC | SOCK_NONBLOCK, 0);
         if (s < 0) {
-                r = -n_acd_errno();
+                r = -c_errno();
                 goto error;
         }
 
         if (fd_bpf_prog >= 0) {
                 r = setsockopt(s, SOL_SOCKET, SO_ATTACH_BPF, &fd_bpf_prog, sizeof(fd_bpf_prog));
                 if (r < 0)
-                        return -n_acd_errno();
+                        return -c_errno();
         }
 
         r = bind(s, (struct sockaddr *)&address, sizeof(address));
         if (r < 0) {
-                r = -n_acd_errno();
+                r = -c_errno();
                 goto error;
         }
 
@@ -103,10 +148,21 @@ error:
 }
 
 /**
- * XXX
+ * n_acd_config_new() - create configuration object
+ * @configp:                    output argument for new configuration
+ *
+ * This creates a new configuration object and provides it to the caller. The
+ * object is fully owned by the caller upon function return.
+ *
+ * A configuration object is a passive structure that is used to collect
+ * information that is then passed to a constructor or other function. A
+ * configuration never validates the data, but it is up to the consumer of a
+ * configuration to do that.
+ *
+ * Return: 0 on success, negative error code on failure.
  */
-_public_ int n_acd_config_new(NAcdConfig **configp) {
-        _cleanup_(n_acd_config_freep) NAcdConfig *config = NULL;
+_c_public_ int n_acd_config_new(NAcdConfig **configp) {
+        _c_cleanup_(n_acd_config_freep) NAcdConfig *config = NULL;
 
         config = malloc(sizeof(*config));
         if (!config)
@@ -120,9 +176,15 @@ _public_ int n_acd_config_new(NAcdConfig **configp) {
 }
 
 /**
- * XXX
+ * n_acd_config_free() - destroy configuration object
+ * @config:                     configuration to operate on, or NULL
+ *
+ * This destroys the configuration object @config. If @config is NULL, this is
+ * a no-op.
+ *
+ * Return: NULL is returned.
  */
-_public_ NAcdConfig *n_acd_config_free(NAcdConfig *config) {
+_c_public_ NAcdConfig *n_acd_config_free(NAcdConfig *config) {
         if (!config)
                 return NULL;
 
@@ -132,23 +194,55 @@ _public_ NAcdConfig *n_acd_config_free(NAcdConfig *config) {
 }
 
 /**
- * XXX
+ * n_acd_config_set_ifindex() - set ifindex property
+ * @config:                     configuration to operate on
+ * @ifindex:                    ifindex to set
+ *
+ * This sets the @ifindex property of the configuration object. Any previous
+ * value is overwritten.
+ *
+ * A valid ifindex is a 32bit integer greater than 0. Any other value is
+ * treated as unspecified.
+ *
+ * The ifindex corresponds to the interface index provided by the linux kernel.
+ * It specifies the network device to be used.
  */
-_public_ void n_acd_config_set_ifindex(NAcdConfig *config, int ifindex) {
+_c_public_ void n_acd_config_set_ifindex(NAcdConfig *config, int ifindex) {
         config->ifindex = ifindex;
 }
 
 /**
- * XXX
+ * n_acd_config_set_transport() - set transport property
+ * @config:                     configuration to operate on
+ * @transport:                  transport to set
+ *
+ * This specifies the transport to use. A transport must be one of the
+ * `N_ACD_TRANSPORT_*` identifiers. It selects which transport protocol `n-acd`
+ * will run on.
  */
-_public_ void n_acd_config_set_transport(NAcdConfig *config, unsigned int transport) {
+_c_public_ void n_acd_config_set_transport(NAcdConfig *config, unsigned int transport) {
         config->transport = transport;
 }
 
 /**
- * XXX
+ * n_acd_config_set_mac() - set mac property
+ * @config:                     configuration to operate on
+ * @mac:                        mac to set
+ *
+ * This specifies the hardware address (also referred to as `MAC Address`) to
+ * use. Any hardware address can be specified. It is the caller's
+ * responsibility to make sure the address can actually be used.
+ *
+ * The address in @mac is copied into @config. It does not have to be retained
+ * by the caller.
  */
-_public_ void n_acd_config_set_mac(NAcdConfig *config, const uint8_t *mac, size_t n_mac) {
+_c_public_ void n_acd_config_set_mac(NAcdConfig *config, const uint8_t *mac, size_t n_mac) {
+        /*
+         * We truncate the address at the maximum we support. We still remember
+         * the original length, so any consumer of this configuration can then
+         * complain about an unsupported address length. This allows us to
+         * avoid a memory allocation here and having to return `int`.
+         */
         config->n_mac = n_mac;
         memcpy(config->mac, mac, n_mac > ETH_ALEN ? ETH_ALEN : n_mac);
 }
@@ -179,7 +273,7 @@ NAcdEventNode *n_acd_event_node_free(NAcdEventNode *node) {
 
 int n_acd_ensure_bpf_map_space(NAcd *acd) {
         NAcdProbe *probe;
-        _cleanup_(n_acd_closep) int fd_map = -1, fd_prog = -1;
+        _c_cleanup_(c_closep) int fd_map = -1, fd_prog = -1;
         size_t  max_map;
         int r;
 
@@ -205,7 +299,7 @@ int n_acd_ensure_bpf_map_space(NAcd *acd) {
         if (fd_prog >= 0) {
                 r = setsockopt(acd->fd_socket, SOL_SOCKET, SO_ATTACH_BPF, &fd_prog, sizeof(fd_prog));
                 if (r)
-                        return -n_acd_errno();
+                        return -c_errno();
         }
 
         if (acd->fd_bpf_map >= 0)
@@ -218,16 +312,20 @@ int n_acd_ensure_bpf_map_space(NAcd *acd) {
 
 /**
  * n_acd_new() - create a new ACD context
- * @acdp:       output argument for context
- * @config:     configuration parameters
+ * @acdp:                       output argument for new context object
+ * @config:                     configuration parameters
  *
- * Create a new ACD context and return it in @acdp.
+ * Create a new ACD context and return it in @acdp. The configuration @config
+ * must be initialized by the caller and must specify a valid network
+ * interface, transport mechanism, as well as hardware address compatible with
+ * the selected transport. The configuration is copied into the context. The
+ * @config object thus does not have to be retained by the caller.
  *
- * Return: 0 on success, or a negative error code on failure.
+ * Return: 0 on success, negative error code on failure.
  */
-_public_ int n_acd_new(NAcd **acdp, NAcdConfig *config) {
-        _cleanup_(n_acd_unrefp) NAcd *acd = NULL;
-        _cleanup_(n_acd_closep) int fd_bpf_prog = -1;
+_c_public_ int n_acd_new(NAcd **acdp, NAcdConfig *config) {
+        _c_cleanup_(n_acd_unrefp) NAcd *acd = NULL;
+        _c_cleanup_(c_closep) int fd_bpf_prog = -1;
         int r;
 
         if (config->ifindex <= 0 ||
@@ -250,7 +348,7 @@ _public_ int n_acd_new(NAcd **acdp, NAcdConfig *config) {
 
         acd->fd_epoll = epoll_create1(EPOLL_CLOEXEC);
         if (acd->fd_epoll < 0)
-                return -n_acd_errno();
+                return -c_errno();
 
         r = timer_init(&acd->timer);
         if (r < 0)
@@ -276,7 +374,7 @@ _public_ int n_acd_new(NAcd **acdp, NAcdConfig *config) {
                               .data.u32 = N_ACD_EPOLL_TIMER,
                       });
         if (r < 0)
-                return -n_acd_errno();
+                return -c_errno();
 
         r = epoll_ctl(acd->fd_epoll, EPOLL_CTL_ADD, acd->fd_socket,
                       &(struct epoll_event){
@@ -284,14 +382,14 @@ _public_ int n_acd_new(NAcd **acdp, NAcdConfig *config) {
                               .data.u32 = N_ACD_EPOLL_SOCKET,
                       });
         if (r < 0)
-                return -n_acd_errno();
+                return -c_errno();
 
         *acdp = acd;
         acd = NULL;
         return 0;
 }
 
-static void n_acd_free(NAcd *acd) {
+static void n_acd_free_internal(NAcd *acd) {
         NAcdEventNode *node, *t_node;
 
         if (!acd)
@@ -300,10 +398,10 @@ static void n_acd_free(NAcd *acd) {
         c_list_for_each_entry_safe(node, t_node, &acd->event_list, acd_link)
                 n_acd_event_node_free(node);
 
-        assert(c_rbtree_is_empty(&acd->ip_tree));
+        c_assert(c_rbtree_is_empty(&acd->ip_tree));
 
         if (acd->fd_socket >= 0) {
-                assert(acd->fd_epoll >= 0);
+                c_assert(acd->fd_epoll >= 0);
                 epoll_ctl(acd->fd_epoll, EPOLL_CTL_DEL, acd->fd_socket, NULL);
                 close(acd->fd_socket);
                 acd->fd_socket = -1;
@@ -315,7 +413,7 @@ static void n_acd_free(NAcd *acd) {
         }
 
         if (acd->timer.fd >= 0) {
-                assert(acd->fd_epoll >= 0);
+                c_assert(acd->fd_epoll >= 0);
                 epoll_ctl(acd->fd_epoll, EPOLL_CTL_DEL, acd->timer.fd, NULL);
                 timer_deinit(&acd->timer);
         }
@@ -329,20 +427,32 @@ static void n_acd_free(NAcd *acd) {
 }
 
 /**
- * XXX
+ * n_acd_ref() - acquire reference
+ * @acd:                        context to operate on, or NULL
+ *
+ * This acquires a single reference to the context specified as @acd. If @acd
+ * is NULL, this is a no-op.
+ *
+ * Return: @acd is returned.
  */
-_public_ NAcd *n_acd_ref(NAcd *acd) {
+_c_public_ NAcd *n_acd_ref(NAcd *acd) {
         if (acd)
                 ++acd->n_refs;
         return acd;
 }
 
 /**
- * XXX
+ * n_acd_unref() - release reference
+ * @acd:                        context to operate on, or NULL
+ *
+ * This releases a single reference to the context @acd. If this is the last
+ * reference, the context is torn down and deallocated.
+ *
+ * Return: NULL is returned.
  */
-_public_ NAcd *n_acd_unref(NAcd *acd) {
+_c_public_ NAcd *n_acd_unref(NAcd *acd) {
         if (acd && !--acd->n_refs)
-                n_acd_free(acd);
+                n_acd_free_internal(acd);
         return NULL;
 }
 
@@ -426,7 +536,7 @@ int n_acd_send(NAcd *acd, const struct in_addr *tpa, const struct in_addr *spa)
                  * Random network error. We treat this as fatal and propagate
                  * the error, so it is noticed and can be investigated.
                  */
-                return -n_acd_errno();
+                return -c_errno();
         } else if (l != (ssize_t)sizeof(arp)) {
                 /*
                  * Ugh, the kernel modified the packet. This is unexpected. We
@@ -440,13 +550,22 @@ int n_acd_send(NAcd *acd, const struct in_addr *tpa, const struct in_addr *spa)
 
 /**
  * n_acd_get_fd() - get pollable file descriptor
- * @acd:        ACD context
- * @fdp:        output argument for file descriptor
+ * @acd:                        context object to operate on
+ * @fdp:                        output argument for file descriptor
+ *
+ * This returns the backing file-descriptor of the context object @acd. The
+ * file-descriptor is owned by @acd and valid as long as @acd is. The
+ * file-descriptor never changes, so it can be cached by the caller as long as
+ * they hold a reference to @acd.
+ *
+ * The file-descriptor is internal to the @acd context and should not be
+ * modified by the caller. It is only exposed to allow the caller to poll on
+ * it. Whenever the file-descriptor polls readable, n_acd_dispatch() should be
+ * called.
  *
- * Returns a file descriptor in @fdp. This file descriptor can be polled by
- * the caller to indicate when the ACD context can be dispatched.
+ * Currently, the file-descriptor is an epoll-fd.
  */
-_public_ void n_acd_get_fd(NAcd *acd, int *fdp) {
+_c_public_ void n_acd_get_fd(NAcd *acd, int *fdp) {
         *fdp = acd->fd_epoll;
 }
 
@@ -597,7 +716,7 @@ static int n_acd_dispatch_timer(NAcd *acd, struct epoll_event *event) {
                 if (r <= 0)
                         return r;
 
-                assert(r == TIMER_E_TRIGGERED);
+                c_assert(r == TIMER_E_TRIGGERED);
 
                 /*
                  * A timer triggered, handle all pending timeouts at a given
@@ -710,7 +829,7 @@ static int n_acd_dispatch_socket(NAcd *acd, struct epoll_event *event) {
                          * Something went wrong. Propagate the error-code, so
                          * this can be investigated.
                          */
-                        return -n_acd_errno();
+                        return -c_errno();
                 }
         } else if (n >= (ssize_t)n_batch) {
                 /*
@@ -750,16 +869,34 @@ static int n_acd_dispatch_socket(NAcd *acd, struct epoll_event *event) {
 }
 
 /**
- * XXX
+ * n_acd_dispatch() - dispatch context
+ * @acd:                        context object to operate on
+ *
+ * This dispatches the internal state-machine of all probes and operations
+ * running on the context @acd.
+ *
+ * Any outside effect or event triggered by this dispatcher will be queued on
+ * the event-queue of @acd. Whenever the dispatcher returns, the caller is
+ * required to drain the event-queue via n_acd_pop_event() until it is empty.
+ *
+ * This function dispatches as many events as possible up to a static limit to
+ * prevent stalling execution. If the static limit is reached, this function
+ * will return with N_ACD_E_PREEMPTED, otherwise 0 is returned. In most cases
+ * preemption can be ignored, because level-triggered event notification
+ * handles it automatically. However, in case of edge-triggered event
+ * mechanisms, the caller must make sure to call the dispatcher again.
+ *
+ * Return: 0 on success, N_ACD_E_PREEMPTED on preemption, negative error code
+ *         on failure.
  */
-_public_ int n_acd_dispatch(NAcd *acd) {
+_c_public_ int n_acd_dispatch(NAcd *acd) {
         struct epoll_event events[2];
         int n, i, r = 0;
 
         n = epoll_wait(acd->fd_epoll, events, sizeof(events) / sizeof(*events), 0);
         if (n < 0) {
                 /* Linux never returns EINTR if `timeout == 0'. */
-                return -n_acd_errno();
+                return -c_errno();
         }
 
         acd->preempted = false;
@@ -773,7 +910,7 @@ _public_ int n_acd_dispatch(NAcd *acd) {
                         r = n_acd_dispatch_socket(acd, events + i);
                         break;
                 default:
-                        assert(0);
+                        c_assert(0);
                         r = 0;
                         break;
                 }
@@ -787,8 +924,8 @@ _public_ int n_acd_dispatch(NAcd *acd) {
 
 /**
  * n_acd_pop_event() - get the next pending event
- * @acd:        ACD context
- * @eventp:     output argument for the event
+ * @acd:                        context object to operate on
+ * @eventp:                     output argument for the event
  *
  * Returns a pointer to the next pending event. The event is still owend by
  * the context, and is only valid until the next call to n_acd_pop_event()
@@ -840,7 +977,7 @@ _public_ int n_acd_dispatch(NAcd *acd) {
  *          @eventp and 0 is returned. If an error is returned, @eventp is left
  *          untouched.
  */
-_public_ int n_acd_pop_event(NAcd *acd, NAcdEvent **eventp) {
+_c_public_ int n_acd_pop_event(NAcd *acd, NAcdEvent **eventp) {
         NAcdEventNode *node, *t_node;
 
         c_list_for_each_entry_safe(node, t_node, &acd->event_list, acd_link) {
@@ -859,8 +996,29 @@ _public_ int n_acd_pop_event(NAcd *acd, NAcdEvent **eventp) {
 }
 
 /**
- * XXX
+ * n_acd_probe() - start new probe
+ * @acd:                        context object to operate on
+ * @probep:                     output argument for new probe
+ * @config:                     probe configuration
+ *
+ * This creates a new probe on the context @acd and returns the probe in
+ * @probep. The configuration @config must provide valid probe parameters. At
+ * least a valid IP address must be provided through the configuration.
+ *
+ * This function does not reject duplicate probes for the same address. It is
+ * the caller's decision whether duplicates are allowed or not. But note that
+ * duplicate probes on the same context will not conflict each other. That is,
+ * running a probe for the same address twice on the same context will not
+ * cause them to consider each other a duplicate.
+ *
+ * Probes are rather lightweight objects. They do not create any
+ * file-descriptors or other kernel objects. Probes always re-use the
+ * infrastructure provided by the context object @acd. This allows running many
+ * probes simultaneously without exhausting resources.
+ *
+ * Return: 0 on success, N_ACD_E_INVALID_ARGUMENT on invalid configuration
+ *         parameters, negative error code on failure.
  */
-_public_ int n_acd_probe(NAcd *acd, NAcdProbe **probep, NAcdProbeConfig *config) {
+_c_public_ int n_acd_probe(NAcd *acd, NAcdProbe **probep, NAcdProbeConfig *config) {
         return n_acd_probe_new(probep, acd, config);
 }
diff --git a/shared/n-acd/src/n-acd.h b/shared/n-acd/src/n-acd.h
index 74b0aacb..e2b01270 100644
--- a/shared/n-acd/src/n-acd.h
+++ b/shared/n-acd/src/n-acd.h
@@ -13,7 +13,9 @@ extern "C" {
 #endif
 
 #include <netinet/in.h>
+#include <inttypes.h>
 #include <stdbool.h>
+#include <stdlib.h>
 
 typedef struct NAcd NAcd;
 typedef struct NAcdConfig NAcdConfig;
diff --git a/shared/n-acd/src/util/timer.c b/shared/n-acd/src/util/timer.c
index 07dbf34e..3c9570a1 100644
--- a/shared/n-acd/src/util/timer.c
+++ b/shared/n-acd/src/util/timer.c
@@ -4,6 +4,7 @@
 
 #include <assert.h>
 #include <c-rbtree.h>
+#include <c-stdaux.h>
 #include <errno.h>
 #include <stdlib.h>
 #include <sys/timerfd.h>
@@ -30,7 +31,7 @@ int timer_init(Timer *timer) {
 }
 
 void timer_deinit(Timer *timer) {
-        assert(c_rbtree_is_empty(&timer->tree));
+        c_assert(c_rbtree_is_empty(&timer->tree));
 
         if (timer->fd >= 0) {
                 close(timer->fd);
@@ -43,8 +44,7 @@ void timer_now(Timer *timer, uint64_t *nowp) {
         int r;
 
         r = clock_gettime(timer->clock, &ts);
-        assert(r >= 0);
-        (void)r;
+        c_assert(r >= 0);
 
         *nowp = ts.tv_sec * UINT64_C(1000000000) + ts.tv_nsec;
 }
@@ -60,7 +60,7 @@ void timer_rearm(Timer *timer) {
          */
 
         timeout = c_rbnode_entry(c_rbtree_first(&timer->tree), Timeout, node);
-        assert(!timeout || timeout->timeout);
+        c_assert(!timeout || timeout->timeout);
 
         time = timeout ? timeout->timeout : 0;
 
@@ -74,8 +74,7 @@ void timer_rearm(Timer *timer) {
                                             },
                                     },
                                     NULL);
-                assert(r >= 0);
-                (void)r;
+                c_assert(r >= 0);
 
                 timer->scheduled_timeout = time;
         }
@@ -134,8 +133,7 @@ int timer_pop_timeout(Timer *timer, uint64_t until, Timeout **timeoutp) {
 }
 
 void timeout_schedule(Timeout *timeout, Timer *timer, uint64_t time) {
-
-        assert(time);
+        c_assert(time);
 
         /*
          * In case @timeout was already scheduled, remove it from the
diff --git a/shared/n-acd/src/util/timer.h b/shared/n-acd/src/util/timer.h
index 2acc99e3..d01b2741 100644
--- a/shared/n-acd/src/util/timer.h
+++ b/shared/n-acd/src/util/timer.h
@@ -1,6 +1,7 @@
 #pragma once
 
 #include <c-rbtree.h>
+#include <c-stdaux.h>
 #include <inttypes.h>
 #include <stdlib.h>
 #include <time.h>