ixl: fix the first TX credits update in head writeback mode

[wanpengqian_gmail.com]

Summary

In head writeback mode ixl_isc_txd_credits_update_hwb() returns the
distance from tx_cidx_processed to the head index reported by the
hardware, which is the next descriptor the hardware will process and is
0 after ixl_init_tx_ring(). ixl_init_tx_cidx() initialized
tx_cidx_processed to the end of the ring (ntxd - 1), the value that
ixl_init_tx_rsqs() uses for the report status queue, where it stands
for the last descriptor done. As a result, the first credits update
after every (re)initialization reported one descriptor more than the
hardware had processed.

iflib's own TX path does not notice: DESC_RECLAIMABLE() keeps
isc_tx_nsegments descriptors in hand. iflib_netmap_txsync() uses the
count as it is to advance nr_hwtail, so as soon as a reclaim runs after
the NIC has caught up, nr_hwtail equals nr_hwcur and the netmap TX ring
looks full from then on. With the NIC attached to a VALE switch
(valectl -h) the switch stops forwarding packets to the NIC after a
few packets, while reception keeps working.

Initialize tx_cidx_processed to 0 in head writeback mode. Linux's i40e
reads the same head write-back value and starts from 0 as well:
i40e_setup_tx_descriptors() sets next_to_clean to 0, and
i40e_clean_xdp_tx_irq() (AF_XDP zero-copy) computes the completed
descriptors as i40e_get_head() - next_to_clean.

Signed-off-by: Wanpeng Qian <[e-mail]>
Sponsored by: keelos.dev

Test Plan

Builds on main at f958aa7e7 (2026-10-02), GENERIC amd64.

Run-tested on hardware with 14.5-RELEASE's kernel plus this change (keelOS, a FreeBSD 14.5 based system): Supermicro X11SPW-TF, on-board X722 for 10GBASE-T (0x8086:0x37d2), link at 1 Gbit/s. ixl_init_tx_cidx() and ixl_isc_txd_credits_update_hwb() are identical in main.

Before, hw.ixl.enable_head_writeback=1 (the default): valectl -h vale1:ixl0, two bhyve guests with virtio-net on the switch. The guests receive, but nothing reaches the wire from them after 5, 101 and 107 packets in three runs (dev.ixl.0.pf.txq00.packets stops counting). With a debug print in netmap_bwrap_notify(): 5 slots submitted, the credits updates returned 1 (before the NIC had processed anything), 1, 1, 1 and then 2, so the hw TX kring ended with nr_hwtail == nr_hwcur == 5 and nm_kr_space() of the bwrap's ring stayed 0.

A simpler reproducer without VALE, nmempty.c (below): nmempty ixl0 200 25 2 0 (2 packets per NIOCTXSYNC, a second NIOCTXSYNC 20 ms later, no empty packets) stops with ixl0: TX ring stuck after 2 packets: head 2 cur 2 tail 2 (of 1024); with the change all 200 packets go out and the ring ends with tail == head - 1.

With hw.ixl.enable_head_writeback=0 the same test passes without the change (in that mode only the descriptors at indexes 0 and ntxd/2 enter the report status queue under netmap).

After, in the default mode: the same test passes. A guest reaches the LAN through the port at 938 Mbit/s in both directions; 60 s and 20 min of mixed load (guest to guest and guest to LAN at the same time) run without a stall. A netmap program sending 20 packets on netmap:ixl0 leaves the TX ring fully reclaimed (tail == head - 1). The second port of the same NIC carried the host's own traffic (not netmap) with the patched kernel during these tests.

nmempty.c

/*
 * nmempty IFNAME [COUNT [WAIT [BURST [EMPTY]]]]: sends COUNT packets on IFNAME's
 * first netmap TX ring: 60-byte broadcast frames from the interface's address with
 * ethertype 0x88b5 and, unless EMPTY is 0, every other one an empty packet (one
 * slot of length 0).  BURST (default 1) packets go into the ring before each
 * NIOCTXSYNC; 20 ms later a second NIOCTXSYNC only reclaims.
 * WAIT: seconds to wait after opening the port (link renegotiation, STP).
 * The interface leaves the host stack while this runs.
 *   cc -O2 -o nmempty nmempty.c
 */
#define NETMAP_WITH_LIBS
#include <sys/types.h>
#include <sys/ioctl.h>
#include <sys/socket.h>
#include <net/if.h>
#include <net/if_dl.h>
#include <net/netmap_user.h>
#include <ifaddrs.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int
main(int argc, char **argv)
{
	unsigned char hdr[14] = { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
	    0x02, 0x00, 0x00, 0x00, 0x00, 0x01, 0x88, 0xb5 };
	struct ifaddrs *ifa0, *ifa;
	struct nm_desc *d;
	struct netmap_ring *r;
	struct pollfd pfd;
	char name[64];
	int i, n, wait, stuck, burst, with_empty, empty = 0;

	if (argc < 2) {
		fprintf(stderr, "usage: nmempty IFNAME [COUNT [WAIT [BURST [EMPTY]]]]\n");
		return (1);
	}
	/* the frames' source: the interface's own address */
	if (getifaddrs(&ifa0) == 0) {
		for (ifa = ifa0; ifa != NULL; ifa = ifa->ifa_next)
			if (ifa->ifa_addr != NULL && ifa->ifa_addr->sa_family == AF_LINK &&
			    strcmp(ifa->ifa_name, argv[1]) == 0)
				memcpy(hdr + 6, LLADDR((struct sockaddr_dl *)ifa->ifa_addr), 6);
		freeifaddrs(ifa0);
	}
	n = argc > 2 ? atoi(argv[2]) : 10;
	wait = argc > 3 ? atoi(argv[3]) : 45;
	burst = argc > 4 && atoi(argv[4]) > 0 ? atoi(argv[4]) : 1;
	with_empty = argc > 5 ? atoi(argv[5]) : 1;
	snprintf(name, sizeof(name), "netmap:%s", argv[1]);
	if ((d = nm_open(name, NULL, 0, NULL)) == NULL) {
		perror(name);
		return (1);
	}
	sleep(wait);	/* the NIC reinitialises: the link comes back, a switch port's STP takes 30 s */
	r = NETMAP_TXRING(d->nifp, d->first_tx_ring);
	pfd.fd = d->fd;
	pfd.events = POLLOUT;
	for (i = 0; i < n; i++) {
		struct netmap_slot *slot;

		for (stuck = 0; nm_ring_empty(r); stuck++) {
			if (stuck == 5) {	/* 5 s without a free slot: the ring is not reclaimed */
				printf("%s: TX ring stuck after %d packets: head %u cur %u tail %u (of %u)\n",
				    argv[1], i, r->head, r->cur, r->tail, r->num_slots);
				nm_close(d);
				return (2);
			}
			poll(&pfd, 1, 1000);
			ioctl(d->fd, NIOCTXSYNC, NULL);
		}
		slot = &r->slot[r->head];
		if (with_empty && i % 2 == 1) {
			slot->len = 0;
			empty++;
		} else {
			char *buf = NETMAP_BUF(r, slot->buf_idx);

			memset(buf, 0, 60);
			memcpy(buf, hdr, sizeof(hdr));
			buf[14] = i >> 8;
			buf[15] = i;
			slot->len = 60;
		}
		slot->flags = 0;
		r->head = r->cur = nm_ring_next(r, r->head);
		if ((i + 1) % burst != 0 && i != n - 1)
			continue;
		ioctl(d->fd, NIOCTXSYNC, NULL);
		usleep(20000);
		ioctl(d->fd, NIOCTXSYNC, NULL);	/* nothing new: reclaims what the NIC has sent */
	}
	sleep(1);
	ioctl(d->fd, NIOCTXSYNC, NULL);
	printf("%s: %d packets sent, %d of them empty; TX ring head %u cur %u tail %u (of %u)\n",
	    argv[1], n, empty, r->head, r->cur, r->tail, r->num_slots);
	nm_close(d);
	return (0);
}

[wanpengqian_gmail.com]

Found a simpler way to trigger this, without VALE: a small netmap program (nmempty.c, now in the test plan) that puts 2 packets into the TX ring per NIOCTXSYNC and syncs again 20 ms later.

Without the change: ixl0: TX ring stuck after 2 packets: head 2 cur 2 tail 2 (of 1024).
With it: all 200 packets go out and the ring ends with tail == head - 1.

One packet per txsync does not show it, because the reclaim that follows each packet finds the NIC one descriptor behind.