Re: [PATCH v11 2/9] fwd: Add cache table for ARP/NDP contents

[Stefano Brivio <sbrivio@redhat.com>]

Almost entirely nitpicks here:

On Sat, 27 Sep 2025 15:25:15 -0400
Jon Maloy <jmaloy@redhat.com> wrote:

> We add a cache table to keep track of the contents of the kernel ARP
> and NDP tables. The table is fed from the just introduced netlink based
> neigbour subscription function. The new table eliminates the need for
> explicit netlink calls to find a host's MAC address.
> 
> Signed-off-by: Jon Maloy <jmaloy@redhat.com>
> 
> ---
> v5: - Moved to earlier in series to reduce rebase conflicts
> v6: - Sqashed the hash list commit and the FIFO/LRU queue commit
>     - Removed hash lookup. We now only use linear lookup in a
>       linked list
>     - Eliminated dynamic memory allocation.
>     - Ensured there is only one call to clock_gettime()
>     - Using MAC_ZERO instead of the previously dedicated definitions
> v7: - NOW using MAC_ZERO where needed
>     - I am still using linear back-off for empty cache entries. Even
>       an incoming, flow-creating packet from a local host gives no
>       guarantee that its MAC address is in the ARP table, so we must
>       allow for a few new attempts at first possible occasions. Only
>       after several failed lookups can we conclude that we probably
>       never will succeed. Hence the back-off.
>     - Fixed a bug that David inadvertently made me aware of: I only
>       intended to set the initial expiry value to MAC_CACHE_RENEWAL
>       when an ARP/NDP table lookup was successful.
>     - Improved struct and function description comments.
> v8: - Total re-design of table, adapting to the new, subscription
>       based way of updating it.
> v9: - Catering for MAC address change for an existing host.
> v10: - Changes according to feedback from David Gibson
> ---
>  conf.c    |   1 +
>  fwd.c     | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  fwd.h     |   7 +++
>  netlink.c |   2 +
>  4 files changed, 174 insertions(+)
> 
> diff --git a/conf.c b/conf.c
> index 66b9e63..cfd8590 100644
> --- a/conf.c
> +++ b/conf.c
> @@ -2133,6 +2133,7 @@ void conf(struct ctx *c, int argc, char **argv)
>  		c->udp.fwd_out.mode = fwd_default;
>  
>  	fwd_scan_ports_init(c);
> +	fwd_neigh_table_init();
>  
>  	if (!c->quiet)
>  		conf_print(c);
> diff --git a/fwd.c b/fwd.c
> index 250cf56..2fd6cee 100644
> --- a/fwd.c
> +++ b/fwd.c
> @@ -33,6 +33,170 @@ static in_port_t fwd_ephemeral_max = NUM_PORTS - 1;
>  
>  #define PORT_RANGE_SYSCTL	"/proc/sys/net/ipv4/ip_local_port_range"
>  
> +#define NEIGH_TABLE_SLOTS    1024  /* Must be power of two */
> +#define NEIGH_TABLE_SIZE     (NEIGH_TABLE_SLOTS / 2)
> +
> +/**
> + * neigh_table_entry -  Entry in the ARP/NDP table

It's a struct (it could be a union), so kerneldoc says:

 * struct neigh_table_entry - ...

> + * @next:	Next entry in slot or free list
> + * @addr:	IP address of represented host
> + * @mac:	MAC address of represented host
> + */
> +struct neigh_table_entry {
> +	struct neigh_table_entry *next;
> +	union inany_addr addr;
> +	uint8_t mac[ETH_ALEN];
> +};
> +
> +/**
> + * neigh_table -  Cache of ARP/NDP table contents

Same as above.

> + * @entries:	Entries to be plugged into the hash slots when allocated
> + * @slots:	Hash table slots
> + * @free:	Linked list of unused entries
> + */
> +struct neigh_table {
> +	struct neigh_table_entry entries[NEIGH_TABLE_SIZE];
> +	struct neigh_table_entry *slots[NEIGH_TABLE_SLOTS];
> +	struct neigh_table_entry *free;
> +};
> +
> +static struct neigh_table neigh_table;
> +
> +/**
> + * neigh_table_slot() - Hash key to a number within the table range
> + * @c:		Execution context
> + * @key:	The key to be used for the hash
> + *
> + * Return: The resulting hash value
> + */
> +static inline size_t neigh_table_slot(const struct ctx *c,

See:

  https://www.kernel.org/doc/html/latest/process/coding-style.html#the-inline-disease

> +				      const union inany_addr *key)
> +{
> +	struct siphash_state st = SIPHASH_INIT(c->hash_secret);
> +	uint32_t i;
> +
> +	inany_siphash_feed(&st, key);
> +	i = siphash_final(&st, sizeof(*key), 0);
> +
> +	return ((size_t)i) & (NEIGH_TABLE_SIZE - 1);
> +}
> +
> +/**
> + * fwd_neigh_table_find() - Find a MAC table entry

Strictly speaking, it's a MAC address table -- MAC refers to the access
control itself.

> + * @c:		Execution context
> + * @addr:	Neighbour address to be used as key for the lookup
> + *
> + * Return: The found entry, if any. Otherwise NULL.

In the spirit of the closing lines of:

  https://archives.passt.top/passt-dev/20250915081319.00e72e53@elisabeth/

I'd suggest that in Germanic languages verb participles don't always
behave like adjectives, so you can say "The entry [that was] found",
but "The found entry" is rather awkward. Or go with "matching entry",
gerunds are forgiving.

> + */
> +static struct neigh_table_entry *fwd_neigh_table_find(const struct ctx *c,
> +						      const union inany_addr *addr)
> +{
> +	size_t slot = neigh_table_slot(c, addr);
> +	struct neigh_table_entry *e = neigh_table.slots[slot];
> +
> +	while (e && !inany_equals(&e->addr, addr))
> +		e = e->next;
> +
> +	return e;
> +}
> +
> +/**
> + * fwd_neigh_table_update() - Allocate a neigbour table entry from the free list

neighbour

> + * @c:		Execution context
> + * @addr:	Address used to determine insertion slot and store in entry
> + * @mac:	The MAC address associated with the neighbour address
> + */
> +void fwd_neigh_table_update(const struct ctx *c,
> +			    const union inany_addr *addr, uint8_t *mac)

Cppcheck suggests that:

fwd.c:112:47: style: Parameter 'mac' can be declared as pointer to const [constParameterPointer]
       const union inany_addr *addr, uint8_t *mac)
                                              ^
> +{
> +	struct neigh_table *t = &neigh_table;
> +	struct neigh_table_entry *e;
> +	ssize_t slot;
> +
> +	/* MAC address might change sometimes */
> +	e = fwd_neigh_table_find(c, addr);
> +	if (e) {
> +		memcpy(e->mac, mac, ETH_ALEN);
> +		return;
> +	}
> +
> +	e = t->free;
> +	if (!e)
> +		return;

Log a debug() or trace() message here? We might be staring at something
like this for a while otherwise.

> +	t->free = e->next;
> +
> +	slot = neigh_table_slot(c, addr);
> +	e->next = t->slots[slot];
> +	t->slots[slot] = e;
> +
> +	memcpy(&e->addr, addr, sizeof(*addr));
> +	memcpy(e->mac, mac, ETH_ALEN);
> +}
> +
> +/**
> + * fwd_neigh_table_free() - Remove an entry from a slot and add it to free list
> + * @c:		Execution context
> + * @addr:	Neighbour address used to find the slot for the entry

The neighbour address can be a link-layer / MAC address, or an IP
address.

Perhaps go with "IP address" here, so that it's clear that we free by
IP address, and not by MAC address?

> + */
> +void fwd_neigh_table_free(const struct ctx *c, const union inany_addr *addr)
> +{
> +	ssize_t slot = neigh_table_slot(c, addr);
> +	struct neigh_table *t = &neigh_table;
> +	struct neigh_table_entry *e, **prev;
> +
> +	prev = &t->slots[slot];
> +	e = t->slots[slot];
> +	while (e && !inany_equals(&e->addr, addr)) {
> +		prev = &e->next;
> +		e = e->next;
> +	}
> +	if (!e)
> +		return;
> +
> +	*prev = e->next;
> +	e->next = t->free;
> +	t->free = e;
> +	memset(&e->addr, 0, sizeof(*addr));
> +	memset(e->mac, 0, ETH_ALEN);

Do we care about zeroing them? If we do because we might find those
entries, note that both all-zero MAC address and IP addresses are
valid.

If we can't find those entries linked anywhere, we don't necessarily
care about zeroing them. If it makes you feel better, though, I'd say
keep that.

> +}
> +
> +/**
> + * fwd_neigh_mac_get() - Lookup MAC address in the ARP/NDP table

Look up (the verb, not the noun)

> + * @c:		Execution context
> + * @addr:	Neighbour address used as lookup key
> + * @mac:	Buffer for Ethernet MAC to return, found or default value.
> + *
> + * Return: true if real MAC found, false if not found or if failure

on failure

...by the way, you're ignoring this return value in the rest of the
series. Is it a left-over?

> + */
> +bool fwd_neigh_mac_get(const struct ctx *c, const union inany_addr *addr,
> +		       uint8_t *mac)
> +{
> +	struct neigh_table_entry *e = fwd_neigh_table_find(c, addr);

My pedantic friend reports:

fwd.c:182:28: style: Variable 'e' can be declared as pointer to const [constVariablePointer]
 struct neigh_table_entry *e = fwd_neigh_table_find(c, addr);
                           ^

> +
> +	if (e)
> +		memcpy(mac, e->mac, ETH_ALEN);
> +	else
> +		memcpy(mac, c->our_tap_mac, ETH_ALEN);
> +
> +	return !!e;
> +}
> +
> +/**
> + * fwd_neigh_table_init() - Initialize the neighbor table

neighbour, for consistency, not correctness.

> + */
> +void fwd_neigh_table_init(void)
> +{
> +	struct neigh_table *t = &neigh_table;
> +	struct neigh_table_entry *e;
> +
> +	memset(t, 0, sizeof(*t));
> +	for (int i = 0; i < NEIGH_TABLE_SIZE; i++) {

For consistency: we never declare variables in loop headers.

> +		e = &t->entries[i];
> +		e->next = t->free;
> +		t->free = e;

This, by the way, has the practical effect of making the kernel
allocate memory for the full table, even if it's otherwise unused,
because of those pointers.

It's ~24 kB so I don't really care, and I can't think of a much better
way to organise it, either.

> +	}
> +}
> +
>  /** fwd_probe_ephemeral() - Determine what ports this host considers ephemeral
>   *
>   * Work out what ports the host thinks are emphemeral and record it for later
> diff --git a/fwd.h b/fwd.h
> index 65c7c96..5464349 100644
> --- a/fwd.h
> +++ b/fwd.h
> @@ -56,5 +56,12 @@ uint8_t fwd_nat_from_splice(const struct ctx *c, uint8_t proto,
>  			    const struct flowside *ini, struct flowside *tgt);
>  uint8_t fwd_nat_from_host(const struct ctx *c, uint8_t proto,
>  			  const struct flowside *ini, struct flowside *tgt);
> +void fwd_neigh_table_update(const struct ctx *c,
> +			    const union inany_addr *addr, uint8_t *mac);
> +void fwd_neigh_table_free(const struct ctx *c,
> +			  const union inany_addr *addr);
> +bool fwd_neigh_mac_get(const struct ctx *c, const union inany_addr *addr,
> +		       uint8_t *mac);
> +void fwd_neigh_table_init(void);
>  
>  #endif /* FWD_H */
> diff --git a/netlink.c b/netlink.c
> index 0dc4e9d..da9e1d5 100644
> --- a/netlink.c
> +++ b/netlink.c
> @@ -1189,8 +1189,10 @@ static void nl_neigh_msg_read(const struct ctx *c, struct nlmsghdr *nh)
>  	if (nh->nlmsg_type == RTM_NEWNEIGH &&
>  	    ndm->ndm_state & NUD_VALID) {
>  		trace("neigh table update: %s / %s", ip_str, mac_str);
> +		fwd_neigh_table_update(c, &addr, mac);
>  	} else {
>  		trace("neigh table delete: %s / %s", ip_str, mac_str);
> +		fwd_neigh_table_free(c, &addr);
>  	}
>  }
>