interfaces: T7730: Add interrupt coalescing settings for Ethernet interfaces

[alexandr-san4ez]

Change summary

This change introduces CLI support for configuring network interface interrupt coalescing parameters (ethtool --coalesce).

Note: Not all NIC drivers support interrupt coalescing.

vyos@vyos:~$ ethtool --coalesce eth0 adaptive-rx on
netlink error: cannot modify an unsupported parameter (offset 36)
netlink error: Invalid argument

Before you run the tests, make sure your device supports all of these features.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Code style update (formatting, renaming)
• Refactoring (no functional changes)
• Migration from an old Vyatta component to vyos-1x, please link to related PR inside obsoleted component
• Other (please describe):

Related Task(s)

• https://vyos.dev/T7730

Related PR(s)

• ethtool: T7730: Add configuration coalesce for interface vyos-documentation#1728

How to test / Smoketest result

Manual test:

1. Manual interrupt moderation

conf
set interfaces ethernet eth2 interrupt-coalescing rx-usecs 64
set interfaces ethernet eth2 interrupt-coalescing tx-usecs 64
commit

vyos@he-r650-01:~$ ethtool --show-coalesce eth2
Coalesce parameters for eth2:
Adaptive RX: off  TX: off
stats-block-usecs:      n/a
sample-interval:        n/a
pkt-rate-low:           n/a
pkt-rate-high:          n/a

rx-usecs:       64
rx-frames:      32
rx-usecs-irq:   n/a
rx-frames-irq:  n/a

tx-usecs:       64
tx-frames:      32
tx-usecs-irq:   n/a
tx-frames-irq:  n/a
...

2. Adaptive interrupt coalescing

conf
set interfaces ethernet eth2 interrupt-coalescing adaptive-rx
set interfaces ethernet eth2 interrupt-coalescing adaptive-tx
commit

vyos@he-r650-01# ethtool --show-coalesce eth2
Coalesce parameters for eth2:
Adaptive RX: on  TX: on
stats-block-usecs:      n/a
sample-interval:        n/a
pkt-rate-low:           n/a
pkt-rate-high:          n/a
...

3. Unsupported NIC driver

conf
set interfaces ethernet eth1 interrupt-coalescing adaptive-rx
set interfaces ethernet eth1 interrupt-coalescing adaptive-tx
commit

vyos@vyos# commit
[ interfaces ethernet eth1 ]
Driver does not support "adaptive-rx" coalesce setting!
[[interfaces ethernet eth1]] failed
Commit failed

Smoketest:

vyos@he-r650-01:~$ /usr/libexec/vyos/tests/smoke/cli/test_interfaces_ethernet.py -k ethtool_coalesce
test_ethtool_coalesce (__main__.EthernetInterfaceTest.test_ethtool_coalesce)
 Verify that coalesce configuration is correctly applied to the interface using ethtool ... ok
...

Checklist:

• I have read the CONTRIBUTING document
• I have linked this PR to one or more Phabricator Task(s)
• I have run the components SMOKETESTS if applicable
• My commit headlines contain a valid Task id
• My change requires a change to the documentation
• I have updated the documentation accordingly

[github-actions]

👍
No issues in PR Title / Commit Title

[Copilot]

Pull request overview

This PR adds CLI support for configuring network interface interrupt coalescing parameters via ethtool --coalesce. This allows users to tune interrupt moderation settings including adaptive modes (adaptive-rx, adaptive-tx) and static delay values (rx-usecs, tx-usecs) for better network performance optimization.

Key Changes:

• Adds new CLI configuration nodes under interfaces ethernet <name> coalesce for adaptive-rx, adaptive-tx, rx-usecs, and tx-usecs
• Implements verification logic to ensure NIC driver support before applying settings
• Includes comprehensive smoketests to validate functionality across different NIC types

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
interface-definitions/interfaces_ethernet.xml.in	Defines new CLI configuration nodes for coalesce settings with appropriate constraints (0-16384 range for usecs values)
python/vyos/ethtool.py	Adds coalesce parsing, storage, and accessor methods (check_coalesce, get_coalesce) to the Ethtool class
python/vyos/ifconfig/ethernet.py	Implements set_coalesce method to apply settings via ethtool command and integrates it into the update flow
src/conf_mode/interfaces_ethernet.py	Adds verify_coalesce function to validate driver support and parameter compatibility before committing
smoketest/scripts/cli/test_interfaces_ethernet.py	Provides comprehensive test coverage for both manual and adaptive coalesce configuration modes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zdc]

In addition to the code-related feedback, there is an important functional consideration.

Exposing only rx/tx-usecs is not practical because disabling adaptive mode activates all settings - not just the usecs values. This means we effectively switch to a "manual" configuration mode, yet we only grant users access to a subset of the controls they actually need to use this mode effectively.

Therefore, if we proceed with this approach, all coalesce settings should be introduced simultaneously.

[alexandr-san4ez]

@zdc I have pushed an updated version of the implementation which contains all the available settings from ethtool v6.10.

[sever-sever]

Adds the ethtool coalesce configuration feature for an interface
(checked only working options, other options not allowed on my virtio device, needs to check HELP values if we ok with them)

vyos@r14# run show conf com | match coa
set interfaces ethernet eth1 coalesce rx-frames '23'
[edit]
vyos@r14# sudo ethtool --show-coalesce eth1
Coalesce parameters for eth1:
Adaptive RX: n/a  TX: n/a
stats-block-usecs:	n/a
sample-interval:	n/a
pkt-rate-low:		n/a
pkt-rate-high:		n/a

rx-usecs:	n/a
rx-frames:	23
rx-usecs-irq:	n/a
rx-frames-irq:	n/a

tx-usecs:	n/a
tx-frames:	n/a
tx-usecs-irq:	n/a
tx-frames-irq:	n/a

rx-usecs-low:	n/a
rx-frame-low:	n/a
tx-usecs-low:	n/a
tx-frame-low:	n/a

rx-usecs-high:	n/a
rx-frame-high:	n/a
tx-usecs-high:	n/a
tx-frame-high:	n/a

CQE mode RX: n/a  TX: n/a

tx-aggr-max-bytes:	n/a
tx-aggr-max-frames:	n/a
tx-aggr-time-usecs:	n/a

[edit]
vyos@r14# 
[edit]
vyos@r14# set interfaces ethernet eth1 coalesce 
Possible completions:
   adaptive-rx          Enable adaptive receive interrupt moderation
   adaptive-tx          Enable adaptive transmit interrupt moderation
   cqe-mode-rx          Enable RX CQE (Completion Queue Entry) mode
   cqe-mode-tx          Enable TX CQE (Completion Queue Entry) mode
   pkt-rate-high        Upper packet rate threshold for adaptive coalescing
   pkt-rate-low         Lower packet rate threshold for adaptive coalescing
   rx-frames            Number of RX frames before generating interrupt
   rx-frames-high       RX coalescing frames threshold for high packet rate
   rx-frames-irq        Number of RX frames before generating interrupt while servicing
                        IRQ
   rx-frames-low        RX coalescing frames threshold for low packet rate
   rx-usecs             Delay in microseconds before generating RX interrupt
   rx-usecs-high        RX coalescing delay (usecs) for high packet rate
   rx-usecs-irq         Delay in microseconds before generating RX interrupt while
                        servicing IRQ
   rx-usecs-low         RX coalescing delay (usecs) for low packet rate
   sample-interval      Sampling interval for adaptive coalescing (in seconds)
   stats-block-usecs    Time in microseconds between updating coalescing statistics
   tx-aggr-max-bytes    Maximum number of bytes to aggregate before transmitting
   tx-aggr-max-frames   Maximum number of frames to aggregate before transmitting
   tx-aggr-time-usecs   Maximum time in microseconds to wait before transmitting
                        aggregated frames
   tx-frames            Number of TX frames before generating interrupt
   tx-frames-high       TX coalescing frames threshold for high packet rate
   tx-frames-irq        Number of TX frames before generating interrupt while servicing
                        IRQ
   tx-frames-low        TX coalescing frames threshold for low packet rate
   tx-usecs             Delay in microseconds before generating TX interrupt
   tx-usecs-high        TX coalescing delay (usecs) for high packet rate
   tx-usecs-irq         Delay in microseconds before generating TX interrupt while
                        servicing IRQ
   tx-usecs-low         TX coalescing delay (usecs) for low packet rate

      
[edit]
vyos@r14# 

[c-po]

All requested changes addressed. Code looks good and clean.
Verified by smoketests which got extended for this new feature.

[c-po]

Re-requested review from @zdc

[dmbaturin]

The logic looks good to me. I have aesthetic comments, though.

First, I don't like that the same thing is sometimes called "coalescing" and sometimes "moderation" in help strings — they are different terms for the same thing and generally people understand them both, but it may be better to stick with one term consistently. I don't have a strong opinion which one to use, we should discuss that; or toss a coin if nothing else.

I also wonder if the node name should be something like interrupt-moderation/interrupt-coalescing to make it clear to people less experienced with ethtool what exactly the option is about.

[alexandr-san4ez]

It's already difficult for me to think of a new name, because I'm used to using coalesce but what about moderation interrupt? Because I think "moderation" can be reused in the future.

[dmbaturin]

After a discussion we settled on "coalescing" and @alexandr-san4ez agreed to change all instances of "moderation" to "coalescing".

[dmbaturin]

My suggestions about option names are addressed now, and the logic was always fine.

[alexandr-san4ez]

@zdc provided me example of using netlink API instead of call ethtool CLI. I will change the implementation.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

CI integration 👍 passed!

Details

CI logs

• CLI Smoketests 👍 passed
• CLI Smoketests (interfaces only) 👍 passed
• Config tests 👍 passed
• RAID1 tests 👍 passed
• CLI Smoketests VPP 👍 passed
• Config tests VPP 👍 passed
• TPM tests 👍 passed