diff options
Diffstat (limited to 'shared/n-acd')
| -rw-r--r-- | shared/n-acd/src/n-acd-bpf-fallback.c | 1 | ||||
| -rw-r--r-- | shared/n-acd/src/n-acd-bpf.c | 1 | ||||
| -rw-r--r-- | shared/n-acd/src/n-acd-private.h | 20 | ||||
| -rw-r--r-- | shared/n-acd/src/n-acd-probe.c | 135 | ||||
| -rw-r--r-- | shared/n-acd/src/n-acd.c | 264 | ||||
| -rw-r--r-- | shared/n-acd/src/n-acd.h | 2 | ||||
| -rw-r--r-- | shared/n-acd/src/util/timer.c | 14 | ||||
| -rw-r--r-- | shared/n-acd/src/util/timer.h | 1 |
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> |