ethtool: add RSS and ring configuration over netlink

[aarcamp]

Description

Add generic netlink support for reading and updating ring parameters, including TCP header/data split and its threshold. Add RSS get and partial set support for existing contexts so callers can safely update the indirection table without disturbing the hash key or function.

Unit tests cover attribute encoding, decoding, malformed replies, optional update semantics, and netlink attribute size limits.

These changes will help Cilium take advantage of the zero-copy networking features added in Linux 7.1—see the upstream queue-leasing merge.

Hardware validation: RSS and TCP header/data split

The RSS and ring-parameter implementations in this branch were tested on Aquantia Atlantic and Intel ICE hardware using Ubuntu's Linux 7.0 HWE kernel.

Environment

• Host OS: Ubuntu 24.04.3 LTS
• Kernel: 7.0.0-28-generic
• Architecture: x86_64
• Go toolchain: go1.25.0 linux/amd64

RSS device:

• Interface: eno2
• Device: Aquantia AQC113 NBase-T/Antigua 10G (1d6a:04c0, revision 03)
• Driver: atlantic, kernel version 7.0.0-28-generic
• Firmware: 1.5.39
• PCI address: 0000:03:00.0
• Active RX queues: 8
• Main RSS context: 0
• RSS indirection table: 64 entries
• RSS hash key: 40 bytes
• RSS hash function: Toeplitz (0x1)
• RSS input transformation: none (0x0)

Header-split device:

• Interface: enp129s0f1np1
• Driver: ice, kernel version 7.0.0-28-generic
• Active RX queues: 6
• RX ring size: 2048
• TX ring size: 256
• Initial TCP data-split mode: disabled

The standalone sources are attached together as netlink-ethtool-rss-rings-hardware-tests.tgz:

• netlink-ethtool-rss-hardware-test.go
• netlink-ethtool-header-split-hardware-test.go

Build and execution

cd "$test_dir"
/usr/local/go1.25/bin/go build \
    -o "$test_dir/rss-hw-amd64" \
    /tmp/netlink-ethtool-rss-hardware-test.go
/usr/local/go1.25/bin/go build \
    -o "$test_dir/header-split-hw-amd64" \
    /tmp/netlink-ethtool-header-split-hardware-test.go

sudo "$test_dir/rss-hw-amd64" \
    -mode snapshot -device eno2 -state "$state_file"
sudo "$test_dir/rss-hw-amd64" \
    -mode test -device eno2 -state "$state_file"
sudo "$test_dir/rss-hw-amd64" \
    -mode verify -device eno2 -state "$state_file"

sudo "$test_dir/header-split-hw-amd64" \
    -device enp129s0f1np1

RSS indirection-table validation: Atlantic

The RSS program:

1. Calls NetDevRSSGet for the main RSS context and independently reads the same state using the legacy ETHTOOL_GRSSH ioctl.
2. Checks that both APIs report the same context, hash function, indirection table, hash key, and input transformation.
3. Swaps two indirection-table entries that map to different queues.
4. Calls NetDevRSSSet with the modified table.
5. Reads the complete configuration through generic netlink and the ioctl and checks that both match the requested state.
6. Restores the original table with NetDevRSSSet and checks through both read paths that the complete original configuration is restored.

It checks that the device and interface index still match the saved state, refuses to continue if the configuration changes unexpectedly, performs deferred best-effort restoration if a case fails, and exits nonzero on any failed invariant.

The original 64-entry table mapped entries to queues 0 through 7 in a repeating pattern. The program swapped entry 63 from queue 7 with entry 60 from queue 4, then restored both entries:

State	table[60]	table[63]	RSS state SHA-256	Generic netlink/ioctl readback
Original	4	7	17a3ddcb68d0e9fc1ab26f2c2cb9d6b58f6ae166d985d70996505f9a90cc19c2	Match
Programmed	7	4	5eb74a4c7001945251acaf941163cde5aed4256e9413a3115bc4fdb0d974840c	Match
Restored	4	7	17a3ddcb68d0e9fc1ab26f2c2cb9d6b58f6ae166d985d70996505f9a90cc19c2	Match

The digest covers the context, hash function, input transformation, complete 64-entry table, and hash key. Its change confirms that the requested table was programmed; returning to the original digest confirms exact restoration.

rss.change=swap table[63]=7 with table[60]=4
programmed.netlink_ioctl_match=PASS
rss.program=PASS
restore.method=netlink
restored.netlink_ioctl_match=PASS
rss.restore=PASS
mode=test overall=PASS
verify.netlink_ioctl_match=PASS
mode=verify overall=PASS

TCP header/data-split validation: Intel ICE

The header-split program:

1. Snapshots the complete ring parameters with NetDevRingsGet and the main RSS context with NetDevRSSGet.
2. Changes TCPDataSplit from disabled to enabled using a partial NetDevRingsSet update.
3. Reads both configurations back and checks that TCP data split is enabled while the complete RSS state remains unchanged.
4. Restores TCP data split to disabled with NetDevRingsSet.
5. Checks that the complete final ring and RSS snapshots exactly match their initial values.

device=enp129s0f1np1 ifindex=5
initial.rings tcp_data_split=disabled hds_threshold=0 rx=2048 tx=256
initial.rss table_entries=2048 table_prefix=[0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3] hash_key_bytes=52 input_transformation=0x0
header_split.change=disabled->enabled
programmed.rings tcp_data_split=enabled hds_threshold=0 rx=2048 tx=256
programmed.rss table_entries=2048 table_prefix=[0 1 2 3 4 5 0 1 2 3 4 5 0 1 2 3] hash_key_bytes=52 input_transformation=0x0
header_split.program=PASS
rss.preserved_while_programmed=PASS
final.restore_verify=PASS
header_split.restore=PASS
overall=PASS

Scope and limitations

The Atlantic test validates the complete RSS indirection-table control-plane round trip against a real driver: generic-netlink read, partial update, readback, restoration, and agreement with the legacy ioctl read path.

The ICE test validates TCP header/data-split control-plane programming, readback, RSS preservation, and restoration through NetDevRingsGet and NetDevRingsSet.

No controlled matching traffic was generated and per-queue packet counters or receive buffers were not inspected. The tests therefore do not independently validate data-plane RSS distribution or prove that ICE placed TCP headers and payloads in separate buffers.

The RSS test did not change the hash key, hash function, or input transformation. The ICE test changed only TCPDataSplit; it did not program HDSThreshold, ring sizes, buffer length, or channel count.

netlink-ethtool-rss-rings-hardware-tests.tgz

Summary by CodeRabbit

• New Features
  • Added Linux ethtool support for reading and updating network device ring parameters.
  • Added Linux support for reading and updating RSS configuration, including hash functions, indirection tables, hash keys, and input transformations.
  • Added validation for invalid device settings, malformed network data, and unsupported configuration values.
• Tests
  • Added comprehensive coverage for ethtool requests, ring and RSS parsing, serialization, validation, and error handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: df71cca0-d32d-4a3e-85ff-543c2073fac2

📥 Commits

Reviewing files that changed from the base of the PR and between 0ab8595 and cb8f5d0.

📒 Files selected for processing (3)

• ethtool_linux.go
• ethtool_rss_linux.go
• ethtool_rss_linux_test.go

---

📝 Walkthrough

Walkthrough

Added Linux generic-netlink ethtool support. The change implements shared request handling, ring-parameter get/set APIs, RSS configuration get/set APIs, validation, attribute parsing, serialization, and Linux tests.

Changes

Linux ethtool support

Layer / File(s)	Summary
Generic-netlink ethtool protocol nl/ethtool_linux.go, ethtool_linux.go, ethtool_linux_test.go	Defines ethtool family, command, and attribute identifiers. Builds requests, validates headers and payload sizes, decodes attributes, and tests nested header encoding.
Ring parameter get and set ethtool_rings_linux.go, ethtool_rings_linux_test.go	Adds ring state and partial-update types, parses ring attributes, exposes package and Handle APIs, validates updates, serializes optional fields, and tests malformed and invalid inputs.
RSS configuration get and set ethtool_rss_linux.go, ethtool_rss_linux_test.go	Adds RSS types and constants, parses context-specific responses, serializes partial updates, validates table, key, hash, and transformation values, and tests reset behavior and buffer isolation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant NetDevRingsSet
  participant ethtoolRequest
  participant EthtoolFamily
  Caller->>NetDevRingsSet: submit ring configuration
  NetDevRingsSet->>ethtoolRequest: send ETHTOOL_MSG_RINGS_SET
  ethtoolRequest->>EthtoolFamily: generic-netlink update with ring attributes
  EthtoolFamily-->>ethtoolRequest: acknowledgement
  ethtoolRequest-->>NetDevRingsSet: request result
  NetDevRingsSet-->>Caller: error or success

Loading

sequenceDiagram
  participant Caller
  participant NetDevRSSSet
  participant ethtoolRequest
  participant EthtoolFamily
  Caller->>NetDevRSSSet: submit RSS configuration
  NetDevRSSSet->>ethtoolRequest: send ETHTOOL_MSG_RSS_SET with context
  ethtoolRequest->>EthtoolFamily: generic-netlink update with RSS attributes
  EthtoolFamily-->>ethtoolRequest: acknowledgement
  ethtoolRequest-->>NetDevRSSSet: request result
  NetDevRSSSet-->>Caller: error or success

Loading

Possibly related PRs

• vishvananda/netlink#1211: Directly overlaps with the ethtool helpers, ring and RSS implementations, tests, and netlink constants.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.81% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding RSS and ring configuration support over ethtool generic netlink.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

putComment timed out

[aarcamp]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.