Ethtool : PRBS feature

Ethtool : PRBS feature

[Das, Shubham]

Hi All,

I'm looking for feedback on a potential extension to ethtool for controlling Ethernet PHY link characterization using PRBS generation and error injection.
PRBS is a port level configuration and ethtool ?phy-test will provide control interface at every port-level.

PRBS is an IEEE standard, and almost all Ethernet PHY SerDes comes with PRBS generator and receiver to assist physical link characterization.
In addition to PRBS sequence, we want to support provide SW control knobs to insert fixed number of errors, retrieve the bit error count, and clear them as needed.
With this, we are trying to standardize a multi-decade technology PRBS, so every Ethernet vendor can get benefited and replace the device specific custom tools.
From Ethernet designer point-of-view, it helps identify, fine tune, and make the ethernet communication better and stable. 
From end-user point of view, it helps gather debug data when something is not working at expected speeds.

Typical operations include:

ethtool --phy-test eth1 tx-prbs prbs7
ethtool --phy-test eth2 rx-prbs prbs7

ethtool --phy-test eth2 bert start
ethtool --phy-test eth2 bert stop
ethtool --phy-test eth2 stats
ethtool --phy-test eth2 clear-stats

ethtool --phy-test eth1 inject-error 1
ethtool --phy-test eth1 inject-error 1e-3

ethtool --phy-test eth1 tx-prbs off
ethtool --phy-test eth2 rx-prbs off


Approach would be to add a generic ethtool netlink API for PHY/SerDes and allow drivers to implement the operations directly. 
Conceptually:
       ethtool ⇒ ethtool netlink ⇒ driver-specific implementation

The intent would be to provide a common userspace interface while allowing implementations in NIC drivers.

Before proceeding further, I would appreciate feedback on:

1. Whether ethtool is considered the appropriate userspace interface for these functionality
2. Whether similar work has been proposed previously.

Thanks,
Shubham D

Re: Ethtool : PRBS feature

[Andrew Lunn]

> 2. Whether similar work has been proposed previously.

There was a presentation at netdev conf last year about this topic,
and how you use it to configure SERDES eyes. And then a long
discussion on the netdev mailing afterwards. You should read the
discussion, and incorporate the ideas. There was a couple of points
raised:

SERDES are also used for PCIe, USB, SATA, and they have similar
capabilities to a SERDES used for networking. Do we want a networking
specific solution, or something more generic?

You need to include lane information, since there can be 1, 2 or 4
lanes involved, and you need to specify which lane you want to test.

      Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

Hi Andrew,

Thanks for the feedback.

Yes, for multi-lane ports we can accept the lane number as an argument like:

ethtool --phy-test eth1 lane 0 tx-prbs prbs7
ethtool --phy-test eth2 lane 0 rx-prbs prbs7

We referred to "Lee Trager's" "Open-Source Tooling for PHY Management and Testing" session:
https://netdevconf.info/0x19/sessions/talk/open-source-tooling-for-phy-management-and-testing.html?.
We have been trying to reach "Lee Trager" to seek more input, latest update on the approach and understand if there is a parallel effort in active so we can collaborate.
If you can, please help me connect with "Lee Trager" and others who expressed interest in Ethernet PRBS. We are happy to align and start implementation.

About standardizing across other bus like PCIe and USB, I had a quick discussion with our internal designers, but I didn't observe any such SW-level config knobs interest. 
Looks like Ethernet has clear interest and we are joining that Ethernet PRBS community too.

Ethernet PRBS configuration and diagnostics support is well established and already widely used in existing Ethernet SERDES deployments.
We think Ethernet is the most natural starting point within netdev, as it aligns with current driver practice and existing validation workflows. 

Thanks,
Shubham D


> -----Original Message-----
> From: Andrew Lunn <andrew@lunn.ch>
> Sent: 11 June 2026 21:14
> To: Das, Shubham <shubham.das@intel.com>
> Cc: netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
> <siddaraju.dh@intel.com>; Chintalapalle, Balaji <balaji.chintalapalle@intel.com>
> Subject: Re: Ethtool : PRBS feature
> 
> > 2. Whether similar work has been proposed previously.
> 
> There was a presentation at netdev conf last year about this topic,
> and how you use it to configure SERDES eyes. And then a long
> discussion on the netdev mailing afterwards. You should read the
> discussion, and incorporate the ideas. There was a couple of points
> raised:
> 
> SERDES are also used for PCIe, USB, SATA, and they have similar
> capabilities to a SERDES used for networking. Do we want a networking
> specific solution, or something more generic?
> 
> You need to include lane information, since there can be 1, 2 or 4
> lanes involved, and you need to specify which lane you want to test.
> 
>       Andrew

Re: Ethtool : PRBS feature

[Alexander H Duyck]

On Tue, 2026-06-16 at 12:14 +0000, Das, Shubham wrote:
> Hi Andrew,
> 
> Thanks for the feedback.
> 
> Yes, for multi-lane ports we can accept the lane number as an argument like:
> 
> ethtool --phy-test eth1 lane 0 tx-prbs prbs7
> ethtool --phy-test eth2 lane 0 rx-prbs prbs7
> 
> We referred to "Lee Trager's" "Open-Source Tooling for PHY Management and Testing" session:
> https://netdevconf.info/0x19/sessions/talk/open-source-tooling-for-phy-management-and-testing.html?.
> We have been trying to reach "Lee Trager" to seek more input, latest update on the approach and understand if there is a parallel effort in active so we can collaborate.
> If you can, please help me connect with "Lee Trager" and others who expressed interest in Ethernet PRBS. We are happy to align and start implementation.
> 

You aren't going to have much luck if you are trying to reach out via
his Meta address as he has moved onto Nvidia so he is no longer working
on the fbnic driver.

As far as the work done most of it was internal and making use of
debugfs. I don't believe any of the work for fbnic began to approach
the suggested methods for upstreamming the feature as Lee had been
pulled into other efforts.

> About standardizing across other bus like PCIe and USB, I had a quick discussion with our internal designers, but I didn't observe any such SW-level config knobs interest. 
> Looks like Ethernet has clear interest and we are joining that Ethernet PRBS community too.

I think it largely depends on what your implementation looks like. The
point being made was that many of the SerDes PHYs out there are capable
of use in multiple applications. So instead of being a networking
device you would be looking at a SerDes PHY such as those in
"/drivers/phy/".

Also do you know what layer in the PHY you are injecting this PRBS at?
I would be curious if this is PCS or at the PMD level?

If you are referring to the PCS level then yes, it would make sense to
have it in the networking subsystem as the PCS at this point is more a
netdev specific set of drivers, see "/drivers/net/pcs/".

In the case of the PMD that is where things get a bit more interesting.
There is an IEEE c45 register definition that includes PRBS testing
registers, however in the case of our implementation the PMD doesn't
follow that specification and follows more the "/drivers/phy/" model.

> Ethernet PRBS configuration and diagnostics support is well established and already widely used in existing Ethernet SERDES deployments.
> We think Ethernet is the most natural starting point within netdev, as it aligns with current driver practice and existing validation workflows. 

The problem is many of these parts used as an Ethernet Serdes PMD are
really a multiuse part. So for example in the case of the hardware in
FBNIC we use the same part on the Ethernet PHY as we do for the PCIe
Gen5 PHY.

The complication in our case is that both are buried behind our FW due
to the fact that both are shared between slices. However for testing
purposes and such we could look at disabling the odd slices to
essentially unshare the hardware if you need another platform to test
something like this with.

RE: Ethtool : PRBS feature

[Das, Shubham]

> Also do you know what layer in the PHY you are injecting this PRBS at?
> I would be curious if this is PCS or at the PMD level?

In our case PRBS functionality is implemented in the PHY firmware at the PCS (TX/RX) + PMA (FEC Error Injection) layer.


Andrew,  Alexander, Lee,

The host driver does not directly access any registers but requests the PHY FW to manage PRBS on behalf of it.
Because of this, the implementation does not naturally fit the traditional PHYLIB model, where Linux PHY drivers directly manage PHY registers. 
The functionality is closer to a firmware-managed service exposed through the PCIe driver, so we thought the right place would be to extend ethtool.

We come from the Ethernet PHY field and are attempting to generalize PRBS for generic PHYs to accommodate all bus types, which might distract us, I believe.
The existing ethtool user application interface will give a quick start for Ethernet PHY PRBS management. 
When we need other buses or when we have another model implementation, then we can abstract the commonalities into a framework.

Should we proceed with implementing the "ethtool --phy-test" ?


> -----Original Message-----
> From: Alexander H Duyck <alexander.duyck@gmail.com>
> Sent: 16 June 2026 21:45
> To: Das, Shubham <shubham.das@intel.com>; Andrew Lunn <andrew@lunn.ch>
> Cc: netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
> <siddaraju.dh@intel.com>; Chintalapalle, Balaji <balaji.chintalapalle@intel.com>
> Subject: Re: Ethtool : PRBS feature
> 
> On Tue, 2026-06-16 at 12:14 +0000, Das, Shubham wrote:
> > Hi Andrew,
> >
> > Thanks for the feedback.
> >
> > Yes, for multi-lane ports we can accept the lane number as an argument like:
> >
> > ethtool --phy-test eth1 lane 0 tx-prbs prbs7 ethtool --phy-test eth2
> > lane 0 rx-prbs prbs7
> >
> > We referred to "Lee Trager's" "Open-Source Tooling for PHY Management and
> Testing" session:
> > https://netdevconf.info/0x19/sessions/talk/open-source-tooling-for-phy-
> management-and-testing.html?.
> > We have been trying to reach "Lee Trager" to seek more input, latest update on
> the approach and understand if there is a parallel effort in active so we can
> collaborate.
> > If you can, please help me connect with "Lee Trager" and others who expressed
> interest in Ethernet PRBS. We are happy to align and start implementation.
> >
> 
> You aren't going to have much luck if you are trying to reach out via his Meta
> address as he has moved onto Nvidia so he is no longer working on the fbnic
> driver.
> 
> As far as the work done most of it was internal and making use of debugfs. I don't
> believe any of the work for fbnic began to approach the suggested methods for
> upstreamming the feature as Lee had been pulled into other efforts.
> 
> > About standardizing across other bus like PCIe and USB, I had a quick discussion
> with our internal designers, but I didn't observe any such SW-level config knobs
> interest.
> > Looks like Ethernet has clear interest and we are joining that Ethernet PRBS
> community too.
> 
> I think it largely depends on what your implementation looks like. The point being
> made was that many of the SerDes PHYs out there are capable of use in multiple
> applications. So instead of being a networking device you would be looking at a
> SerDes PHY such as those in "/drivers/phy/".
> 
> Also do you know what layer in the PHY you are injecting this PRBS at?
> I would be curious if this is PCS or at the PMD level?
> 
> If you are referring to the PCS level then yes, it would make sense to have it in the
> networking subsystem as the PCS at this point is more a netdev specific set of
> drivers, see "/drivers/net/pcs/".
> 
> In the case of the PMD that is where things get a bit more interesting.
> There is an IEEE c45 register definition that includes PRBS testing registers,
> however in the case of our implementation the PMD doesn't follow that
> specification and follows more the "/drivers/phy/" model.
> 
> > Ethernet PRBS configuration and diagnostics support is well established and
> already widely used in existing Ethernet SERDES deployments.
> > We think Ethernet is the most natural starting point within netdev, as
> > it aligns with current driver practice and existing validation workflows.
> 
> The problem is many of these parts used as an Ethernet Serdes PMD are really a
> multiuse part. So for example in the case of the hardware in FBNIC we use the
> same part on the Ethernet PHY as we do for the PCIe
> Gen5 PHY.
> 
> The complication in our case is that both are buried behind our FW due to the fact
> that both are shared between slices. However for testing purposes and such we
> could look at disabling the odd slices to essentially unshare the hardware if you
> need another platform to test something like this with.

Re: Ethtool : PRBS feature

[Andrew Lunn]

> The host driver does not directly access any registers but requests
> the PHY FW to manage PRBS on behalf of it.

Maybe a dumb question. Why?

Can you change the firmware to expose the 802.3 registers for PRBS?
You can then write a library which both plylib and your driver can
use.

	Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

> Can you change the firmware to expose the 802.3 registers for PRBS?
> You can then write a library which both plylib and your driver can use.

Andrew,

No, exposing the PRBS registers to drivers is not possible in our design (the registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).

Additionally, the PHY PRBS registers are not in accordance with the IEEE Clause 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.

Given these constraints, we think ethtool --phy-test is a reasonable starting point for exposing the long-established Ethernet PRBS functionality to Linux userspace, as it aligns well with the driver-owned NIC architecture model. If you think a more generic layered approach would be preferable, we would appreciate guidance on the expected architecture. That would help us better understand the implementation complexity, required effort, and delivery timelines.

Thanks,
Shubham D

> -----Original Message-----
> From: Andrew Lunn <andrew@lunn.ch>
> Sent: 20 June 2026 00:07
> To: Das, Shubham <shubham.das@intel.com>
> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> Subject: Re: Ethtool : PRBS feature
> 
> > The host driver does not directly access any registers but requests
> > the PHY FW to manage PRBS on behalf of it.
> 
> Maybe a dumb question. Why?
> 
> Can you change the firmware to expose the 802.3 registers for PRBS?
> You can then write a library which both plylib and your driver can use.
> 
> 	Andrew

Re: Ethtool : PRBS feature

[Maxime Chevallier]

Hi,

On 6/20/26 15:48, Das, Shubham wrote:
>> Can you change the firmware to expose the 802.3 registers for PRBS?
>> You can then write a library which both plylib and your driver can use.
> 
> Andrew,
> 
> No, exposing the PRBS registers to drivers is not possible in our design (the registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).
> 
> Additionally, the PHY PRBS registers are not in accordance with the IEEE Clause 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.
> 
> Given these constraints, we think ethtool --phy-test is a reasonable starting point for exposing the long-established Ethernet PRBS functionality to Linux userspace, as it aligns well with the driver-owned NIC architecture model. If you think a more generic layered approach would be preferable, we would appreciate guidance on the expected architecture. That would help us better understand the implementation complexity, required effort, and delivery timelines.

Can you elaborate on what you have in mind for now ? what would the
"ethtool --phy-test" command look like in terms of its behaviour and
parameters ?

This feature is interesting for multiple people, each having different
hardware designs and constraints. It's good to consider an iterative
approach to build this, however we need to have in mind that this is
uAPI, so once we commit to a design choice, we have to live with it.

We do have flexibility on the kernel side of the API. We can implement PRBS
in generic PHY, phylib, some MAC driver that talks to a firmware, etc. and
hide away these implementation details to userspace, but we need to make
sure the uAPI we come up with allows us to support all of that.

Let's figure this out together, if you already have some ideas in mind we
can use that as a starting point for the discussion :)

Maxime

> 
> Thanks,
> Shubham D
> 
>> -----Original Message-----
>> From: Andrew Lunn <andrew@lunn.ch>
>> Sent: 20 June 2026 00:07
>> To: Das, Shubham <shubham.das@intel.com>
>> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
>> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
>> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
>> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
>> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
>> Subject: Re: Ethtool : PRBS feature
>>
>>> The host driver does not directly access any registers but requests
>>> the PHY FW to manage PRBS on behalf of it.
>>
>> Maybe a dumb question. Why?
>>
>> Can you change the firmware to expose the 802.3 registers for PRBS?
>> You can then write a library which both plylib and your driver can use.
>>
>> 	Andrew
> 

Re: Ethtool : PRBS feature

[Andrew Lunn]

On Sat, Jun 20, 2026 at 04:39:06PM +0200, Maxime Chevallier wrote:
> Hi,
> 
> On 6/20/26 15:48, Das, Shubham wrote:
> >> Can you change the firmware to expose the 802.3 registers for PRBS?
> >> You can then write a library which both plylib and your driver can use.
> > 
> > Andrew,
> > 
> > No, exposing the PRBS registers to drivers is not possible in our design (the registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).
> > 
> > Additionally, the PHY PRBS registers are not in accordance with the IEEE Clause 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.
> > 

Hi Shubham

Do you at least have the functionality of the standard C45 registers,
even if the addresses and bit fields are messed up?

If you do, maybe we should actually start with a C45 conforming
implementation, and then you can do a translation layer to whatever
oddball implementation you have?

> > Given these constraints, we think ethtool --phy-test is a
> > reasonable starting point for exposing the long-established
> > Ethernet PRBS functionality to Linux userspace, as it aligns well
> > with the driver-owned NIC architecture model.

I agree an ethtool --phy-test makes sense, but we need to ensure
standard based C45 functionality is covered, not just your oddball
vendor functionality.

	Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

> Do you at least have the functionality of the standard C45 registers, even if the addresses and bit fields are messed up?
> If you do, maybe we should actually start with a C45 conforming implementation, and then you can do a translation layer to whatever oddball implementation you have?

The PHY supports the equivalent functionality (PRBS TX, PRBS RX/checker, BER testing, error injection, and symbol/error counters read), 
but these are not exposed through standard Clause 45 PRBS registers. Instead, all operations are implemented by PHY firmware
and accessed through a command/control register interface.

If we want to support both driver-owned NIC architectures and use cases where the PHY driver directly manages the PRBS functionality,
Should this be exposed through a common phylib abstraction/API or a different approach ?

- Shubham D

> -----Original Message-----
> From: Andrew Lunn <andrew@lunn.ch>
> Sent: 21 June 2026 00:51
> To: Maxime Chevallier <maxime.chevallier@bootlin.com>
> Cc: Das, Shubham <shubham.das@intel.com>; Alexander H Duyck
> <alexander.duyck@gmail.com>; lee@trager.us; netdev@vger.kernel.org;
> mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle,
> Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> Subject: Re: Ethtool : PRBS feature
> 
> On Sat, Jun 20, 2026 at 04:39:06PM +0200, Maxime Chevallier wrote:
> > Hi,
> >
> > On 6/20/26 15:48, Das, Shubham wrote:
> > >> Can you change the firmware to expose the 802.3 registers for PRBS?
> > >> You can then write a library which both plylib and your driver can use.
> > >
> > > Andrew,
> > >
> > > No, exposing the PRBS registers to drivers is not possible in our design (the
> registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).
> > >
> > > Additionally, the PHY PRBS registers are not in accordance with the IEEE
> Clause 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.
> > >
> 
> Hi Shubham
> 
> Do you at least have the functionality of the standard C45 registers, even if the
> addresses and bit fields are messed up?
> 
> If you do, maybe we should actually start with a C45 conforming implementation,
> and then you can do a translation layer to whatever oddball implementation you
> have?
> 
> > > Given these constraints, we think ethtool --phy-test is a reasonable
> > > starting point for exposing the long-established Ethernet PRBS
> > > functionality to Linux userspace, as it aligns well with the
> > > driver-owned NIC architecture model.
> 
> I agree an ethtool --phy-test makes sense, but we need to ensure standard based
> C45 functionality is covered, not just your oddball vendor functionality.
> 
> 	Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

Hi Maxime,

> Can you elaborate on what you have in mind for now ? what would the "ethtool --
> phy-test" command look like in terms of its behaviour and parameters ?

We are trying to converge on a userspace uAPI for PRBS/BERT functionality that can work across
different hardware models (PHY-managed, MAC/NIC-offloaded, or firmware-based implementations),
without exposing those differences to userspace.

Based on the functionality we currently have, we proposed below commands in first email :

PRBS Transmitter/Checker Pattern Configuration:
ethtool --phy-test eth1 tx-prbs prbs7
ethtool --phy-test eth2 rx-prbs prbs7

BERT Test:
ethtool --phy-test eth2 bert start
ethtool --phy-test eth2 bert stop

BERT Test Counter Read/ PRBS Lock Status:
ethtool --phy-test eth2 stats

BERT Clear stats - Symbol and Error counter:
ethtool --phy-test eth2 clear-stats

TX Error Injection:
ethtool --phy-test eth1 inject-error 1
ethtool --phy-test eth1 inject-error 1e-3

Disable PRBS Pattern : TX/RX
ethtool --phy-test eth1 tx-prbs off
ethtool --phy-test eth2 rx-prbs off

Approach would be to add a generic ethtool netlink API for PHY/SerDes and allow drivers to implement the operations directly. 
Conceptually:
       ethtool ⇒ ethtool netlink ⇒ driver-specific implementation

We would appreciate your input on whether a command-based model is suitable for a uAPI, and how we should design
it to accommodate different implementation models, such as PHY-based, phylib-based, and MAC/firmware-offloaded PRBS.

- Shubham D

> -----Original Message-----
> From: Maxime Chevallier <maxime.chevallier@bootlin.com>
> Sent: 20 June 2026 20:09
> To: Das, Shubham <shubham.das@intel.com>; Andrew Lunn <andrew@lunn.ch>
> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> Subject: Re: Ethtool : PRBS feature
> 
> Hi,
> 
> On 6/20/26 15:48, Das, Shubham wrote:
> >> Can you change the firmware to expose the 802.3 registers for PRBS?
> >> You can then write a library which both plylib and your driver can use.
> >
> > Andrew,
> >
> > No, exposing the PRBS registers to drivers is not possible in our design (the
> registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).
> >
> > Additionally, the PHY PRBS registers are not in accordance with the IEEE Clause
> 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.
> >
> > Given these constraints, we think ethtool --phy-test is a reasonable starting
> point for exposing the long-established Ethernet PRBS functionality to Linux
> userspace, as it aligns well with the driver-owned NIC architecture model. If you
> think a more generic layered approach would be preferable, we would appreciate
> guidance on the expected architecture. That would help us better understand the
> implementation complexity, required effort, and delivery timelines.
> 
> Can you elaborate on what you have in mind for now ? what would the "ethtool --
> phy-test" command look like in terms of its behaviour and parameters ?
> 
> This feature is interesting for multiple people, each having different hardware
> designs and constraints. It's good to consider an iterative approach to build this,
> however we need to have in mind that this is uAPI, so once we commit to a design
> choice, we have to live with it.
> 
> We do have flexibility on the kernel side of the API. We can implement PRBS in
> generic PHY, phylib, some MAC driver that talks to a firmware, etc. and hide away
> these implementation details to userspace, but we need to make sure the uAPI
> we come up with allows us to support all of that.
> 
> Let's figure this out together, if you already have some ideas in mind we can use
> that as a starting point for the discussion :)
> 
> Maxime
> 
> >
> > Thanks,
> > Shubham D
> >
> >> -----Original Message-----
> >> From: Andrew Lunn <andrew@lunn.ch>
> >> Sent: 20 June 2026 00:07
> >> To: Das, Shubham <shubham.das@intel.com>
> >> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
> >> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
> >> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
> >> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> >> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> >> Subject: Re: Ethtool : PRBS feature
> >>
> >>> The host driver does not directly access any registers but requests
> >>> the PHY FW to manage PRBS on behalf of it.
> >>
> >> Maybe a dumb question. Why?
> >>
> >> Can you change the firmware to expose the 802.3 registers for PRBS?
> >> You can then write a library which both plylib and your driver can use.
> >>
> >> 	Andrew
> >

Re: Ethtool : PRBS feature

[Lee Trager]

On 6/22/26 8:38 AM, Das, Shubham wrote:

> Hi Maxime,
>
>> Can you elaborate on what you have in mind for now ? what would the "ethtool --
>> phy-test" command look like in terms of its behaviour and parameters ?
> We are trying to converge on a userspace uAPI for PRBS/BERT functionality that can work across
> different hardware models (PHY-managed, MAC/NIC-offloaded, or firmware-based implementations),
> without exposing those differences to userspace.

This was my original thought as well. Create a well defined uAPI for 
PRBS testing/TX FIR tuning and allow the driver to implement support 
however it sees fit. Since our target is for ethernet devices ethtool 
was a natural spot for the uAPI.

I presented this at netdev last year and received strong push back 
against associating PRBS testing/TX FIR tuning with ethtool. The 
argument being any new uAPI added to the kernel should be generic enough 
to handle future use cases so duplicate uAPIs don't have to be added. 
Since PRBS testing/TX FIR tuning can be done on many phys(Ethernet, 
PCIE, USB, etc) the uAPI does not belong in ethtool and needs to be 
structured to support other use cases.

As drivers/phy is the base phy library the thought was support should be 
added in drivers/phy and a new phytool should be created to interact 
with a uAPI. This would be generic enough to support all use cases, with 
the downside being existing drivers would have to onboard to drivers/phy.

I do wonder if the best path forward would be to create phytool in a way 
that allows the driver to implement PRBS testing/TX FIR tuning as it 
sees fit instead of being strictly tied to drivers/phy.

>
> Based on the functionality we currently have, we proposed below commands in first email :
>
> PRBS Transmitter/Checker Pattern Configuration:
> ethtool --phy-test eth1 tx-prbs prbs7
> ethtool --phy-test eth2 rx-prbs prbs7
>
> BERT Test:
> ethtool --phy-test eth2 bert start
> ethtool --phy-test eth2 bert stop
>
> BERT Test Counter Read/ PRBS Lock Status:
> ethtool --phy-test eth2 stats
>
> BERT Clear stats - Symbol and Error counter:
> ethtool --phy-test eth2 clear-stats
>
> TX Error Injection:
> ethtool --phy-test eth1 inject-error 1
> ethtool --phy-test eth1 inject-error 1e-3
>
> Disable PRBS Pattern : TX/RX
> ethtool --phy-test eth1 tx-prbs off
> ethtool --phy-test eth2 rx-prbs off

The goal of running testing is to validate TX FIR values. If testing 
fails we need a uAPI to change those values.

Also the uAPI need to support testing per lane. One thing hardware 
engineers at Meta did was test each lane with a different set of TX FIR 
values which allowed them to quickly determine the best set of values.

>
> Approach would be to add a generic ethtool netlink API for PHY/SerDes and allow drivers to implement the operations directly.
> Conceptually:
>         ethtool ⇒ ethtool netlink ⇒ driver-specific implementation
>
> We would appreciate your input on whether a command-based model is suitable for a uAPI, and how we should design
> it to accommodate different implementation models, such as PHY-based, phylib-based, and MAC/firmware-offloaded PRBS.
>
> - Shubham D
>
>> -----Original Message-----
>> From: Maxime Chevallier <maxime.chevallier@bootlin.com>
>> Sent: 20 June 2026 20:09
>> To: Das, Shubham <shubham.das@intel.com>; Andrew Lunn <andrew@lunn.ch>
>> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
>> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
>> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
>> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
>> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
>> Subject: Re: Ethtool : PRBS feature
>>
>> Hi,
>>
>> On 6/20/26 15:48, Das, Shubham wrote:
>>>> Can you change the firmware to expose the 802.3 registers for PRBS?
>>>> You can then write a library which both plylib and your driver can use.
>>> Andrew,
>>>
>>> No, exposing the PRBS registers to drivers is not possible in our design (the
>> registers are buried deep within the Accelerator/NIC/PHY/Analog IP hierarchy).
>>> Additionally, the PHY PRBS registers are not in accordance with the IEEE Clause
>> 45 definitions. For instance, the PRBS registers are paged and 32-bit wide.
>>> Given these constraints, we think ethtool --phy-test is a reasonable starting
>> point for exposing the long-established Ethernet PRBS functionality to Linux
>> userspace, as it aligns well with the driver-owned NIC architecture model. If you
>> think a more generic layered approach would be preferable, we would appreciate
>> guidance on the expected architecture. That would help us better understand the
>> implementation complexity, required effort, and delivery timelines.
>>
>> Can you elaborate on what you have in mind for now ? what would the "ethtool --
>> phy-test" command look like in terms of its behaviour and parameters ?
>>
>> This feature is interesting for multiple people, each having different hardware
>> designs and constraints. It's good to consider an iterative approach to build this,
>> however we need to have in mind that this is uAPI, so once we commit to a design
>> choice, we have to live with it.
>>
>> We do have flexibility on the kernel side of the API. We can implement PRBS in
>> generic PHY, phylib, some MAC driver that talks to a firmware, etc. and hide away
>> these implementation details to userspace, but we need to make sure the uAPI
>> we come up with allows us to support all of that.
>>
>> Let's figure this out together, if you already have some ideas in mind we can use
>> that as a starting point for the discussion :)
>>
>> Maxime
>>
>>> Thanks,
>>> Shubham D
>>>
>>>> -----Original Message-----
>>>> From: Andrew Lunn <andrew@lunn.ch>
>>>> Sent: 20 June 2026 00:07
>>>> To: Das, Shubham <shubham.das@intel.com>
>>>> Cc: Alexander H Duyck <alexander.duyck@gmail.com>; lee@trager.us;
>>>> netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju
>>>> <siddaraju.dh@intel.com>; Chintalapalle, Balaji
>>>> <balaji.chintalapalle@intel.com>; Lindberg, Magnus
>>>> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
>>>> Subject: Re: Ethtool : PRBS feature
>>>>
>>>>> The host driver does not directly access any registers but requests
>>>>> the PHY FW to manage PRBS on behalf of it.
>>>> Maybe a dumb question. Why?
>>>>
>>>> Can you change the firmware to expose the 802.3 registers for PRBS?
>>>> You can then write a library which both plylib and your driver can use.
>>>>
>>>> 	Andrew

Re: Ethtool : PRBS feature

[Andrew Lunn]

On Mon, Jun 22, 2026 at 03:38:30PM +0000, Das, Shubham wrote:
> Hi Maxime,
> 
> > Can you elaborate on what you have in mind for now ? what would the "ethtool --
> > phy-test" command look like in terms of its behaviour and parameters ?
> 
> We are trying to converge on a userspace uAPI for PRBS/BERT functionality that can work across
> different hardware models (PHY-managed, MAC/NIC-offloaded, or firmware-based implementations),
> without exposing those differences to userspace.
> 
> Based on the functionality we currently have, we proposed below commands in first email :
> 
> PRBS Transmitter/Checker Pattern Configuration:
> ethtool --phy-test eth1 tx-prbs prbs7
> ethtool --phy-test eth2 rx-prbs prbs7
> 
> BERT Test:
> ethtool --phy-test eth2 bert start
> ethtool --phy-test eth2 bert stop
> 
> BERT Test Counter Read/ PRBS Lock Status:
> ethtool --phy-test eth2 stats
> 
> BERT Clear stats - Symbol and Error counter:
> ethtool --phy-test eth2 clear-stats
> 
> TX Error Injection:
> ethtool --phy-test eth1 inject-error 1
> ethtool --phy-test eth1 inject-error 1e-3
> 
> Disable PRBS Pattern : TX/RX
> ethtool --phy-test eth1 tx-prbs off
> ethtool --phy-test eth2 rx-prbs off
> 
> Approach would be to add a generic ethtool netlink API for PHY/SerDes and allow drivers to implement the operations directly. 
> Conceptually:
>        ethtool ⇒ ethtool netlink ⇒ driver-specific implementation
> 
> We would appreciate your input on whether a command-based model is suitable for a uAPI, and how we should design
> it to accommodate different implementation models, such as PHY-based, phylib-based, and MAC/firmware-offloaded PRBS.

This is technical, not the uAPI. You need to define the netlink
messages and all the attributes that are passed between user space and
kernel. Please take a look at Documentation/netlink/specs and propose
an extension to ethtool.yaml.

Taking a quick look at this:

You are missing a way to enumerate what test patterns the hardware
supports. There is more than prbs7. You want to be able to report the
contents of C45 1.1500, and other similar registers.

To avoid race conditions, maybe some of these commands need combining. 
ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start

The configuration is then atomic, with respect to the uAPI, so we
don't get two users configuring it at the same time, ending up with a
messed up configuration.

Traditionally, Unix does not offer a way to clear statistic counters
back to zero. So i'm not sure about clear-stats. We also need to think
about hardware which does not support that. And there is locking
issues, can the stats be cleared while a test is active? 

You need to think about the units for inject errors. There is no
floating point support. Also, is this corrupt packets? Or single bit
flips in the stream? It needs to be well defined what it actually
means. The driver can then convert it to whatever the hardware
supports. How does 802.3 specify this?

Also, 802.3 defines PRBS7 as a benign pattern. With a quick look, i
did not find a definition of benign, but injecting errors does not
seem benign to me.

I'm assuming when 'start' is used, the networking core will change the
interface status to IF_OPER_TESTING. It is not always obvious why an
interface is in testing mode, rather than IF_OPER_UP. Cable testing
could also be running, etc. So maybe there needs to be a way to report
why it is in IF_OPER_TESTING?

I also wounder if a timeout should be used with start, so that it will
return to IF_OPER_UP after a time period?

       Andrew

Re: Ethtool : PRBS feature

[Lee Trager]

On 6/23/26 2:43 AM, Andrew Lunn wrote:

> Taking a quick look at this:
>
> You are missing a way to enumerate what test patterns the hardware
> supports. There is more than prbs7. You want to be able to report the
> contents of C45 1.1500, and other similar registers.
Not only is there more than PRBS7 but also PRBS 8/10 encoding which is 
an option on any test. There may be other options, that was the only one 
fbnic supported. I agree there does need to be a user interface which 
displays supported tests and options.
> To avoid race conditions, maybe some of these commands need combining.
> ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start
>
> The configuration is then atomic, with respect to the uAPI, so we
> don't get two users configuring it at the same time, ending up with a
> messed up configuration.
Testing consumes the link so you really don't want anything done to the 
netdev while testing is running. fbnic does the following.

1. Testing cannot start when the link is up
2. Once testing starts the driver removes the netdev to prevent use. The 
netdev is only added back when testing stops. The upstream solution will 
need something that can keep the netdev but lock everything down while 
testing is running.
3. Once testing starts you cannot change the test, even on an individual 
lane basis. You must stop testing first.
>
> Traditionally, Unix does not offer a way to clear statistic counters
> back to zero. So i'm not sure about clear-stats. We also need to think
> about hardware which does not support that. And there is locking
> issues, can the stats be cleared while a test is active?

fbnic actually has separate registers for PRBS test results. Results do 
need to be clean between runs but I never created an explicit clear 
interface. Firmware automatically reset the registers when a new test 
was started. This also allows results to be viewed after testing has 
stopped.

Reading results was a little tricky due to roll over between two 32bit 
registers. I was able to read results while testing was running without 
pausing. Technically I could clear results while testing was running but 
never saw a need to.

>
> You need to think about the units for inject errors. There is no
> floating point support. Also, is this corrupt packets? Or single bit
> flips in the stream? It needs to be well defined what it actually
> means. The driver can then convert it to whatever the hardware
> supports. How does 802.3 specify this?
>
> Also, 802.3 defines PRBS7 as a benign pattern. With a quick look, i
> did not find a definition of benign, but injecting errors does not
> seem benign to me.
>
> I'm assuming when 'start' is used, the networking core will change the
> interface status to IF_OPER_TESTING. It is not always obvious why an
> interface is in testing mode, rather than IF_OPER_UP. Cable testing
> could also be running, etc. So maybe there needs to be a way to report
> why it is in IF_OPER_TESTING?
>
> I also wounder if a timeout should be used with start, so that it will
> return to IF_OPER_UP after a time period?

When I spoke to hardware engineers at Meta they did not want a timeout. 
Testing often occurred over days, so they wanted to be able to start it 
and explicitly stop it. I'm not against a time out but I do think it 
should be optional.

Since PRBS testing is handled by firmware one safety measure I added is 
if firmware lost contact with the host testing was automatically stopped 
and TX FIR values were reset to factory. This ensured that the NIC won't 
get stuck in testing and on initialization the driver doesn't have to 
worry about testing state.

Lee

Re: Ethtool : PRBS feature

[Andrew Lunn]

>     To avoid race conditions, maybe some of these commands need combining.
>     ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start
> 
>     The configuration is then atomic, with respect to the uAPI, so we
>     don't get two users configuring it at the same time, ending up with a
>     messed up configuration.
> 
> Testing consumes the link so you really don't want anything done to the netdev
> while testing is running. fbnic does the following.
> 
> 1. Testing cannot start when the link is up

That is not going to work in the generic case. Many MAC drivers don't
bind to there PCS or PHY until open() is called. So there is no way to
pass the uAPI calls onto the PCS or PHY if the interface is
down. There are also some MACs which connect to multiple PCSs, and
there can be multiple PHYs. So you need to somehow indicate which
PCS/PHY should perform the PRBS. There was a discussion about loopback
recently, which has the same issue, you can perform loopback testing
in multiple places. So i expect the same concept will be used for
this.

> 2. Once testing starts the driver removes the netdev to prevent use. The netdev
> is only added back when testing stops. The upstream solution will need
> something that can keep the netdev but lock everything down while testing is
> running.

Probably IF_OPER_TESTING would be part of this. If the interface is in
this state, you want many other things blocked. However, probably
ksettings get/set need to work, so you can force the link into a
specific mode.

> 3. Once testing starts you cannot change the test, even on an individual lane
> basis. You must stop testing first.
> 
> 
>     Traditionally, Unix does not offer a way to clear statistic counters
>     back to zero. So i'm not sure about clear-stats. We also need to think
>     about hardware which does not support that. And there is locking
>     issues, can the stats be cleared while a test is active?
> 
> fbnic actually has separate registers for PRBS test results. Results do need to
> be clean between runs but I never created an explicit clear interface. Firmware
> automatically reset the registers when a new test was started. This also allows
> results to be viewed after testing has stopped.

We should really take 802.3 as the model, but i've not had time yet to
read what it says about the statistics.

> Reading results was a little tricky due to roll over between two 32bit
> registers.

802.3 is make this even more interesting, since those registers are 16
bits.

> When I spoke to hardware engineers at Meta they did not want a timeout. Testing
> often occurred over days, so they wanted to be able to start it and explicitly
> stop it. I'm not against a time out but I do think it should be optional.
> 
> Since PRBS testing is handled by firmware one safety measure I added is if
> firmware lost contact with the host testing was automatically stopped and TX
> FIR values were reset to factory. This ensured that the NIC won't get stuck in
> testing and on initialization the driver doesn't have to worry about testing
> state.

That will work for firmware, but not when Linux is driving the
hardware. I don't know if netlink will allow it, or if RTNL will get
in the way etc, but it could be we actually don't want a start and
stop commands at all, it is a blocking netlink call, and the test runs
until the user space process closes the socket?

      Andrew

Re: Ethtool : PRBS feature

[Alexander Duyck]

On Tue, Jun 23, 2026 at 7:30 PM Andrew Lunn <andrew@lunn.ch> wrote:
>
> >     To avoid race conditions, maybe some of these commands need combining.
> >     ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start
> >
> >     The configuration is then atomic, with respect to the uAPI, so we
> >     don't get two users configuring it at the same time, ending up with a
> >     messed up configuration.
> >
> > Testing consumes the link so you really don't want anything done to the netdev
> > while testing is running. fbnic does the following.
> >
> > 1. Testing cannot start when the link is up
>
> That is not going to work in the generic case. Many MAC drivers don't
> bind to there PCS or PHY until open() is called. So there is no way to
> pass the uAPI calls onto the PCS or PHY if the interface is
> down. There are also some MACs which connect to multiple PCSs, and
> there can be multiple PHYs. So you need to somehow indicate which
> PCS/PHY should perform the PRBS. There was a discussion about loopback
> recently, which has the same issue, you can perform loopback testing
> in multiple places. So i expect the same concept will be used for
> this.

I would think something like this would still be usable. You would
just need to specify the phy address and possibly device address in
the case that you support doing such testing at multiple layers.
Basically it would be up to the driver to provide a way to connect the
request with the desired interface. I would imagine something similar
is the case for the loopback handling since there are so many layers
where you can hairpin things back to the port it came in on.

> > 2. Once testing starts the driver removes the netdev to prevent use. The netdev
> > is only added back when testing stops. The upstream solution will need
> > something that can keep the netdev but lock everything down while testing is
> > running.
>
> Probably IF_OPER_TESTING would be part of this. If the interface is in
> this state, you want many other things blocked. However, probably
> ksettings get/set need to work, so you can force the link into a
> specific mode.

I would imagine it depends on if you want to enforce ordering on this
or not. I would say the set would probably need to be blocked as you
wouldn't normally want to be changing the setting in the middle of a
test as it would cause the error stats to climb quickly.

> > 3. Once testing starts you cannot change the test, even on an individual lane
> > basis. You must stop testing first.
> >
> >
> >     Traditionally, Unix does not offer a way to clear statistic counters
> >     back to zero. So i'm not sure about clear-stats. We also need to think
> >     about hardware which does not support that. And there is locking
> >     issues, can the stats be cleared while a test is active?
> >
> > fbnic actually has separate registers for PRBS test results. Results do need to
> > be clean between runs but I never created an explicit clear interface. Firmware
> > automatically reset the registers when a new test was started. This also allows
> > results to be viewed after testing has stopped.
>
> We should really take 802.3 as the model, but i've not had time yet to
> read what it says about the statistics.

I think most of this is all called out in the IEEE 802.3-2022 spec
under section 45.2.1.169 - 45.2.1.174. Basically the ability and
controls live in the 1500 range, Tx error statistics in the 1600, and
Rx statistics in the 1700 range.

> > Reading results was a little tricky due to roll over between two 32bit
> > registers.
>
> 802.3 is make this even more interesting, since those registers are 16
> bits.

Yeah, normally to deal with something like that we would likely be
looking at having to maintain a fairly high read frequency. Although
in theory the error counts shouldn't be climbing that fast anyway. The
spec calls out that the registers are clear on read and held at ~0 in
the event of overflow which would be a failing case for any reasonable
test anyway.

> > When I spoke to hardware engineers at Meta they did not want a timeout. Testing
> > often occurred over days, so they wanted to be able to start it and explicitly
> > stop it. I'm not against a time out but I do think it should be optional.
> >
> > Since PRBS testing is handled by firmware one safety measure I added is if
> > firmware lost contact with the host testing was automatically stopped and TX
> > FIR values were reset to factory. This ensured that the NIC won't get stuck in
> > testing and on initialization the driver doesn't have to worry about testing
> > state.
>
> That will work for firmware, but not when Linux is driving the
> hardware. I don't know if netlink will allow it, or if RTNL will get
> in the way etc, but it could be we actually don't want a start and
> stop commands at all, it is a blocking netlink call, and the test runs
> until the user space process closes the socket?

What we would probably need to do is look at testing as a state rather
than an operation. Basically the NIC would be put into the testing
state and as a result it would just be sitting there emitting whatever
test pattern it is supposed to emit, and validating it is receiving
the pattern it expects to receive.

The statistics could probably just be a subset of the PHY statistics
that could be collected separately. Actually now that I think about it
I wonder if we couldn't look at putting together the interface similar
to how we currently handle FEC where you have the --set-fec interface
to configure things and the --show-fec interface with the -I option to
show the current state and also dump the statistics.

RE: Ethtool : PRBS feature

[Das, Shubham]

Hi All,

Below are the proposed modifications to the UAPI, data structures, and Netlink messages to support PRBS/BERT and test pattern configuration.

diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
index 5e9135e3774f..cb11e139dd81 100644
--- a/Documentation/netlink/specs/ethtool.yaml
+++ b/Documentation/netlink/specs/ethtool.yaml
@@ -30,6 +30,36 @@ definitions:
+    name: phy-test-pattern
+    enum-name: phy-test-pattern
+    type: enum
+    name-prefix: phy-test-pattern-
+    doc: PRBS and other PHY test patterns
+    entries:
+      - off
+      - prbs7
+      - prbs9
+      - prbs11
+      - prbs13
+      - prbs15
+      - prbs23
+      - prbs31
+      - ssprq
+      - prbs13q
+      - prbs31q
+      - square
+  -
+    name: phy-test-action
+    enum-name: phy-test-action
+    type: enum
+    name-prefix: phy-test-action-
+    doc: Actions for PHY BERT test control
+    entries:
+      - none
+      - start
+      - stop
+      - stats
   -
     name: header-flags
     type: flags
@@ -1818,6 +1848,58 @@ attribute-sets:
         type: u32
         enum: loopback-type
 
+  -
+    name: phy-test
+    attr-cnt-name: __ethtool-a-phy-test-cnt
+    doc: |
+      PHY test configuration for pattern generation/checking,
+      BERT (Bit Error Rate Test), and statistics.
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: header
+        type: nest
+        nested-attributes: header
+      -
+        name: tx-pattern
+        type: u32
+        doc: TX test pattern type (PRBS or square wave)
+        enum: phy-test-pattern
+      -
+        name: rx-pattern
+        type: u32
+        doc: RX checker pattern type (PRBS or square wave)
+        enum: phy-test-pattern
+      -
+        name: bert-action
+        type: u32
+        doc: BERT test start/stop/stats
+        enum: phy-test-action
+      -
+        name: inject-error-count
+        type: u32
+        doc: |
+          Number of errors to inject. Each invocation injects the specified
+          number of bit errors into the data stream.
+      -
+        name: ber-lock-status
+        type: u8
+        doc: PRBS lock status (1=locked, 0=not locked)
+      -
+        name: ber-error-count
+        type: u64
+        doc: BERT bit error count
+      -
+        name: ber-total-bits-sent
+        type: u64
+        doc: BERT total bits tested
+      -
+        name: supported-test-patterns
+        type: u32
+        doc: Bitmask of supported test patterns
 
   -
     name: phy-tunable
@@ -2924,6 +3006,53 @@ operations:
            - header
            - enabled
            - type
+    -
+      name: phy-test-act
+      doc: |
+        Configure PHY test parameters. Each attribute is optional and only
+        specified attributes are applied. TX/RX patterns are set on the
+        local port. BERT and error injection operate on the receiver port.
+        When bert-action is stats, a reply with BERT counters is returned.
+        Typical workflow:
+          ethtool --phy-test eth1 tx-pattern prbs7  (TX side)
+          ethtool --phy-test eth2 rx-pattern prbs7  (RX side)
+          ethtool --phy-test eth2 bert start        (start BERT on RX)
+          ethtool --phy-test eth2 bert stats        (read counters and lock status)
+          ethtool --phy-test eth2 bert stop         (stop BERT)
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+            - tx-pattern
+            - rx-pattern
+            - bert-action
+            - inject-error-count
+        reply:
+          attributes:
+            - header
+            - ber-lock-status
+            - ber-error-count
+            - ber-total-bits-sent
+    -
+      name: phy-test-get
+      doc: |
+        Get PHY test configuration status and supported patterns.
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+        reply:
+          attributes:
+            - header
+            - tx-pattern
+            - rx-pattern
+            - supported-test-patterns
 
 mcast-groups:
   list:
diff --git a/include/linux/ethtool.h b/include/linux/ethtool.h
index 1ac85b8aebd7..3bcca506cf7b 100644
--- a/include/linux/ethtool.h
+++ b/include/linux/ethtool.h

+/* Bitmask of which ethtool_phy_test fields were explicitly specified */
+#define PHY_TEST_CMD_TX_PATTERN		    BIT(0)
+#define PHY_TEST_CMD_RX_PATTERN		    BIT(1)
+#define PHY_TEST_CMD_BERT_ACTION	    BIT(2)
+#define PHY_TEST_CMD_INJECT_COUNT	    BIT(3)
+
+/**
+ * struct ethtool_phy_test - PHY test configuration and status
+ * @cmd: Bitmask of PHY_TEST_CMD_* indicating which fields to apply (SET)
+ * @tx_pattern: TX test pattern
+ * @rx_pattern: RX checker pattern
+ * @bert_action: BERT start/stop/stats action
+ * @inject_error_count: Number of bit errors to inject (SET only)
+ * @supported_test_patterns: Bitmask of supported patterns (GET only)
+ * @ber_lock_status: BER lock status 1=locked, 0=not locked (GET only)
+ * @ber_error_count: BERT bit error count (GET only)
+ * @ber_total_bits_sent: BERT total bits tested (GET only)
+ */
+struct ethtool_phy_test {
+	u32 cmd;
+	enum phy_test_pattern tx_pattern;
+	enum phy_test_pattern rx_pattern;
+	enum phy_test_action bert_action;
+	u32 inject_error_count;
+	u32 supported_test_patterns;
+	u8 ber_lock_status;
+	u64 ber_error_count;
+	u64 ber_total_bits_sent;
+};
+
 /**
  * struct ethtool_ops - optional netdev operations
  * @supported_input_xfrm: supported types of input xfrm from %RXH_XFRM_*.
@@ -1091,7 +1121,8 @@ struct ethtool_loopback {
  * @get_mm: Query the 802.3 MAC Merge layer state.
  * @set_mm: Set the 802.3 MAC Merge layer parameters.
  * @get_mm_stats: Query the 802.3 MAC Merge layer statistics.
- *
+ * @get_phy_test: Get PHY test status, patterns, and BERT counters.
+ * @set_phy_test: Configure PHY test (pattern, BERT, error injection). *
  * All operations are optional (i.e. the function pointer may be set
  * to %NULL) and callers must take this into account.  Callers must
  * hold the RTNL lock.
@@ -1260,6 +1291,10 @@ struct ethtool_ops {
 	void	(*get_mm_stats)(struct net_device *dev, struct ethtool_mm_stats *stats);
+	int	(*get_phy_test)(struct net_device *dev,
+				struct ethtool_phy_test *test);
+	int	(*set_phy_test)(struct net_device *dev,
+				struct ethtool_phy_test *test);
 };


The 'tx_prbs' and 'rx_prbs' command parameters have been renamed to 'tx_pattern' and 'rx_pattern' to allow support
for additional test patterns defined in the RFC, such as square patterns, in addition to PRBS.

The statistics have been moved to the 'ber' test command.

I also think it would be better to expose 'tx_pattern' and 'rx_pattern' as separate commands,
since the TX and RX ports can be different. They are only the same when operating in loopback mode.


> You need to think about the units for inject errors. There is no floating point support. Also, is this corrupt packets? 
> Or single bit flips in the stream? It needs to be well defined what it actually means. The driver can then convert it to whatever the hardware supports. How does 802.3 specify this?

I believe it is not mentioned in IEEE specs, But it will be helpful in debug in both data and PRBS mode.
Maybe we can have number of errors injected in steam when we issue command rather than error rate ?


> Traditionally, Unix does not offer a way to clear statistic counters back to zero. So i'm not sure about clear-stats.
> We also need to think about hardware which does not support that. And there is locking issues, can the stats be cleared while a test is active? 

I think we can auto clear in PHY FW or in implementation when we start the test.

Also, as previously suggested we need new status to indicate device is under test for net device.
 
- Shubham D

> -----Original Message-----
> From: Alexander Duyck <alexander.duyck@gmail.com>
> Sent: 24 June 2026 21:06
> To: Andrew Lunn <andrew@lunn.ch>
> Cc: Lee Trager <lee@trager.us>; Das, Shubham <shubham.das@intel.com>;
> Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org;
> mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle,
> Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> Subject: Re: Ethtool : PRBS feature
> 
> On Tue, Jun 23, 2026 at 7:30 PM Andrew Lunn <andrew@lunn.ch> wrote:
> >
> > >     To avoid race conditions, maybe some of these commands need combining.
> > >     ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start
> > >
> > >     The configuration is then atomic, with respect to the uAPI, so we
> > >     don't get two users configuring it at the same time, ending up with a
> > >     messed up configuration.
> > >
> > > Testing consumes the link so you really don't want anything done to
> > > the netdev while testing is running. fbnic does the following.
> > >
> > > 1. Testing cannot start when the link is up
> >
> > That is not going to work in the generic case. Many MAC drivers don't
> > bind to there PCS or PHY until open() is called. So there is no way to
> > pass the uAPI calls onto the PCS or PHY if the interface is down.
> > There are also some MACs which connect to multiple PCSs, and there can
> > be multiple PHYs. So you need to somehow indicate which PCS/PHY should
> > perform the PRBS. There was a discussion about loopback recently,
> > which has the same issue, you can perform loopback testing in multiple
> > places. So i expect the same concept will be used for this.
> 
> I would think something like this would still be usable. You would just need to
> specify the phy address and possibly device address in the case that you support
> doing such testing at multiple layers.
> Basically it would be up to the driver to provide a way to connect the request with
> the desired interface. I would imagine something similar is the case for the
> loopback handling since there are so many layers where you can hairpin things
> back to the port it came in on.
> 
> > > 2. Once testing starts the driver removes the netdev to prevent use.
> > > The netdev is only added back when testing stops. The upstream
> > > solution will need something that can keep the netdev but lock
> > > everything down while testing is running.
> >
> > Probably IF_OPER_TESTING would be part of this. If the interface is in
> > this state, you want many other things blocked. However, probably
> > ksettings get/set need to work, so you can force the link into a
> > specific mode.
> 
> I would imagine it depends on if you want to enforce ordering on this or not. I
> would say the set would probably need to be blocked as you wouldn't normally
> want to be changing the setting in the middle of a test as it would cause the error
> stats to climb quickly.
> 
> > > 3. Once testing starts you cannot change the test, even on an
> > > individual lane basis. You must stop testing first.
> > >
> > >
> > >     Traditionally, Unix does not offer a way to clear statistic counters
> > >     back to zero. So i'm not sure about clear-stats. We also need to think
> > >     about hardware which does not support that. And there is locking
> > >     issues, can the stats be cleared while a test is active?
> > >
> > > fbnic actually has separate registers for PRBS test results. Results
> > > do need to be clean between runs but I never created an explicit
> > > clear interface. Firmware automatically reset the registers when a
> > > new test was started. This also allows results to be viewed after testing has
> stopped.
> >
> > We should really take 802.3 as the model, but i've not had time yet to
> > read what it says about the statistics.
> 
> I think most of this is all called out in the IEEE 802.3-2022 spec under section
> 45.2.1.169 - 45.2.1.174. Basically the ability and controls live in the 1500 range,
> Tx error statistics in the 1600, and Rx statistics in the 1700 range.
> 
> > > Reading results was a little tricky due to roll over between two
> > > 32bit registers.
> >
> > 802.3 is make this even more interesting, since those registers are 16
> > bits.
> 
> Yeah, normally to deal with something like that we would likely be looking at
> having to maintain a fairly high read frequency. Although in theory the error
> counts shouldn't be climbing that fast anyway. The spec calls out that the registers
> are clear on read and held at ~0 in the event of overflow which would be a failing
> case for any reasonable test anyway.
> 
> > > When I spoke to hardware engineers at Meta they did not want a
> > > timeout. Testing often occurred over days, so they wanted to be able
> > > to start it and explicitly stop it. I'm not against a time out but I do think it
> should be optional.
> > >
> > > Since PRBS testing is handled by firmware one safety measure I added
> > > is if firmware lost contact with the host testing was automatically
> > > stopped and TX FIR values were reset to factory. This ensured that
> > > the NIC won't get stuck in testing and on initialization the driver
> > > doesn't have to worry about testing state.
> >
> > That will work for firmware, but not when Linux is driving the
> > hardware. I don't know if netlink will allow it, or if RTNL will get
> > in the way etc, but it could be we actually don't want a start and
> > stop commands at all, it is a blocking netlink call, and the test runs
> > until the user space process closes the socket?
> 
> What we would probably need to do is look at testing as a state rather than an
> operation. Basically the NIC would be put into the testing state and as a result it
> would just be sitting there emitting whatever test pattern it is supposed to emit,
> and validating it is receiving the pattern it expects to receive.
> 
> The statistics could probably just be a subset of the PHY statistics that could be
> collected separately. Actually now that I think about it I wonder if we couldn't
> look at putting together the interface similar to how we currently handle FEC
> where you have the --set-fec interface to configure things and the --show-fec
> interface with the -I option to show the current state and also dump the
> statistics.

Re: Ethtool : PRBS feature

[Andrew Lunn]

> +        name: inject-error-count
> +        type: u32
> +        doc: |
> +          Number of errors to inject. Each invocation injects the specified
> +          number of bit errors into the data stream.

Sorry, but i could not implement that, in a sensible way, given its
current specification.

I suppose i could simply flip the first `inject-error-count` bits, and
make the rest of the stream perfect? I could also wait until the stop
command is received, and then flip that many bits before i stop the
stream? But none of these seem sensible.

Please make this specification have sufficient details, or references
to 802.3, that you could give it to another engineer and get back a
reasonable implementation, without having to answer any questions.

> +      name: phy-test-act
> +      doc: |
> +        Configure PHY test parameters. Each attribute is optional and only
> +        specified attributes are applied. TX/RX patterns are set on the
> +        local port. BERT and error injection operate on the receiver port.

Error injection operates on the receive port? That is not what i
expected. I should go read 802.3, and understand how this is used.

	Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

> Sorry, but i could not implement that, in a sensible way, given its current
> specification.
> 
> I suppose i could simply flip the first `inject-error-count` bits, and make the rest of
> the stream perfect? I could also wait until the stop command is received, and
> then flip that many bits before i stop the stream? But none of these seem
> sensible.
> 
> Please make this specification have sufficient details, or references to 802.3, that
> you could give it to another engineer and get back a reasonable implementation,
> without having to answer any questions.

Andrew,

IEEE has clear documentation of the PRBS Receiver block and the BER counter as an output.
Before performing the actual BER validation, it is a usual industry practice to introduce errors
to guarantee that the checker is functional and accurately identifying them.

Similarly, in DATA mode, error injection is used to verify the FEC block
by ensuring that injected errors are detected and corrected as expected.

Updated description.

+        name: inject-error-count
+        type: u32
+        doc: |
+          Request the PHY to inject exactly this many bit errors into the
+          currently active test data stream.
+
+          This is a diagnostic tool used to validate that the far-end PRBS
+          checker or FEC decoder is functioning correctly. For example,
+          after enabling a PRBS pattern and confirming ber-lock-status is
+          locked, injecting N errors should cause ber-error-count to
+          increment by exactly N on the receiving port, confirming the
+          checker is actively detecting bit errors. Similarly, in normal
+          data mode with FEC enabled, injecting errors verifies that the
+          FEC block detects errors as expected.

> > +      name: phy-test-act
> > +      doc: |
> > +        Configure PHY test parameters. Each attribute is optional and only
> > +        specified attributes are applied. TX/RX patterns are set on the
> > +        local port. BERT and error injection operate on the receiver port.
> 
> Error injection operates on the receive port? That is not what i expected. I should
> go read 802.3, and understand how this is used.

Thanks for the correction, it is in transmit direction, Updated description.

+      name: phy-test-act
+      doc: |
+        Configure PHY test parameters. Each attribute is optional and only
+        specified attributes are applied. TX/RX patterns are set on the
+        local port. BERT operates on the receiver port, while errors
+        are injected through the PRBS/DATA transmission port. 
+        When bert-action is stats, a reply with BERT counters is returned.
+        Typical workflow:
+          ethtool --phy-test eth1 tx-pattern prbs7  (TX side)
+          ethtool --phy-test eth2 rx-pattern prbs7  (RX side)
+          ethtool --phy-test eth2 bert start        (start BERT on RX)
+          ethtool --phy-test eth2 bert stats        (read counters)
+          ethtool --phy-test eth2 bert stop         (stop BERT)

- Shubham D


> -----Original Message-----
> From: Andrew Lunn <andrew@lunn.ch>
> Sent: 29 June 2026 22:27
> To: Das, Shubham <shubham.das@intel.com>
> Cc: Alexander Duyck <alexander.duyck@gmail.com>; Lee Trager <lee@trager.us>;
> Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org;
> mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle,
> Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
> Subject: Re: Ethtool : PRBS feature
> 
> > +        name: inject-error-count
> > +        type: u32
> > +        doc: |
> > +          Number of errors to inject. Each invocation injects the specified
> > +          number of bit errors into the data stream.
> 
> Sorry, but i could not implement that, in a sensible way, given its current
> specification.
> 
> I suppose i could simply flip the first `inject-error-count` bits, and make the rest of
> the stream perfect? I could also wait until the stop command is received, and
> then flip that many bits before i stop the stream? But none of these seem
> sensible.
> 
> Please make this specification have sufficient details, or references to 802.3, that
> you could give it to another engineer and get back a reasonable implementation,
> without having to answer any questions.
> 
> > +      name: phy-test-act
> > +      doc: |
> > +        Configure PHY test parameters. Each attribute is optional and only
> > +        specified attributes are applied. TX/RX patterns are set on the
> > +        local port. BERT and error injection operate on the receiver port.
> 
> Error injection operates on the receive port? That is not what i expected. I should
> go read 802.3, and understand how this is used.
> 
> 	Andrew

Re: Ethtool : PRBS feature

[Andrew Lunn]

On Wed, Jul 01, 2026 at 05:10:43PM +0000, Das, Shubham wrote:
> > Sorry, but i could not implement that, in a sensible way, given its current
> > specification.
> > 
> > I suppose i could simply flip the first `inject-error-count` bits, and make the rest of
> > the stream perfect? I could also wait until the stop command is received, and
> > then flip that many bits before i stop the stream? But none of these seem
> > sensible.
> > 
> > Please make this specification have sufficient details, or references to 802.3, that
> > you could give it to another engineer and get back a reasonable implementation,
> > without having to answer any questions.
> 
> Andrew,
> 
> IEEE has clear documentation of the PRBS Receiver block and the BER counter as an output.
> Before performing the actual BER validation, it is a usual industry practice to introduce errors
> to guarantee that the checker is functional and accurately identifying them.
> 
> Similarly, in DATA mode, error injection is used to verify the FEC block
> by ensuring that injected errors are detected and corrected as expected.
> 
> Updated description.
> 
> +        name: inject-error-count
> +        type: u32
> +        doc: |
> +          Request the PHY to inject exactly this many bit errors into the
> +          currently active test data stream.
> +
> +          This is a diagnostic tool used to validate that the far-end PRBS
> +          checker or FEC decoder is functioning correctly. For example,
> +          after enabling a PRBS pattern and confirming ber-lock-status is
> +          locked, injecting N errors should cause ber-error-count to
> +          increment by exactly N on the receiving port, confirming the
> +          checker is actively detecting bit errors. Similarly, in normal
> +          data mode with FEC enabled, injecting errors verifies that the
> +          FEC block detects errors as expected.

There is no mention of how many frames to send in the stream. I don't
think that is part of the API? Because we have no idea of how many
frames will be sent, it is not possible to distribute the corrupted
frames over the duration of the stream. So that means i should flip
one bit, anywhere in the first inject-error-count frames. All frames
after that should not have bit flips. The assumption being, the stream
has a minimum of inject-error-count frames, and if the stream is
short, the counter will be too low. But it does not matter if the
stream is longer.

Your description has no mention of frames. Should it? What exactly
does the ber-error-count count? Can multiple bit flip within one frame
be counted individually? I don't see how, since the checksum just says
the frame is bad, and cannot report how bad.

As i said, give this description to another engineer and ask him/her
how it could be implemented.

https://www.youtube.com/watch?v=j-6N3bLgYyQ

	Andrew

Re: Ethtool : PRBS feature

[Srinivasan, Vijay]

[-- Attachment #1.1: Type: text/plain, Size: 6186 bytes --]

Hi Andrew,
I think there is a disconnect here. Please see the diagram attached indicating the error injection location.
Here, we are referring to error injection at the "bit" level, not "frame" level.
Bit error(s) injected at the PMA/PMD boundary, does not distinguish between data (Frames) vs test patterns (PRBS).
Many SerDes IP's , if not all, include error injection as part of the test pattern block (BIST in the diagram).
Some IP's may have error injection outside of BIST in the common data path (as shown in the diagram) in which case bit errors may be injected in both data mode (frame/traffic) and test pattern mode (BIST).
Regardless, we are seeking error injection capability at PMA/PMD to be made available through user/driver space (ethtool) .

Notes:

  1.
Error injection can be "one-shot" (single error) or continuous (fixed rate, say 1 bit error every 10**6 bits (1E-6)).
  2.
Error injection availability is IP/API dependent. One-shot mode is highly likely to be available in all SerDes IP's.
  3.
Error injection location and implementation is IP dependent.
  4.
If IP/API supported:
     *
One-shot error injected in test pattern (PRBS) mode captured as individual/single bit error at the far-end checker.
     *
One-shot error injected in data (traffic/frame) mode captured as:
        *
Individual/single corrected codeword error if FEC is used for the link
        *
Individual/single CRC:  (a) if FEC is not used for the link and (b) if bit error injected corrupts any of the bits used to compute CRC.
     *
Effect of errors injected at fixed rate is a corollary to one-shot with additional :
        *
Errors injected at higher rates (> 1E-4) may result in uncorrected FEC codewords or loss of link
        *
Presence of uncorrected FEC codewords will lead to MAC CRCs

What is requested:

  1.
One-shot bit error injection (required/preferred), fixed rate is optional

How to inject error:

  1.
Test pattern mode:
     *
Generate any PRBS pattern
     *
Configure error checker on receive side (same device in loopback mode or far-end device) - measure Bit Error Ratio (BER) without error injection
     *
Inject error and verify BER>0 (if BER==0 without injection)
  2.
Data (Traffic/Frame) mode:
     *
Configure and establish link (same device in loopback mode or far-end device)
     *
Measure MAC CRC and/or FEC corrected/uncorrected codeword counts
     *
Inject error and verify MAC CRC or FEC corrected counts match injected error count



Vijay

________________________________
From: Andrew Lunn <andrew@lunn.ch>
Sent: Wednesday, July 1, 2026 10:32 AM
To: Das, Shubham <shubham.das@intel.com>
Cc: Alexander Duyck <alexander.duyck@gmail.com>; Lee Trager <lee@trager.us>; Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org <netdev@vger.kernel.org>; mkubecek@suse.cz <mkubecek@suse.cz>; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle, Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com <niklas.damberg@ericsson.com>; Wirandi, Jonas <jonas.wirandi@ericsson.com>; Srinivasan, Vijay <vijay.srinivasan@intel.com>
Subject: Re: Ethtool : PRBS feature

On Wed, Jul 01, 2026 at 05:10:43PM +0000, Das, Shubham wrote:
> > Sorry, but i could not implement that, in a sensible way, given its current
> > specification.
> >
> > I suppose i could simply flip the first `inject-error-count` bits, and make the rest of
> > the stream perfect? I could also wait until the stop command is received, and
> > then flip that many bits before i stop the stream? But none of these seem
> > sensible.
> >
> > Please make this specification have sufficient details, or references to 802.3, that
> > you could give it to another engineer and get back a reasonable implementation,
> > without having to answer any questions.
>
> Andrew,
>
> IEEE has clear documentation of the PRBS Receiver block and the BER counter as an output.
> Before performing the actual BER validation, it is a usual industry practice to introduce errors
> to guarantee that the checker is functional and accurately identifying them.
>
> Similarly, in DATA mode, error injection is used to verify the FEC block
> by ensuring that injected errors are detected and corrected as expected.
>
> Updated description.
>
> +        name: inject-error-count
> +        type: u32
> +        doc: |
> +          Request the PHY to inject exactly this many bit errors into the
> +          currently active test data stream.
> +
> +          This is a diagnostic tool used to validate that the far-end PRBS
> +          checker or FEC decoder is functioning correctly. For example,
> +          after enabling a PRBS pattern and confirming ber-lock-status is
> +          locked, injecting N errors should cause ber-error-count to
> +          increment by exactly N on the receiving port, confirming the
> +          checker is actively detecting bit errors. Similarly, in normal
> +          data mode with FEC enabled, injecting errors verifies that the
> +          FEC block detects errors as expected.

There is no mention of how many frames to send in the stream. I don't
think that is part of the API? Because we have no idea of how many
frames will be sent, it is not possible to distribute the corrupted
frames over the duration of the stream. So that means i should flip
one bit, anywhere in the first inject-error-count frames. All frames
after that should not have bit flips. The assumption being, the stream
has a minimum of inject-error-count frames, and if the stream is
short, the counter will be too low. But it does not matter if the
stream is longer.

Your description has no mention of frames. Should it? What exactly
does the ber-error-count count? Can multiple bit flip within one frame
be counted individually? I don't see how, since the checksum just says
the frame is bad, and cannot report how bad.

As i said, give this description to another engineer and ask him/her
how it could be implemented.

https://www.youtube.com/watch?v=j-6N3bLgYyQ

        Andrew

[-- Attachment #1.2: Type: text/html, Size: 16159 bytes --]

[-- Attachment #2: Error Injection at Bit Level.pdf --]
[-- Type: application/pdf, Size: 38062 bytes --]

Re: Ethtool : PRBS feature

[Andrew Lunn]

On Wed, Jul 01, 2026 at 09:38:08PM +0000, Srinivasan, Vijay wrote:
> Hi Andrew,
> I think there is a disconnect here.

Which proves my point. The specification is not sufficient if you have
to keep correcting me.

The kAPI should be understandable by somebody who has a general
networking background. Please write a specification with that
assumption in mind. Don't assume the reader is a test engineer who has
used PRBS for half his life. Assume it is a brand new test engineer
who is hearing PRBS for the first time. That is what most engineers on
the netdev list are. Me included.

    Andrew

Re: Ethtool : PRBS feature

[Lee Trager]

On 6/29/26 9:15 AM, Das, Shubham wrote:

> Hi All,
>
> Below are the proposed modifications to the UAPI, data structures, and Netlink messages to support PRBS/BERT and test pattern configuration.
>
> diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
> index 5e9135e3774f..cb11e139dd81 100644
> --- a/Documentation/netlink/specs/ethtool.yaml
> +++ b/Documentation/netlink/specs/ethtool.yaml
> @@ -30,6 +30,36 @@ definitions:
> +    name: phy-test-pattern
> +    enum-name: phy-test-pattern
> +    type: enum
> +    name-prefix: phy-test-pattern-
> +    doc: PRBS and other PHY test patterns
> +    entries:
> +      - off
> +      - prbs7
> +      - prbs9
> +      - prbs11

fbnic supports a number of other tests as well. Getting the full list of 
common PRBS tests codified would be ideal

- prbs11.0

- prbs11.1

- prbs11.2

- prbs11.3

> +      - prbs13

  - prbs13.0

- prbs13.1

- prbs13.2

- prbs13.3

> +      - prbs15
- prbs16
> +      - prbs23
> +      - prbs31
- prbs32
> +      - ssprq
> +      - prbs13q
> +      - prbs31q
> +      - square
> +  -
> +    name: phy-test-action
> +    enum-name: phy-test-action
Each lane and each direction is a completely separate test with its own 
test of statistics. The test is actually verified on the Rx side, Tx is 
your generator so you won't have data to collect. So when you run PRBS 
testing on a 2 lane NIC you are actually running 4 independent tests. 
While its fine to have a shortcut to run the same test on all lanes we 
absolutely need a way to run tests per lane and the ability to choose 
Rx, Tx, or both.
> +    type: enum
> +    name-prefix: phy-test-action-
> +    doc: Actions for PHY BERT test control
> +    entries:
> +      - none
> +      - start
> +      - stop
> +      - stats
I wouldn't consider stats a phy-test action. It shouldn't change the 
state of the NIC at all. I would just add phy-test-stats as set of 
standard ethtool statistics.
>     -
>       name: header-flags
>       type: flags
> @@ -1818,6 +1848,58 @@ attribute-sets:
>           type: u32
>           enum: loopback-type
>   
> +  -
> +    name: phy-test
> +    attr-cnt-name: __ethtool-a-phy-test-cnt
> +    doc: |
> +      PHY test configuration for pattern generation/checking,
> +      BERT (Bit Error Rate Test), and statistics.
> +    attributes:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0
> +      -
> +        name: header
> +        type: nest
> +        nested-attributes: header
> +      -
> +        name: tx-pattern
> +        type: u32
> +        doc: TX test pattern type (PRBS or square wave)
> +        enum: phy-test-pattern
> +      -
> +        name: rx-pattern
> +        type: u32
> +        doc: RX checker pattern type (PRBS or square wave)
> +        enum: phy-test-pattern
> +      -
> +        name: bert-action
> +        type: u32
> +        doc: BERT test start/stop/stats
> +        enum: phy-test-action
> +      -
> +        name: inject-error-count
> +        type: u32
> +        doc: |
> +          Number of errors to inject. Each invocation injects the specified
> +          number of bit errors into the data stream.
> +      -
> +        name: ber-lock-status
> +        type: u8
> +        doc: PRBS lock status (1=locked, 0=not locked)
> +      -
> +        name: ber-error-count
> +        type: u64
> +        doc: BERT bit error count
> +      -
> +        name: ber-total-bits-sent
> +        type: u64
> +        doc: BERT total bits tested
> +      -
> +        name: supported-test-patterns
> +        type: u32
> +        doc: Bitmask of supported test patterns
Again all of this needs to be per lane.
>   
>     -
>       name: phy-tunable
> @@ -2924,6 +3006,53 @@ operations:
>              - header
>              - enabled
>              - type
> +    -
> +      name: phy-test-act
> +      doc: |
> +        Configure PHY test parameters. Each attribute is optional and only
> +        specified attributes are applied. TX/RX patterns are set on the
> +        local port. BERT and error injection operate on the receiver port.
> +        When bert-action is stats, a reply with BERT counters is returned.
> +        Typical workflow:
> +          ethtool --phy-test eth1 tx-pattern prbs7  (TX side)
> +          ethtool --phy-test eth2 rx-pattern prbs7  (RX side)
> +          ethtool --phy-test eth2 bert start        (start BERT on RX)
> +          ethtool --phy-test eth2 bert stats        (read counters and lock status)
> +          ethtool --phy-test eth2 bert stop         (stop BERT)
> +
> +      attribute-set: phy-test
> +
> +      do:
> +        request:
> +          attributes:
> +            - header
> +            - tx-pattern
> +            - rx-pattern
> +            - bert-action
> +            - inject-error-count
> +        reply:
> +          attributes:
> +            - header
> +            - ber-lock-status
> +            - ber-error-count
> +            - ber-total-bits-sent
> +    -
> +      name: phy-test-get
> +      doc: |
> +        Get PHY test configuration status and supported patterns.
> +
> +      attribute-set: phy-test
> +
> +      do:
> +        request:
> +          attributes:
> +            - header
> +        reply:
> +          attributes:
> +            - header
> +            - tx-pattern
> +            - rx-pattern
> +            - supported-test-patterns
>   
>   mcast-groups:
>     list:
> diff --git a/include/linux/ethtool.h b/include/linux/ethtool.h
> index 1ac85b8aebd7..3bcca506cf7b 100644
> --- a/include/linux/ethtool.h
> +++ b/include/linux/ethtool.h
>
> +/* Bitmask of which ethtool_phy_test fields were explicitly specified */
> +#define PHY_TEST_CMD_TX_PATTERN		    BIT(0)
> +#define PHY_TEST_CMD_RX_PATTERN		    BIT(1)
> +#define PHY_TEST_CMD_BERT_ACTION	    BIT(2)
> +#define PHY_TEST_CMD_INJECT_COUNT	    BIT(3)
> +
> +/**
> + * struct ethtool_phy_test - PHY test configuration and status
> + * @cmd: Bitmask of PHY_TEST_CMD_* indicating which fields to apply (SET)
> + * @tx_pattern: TX test pattern
> + * @rx_pattern: RX checker pattern
> + * @bert_action: BERT start/stop/stats action
> + * @inject_error_count: Number of bit errors to inject (SET only)
> + * @supported_test_patterns: Bitmask of supported patterns (GET only)
> + * @ber_lock_status: BER lock status 1=locked, 0=not locked (GET only)
> + * @ber_error_count: BERT bit error count (GET only)
> + * @ber_total_bits_sent: BERT total bits tested (GET only)
> + */
> +struct ethtool_phy_test {
> +	u32 cmd;
> +	enum phy_test_pattern tx_pattern;
> +	enum phy_test_pattern rx_pattern;
> +	enum phy_test_action bert_action;
> +	u32 inject_error_count;
> +	u32 supported_test_patterns;
> +	u8 ber_lock_status;
> +	u64 ber_error_count;
> +	u64 ber_total_bits_sent;
> +};
> +
>   /**
>    * struct ethtool_ops - optional netdev operations
>    * @supported_input_xfrm: supported types of input xfrm from %RXH_XFRM_*.
> @@ -1091,7 +1121,8 @@ struct ethtool_loopback {
>    * @get_mm: Query the 802.3 MAC Merge layer state.
>    * @set_mm: Set the 802.3 MAC Merge layer parameters.
>    * @get_mm_stats: Query the 802.3 MAC Merge layer statistics.
> - *
> + * @get_phy_test: Get PHY test status, patterns, and BERT counters.
> + * @set_phy_test: Configure PHY test (pattern, BERT, error injection). *
>    * All operations are optional (i.e. the function pointer may be set
>    * to %NULL) and callers must take this into account.  Callers must
>    * hold the RTNL lock.
> @@ -1260,6 +1291,10 @@ struct ethtool_ops {
>   	void	(*get_mm_stats)(struct net_device *dev, struct ethtool_mm_stats *stats);
> +	int	(*get_phy_test)(struct net_device *dev,
> +				struct ethtool_phy_test *test);
> +	int	(*set_phy_test)(struct net_device *dev,
> +				struct ethtool_phy_test *test);
>   };
>
>
> The 'tx_prbs' and 'rx_prbs' command parameters have been renamed to 'tx_pattern' and 'rx_pattern' to allow support
> for additional test patterns defined in the RFC, such as square patterns, in addition to PRBS.
>
> The statistics have been moved to the 'ber' test command.
>
> I also think it would be better to expose 'tx_pattern' and 'rx_pattern' as separate commands,
> since the TX and RX ports can be different. They are only the same when operating in loopback mode.
>
>
>> You need to think about the units for inject errors. There is no floating point support. Also, is this corrupt packets?
>> Or single bit flips in the stream? It needs to be well defined what it actually means. The driver can then convert it to whatever the hardware supports. How does 802.3 specify this?
> I believe it is not mentioned in IEEE specs, But it will be helpful in debug in both data and PRBS mode.
> Maybe we can have number of errors injected in steam when we issue command rather than error rate ?
>
>
>> Traditionally, Unix does not offer a way to clear statistic counters back to zero. So i'm not sure about clear-stats.
>> We also need to think about hardware which does not support that. And there is locking issues, can the stats be cleared while a test is active?
> I think we can auto clear in PHY FW or in implementation when we start the test.
>
> Also, as previously suggested we need new status to indicate device is under test for net device.
>   
> - Shubham D
>
>> -----Original Message-----
>> From: Alexander Duyck <alexander.duyck@gmail.com>
>> Sent: 24 June 2026 21:06
>> To: Andrew Lunn <andrew@lunn.ch>
>> Cc: Lee Trager <lee@trager.us>; Das, Shubham <shubham.das@intel.com>;
>> Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org;
>> mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle,
>> Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus
>> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com
>> Subject: Re: Ethtool : PRBS feature
>>
>> On Tue, Jun 23, 2026 at 7:30 PM Andrew Lunn <andrew@lunn.ch> wrote:
>>>>      To avoid race conditions, maybe some of these commands need combining.
>>>>      ethtool --phy-test eth1 tx-prbs prbs7 rx-prbs prbs7 bert start
>>>>
>>>>      The configuration is then atomic, with respect to the uAPI, so we
>>>>      don't get two users configuring it at the same time, ending up with a
>>>>      messed up configuration.
>>>>
>>>> Testing consumes the link so you really don't want anything done to
>>>> the netdev while testing is running. fbnic does the following.
>>>>
>>>> 1. Testing cannot start when the link is up
>>> That is not going to work in the generic case. Many MAC drivers don't
>>> bind to there PCS or PHY until open() is called. So there is no way to
>>> pass the uAPI calls onto the PCS or PHY if the interface is down.
>>> There are also some MACs which connect to multiple PCSs, and there can
>>> be multiple PHYs. So you need to somehow indicate which PCS/PHY should
>>> perform the PRBS. There was a discussion about loopback recently,
>>> which has the same issue, you can perform loopback testing in multiple
>>> places. So i expect the same concept will be used for this.
>> I would think something like this would still be usable. You would just need to
>> specify the phy address and possibly device address in the case that you support
>> doing such testing at multiple layers.
>> Basically it would be up to the driver to provide a way to connect the request with
>> the desired interface. I would imagine something similar is the case for the
>> loopback handling since there are so many layers where you can hairpin things
>> back to the port it came in on.
>>
>>>> 2. Once testing starts the driver removes the netdev to prevent use.
>>>> The netdev is only added back when testing stops. The upstream
>>>> solution will need something that can keep the netdev but lock
>>>> everything down while testing is running.
>>> Probably IF_OPER_TESTING would be part of this. If the interface is in
>>> this state, you want many other things blocked. However, probably
>>> ksettings get/set need to work, so you can force the link into a
>>> specific mode.
>> I would imagine it depends on if you want to enforce ordering on this or not. I
>> would say the set would probably need to be blocked as you wouldn't normally
>> want to be changing the setting in the middle of a test as it would cause the error
>> stats to climb quickly.
>>
>>>> 3. Once testing starts you cannot change the test, even on an
>>>> individual lane basis. You must stop testing first.
>>>>
>>>>
>>>>      Traditionally, Unix does not offer a way to clear statistic counters
>>>>      back to zero. So i'm not sure about clear-stats. We also need to think
>>>>      about hardware which does not support that. And there is locking
>>>>      issues, can the stats be cleared while a test is active?
>>>>
>>>> fbnic actually has separate registers for PRBS test results. Results
>>>> do need to be clean between runs but I never created an explicit
>>>> clear interface. Firmware automatically reset the registers when a
>>>> new test was started. This also allows results to be viewed after testing has
>> stopped.
>>> We should really take 802.3 as the model, but i've not had time yet to
>>> read what it says about the statistics.
>> I think most of this is all called out in the IEEE 802.3-2022 spec under section
>> 45.2.1.169 - 45.2.1.174. Basically the ability and controls live in the 1500 range,
>> Tx error statistics in the 1600, and Rx statistics in the 1700 range.
>>
>>>> Reading results was a little tricky due to roll over between two
>>>> 32bit registers.
>>> 802.3 is make this even more interesting, since those registers are 16
>>> bits.
>> Yeah, normally to deal with something like that we would likely be looking at
>> having to maintain a fairly high read frequency. Although in theory the error
>> counts shouldn't be climbing that fast anyway. The spec calls out that the registers
>> are clear on read and held at ~0 in the event of overflow which would be a failing
>> case for any reasonable test anyway.
>>
>>>> When I spoke to hardware engineers at Meta they did not want a
>>>> timeout. Testing often occurred over days, so they wanted to be able
>>>> to start it and explicitly stop it. I'm not against a time out but I do think it
>> should be optional.
>>>> Since PRBS testing is handled by firmware one safety measure I added
>>>> is if firmware lost contact with the host testing was automatically
>>>> stopped and TX FIR values were reset to factory. This ensured that
>>>> the NIC won't get stuck in testing and on initialization the driver
>>>> doesn't have to worry about testing state.
>>> That will work for firmware, but not when Linux is driving the
>>> hardware. I don't know if netlink will allow it, or if RTNL will get
>>> in the way etc, but it could be we actually don't want a start and
>>> stop commands at all, it is a blocking netlink call, and the test runs
>>> until the user space process closes the socket?
>> What we would probably need to do is look at testing as a state rather than an
>> operation. Basically the NIC would be put into the testing state and as a result it
>> would just be sitting there emitting whatever test pattern it is supposed to emit,
>> and validating it is receiving the pattern it expects to receive.
>>
>> The statistics could probably just be a subset of the PHY statistics that could be
>> collected separately. Actually now that I think about it I wonder if we couldn't
>> look at putting together the interface similar to how we currently handle FEC
>> where you have the --set-fec interface to configure things and the --show-fec
>> interface with the -I option to show the current state and also dump the
>> statistics.

Re: Ethtool : PRBS feature

[Lee Trager]

On 7/1/26 3:02 PM, Andrew Lunn wrote:

> On Wed, Jul 01, 2026 at 09:38:08PM +0000, Srinivasan, Vijay wrote:
>> Hi Andrew,
>> I think there is a disconnect here.
> Which proves my point. The specification is not sufficient if you have
> to keep correcting me.
>
> The kAPI should be understandable by somebody who has a general
> networking background. Please write a specification with that
> assumption in mind. Don't assume the reader is a test engineer who has
> used PRBS for half his life. Assume it is a brand new test engineer
> who is hearing PRBS for the first time. That is what most engineers on
> the netdev list are. Me included.

I think part of the disconnect is that PRBS testing is a signal 
integrity test, not a network test. In this case the phy happens to be 
Ethernet but it could just as easily be PCIE or USB. That is why it was 
heavily suggested to me at netdev 0x19 that this should be done on the 
generic phy layer, not netdev.

Lee

RE: Ethtool : PRBS feature

[Das, Shubham]

Thanks Andrew, Lee for the feedback.

Lee,
I don't see prbs11.0, prbs11.1, prbs11.2, prbs11.3, prbs13.0, prbs13.1, prbs13.2, prbs13.3, prbs16 and prbs32 in IEEE 802.3 2022 standard.
Is this specific to fnic based on base PRBS pattern or it is mentioned in some other standard ?

Each lane and each direction is a completely separate test with its own test of
> statistics. The test is actually verified on the Rx side, Tx is your generator so you
> won't have data to collect. So when you run PRBS testing on a 2 lane NIC you are
> actually running 4 independent tests.
> While its fine to have a shortcut to run the same test on all lanes we absolutely
> need a way to run tests per lane and the ability to choose Rx, Tx, or both.

- Agree, we need lane parameter in commands, Updated command.


> I wouldn't consider stats a phy-test action. It shouldn't change the state of the
> NIC at all. I would just add phy-test-stats as set of standard ethtool statistics.
Yes moved under separate command.

Below are the updated UAPI, data structures, and Netlink messages to support PRBS/BERT and test pattern configuration.

diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
index 5e9135e3774f..113005a5f80a 100644
--- a/Documentation/netlink/specs/ethtool.yaml
+++ b/Documentation/netlink/specs/ethtool.yaml
@@ -30,6 +30,35 @@ definitions:
+  -
+    name: phy-test-pattern
+    enum-name: phy-test-pattern
+    type: enum
+    name-prefix: phy-test-pattern-
+    doc: PRBS and other PHY test patterns
+    entries:
+      - off
+      - prbs7
+      - prbs9
+      - prbs11
+      - prbs13
+      - prbs15
+      - prbs23
+      - prbs31
+      - ssprq
+      - prbs13q
+      - prbs31q
+      - square8

+    name: phy-test-action
+    enum-name: phy-test-action
+    type: enum
+    name-prefix: phy-test-action-
+    doc: Actions for PHY BERT test control
+    entries:
+      - none
+      - start
+      - stop

+    name: phy-test
+    attr-cnt-name: __ethtool-a-phy-test-cnt
+    doc: |
+      PHY test configuration for pattern generation/checking,
+      BERT (Bit Error Rate Test), and statistics.
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: header
+        type: nest
+        nested-attributes: header
+      -
+        name: lane
+        type: u32
+        doc: PHY lane index to target for the test operation
+      -
+        name: tx-pattern
+        type: u32
+        doc: TX test pattern type (PRBS or square8 wave)
+        enum: phy-test-pattern
+      -
+        name: rx-pattern
+        type: u32
+        doc: RX checker pattern type (PRBS or square8 wave)
+        enum: phy-test-pattern
+      -
+        name: bert-action
+        type: u32
+        doc: BERT test start/stop
+        enum: phy-test-action
+      -
+        name: inject-error-count
+        type: u32
+        doc: |
+          Inject a specified number of bit errors into the PHY transmit data
+          stream for diagnostic verification purposes.
+
+          Context and Purpose:
+            When performing Bit Error Ratio Testing (BERT), the receiving side
+            runs a PRBS checker that monitors for bit errors. Before relying
+            on a zero-error BERT result, operators need to confirm Checker
+            state and configuration to qualify result as TRUE.
+            A checker that is broken or misconfigured would also report
+            zero errors, giving a FALSE pass. Error injection provides this
+            confirmation by deliberately introducing a known number of errors
+            on the transmit side and verifying they appear on the receive side.
+
+            Note:
+            Receiver under test maybe in the same port as the transmitter
+            (loopback mode) or a different port in the same device or another
+            device connected to the transmitting port (non-loopback mode).
+
+          Layer and Mechanism:
+            Error injection operates at the PMA/PMD boundary. This is
+            bit-level injection in the serial data stream, not frame-level.
+            The SerDes Built-In Self Test (BIST) block inverts the specified
+            number of bits in the outgoing serial stream. The injection does
+            not distinguish between data frames and test patterns; it
+            corrupts raw bits at the physical layer regardless of what the
+            stream carries.
+
+          Mode of Operation:
+            This command implements "one-shot" injection: a single burst of
+            N bit errors injected immediately. The PHY inverts exactly N
+            consecutive bits in the serial transmit stream at the PMA/PMD
+            layer, then resumes clean transmission. No continuous/fixed-rate
+            injection mode is provided.
+
+          Prerequisites:
+            - A PRBS test pattern must be active on the transmitting port
+              (tx-pattern != off).
+            - The receiving port must have the matching rx-pattern configured
+              and ber-lock-status must be "locked" (indicating the checker
+              has synchronized to the incoming pattern).
+            - BERT must be running on the receiving port (bert start issued).
+
+              Note:
+              Availability of BIST mode test pattern generator, checker and
+              lock indication is IP dependent.
+
+          Semantics:
+            - Fire-and-forget: the command completes immediately. No
+              persistent state is created. Each invocation is an independent
+              injection event.
+            - The command may be issued multiple times. Each invocation
+              injects an additional burst of errors (counts accumulate on
+              the receiver's ber-error-count across invocations).
+            - If no test pattern is active, the behaviour is
+              implementation-defined (hardware may silently ignore the
+              request or return an error).
+
+          Expected Outcome:
+            After injecting N errors on the TX port, the far-end receiver's
+            ber-error-count (read via --show-phy-test) should increment by
+            exactly N (within hardware counter precision). This confirms:
+              1. The PRBS checker is locked and actively counting errors.
+              2. The data path between TX and RX is intact.
+              3. The BERT counters are functioning correctly.
+
+          Example Workflow:
+            # Configure TX pattern on port A
+            ethtool --phy-test eth1 lane 0 tx-pattern prbs31
+            # Configure RX checker on port B, start BERT
+            ethtool --phy-test eth2 lane 0 rx-pattern prbs31
+            ethtool --phy-test eth2 lane 0 bert start
+            # Verify lock
+            ethtool --show-phy-test eth2 lane 0
+            #   -> ber-lock-status: locked, ber-error-count: 0
+            # Inject 5 errors from TX side
+            ethtool --phy-test eth1 lane 0 inject-errors 5
+            # Confirm errors were detected
+            ethtool --show-phy-test eth2 lane 0
+            #   -> ber-error-count: 5
+      -
+        name: ber-lock-status
+        type: u8
+        doc: PRBS lock status (1=locked, 0=not locked)
+      -
+        name: ber-error-count
+        type: u64
+        doc: BERT bit error count
+      -
+        name: ber-total-bits-sent
+        type: u64
+        doc: BERT total bits sent
+      -
+        name: supported-test-patterns
+        type: u32
+        doc: Bitmask of supported test patterns
 
+    -
+      name: phy-test-act
+      doc: |
+        Configure PHY test parameters. Each attribute is optional and only
+        specified attributes are applied. TX/RX patterns are set on the
+        local port. BERT and error injection operate on the receiver port.
+        Typical workflow:
+          ethtool --phy-test eth1 lane 0 tx-pattern prbs7   (TX side)
+          ethtool --phy-test eth2 lane 0 rx-pattern prbs7   (RX side)
+          ethtool --phy-test eth2 lane 0 bert start         (start BERT on RX)
+          ethtool --phy-test eth1 lane 0 inject-errors 10   (inject 10 errors on TX)
+          ethtool --show-phy-test eth2 lane 0               (read counters, expect +10)
+          ethtool --phy-test eth2 lane 0 bert stop          (stop BERT)
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+            - lane
+            - tx-pattern
+            - rx-pattern
+            - bert-action
+            - inject-error-count
+    -
+      name: phy-test-get
+      doc: |
+        Get PHY test configuration status, supported patterns, and BERT
+        statistics (lock status, error count, total bits).
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+            - lane
+        reply:
+          attributes:
+            - header
+            - lane
+            - tx-pattern
+            - rx-pattern
+            - supported-test-patterns
+            - ber-lock-status
+            - ber-error-count
+            - ber-total-bits-sent
 
 mcast-groups:
   list:

- Shubham D

From: Srinivasan, Vijay <vijay.srinivasan@intel.com> 
Sent: 02 July 2026 05:19
To: Lee Trager <lee@trager.us>; Andrew Lunn <andrew@lunn.ch>
Cc: Das, Shubham <shubham.das@intel.com>; Alexander Duyck <alexander.duyck@gmail.com>; Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle, Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com; Wirandi, Jonas <jonas.wirandi@ericsson.com>
Subject: Re: Ethtool : PRBS feature

All good points and noted. 
Will write the specification in general terms with full description of context, usage, configuration, expected outcome etc.

Vijay

________________________________________
From: Lee Trager <mailto:lee@trager.us>
Sent: Wednesday, July 1, 2026 4:28 PM
To: Andrew Lunn <mailto:andrew@lunn.ch>; Srinivasan, Vijay <mailto:vijay.srinivasan@intel.com>
Cc: Das, Shubham <mailto:shubham.das@intel.com>; Alexander Duyck <mailto:alexander.duyck@gmail.com>; Maxime Chevallier <mailto:maxime.chevallier@bootlin.com>; mailto:netdev@vger.kernel.org <mailto:netdev@vger.kernel.org>; mailto:mkubecek@suse.cz <mailto:mkubecek@suse.cz>; D H, Siddaraju <mailto:siddaraju.dh@intel.com>; Chintalapalle, Balaji <mailto:balaji.chintalapalle@intel.com>; Lindberg, Magnus <mailto:magnus.k.lindberg@ericsson.com>; mailto:niklas.damberg@ericsson.com <mailto:niklas.damberg@ericsson.com>; Wirandi, Jonas <mailto:jonas.wirandi@ericsson.com>
Subject: Re: Ethtool : PRBS feature 

On 7/1/26 3:02 PM, Andrew Lunn wrote:

> On Wed, Jul 01, 2026 at 09:38:08PM +0000, Srinivasan, Vijay wrote:
>> Hi Andrew,
>> I think there is a disconnect here.
> Which proves my point. The specification is not sufficient if you have
> to keep correcting me.
>
> The kAPI should be understandable by somebody who has a general
> networking background. Please write a specification with that
> assumption in mind. Don't assume the reader is a test engineer who has
> used PRBS for half his life. Assume it is a brand new test engineer
> who is hearing PRBS for the first time. That is what most engineers on
> the netdev list are. Me included.

I think part of the disconnect is that PRBS testing is a signal
integrity test, not a network test. In this case the phy happens to be
Ethernet but it could just as easily be PCIE or USB. That is why it was
heavily suggested to me at netdev 0x19 that this should be done on the
generic phy layer, not netdev.

Lee

Re: Ethtool : PRBS feature

[Lee Trager]

On 7/7/26 2:06 AM, Das, Shubham wrote:

> Thanks Andrew, Lee for the feedback.
>
> Lee,
> I don't see prbs11.0, prbs11.1, prbs11.2, prbs11.3, prbs13.0, prbs13.1, prbs13.2, prbs13.3, prbs16 and prbs32 in IEEE 802.3 2022 standard.
> Is this specific to fnic based on base PRBS pattern or it is mentioned in some other standard ?
Those were from the fbnic spec, I'm not sure where they originate from. 
I suppose we can drop those for now but its good to keep in mind more 
tests may be added in the future.
>
> Each lane and each direction is a completely separate test with its own test of
>> statistics. The test is actually verified on the Rx side, Tx is your generator so you
>> won't have data to collect. So when you run PRBS testing on a 2 lane NIC you are
>> actually running 4 independent tests.
>> While its fine to have a shortcut to run the same test on all lanes we absolutely
>> need a way to run tests per lane and the ability to choose Rx, Tx, or both.
> - Agree, we need lane parameter in commands, Updated command.
>
>
>> I wouldn't consider stats a phy-test action. It shouldn't change the state of the
>> NIC at all. I would just add phy-test-stats as set of standard ethtool statistics.
> Yes moved under separate command.
>
> Below are the updated UAPI, data structures, and Netlink messages to support PRBS/BERT and test pattern configuration.
>
> diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
> index 5e9135e3774f..113005a5f80a 100644
> --- a/Documentation/netlink/specs/ethtool.yaml
> +++ b/Documentation/netlink/specs/ethtool.yaml
> @@ -30,6 +30,35 @@ definitions:
> +  -
> +    name: phy-test-pattern
> +    enum-name: phy-test-pattern
> +    type: enum
> +    name-prefix: phy-test-pattern-
> +    doc: PRBS and other PHY test patterns
> +    entries:
> +      - off
> +      - prbs7
> +      - prbs9
> +      - prbs11
> +      - prbs13
> +      - prbs15
> +      - prbs23
> +      - prbs31
> +      - ssprq
> +      - prbs13q
> +      - prbs31q
> +      - square8
>
> +    name: phy-test-action
> +    enum-name: phy-test-action
> +    type: enum
> +    name-prefix: phy-test-action-
> +    doc: Actions for PHY BERT test control
> +    entries:
> +      - none
> +      - start
> +      - stop
>
> +    name: phy-test
> +    attr-cnt-name: __ethtool-a-phy-test-cnt
> +    doc: |
> +      PHY test configuration for pattern generation/checking,
> +      BERT (Bit Error Rate Test), and statistics.
> +    attributes:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0
> +      -
> +        name: header
> +        type: nest
> +        nested-attributes: header
> +      -
> +        name: lane
> +        type: u32
> +        doc: PHY lane index to target for the test operation
This could be a mask to allow starting and stopping the same test on 
multiple lanes at once.
> +      -
> +        name: tx-pattern
> +        type: u32
> +        doc: TX test pattern type (PRBS or square8 wave)
> +        enum: phy-test-pattern
> +      -
> +        name: rx-pattern
> +        type: u32
> +        doc: RX checker pattern type (PRBS or square8 wave)
> +        enum: phy-test-pattern
> +      -
> +        name: bert-action
> +        type: u32
> +        doc: BERT test start/stop
> +        enum: phy-test-action
> +      -
> +        name: inject-error-count
> +        type: u32
> +        doc: |
> +          Inject a specified number of bit errors into the PHY transmit data
> +          stream for diagnostic verification purposes.
> +
> +          Context and Purpose:
> +            When performing Bit Error Ratio Testing (BERT), the receiving side
> +            runs a PRBS checker that monitors for bit errors. Before relying
> +            on a zero-error BERT result, operators need to confirm Checker
> +            state and configuration to qualify result as TRUE.
> +            A checker that is broken or misconfigured would also report
> +            zero errors, giving a FALSE pass. Error injection provides this
> +            confirmation by deliberately introducing a known number of errors
> +            on the transmit side and verifying they appear on the receive side.
> +
> +            Note:
> +            Receiver under test maybe in the same port as the transmitter
> +            (loopback mode) or a different port in the same device or another
> +            device connected to the transmitting port (non-loopback mode).
> +
> +          Layer and Mechanism:
> +            Error injection operates at the PMA/PMD boundary. This is
> +            bit-level injection in the serial data stream, not frame-level.
> +            The SerDes Built-In Self Test (BIST) block inverts the specified
> +            number of bits in the outgoing serial stream. The injection does
> +            not distinguish between data frames and test patterns; it
> +            corrupts raw bits at the physical layer regardless of what the
> +            stream carries.
> +
> +          Mode of Operation:
> +            This command implements "one-shot" injection: a single burst of
> +            N bit errors injected immediately. The PHY inverts exactly N
> +            consecutive bits in the serial transmit stream at the PMA/PMD
> +            layer, then resumes clean transmission. No continuous/fixed-rate
> +            injection mode is provided.
> +
> +          Prerequisites:
> +            - A PRBS test pattern must be active on the transmitting port
> +              (tx-pattern != off).
> +            - The receiving port must have the matching rx-pattern configured
> +              and ber-lock-status must be "locked" (indicating the checker
> +              has synchronized to the incoming pattern).
> +            - BERT must be running on the receiving port (bert start issued).
> +
> +              Note:
> +              Availability of BIST mode test pattern generator, checker and
> +              lock indication is IP dependent.
> +
> +          Semantics:
> +            - Fire-and-forget: the command completes immediately. No
> +              persistent state is created. Each invocation is an independent
> +              injection event.
> +            - The command may be issued multiple times. Each invocation
> +              injects an additional burst of errors (counts accumulate on
> +              the receiver's ber-error-count across invocations).
> +            - If no test pattern is active, the behaviour is
> +              implementation-defined (hardware may silently ignore the
> +              request or return an error).
> +
> +          Expected Outcome:
> +            After injecting N errors on the TX port, the far-end receiver's
> +            ber-error-count (read via --show-phy-test) should increment by
> +            exactly N (within hardware counter precision). This confirms:
> +              1. The PRBS checker is locked and actively counting errors.
> +              2. The data path between TX and RX is intact.
> +              3. The BERT counters are functioning correctly.
> +
> +          Example Workflow:
> +            # Configure TX pattern on port A
> +            ethtool --phy-test eth1 lane 0 tx-pattern prbs31
> +            # Configure RX checker on port B, start BERT
> +            ethtool --phy-test eth2 lane 0 rx-pattern prbs31
> +            ethtool --phy-test eth2 lane 0 bert start
> +            # Verify lock
> +            ethtool --show-phy-test eth2 lane 0
> +            #   -> ber-lock-status: locked, ber-error-count: 0
> +            # Inject 5 errors from TX side
> +            ethtool --phy-test eth1 lane 0 inject-errors 5
> +            # Confirm errors were detected
> +            ethtool --show-phy-test eth2 lane 0
> +            #   -> ber-error-count: 5
> +      -
> +        name: ber-lock-status
> +        type: u8
> +        doc: PRBS lock status (1=locked, 0=not locked)
> +      -
> +        name: ber-error-count
> +        type: u64
> +        doc: BERT bit error count
> +      -
> +        name: ber-total-bits-sent
> +        type: u64
> +        doc: BERT total bits sent
nit: Hardware engineers I spoke to expect BER to be a floating point 
number which is calculated as errors / total. I dropped "BER" from 
everything kernel related to avoid confusion. I provided an awk script 
which did the calculation and provided a floating point.
> +      -
> +        name: supported-test-patterns
> +        type: u32
> +        doc: Bitmask of supported test patterns
>   
> +    -
> +      name: phy-test-act
> +      doc: |
> +        Configure PHY test parameters. Each attribute is optional and only
> +        specified attributes are applied. TX/RX patterns are set on the
> +        local port. BERT and error injection operate on the receiver port.
> +        Typical workflow:
> +          ethtool --phy-test eth1 lane 0 tx-pattern prbs7   (TX side)
> +          ethtool --phy-test eth2 lane 0 rx-pattern prbs7   (RX side)
> +          ethtool --phy-test eth2 lane 0 bert start         (start BERT on RX)
> +          ethtool --phy-test eth1 lane 0 inject-errors 10   (inject 10 errors on TX)
> +          ethtool --show-phy-test eth2 lane 0               (read counters, expect +10)
> +          ethtool --phy-test eth2 lane 0 bert stop          (stop BERT)

I think it would be good to follow what existing tools do. Lane is 
optional when not given all lanes are assumed. When specified it can be 
one or more comma separated lanes.

https://networking-docs.nvidia.com/mftswum/43018lts/mlxlink-utility

> +
> +      attribute-set: phy-test
> +
> +      do:
> +        request:
> +          attributes:
> +            - header
> +            - lane
> +            - tx-pattern
> +            - rx-pattern
> +            - bert-action
> +            - inject-error-count
> +    -
> +      name: phy-test-get
> +      doc: |
> +        Get PHY test configuration status, supported patterns, and BERT
> +        statistics (lock status, error count, total bits).
> +
> +      attribute-set: phy-test
> +
> +      do:
> +        request:
> +          attributes:
> +            - header
> +            - lane
Lane should be a mask. This way userspace can poll stats while testing 
is running which would only require one call.
> +        reply:
> +          attributes:
> +            - header
> +            - lane
> +            - tx-pattern
> +            - rx-pattern
> +            - supported-test-patterns
> +            - ber-lock-status
> +            - ber-error-count
> +            - ber-total-bits-sent
>   
>   mcast-groups:
>     list:
>
> - Shubham D
>
> From: Srinivasan, Vijay <vijay.srinivasan@intel.com>
> Sent: 02 July 2026 05:19
> To: Lee Trager <lee@trager.us>; Andrew Lunn <andrew@lunn.ch>
> Cc: Das, Shubham <shubham.das@intel.com>; Alexander Duyck <alexander.duyck@gmail.com>; Maxime Chevallier <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org; mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle, Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com; Wirandi, Jonas <jonas.wirandi@ericsson.com>
> Subject: Re: Ethtool : PRBS feature
>
> All good points and noted.
> Will write the specification in general terms with full description of context, usage, configuration, expected outcome etc.
>
> Vijay
>
> ________________________________________
> From: Lee Trager <mailto:lee@trager.us>
> Sent: Wednesday, July 1, 2026 4:28 PM
> To: Andrew Lunn <mailto:andrew@lunn.ch>; Srinivasan, Vijay <mailto:vijay.srinivasan@intel.com>
> Cc: Das, Shubham <mailto:shubham.das@intel.com>; Alexander Duyck <mailto:alexander.duyck@gmail.com>; Maxime Chevallier <mailto:maxime.chevallier@bootlin.com>; mailto:netdev@vger.kernel.org <mailto:netdev@vger.kernel.org>; mailto:mkubecek@suse.cz <mailto:mkubecek@suse.cz>; D H, Siddaraju <mailto:siddaraju.dh@intel.com>; Chintalapalle, Balaji <mailto:balaji.chintalapalle@intel.com>; Lindberg, Magnus <mailto:magnus.k.lindberg@ericsson.com>; mailto:niklas.damberg@ericsson.com <mailto:niklas.damberg@ericsson.com>; Wirandi, Jonas <mailto:jonas.wirandi@ericsson.com>
> Subject: Re: Ethtool : PRBS feature
>
> On 7/1/26 3:02 PM, Andrew Lunn wrote:
>
>> On Wed, Jul 01, 2026 at 09:38:08PM +0000, Srinivasan, Vijay wrote:
>>> Hi Andrew,
>>> I think there is a disconnect here.
>> Which proves my point. The specification is not sufficient if you have
>> to keep correcting me.
>>
>> The kAPI should be understandable by somebody who has a general
>> networking background. Please write a specification with that
>> assumption in mind. Don't assume the reader is a test engineer who has
>> used PRBS for half his life. Assume it is a brand new test engineer
>> who is hearing PRBS for the first time. That is what most engineers on
>> the netdev list are. Me included.
> I think part of the disconnect is that PRBS testing is a signal
> integrity test, not a network test. In this case the phy happens to be
> Ethernet but it could just as easily be PCIE or USB. That is why it was
> heavily suggested to me at netdev 0x19 that this should be done on the
> generic phy layer, not netdev.
>
> Lee

Re: Ethtool : PRBS feature

[Andrew Lunn]

On Wed, Jul 08, 2026 at 05:58:52PM -0700, Lee Trager wrote:
> On 7/7/26 2:06 AM, Das, Shubham wrote:
> 
> > Thanks Andrew, Lee for the feedback.
> > 
> > Lee,
> > I don't see prbs11.0, prbs11.1, prbs11.2, prbs11.3, prbs13.0, prbs13.1, prbs13.2, prbs13.3, prbs16 and prbs32 in IEEE 802.3 2022 standard.
> > Is this specific to fnic based on base PRBS pattern or it is mentioned in some other standard ?
> Those were from the fbnic spec, I'm not sure where they originate from. I
> suppose we can drop those for now but its good to keep in mind more tests
> may be added in the future.

Can you find out what they actually do. It might be something as silly
as, the .1 indicate it only runs on lane 1? So these are in fact
standard prbs11 and being able to specify the lane via another
attribute is sufficient?

	  Andrew

Re: Ethtool : PRBS feature

[Alexander Duyck]

On Thu, Jul 9, 2026 at 7:37 AM Andrew Lunn <andrew@lunn.ch> wrote:
>
> On Wed, Jul 08, 2026 at 05:58:52PM -0700, Lee Trager wrote:
> > On 7/7/26 2:06 AM, Das, Shubham wrote:
> >
> > > Thanks Andrew, Lee for the feedback.
> > >
> > > Lee,
> > > I don't see prbs11.0, prbs11.1, prbs11.2, prbs11.3, prbs13.0, prbs13.1, prbs13.2, prbs13.3, prbs16 and prbs32 in IEEE 802.3 2022 standard.
> > > Is this specific to fnic based on base PRBS pattern or it is mentioned in some other standard ?
> > Those were from the fbnic spec, I'm not sure where they originate from. I
> > suppose we can drop those for now but its good to keep in mind more tests
> > may be added in the future.
>
> Can you find out what they actually do. It might be something as silly
> as, the .1 indicate it only runs on lane 1? So these are in fact
> standard prbs11 and being able to specify the lane via another
> attribute is sufficient?

Looks like they are different derivations of the polynomial for the
given pattern. For example PRBS11 is 1 + x^9 + x^11, but PRBS11_0 is 1
+ x^5 + x^6 + X^10 + x^11. That is one thing to think about. When we
say PRBS7 the assumption is we are all talking about 1 + x^6 + x^7 for
the polynomial. We may want to have that clearly recorded somewhere so
there isn't any confusion on which polynomials we are using for this
testing as there is always a risk that somebody is playing with
bleeding edge hardware and ends up defining a PRBS polynomial
differently than what is expected. I almost wonder if we couldn't
define the sequence as a bitmap instead of an enum with each bit
representing which fields are in the sequence.

The 13_X values seem to be used to generate QPRBS13. I would assume
the 11_X values are something similar. Odds are they aren't in the
standard. The comphy we use supports both PCIe and SATA use cases as
well as Ethernet so it has support for additional testing that may not
be referred to in the standard. In the case of QPRBS13 it looks like
it was rejected as a testing sequence for 400G so it may not be
something that we have to concern ourselves with, at least when it
comes to testing Ethernet PHYs.

Re: Ethtool : PRBS feature

[Andrew Lunn]

> Looks like they are different derivations of the polynomial for the
> given pattern. For example PRBS11 is 1 + x^9 + x^11

802.3 section "72.6.10.2.6 Training pattern" agrees with you.

, but PRBS11_0 is 1
> + x^5 + x^6 + X^10 + x^11. That is one thing to think about. When we
> say PRBS7 the assumption is we are all talking about 1 + x^6 + x^7 for
> the polynomial.

I could be missing it, but i could not quickly find PRBS7 in the
standard!

> We may want to have that clearly recorded somewhere so
> there isn't any confusion on which polynomials we are using for this
> testing as there is always a risk that somebody is playing with
> bleeding edge hardware and ends up defining a PRBS polynomial
> differently than what is expected.

I would probably give a reference to 802.3, at least for standard
tests. If a vendor has made up their own test sequences then yes,
there needs to be a clear definition of what it is.


> I almost wonder if we couldn't
> define the sequence as a bitmap instead of an enum with each bit
> representing which fields are in the sequence.

Not everything is a polynomial. Look at SSPQR, 120.5.11.2.3 SSPRQ test
pattern.

	Andrew

RE: Ethtool : PRBS feature

[Das, Shubham]

Hi,

> > +        name: lane
> > +        type: u32
> > +        doc: PHY lane index to target for the test operation
> This could be a mask to allow starting and stopping the same test on multiple
> lanes at once.

Yes, changed to bitmask for multi lane port operation.

+        name: lane
+        type: u32
+        doc: |
+          Bitmask of PHY lanes to target for the test operation.
+          Each bit corresponds to a lane index (bit 0 = lane 0,
+          bit 1 = lane 1, etc.). Multiple lanes can be selected
+          simultaneously.
+
+          For phy-test-act (set): required. The operation is applied
+          to each lane indicated in the mask.
+
+          For phy-test-get (show): optional. When omitted, status is
+          returned for all lanes. When specified, only the indicated
+          lanes are queried.

+        Examples:
+          # Single lane
+          ethtool --phy-test eth1 lane 0 tx-pattern prbs7
+          ethtool --phy-test eth2 lane 0 rx-pattern prbs7
+          ethtool --phy-test eth2 lane 0 bert start
+
+          # Multiple lanes (comma-separated)
+          ethtool --phy-test eth1 lane 0,1,2,3 tx-pattern prbs31

> > +        name: ber-total-bits-sent
> > +        type: u64
> > +        doc: BERT total bits sent
> nit: Hardware engineers I spoke to expect BER to be a floating point number
> which is calculated as errors / total. I dropped "BER" from everything kernel
> related to avoid confusion. I provided an awk script which did the calculation and
> provided a floating point.

Removed BER prefix from lock, error-count and total-bits-sent parameter and added required description.

+        name: checker-lock
+        type: u8
+        doc: |
+          Indicates when receiver side checker is aligned and locked
+          to expected pattern. Lock is a prerequisite for valid BERT
+          (Bit Error Ratio Testing) results.
+          Checker lock status (1=locked, 0=not locked).
+      -
+        name: error-count
+        type: u64
+        doc: |
+          Number of bit errors detected by the PRBS checker during
+          BERT (Bit Error Ratio Testing). This is the raw error count
+          accumulated since bert start. To compute Bit Error Ratio,
+          divide error-count by total-bits-sent
+          (e.g., BER = error-count / total-bits-sent).
+      -
+        name: total-bits-sent
+        type: u64
+        doc: |
+          Total number of bits processed by the PRBS checker
+          during BERT (Bit Error Ratio Testing). Accumulated since
+          bert start. Used together with error-count to calculate
+          Bit Error Ratio: BER = error-count / total-bits-sent.

> I think it would be good to follow what existing tools do. Lane is optional when
> not given all lanes are assumed. When specified it can be one or more comma
> separated lanes.

Lane can be optional for the get operation. If it is not specified, the driver can iterate
over all lanes based on the port configuration and return the corresponding results.

For the set phy-test operation, however, we believe the lane should be mandatory.
Depending on the PHY implementation, error checkers may either be shared across
all lanes or instantiated per lane. Requiring an explicit lane avoids ambiguity
and ensures that the test configuration is applied to the intended lane.

> Lane should be a mask. This way userspace can poll stats while testing is running
> which would only require one call.

Yes, lane is changed to bitmask field.

- Shubham 

> -----Original Message-----
> From: Lee Trager <lee@trager.us>
> Sent: 09 July 2026 06:29
> To: Das, Shubham <shubham.das@intel.com>; Srinivasan, Vijay
> <vijay.srinivasan@intel.com>; Andrew Lunn <andrew@lunn.ch>
> Cc: Alexander Duyck <alexander.duyck@gmail.com>; Maxime Chevallier
> <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org;
> mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>; Chintalapalle,
> Balaji <balaji.chintalapalle@intel.com>; Lindberg, Magnus
> <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com; Wirandi,
> Jonas <jonas.wirandi@ericsson.com>
> Subject: Re: Ethtool : PRBS feature
> 
> On 7/7/26 2:06 AM, Das, Shubham wrote:
> 
> > Thanks Andrew, Lee for the feedback.
> >
> > Lee,
> > I don't see prbs11.0, prbs11.1, prbs11.2, prbs11.3, prbs13.0, prbs13.1, prbs13.2,
> prbs13.3, prbs16 and prbs32 in IEEE 802.3 2022 standard.
> > Is this specific to fnic based on base PRBS pattern or it is mentioned in some
> other standard ?
> Those were from the fbnic spec, I'm not sure where they originate from.
> I suppose we can drop those for now but its good to keep in mind more tests may
> be added in the future.
> >
> > Each lane and each direction is a completely separate test with its
> > own test of
> >> statistics. The test is actually verified on the Rx side, Tx is your
> >> generator so you won't have data to collect. So when you run PRBS
> >> testing on a 2 lane NIC you are actually running 4 independent tests.
> >> While its fine to have a shortcut to run the same test on all lanes
> >> we absolutely need a way to run tests per lane and the ability to choose Rx, Tx,
> or both.
> > - Agree, we need lane parameter in commands, Updated command.
> >
> >
> >> I wouldn't consider stats a phy-test action. It shouldn't change the
> >> state of the NIC at all. I would just add phy-test-stats as set of standard
> ethtool statistics.
> > Yes moved under separate command.
> >
> > Below are the updated UAPI, data structures, and Netlink messages to support
> PRBS/BERT and test pattern configuration.
> >
> > diff --git a/Documentation/netlink/specs/ethtool.yaml
> > b/Documentation/netlink/specs/ethtool.yaml
> > index 5e9135e3774f..113005a5f80a 100644
> > --- a/Documentation/netlink/specs/ethtool.yaml
> > +++ b/Documentation/netlink/specs/ethtool.yaml
> > @@ -30,6 +30,35 @@ definitions:
> > +  -
> > +    name: phy-test-pattern
> > +    enum-name: phy-test-pattern
> > +    type: enum
> > +    name-prefix: phy-test-pattern-
> > +    doc: PRBS and other PHY test patterns
> > +    entries:
> > +      - off
> > +      - prbs7
> > +      - prbs9
> > +      - prbs11
> > +      - prbs13
> > +      - prbs15
> > +      - prbs23
> > +      - prbs31
> > +      - ssprq
> > +      - prbs13q
> > +      - prbs31q
> > +      - square8
> >
> > +    name: phy-test-action
> > +    enum-name: phy-test-action
> > +    type: enum
> > +    name-prefix: phy-test-action-
> > +    doc: Actions for PHY BERT test control
> > +    entries:
> > +      - none
> > +      - start
> > +      - stop
> >
> > +    name: phy-test
> > +    attr-cnt-name: __ethtool-a-phy-test-cnt
> > +    doc: |
> > +      PHY test configuration for pattern generation/checking,
> > +      BERT (Bit Error Rate Test), and statistics.
> > +    attributes:
> > +      -
> > +        name: unspec
> > +        type: unused
> > +        value: 0
> > +      -
> > +        name: header
> > +        type: nest
> > +        nested-attributes: header
> > +      -
> > +        name: lane
> > +        type: u32
> > +        doc: PHY lane index to target for the test operation
> This could be a mask to allow starting and stopping the same test on multiple
> lanes at once.
> > +      -
> > +        name: tx-pattern
> > +        type: u32
> > +        doc: TX test pattern type (PRBS or square8 wave)
> > +        enum: phy-test-pattern
> > +      -
> > +        name: rx-pattern
> > +        type: u32
> > +        doc: RX checker pattern type (PRBS or square8 wave)
> > +        enum: phy-test-pattern
> > +      -
> > +        name: bert-action
> > +        type: u32
> > +        doc: BERT test start/stop
> > +        enum: phy-test-action
> > +      -
> > +        name: inject-error-count
> > +        type: u32
> > +        doc: |
> > +          Inject a specified number of bit errors into the PHY transmit data
> > +          stream for diagnostic verification purposes.
> > +
> > +          Context and Purpose:
> > +            When performing Bit Error Ratio Testing (BERT), the receiving side
> > +            runs a PRBS checker that monitors for bit errors. Before relying
> > +            on a zero-error BERT result, operators need to confirm Checker
> > +            state and configuration to qualify result as TRUE.
> > +            A checker that is broken or misconfigured would also report
> > +            zero errors, giving a FALSE pass. Error injection provides this
> > +            confirmation by deliberately introducing a known number of errors
> > +            on the transmit side and verifying they appear on the receive side.
> > +
> > +            Note:
> > +            Receiver under test maybe in the same port as the transmitter
> > +            (loopback mode) or a different port in the same device or another
> > +            device connected to the transmitting port (non-loopback mode).
> > +
> > +          Layer and Mechanism:
> > +            Error injection operates at the PMA/PMD boundary. This is
> > +            bit-level injection in the serial data stream, not frame-level.
> > +            The SerDes Built-In Self Test (BIST) block inverts the specified
> > +            number of bits in the outgoing serial stream. The injection does
> > +            not distinguish between data frames and test patterns; it
> > +            corrupts raw bits at the physical layer regardless of what the
> > +            stream carries.
> > +
> > +          Mode of Operation:
> > +            This command implements "one-shot" injection: a single burst of
> > +            N bit errors injected immediately. The PHY inverts exactly N
> > +            consecutive bits in the serial transmit stream at the PMA/PMD
> > +            layer, then resumes clean transmission. No continuous/fixed-rate
> > +            injection mode is provided.
> > +
> > +          Prerequisites:
> > +            - A PRBS test pattern must be active on the transmitting port
> > +              (tx-pattern != off).
> > +            - The receiving port must have the matching rx-pattern configured
> > +              and ber-lock-status must be "locked" (indicating the checker
> > +              has synchronized to the incoming pattern).
> > +            - BERT must be running on the receiving port (bert start issued).
> > +
> > +              Note:
> > +              Availability of BIST mode test pattern generator, checker and
> > +              lock indication is IP dependent.
> > +
> > +          Semantics:
> > +            - Fire-and-forget: the command completes immediately. No
> > +              persistent state is created. Each invocation is an independent
> > +              injection event.
> > +            - The command may be issued multiple times. Each invocation
> > +              injects an additional burst of errors (counts accumulate on
> > +              the receiver's ber-error-count across invocations).
> > +            - If no test pattern is active, the behaviour is
> > +              implementation-defined (hardware may silently ignore the
> > +              request or return an error).
> > +
> > +          Expected Outcome:
> > +            After injecting N errors on the TX port, the far-end receiver's
> > +            ber-error-count (read via --show-phy-test) should increment by
> > +            exactly N (within hardware counter precision). This confirms:
> > +              1. The PRBS checker is locked and actively counting errors.
> > +              2. The data path between TX and RX is intact.
> > +              3. The BERT counters are functioning correctly.
> > +
> > +          Example Workflow:
> > +            # Configure TX pattern on port A
> > +            ethtool --phy-test eth1 lane 0 tx-pattern prbs31
> > +            # Configure RX checker on port B, start BERT
> > +            ethtool --phy-test eth2 lane 0 rx-pattern prbs31
> > +            ethtool --phy-test eth2 lane 0 bert start
> > +            # Verify lock
> > +            ethtool --show-phy-test eth2 lane 0
> > +            #   -> ber-lock-status: locked, ber-error-count: 0
> > +            # Inject 5 errors from TX side
> > +            ethtool --phy-test eth1 lane 0 inject-errors 5
> > +            # Confirm errors were detected
> > +            ethtool --show-phy-test eth2 lane 0
> > +            #   -> ber-error-count: 5
> > +      -
> > +        name: ber-lock-status
> > +        type: u8
> > +        doc: PRBS lock status (1=locked, 0=not locked)
> > +      -
> > +        name: ber-error-count
> > +        type: u64
> > +        doc: BERT bit error count
> > +      -
> > +        name: ber-total-bits-sent
> > +        type: u64
> > +        doc: BERT total bits sent
> nit: Hardware engineers I spoke to expect BER to be a floating point number
> which is calculated as errors / total. I dropped "BER" from everything kernel
> related to avoid confusion. I provided an awk script which did the calculation and
> provided a floating point.
> > +      -
> > +        name: supported-test-patterns
> > +        type: u32
> > +        doc: Bitmask of supported test patterns
> >
> > +    -
> > +      name: phy-test-act
> > +      doc: |
> > +        Configure PHY test parameters. Each attribute is optional and only
> > +        specified attributes are applied. TX/RX patterns are set on the
> > +        local port. BERT and error injection operate on the receiver port.
> > +        Typical workflow:
> > +          ethtool --phy-test eth1 lane 0 tx-pattern prbs7   (TX side)
> > +          ethtool --phy-test eth2 lane 0 rx-pattern prbs7   (RX side)
> > +          ethtool --phy-test eth2 lane 0 bert start         (start BERT on RX)
> > +          ethtool --phy-test eth1 lane 0 inject-errors 10   (inject 10 errors on TX)
> > +          ethtool --show-phy-test eth2 lane 0               (read counters, expect +10)
> > +          ethtool --phy-test eth2 lane 0 bert stop          (stop BERT)
> 
> I think it would be good to follow what existing tools do. Lane is optional when
> not given all lanes are assumed. When specified it can be one or more comma
> separated lanes.
> 
> https://networking-docs.nvidia.com/mftswum/43018lts/mlxlink-utility
> 
> > +
> > +      attribute-set: phy-test
> > +
> > +      do:
> > +        request:
> > +          attributes:
> > +            - header
> > +            - lane
> > +            - tx-pattern
> > +            - rx-pattern
> > +            - bert-action
> > +            - inject-error-count
> > +    -
> > +      name: phy-test-get
> > +      doc: |
> > +        Get PHY test configuration status, supported patterns, and BERT
> > +        statistics (lock status, error count, total bits).
> > +
> > +      attribute-set: phy-test
> > +
> > +      do:
> > +        request:
> > +          attributes:
> > +            - header
> > +            - lane
> Lane should be a mask. This way userspace can poll stats while testing is running
> which would only require one call.
> > +        reply:
> > +          attributes:
> > +            - header
> > +            - lane
> > +            - tx-pattern
> > +            - rx-pattern
> > +            - supported-test-patterns
> > +            - ber-lock-status
> > +            - ber-error-count
> > +            - ber-total-bits-sent
> >
> >   mcast-groups:
> >     list:
> >
> > - Shubham D
> >
> > From: Srinivasan, Vijay <vijay.srinivasan@intel.com>
> > Sent: 02 July 2026 05:19
> > To: Lee Trager <lee@trager.us>; Andrew Lunn <andrew@lunn.ch>
> > Cc: Das, Shubham <shubham.das@intel.com>; Alexander Duyck
> > <alexander.duyck@gmail.com>; Maxime Chevallier
> > <maxime.chevallier@bootlin.com>; netdev@vger.kernel.org;
> > mkubecek@suse.cz; D H, Siddaraju <siddaraju.dh@intel.com>;
> > Chintalapalle, Balaji <balaji.chintalapalle@intel.com>; Lindberg,
> > Magnus <magnus.k.lindberg@ericsson.com>; niklas.damberg@ericsson.com;
> > Wirandi, Jonas <jonas.wirandi@ericsson.com>
> > Subject: Re: Ethtool : PRBS feature
> >
> > All good points and noted.
> > Will write the specification in general terms with full description of context,
> usage, configuration, expected outcome etc.
> >
> > Vijay
> >
> > ________________________________________
> > From: Lee Trager <mailto:lee@trager.us>
> > Sent: Wednesday, July 1, 2026 4:28 PM
> > To: Andrew Lunn <mailto:andrew@lunn.ch>; Srinivasan, Vijay
> > <mailto:vijay.srinivasan@intel.com>
> > Cc: Das, Shubham <mailto:shubham.das@intel.com>; Alexander Duyck
> > <mailto:alexander.duyck@gmail.com>; Maxime Chevallier
> > <mailto:maxime.chevallier@bootlin.com>; mailto:netdev@vger.kernel.org
> > <mailto:netdev@vger.kernel.org>; mailto:mkubecek@suse.cz
> > <mailto:mkubecek@suse.cz>; D H, Siddaraju
> > <mailto:siddaraju.dh@intel.com>; Chintalapalle, Balaji
> > <mailto:balaji.chintalapalle@intel.com>; Lindberg, Magnus
> > <mailto:magnus.k.lindberg@ericsson.com>;
> > mailto:niklas.damberg@ericsson.com
> > <mailto:niklas.damberg@ericsson.com>; Wirandi, Jonas
> > <mailto:jonas.wirandi@ericsson.com>
> > Subject: Re: Ethtool : PRBS feature
> >
> > On 7/1/26 3:02 PM, Andrew Lunn wrote:
> >
> >> On Wed, Jul 01, 2026 at 09:38:08PM +0000, Srinivasan, Vijay wrote:
> >>> Hi Andrew,
> >>> I think there is a disconnect here.
> >> Which proves my point. The specification is not sufficient if you
> >> have to keep correcting me.
> >>
> >> The kAPI should be understandable by somebody who has a general
> >> networking background. Please write a specification with that
> >> assumption in mind. Don't assume the reader is a test engineer who
> >> has used PRBS for half his life. Assume it is a brand new test
> >> engineer who is hearing PRBS for the first time. That is what most
> >> engineers on the netdev list are. Me included.
> > I think part of the disconnect is that PRBS testing is a signal
> > integrity test, not a network test. In this case the phy happens to be
> > Ethernet but it could just as easily be PCIE or USB. That is why it
> > was heavily suggested to me at netdev 0x19 that this should be done on
> > the generic phy layer, not netdev.
> >
> > Lee

RE: Ethtool : PRBS feature

[Das, Shubham]

Thanks, Maxime, for summarizing the PRBS discussion from Netdev conference.

Based on the discussion, I'd like to propose the following changes to
the current PRBS proposal. Add a new command:

ethtool --interface-capabilities

This command would expose the interface hardware layout and enumerate all
available functional blocks, including their layer, block ID, and supported hardware
capabilities such as loopback, PRBS generation/checking, BERT, error injection,
and other test operations.

The interface layout is summarized below.
+-------------------------------------------------------------------------------------------------------------------------------------+
|Block        Name                  Component       Sublayer       Depth          Loopback                 PRBS                 |
|------------------------------------------------------------------------------------------------------------------------------------ |
|1            host-mac                    MAC                  RS                  0             Local, Remote              N/A                 |
|2            host-pcs                      PHY                  PCS                 0             Local, Remote              N/A                 |
|3            host-pma                    PHY                  PMA               0             Local, Remote     prbs7-31, ssprq     |
|4            host-pmd                    PHY                  PMD               0             Local, Remote              N/A                |
|5            ext-phy-host-pcs        PHY                  PCS                 0             Local, Remote              N/A                |
|6            ext-phy-host-pma      PHY                  PMA               0             Local, Remote      prbs7-31, ssprq   |
|7            ext-phy-line-pcs         PHY                  PCS                 1             Local, Remote               N/A               |
|8            ext-phy-line-pma       PHY                  PMA               1             Local, Remote      prbs7-31, ssprq   |
|9            ext-pma                       Retimer           PMA               0             Local, Remote     prbs7-31, ssprq    |
|10          module-host              MODULE         PMA                0             Local, Remote     prbs7-31, ssprq    |
|11          module-line                MODULE         PMA               1             Local, Remote      prbs7-31, ssprq   |
+------------------------------------------------------------------------------------------------------------------------------------+

The block ID would be used as the target identifier for --phy-test and 
loopback set/get commands. Based on the block ID, the driver can identify
the corresponding functional block and perform the requested operation.

Host-side information can be populated by the driver based on
the hardware design. External PHY information can be obtained via phylink,
and module-related information can be retrieved over the I2C interface.

The updated proposal is provided below for review and comments.

+    name: intf-component
+    enum-name: intf-component
+    type: enum
+    name-prefix: intf-component-
+    doc: |
+      Type of hardware component in the interface. Each component
+      represents a distinct hardware entity (chip, module, or IP block)
+      that contains one or more functional blocks.
+    entries:
+      - mac
+      - phy
+      - module
+      - retimer
+  -
+    name: intf-sublayer
+    enum-name: intf-sublayer
+    type: enum
+    name-prefix: intf-sublayer-
+    doc: |
+      802.3 sublayer within a component. Identifies the functional
+      layer of a block.
+    entries:
+      - none
+      - rs
+      - pcs
+      - fec
+      - pma
+      - pmd
+  -
+    name: loopback-support
+    enum-name: loopback-support
+    type: flags
+    name-prefix: loopback-support-
+    doc: Bitmask of supported loopback directions for a block
+    entries:
+      - local
+      - remote
+  -
+    name: phy-test-pattern
+    enum-name: phy-test-pattern
+    type: enum
+    name-prefix: phy-test-pattern-
+    doc: PRBS and other PHY test patterns
+    entries:
+      - off
+      - prbs7
+      - prbs9
+      - prbs11
+      - prbs13
+      - prbs15
+      - prbs23
+      - prbs31
+      - ssprq
+      - prbs13q
+      - prbs31q
+      - square_nrz
+      - square_pam4 (JP03A - IEEE Std. 802.3-2022 94.2.9.1)
+      - tx_linearity (LIN - IEEE Std. 802.3-2022 94.2.9.4)
+      - scrambled_idle
+      - k28_5
+      - k28_7
+  -
+    name: phy-test-action
+    enum-name: phy-test-action
+    type: enum
+    name-prefix: phy-test-action-
+    doc: Actions for PHY BERT test control
+    entries:
+      - none
+      - start
+      - stop
   -
     name: header-flags
     type: flags
@@ -1810,6 +1882,10 @@ attribute-sets:
        name: header
        type: nest
        nested-attributes: header
+      -
+       name: block-id
+       type: u32
+       doc: Target block ID from --interface-capabilities.
       -
        name: enabled
        type: u8
@@ -1818,6 +1894,280 @@ attribute-sets:
         type: u32
         enum: loopback-type
 
+  -
+    name: intf-block
+    doc: |
+      A single functional block in the interface. Each block represents
+      a hardware point that supports loopback, pattern
+      generation/checking, BERT, or other HW capabilities.
+      Block IDs returned by intf-caps-get are used as the 'block'
+      parameter in --set-loopback and --phy-test commands.
+    attributes:
+      -
+        name: id
+        type: u32
+        doc: |
+          Unique block identifier within this interface. Used as the
+          'block' parameter in --set-loopback and --phy-test commands.
+      -
+        name: component
+        type: u32
+        enum: intf-component
+        doc: |
+          Physical entity where this block resides.
+          MAC, PHY, MODULE, or RETIMER.
+      -
+        name: sublayer
+        type: u32
+        enum: intf-sublayer
+        doc: |
+          802.3 sublayer (RS, PCS, FEC, PMA, PMD) or NONE for
+          blocks that do not map to a standard sublayer.
+      -
+        name: name
+        type: string
+        doc: |
+          Subsystem label for this block, identifying its role in the
+          interface. Format: <scope>-<sublayer>[-<qualifier>]
+          Examples: "host-mac", "host-pcs", "host-pma", "host-pmd",
+          "ext-phy-host-pcs", "ext-phy-host-pma", "ext-phy-line-pcs",
+          "ext-phy-line-pma", "ext-pma", "module-host", "module-line".
+      -
+        name: depth
+        type: u8
+        doc: |
+          Ordering index within the same (component, sublayer) tuple.
+          Lower depth values are closer to the host side, higher values
+          are closer to the line/media side. Defaults to 0 when there
+          is only one block per (component, sublayer) combination.
+      -
+        name: lanes
+        type: u32
+        doc: Number of lanes of the port.
+      -
+        name: loopback-supported
+        type: u32
+        enum: loopback-support
+        doc: |
+          Bitmask of supported loopback directions.
+          Bit 0 = local, Bit 1 = remote. 0 = no loopback.
+      -
+        name: supported-tx-patterns
+        type: u32
+        doc: |
+          Bitmask of patterns this block can GENERATE (values from
+          phy-test-pattern enum).
+          0 = no TX pattern generation support.
+      -
+        name: supported-rx-patterns
+        type: u32
+        doc: |
+          Bitmask of patterns this block can CHECK (values from
+          phy-test-pattern enum). square wave, SSPRQ, JP03A, tx_linearity,
+          K28.5/K28.7 are TX-only (measured with scope, no checker).
+          0 = no RX pattern checking support.
+      -
+        name: error-inject-supported
+        type: flag
+        doc: Whether this block supports error injection.
+      -
+        name: bert-supported
+        type: flag
+        doc: Whether this block supports BERT test and counters.
+
+  -
+    name: intf-caps
+    attr-cnt-name: __ethtool-a-intf-caps-cnt
+    doc: |
+      Interface capabilities. Reports the full HW layout of an interface,
+      listing all functional blocks with their loopback, pattern
+      generation/checking, BERT, and other test capabilities. Block IDs
+      from this reply are used as the 'block' parameter in
+      --set-loopback and --phy-test commands.
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: header
+        type: nest
+        nested-attributes: header
+      -
+        name: blocks
+        type: nest
+        nested-attributes: intf-block
+        multi-attr: true
+        doc: |
+          Array of interface blocks ordered from host-side to line-side.
+          Each entry describes one functional block and its capabilities.
+
+    name: phy-test
+    attr-cnt-name: __ethtool-a-phy-test-cnt
+    doc: |
+      PHY test configuration for PRBS pattern generation/checking,
+      BERT (Bit Error Ratio Test), and statistics. The 'block-id'
+      field references a block from --interface-capabilities output.
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: header
+        type: nest
+        nested-attributes: header
+      -
+        name: block-id
+        type: u32
+        doc: Target block ID from --interface-capabilities.
+      -
+        name: lane
+        type: u32
+        doc: PHY lane(s) to target for the test operation. Specified
+             as a single lane index or comma-separated list of lane
+             indices (e.g., 0 for single lane, 0,1,2,3 for all 4 lanes).
+             Internally conveyed as a bitmask (bit N = lane N).
+
+             For phy-test-act (set): required. The operation is applied
+             to each specified lane.
+
+             For phy-test-get (show): optional. When omitted, status is
+             returned for all lanes. When specified, only the indicated
+             lanes are queried.
+      -
+        name: tx-pattern
+        type: u32
+        doc: TX test pattern type
+        enum: phy-test-pattern
+      -
+        name: rx-pattern
+        type: u32
+        doc: RX checker pattern type
+        enum: phy-test-pattern
+      -
+        name: bert-action
+        type: u32
+        doc: BERT test start/stop
+        enum: phy-test-action
+      -
+        name: inject-error-count
+        type: u32
+        doc: |
+          Inject a specified number of bit errors into the PHY transmit data
+          stream for diagnostic verification purposes.
+
+          Context and Purpose:
+            When performing Bit Error Ratio Testing (BERT), the receiving side
+            runs a PRBS checker that monitors for bit errors. Before relying
+            on a zero-error BERT result, operators need to confirm that the
+            checker is actually functional. A checker that is broken or
+            misconfigured would also report zero errors, giving a false pass.
+            Error injection provides this confirmation by deliberately
+            introducing a known number of errors on the transmit side and
+            verifying they appear on the receive side.
+
+          Layer and Mechanism:
+            Error injection operates at the PMA/PMD boundary. This is
+            bit-level injection in the serial data stream, not frame-level.
+            The SerDes Built-In Self Test (BIST) block injects the specified
+            number of bit errors in the outgoing serial stream. The injection
+            does not distinguish between data frames and test patterns; it
+            corrupts raw bits at the physical layer regardless of what the
+            stream carries.
+
+            This is a standard SerDes BIST capability present in most (if
+            not all) SerDes IPs. Some implementations have the injection
+            point inside the BIST block (test pattern mode only), while
+            others place it in the common data path (works in both test
+            pattern mode and live data/traffic mode). The availability and
+            exact location is IP-dependent.
+
+          Mode of Operation:
+            This command implements "one-shot" injection: a single burst of
+            N bit errors injected immediately. The PHY injects exactly N
+            consecutive errors in the serial transmit stream at the PMA/PMD
+            layer, then resumes clean transmission. No continuous/fixed-rate
+            injection mode is provided.
+
+          Prerequisites:
+            - A PRBS test pattern must be active on the transmitting port
+              (tx-pattern != off).
+            - The receiving port must have the matching rx-pattern configured
+              and checker-lock must be "locked" (indicating the checker
+              has synchronized to the incoming pattern).
+            - BERT must be running on the receiving port (bert start issued).
+
+          Semantics:
+            - Fire-and-forget: the command completes immediately. No
+              persistent state is created. Each invocation is an independent
+              injection event.
+            - The command may be issued multiple times. Each invocation
+              injects an additional burst of errors (counts accumulate on
+              the receiver's error-count across invocations).
+            - If no test pattern is active, the behavior is
+              implementation-defined (hardware may silently ignore the
+              request or return an error).
+
+          Expected Outcome:
+            After injecting N errors on the TX port, the far-end receiver's
+            error-count (read via --show-phy-test) should increment by
+            exactly N (within hardware counter precision). This confirms:
+              1. The PRBS checker is locked and actively counting errors.
+              2. The data path between TX and RX is intact.
+              3. The BERT counters are functioning correctly.
+
+          Example Workflow:
+            # Discover blocks and pick one that supports PRBS
+            ethtool --interface-capabilities eth1
+            #   -> Block 3: host-pma (supports prbs7-31, bert, inject)
+            # Configure TX pattern on port A, block 3
+            ethtool --phy-test eth1 block 3 lane 0 tx-pattern prbs31
+            # Configure RX checker on port B, block 3, start BERT
+            ethtool --phy-test eth2 block 3 lane 0 rx-pattern prbs31
+            ethtool --phy-test eth2 block 3 lane 0 bert start
+            # Verify lock
+            ethtool --show-phy-test eth2 block 3 lane 0
+            #   -> checker-lock: locked, error-count: 0
+            # Inject 5 errors from TX side
+            ethtool --phy-test eth1 block 3 lane 0 inject-errors 5
+            # Confirm errors were detected
+            ethtool --show-phy-test eth2 block 3 lane 0
+            #   -> error-count: 5
+
+          Constraints:
+            - Maximum value is limited by hardware; implementations may
+              truncate to 16 bits (max 65535 errors per invocation).
+            - A value of 0 is a no-op.
+      -
+        name: checker-lock
+        type: u8
+        doc: Indicates when receiver side checker is aligned and locked
+             to expected pattern. Lock is a prerequisite for valid BERT
+             (Bit Error Ratio Testing) results.
+             Checker lock status (1=locked, 0=not locked).
+     -
+        name: error-count
+        type: u64
+        doc: |
+          Number of bit errors detected by the PRBS checker during
+          BERT (Bit Error Ratio Testing). This is the raw error count
+          accumulated since bert start. To compute Bit Error Ratio,
+          divide error-count by total-bits-sent
+          (e.g., BER = error-count / total-bits-sent).
+      -
+        name: total-bits-sent
+        type: u64
+        doc: |
+          Total number of bits processed by the PRBS checker
+          during BERT (Bit Error Ratio Testing). Accumulated since
+          bert start. Used together with error-count to calculate
+          Bit Error Ratio: BER = error-count / total-bits-sent.
+      -
+        name: supported-test-patterns
+        type: u32
+        doc: Bitmask of supported test patterns
 
+    -
+      name: intf-caps-get
+      doc: |
+        Get interface capabilities. Returns all functional blocks with
+        their loopback, pattern generation/checking, BERT, and other
+        HW capabilities. Block IDs from this reply are used as the
+        'block' parameter in --set-loopback and --phy-test commands.
+
+        The driver aggregates blocks from all subsystems:
+        - Internal blocks (driver/firmware managed)
+        - External PHY blocks (via phylink)
+        - Module blocks (via I2C/CMIS)
+
+      attribute-set: intf-caps
+
+      do:
+        request:
+          attributes:
+            - header
+        reply:
+          attributes:
+            - header
+            - blocks
+    -
+      name: phy-test-act
+      doc: |
+        Configure PHY test parameters on a specific block. The block-id
+        must reference a valid block from --interface-capabilities that
+        supports the requested operation.
+
+        Each attribute is optional and only specified attributes are
+        applied. TX/RX patterns are set on the local port. BERT
+        operates on the receiver port, while error injection is
+        performed on the transmitter (TX) port.
+
+        The lane parameter accepts a single lane index or comma-separated
+        list of lane indices.
+
+        Single lane usage:
+          ethtool --interface-capabilities eth0               (discover blocks)
+          ethtool --phy-test eth0 block 3 lane 0 tx-pattern prbs31
+          ethtool --phy-test eth0 block 3 lane 0 rx-pattern prbs31
+          ethtool --phy-test eth0 block 3 lane 0 bert start
+          ethtool --show-phy-test eth0 block 3 lane 0
+          ethtool --phy-test eth0 block 3 lane 0 inject-errors 5
+          ethtool --phy-test eth0 block 3 lane 0 bert stop
+
+        Multiple lanes (comma-separated):
+          ethtool --phy-test eth0 block 3 lane 0,1,2,3 tx-pattern prbs31
+          ethtool --phy-test eth0 block 3 lane 0,1,2,3 rx-pattern prbs31
+          ethtool --phy-test eth0 block 3 lane 0,1,2,3 bert start
+          ethtool --show-phy-test eth0 block 3 lane 0,1,2,3
+          ethtool --phy-test eth0 block 3 lane 0,1,2,3 bert stop
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+            - block-id
+            - lane
+            - tx-pattern
+            - rx-pattern
+            - bert-action
+            - inject-error-count
+    -
+      name: phy-test-get
+      doc: |
+        Get PHY test configuration status, supported patterns, and BERT
+        statistics (lock status, error count, total bits).
+
+      attribute-set: phy-test
+
+      do:
+        request:
+          attributes:
+            - header
+            - block-id
+            - lane
+        reply:
+          attributes:
+            - header
+            - block-id
+            - lane
+            - tx-pattern
+            - rx-pattern
+            - supported-test-patterns
+            - checker-lock
+            - error-count
+            - total-bits-sent
 
 mcast-groups:
   list:

+/* Loopback direction support bitmask */
+#define LOOPBACK_SUPPORT_LOCAL		BIT(0)
+#define LOOPBACK_SUPPORT_REMOTE		BIT(1)
+
+#define INTF_CAPS_MAX_BLOCKS		16
+#define INTF_BLOCK_NAME_LEN		32
+
+/**
+ * struct ethtool_intf_block - Single functional block in the interface
+ * @id: Unique block ID within this interface, used as 'block' parameter
+ *	  in --set-loopback and --phy-test commands
+ * @component: Hardware component type (MAC, PHY, MODULE, or RETIMER)
+ * @sublayer: 802.3 sublayer type (RS, PCS, FEC, PMA, PMD, or NONE)
+ * @name: Subsystem label identifying the block role in the interface
+ *	         (e.g., "host-pma", "ext-phy-host-pma", "module-host")
+ * @depth: Ordering index within same (component, sublayer) tuple.
+ *	         0 = closest to host, higher values = closer to line/media side
+ * @lanes: Number of lanes available at this block
+ * @loopback_supported: Bitmask of supported loopback directions
+ *	                                  (LOOPBACK_SUPPORT_LOCAL, 
+ *                                            LOOPBACK_SUPPORT_REMOTE)
+ * @supported_tx_patterns: Bitmask of patterns this block can generate,
+ *	                                       using BIT(PHY_TEST_PATTERN_*) values
+ * @supported_rx_patterns: Bitmask of patterns this block can check,
+ *	                                       using BIT(PHY_TEST_PATTERN_*) values
+ * @error_inject_supported: Block supports bit error injection
+ * @bert_supported: Block supports BERT counters (lock, error count, bits)
+ */
+struct ethtool_intf_block {
+	u32 id;
+	enum intf_component component;
+	enum intf_sublayer sublayer;
+	char name[INTF_BLOCK_NAME_LEN];
+	u8 depth;
+	u32 lanes;
+	u32 loopback_supported;
+	u32 supported_tx_patterns;
+	u32 supported_rx_patterns;
+	bool error_inject_supported;
+	bool bert_supported;
+};
+
+/**
+ * struct ethtool_intf_caps - Interface capabilities (all blocks)
+ * @num_blocks: Number of valid entries in blocks[]
+ * @blocks: Array of functional blocks in this interface
+ */
+struct ethtool_intf_caps {
+	u32 num_blocks;
+	struct ethtool_intf_block blocks[INTF_CAPS_MAX_BLOCKS];
+};
+
+/* Bitmask of which ethtool_phy_test fields were explicitly specified */
+#define PHY_TEST_CMD_TX_PATTERN		BIT(0)
+#define PHY_TEST_CMD_RX_PATTERN		BIT(1)
+#define PHY_TEST_CMD_BERT_ACTION	BIT(2)
+#define PHY_TEST_CMD_INJECT_COUNT	BIT(3)
+#define PHY_TEST_CMD_LANE		              BIT(4)
+#define PHY_TEST_CMD_BLOCK_ID		BIT(5)
+
+/**
+ * struct ethtool_phy_test - PHY test configuration and status
+ * @cmd: Bitmask of PHY_TEST_CMD_* indicating which fields to apply (SET)
+ * @block_id: Target block ID from --interface-capabilities
+ * @lane: PHY lane index to target (0-based)
+ * @tx_pattern: TX test pattern
+ * @rx_pattern: RX checker pattern
+ * @bert_action: BERT start/stop/stats action
+ * @inject_error_count: Number of bit errors to inject into the active test
+ *	                               stream immediately (SET only, fire-and-forget).
+ *	                               Used to verify that the far-end PRBS checker
+ *	                               or FEC decoder is functioning correctly.
+ * @supported_test_patterns: Bitmask of supported patterns (GET only)
+ * @checker_lock: Checker lock status 1=locked, 0=not locked (GET only)
+ * @error_count: BERT bit error count (GET only)
+ * @total_bits_sent: BERT total bits tested (GET only)
+ */
+struct ethtool_phy_test {
+	u32 cmd;
+	u32 block_id;
+	u32 lane;
+	enum phy_test_pattern tx_pattern;
+	enum phy_test_pattern rx_pattern;
+	enum phy_test_action bert_action;
+	u32 inject_error_count;
+	u32 supported_test_patterns;
+	u8 checker_lock;
+	u64 error_count;
+	u64 total_bits_sent;
+};
+
 /**
  * struct ethtool_ops - optional netdev operations
  * @supported_input_xfrm: supported types of input xfrm from %RXH_XFRM_*.
@@ -1091,7 +1186,9 @@ struct ethtool_loopback {
  * @get_mm: Query the 802.3 MAC Merge layer state.
  * @set_mm: Set the 802.3 MAC Merge layer parameters.
  * @get_mm_stats: Query the 802.3 MAC Merge layer statistics.
+ * @get_intf_caps: Get interface capabilities (block layout, PRBS/loopback caps).
+ * @get_phy_test: Get PHY test status, patterns, and BERT counters.
+ * @set_phy_test: Configure PHY test (pattern, BERT, error injection). 
   * All operations are optional (i.e. the function pointer may be set
   * to %NULL) and callers must take this into account.  Callers must
   * hold the RTNL lock.
@@ -1260,6 +1357,12 @@ struct ethtool_ops {
 	void	(*get_mm_stats)(struct net_device *dev, struct ethtool_mm_stats *stats);
 	int	(*get_loopback)(struct net_device *dev, struct ethtool_loopback *lpbk);
 	int	(*set_loopback)(struct net_device *dev, struct ethtool_loopback *lpbk);
+	int	(*get_intf_caps)(struct net_device *dev,
+				 struct ethtool_intf_caps *caps);
+	int	(*get_phy_test)(struct net_device *dev,
+				struct ethtool_phy_test *test);
+	int	(*set_phy_test)(struct net_device *dev,
+				struct ethtool_phy_test *test);
 };

- Shubham 

Re: Ethtool : PRBS feature

[Alexander Duyck]

On Fri, Jul 24, 2026 at 8:26 AM Das, Shubham <shubham.das@intel.com> wrote:
>
> Thanks, Maxime, for summarizing the PRBS discussion from Netdev conference.
>
> Based on the discussion, I'd like to propose the following changes to
> the current PRBS proposal. Add a new command:
>
> ethtool --interface-capabilities
>
> This command would expose the interface hardware layout and enumerate all
> available functional blocks, including their layer, block ID, and supported hardware
> capabilities such as loopback, PRBS generation/checking, BERT, error injection,
> and other test operations.
>
> The interface layout is summarized below.
> +-------------------------------------------------------------------------------------------------------------------------------------+
> |Block        Name                  Component       Sublayer       Depth          Loopback                 PRBS                 |
> |------------------------------------------------------------------------------------------------------------------------------------ |
> |1            host-mac                    MAC                  RS                  0             Local, Remote              N/A                 |
> |2            host-pcs                      PHY                  PCS                 0             Local, Remote              N/A                 |
> |3            host-pma                    PHY                  PMA               0             Local, Remote     prbs7-31, ssprq     |
> |4            host-pmd                    PHY                  PMD               0             Local, Remote              N/A                |
> |5            ext-phy-host-pcs        PHY                  PCS                 0             Local, Remote              N/A                |
> |6            ext-phy-host-pma      PHY                  PMA               0             Local, Remote      prbs7-31, ssprq   |
> |7            ext-phy-line-pcs         PHY                  PCS                 1             Local, Remote               N/A               |
> |8            ext-phy-line-pma       PHY                  PMA               1             Local, Remote      prbs7-31, ssprq   |
> |9            ext-pma                       Retimer           PMA               0             Local, Remote     prbs7-31, ssprq    |
> |10          module-host              MODULE         PMA                0             Local, Remote     prbs7-31, ssprq    |
> |11          module-line                MODULE         PMA               1             Local, Remote      prbs7-31, ssprq   |
> +------------------------------------------------------------------------------------------------------------------------------------+

How does this deal with lanes or cases where you have multiple PHYs in
parallel such as the DSA setups?

> The block ID would be used as the target identifier for --phy-test and
> loopback set/get commands. Based on the block ID, the driver can identify
> the corresponding functional block and perform the requested operation.
>
> Host-side information can be populated by the driver based on
> the hardware design. External PHY information can be obtained via phylink,
> and module-related information can be retrieved over the I2C interface.
>
> The updated proposal is provided below for review and comments.
>

...

> +    name: phy-test-pattern
> +    enum-name: phy-test-pattern
> +    type: enum
> +    name-prefix: phy-test-pattern-
> +    doc: PRBS and other PHY test patterns
> +    entries:
> +      - off
> +      - prbs7
> +      - prbs9
> +      - prbs11
> +      - prbs13
> +      - prbs15
> +      - prbs23
> +      - prbs31
> +      - ssprq
> +      - prbs13q
> +      - prbs31q
> +      - square_nrz
> +      - square_pam4 (JP03A - IEEE Std. 802.3-2022 94.2.9.1)
> +      - tx_linearity (LIN - IEEE Std. 802.3-2022 94.2.9.4)
> +      - scrambled_idle
> +      - k28_5
> +      - k28_7

These test patterns are going to be the biggest problem with this
approach. I almost wonder if we shouldn't look at having essentially 2
sets. One for the standard prbs values, and then one set of strings
that work sort of like the private flags where you can just specify
your own string to identify it and add it as a one-off until it can
become standardized.

RE: Ethtool : PRBS feature

[Das, Shubham]

> How does this deal with lanes or cases where you have multiple PHYs in parallel
> such as the DSA setups?

We already have a lane parameter for selecting parallel lanes within a given block.

Could you elaborate on the DSA/multiple PHYs in parallel case you're referring to? 
My understanding is that (netdev, block, lane) should uniquely identify a test point.
If there are topologies where a single netdev can expose multiple instances of the
same block, then we would likely need an additional instance parameter to uniquely
identify the target block instance.

> These test patterns are going to be the biggest problem with this approach. I
> almost wonder if we shouldn't look at having essentially 2 sets. One for the
> standard prbs values, and then one set of strings that work sort of like the private
> flags where you can just specify your own string to identify it and add it as a one-
> off until it can become standardized.

Thanks for the feedback. Just to clarify, the patterns listed above are not custom
or vendor-specific—they are all standard IEEE-defined test patterns. 
 
The proposal is to expose those standardized patterns only. PRBS patterns can be
used with a checker, while the remaining IEEE-defined patterns (square, scrambled idle,
TX linearity, K28.5, K28.7, etc.) are TX-only.

If there's a future need to expose vendor-specific or custom patterns, we can
certainly consider a separate mechanism, similar to private flags. 
 
For now, I think starting with the IEEE-defined patterns is a good baseline,
and we can extend it later based on additional use case.

- Shubham

RE: Ethtool : PRBS feature

[Das, Shubham]

> > How does this deal with lanes or cases where you have multiple PHYs in
> > parallel such as the DSA setups?
> 
> We already have a lane parameter for selecting parallel lanes within a given
> block.
> 
> Could you elaborate on the DSA/multiple PHYs in parallel case you're referring to?
> My understanding is that (netdev, block, lane) should uniquely identify a test
> point.
> If there are topologies where a single netdev can expose multiple instances of the
> same block, then we would likely need an additional instance parameter to
> uniquely identify the target block instance.

We have added an instance field to handle this case.  Instance distinguishes
Multiple hardware entities of the same component type within a single netdev.

For a simple NIC: only instance 0 exists (internal PHY)
For NIC + external PHY: instance 0 = internal, instance 1 = external PHY
For NIC + external PHY + retimer: instance 0, 1, 2

+----------------------------------------------------------------------------------------------------------------------------------------+
|Block   Component   Instance   Sublayer   Depth         Name                         Description                                  |
------------------------------------------------------------------------------------------------------------------------------------------+
| 1               MAC               0                RS            0          host-mac                     MAC reconciliation                       |
| 2               PHY                0               PCS           0          host-phy-pcs               Host PHY PCS                                 |
| 3               PHY                0               PMA         0          host-phy-pma             Host PHY SerDes                           |
| 4               PHY                0               PMD         0          host-phy-pmd             Host PHY output                           |
| 5               PHY                1               PCS           0          ext-phy-pcs-host        External PHY host PCS                  |  
| 6               PHY                1               PMA         0          ext-phy-pma-host      External PHY/retimer host PMA |
| 7               PHY                1               PCS           1          ext-phy-pcs-line         External PHY line PCS                   |
| 8               PHY                1               PMA         1          ext-phy-pma-line       External PHY/retimer line PMA  |
| 9          MODULE            0               PMA         0          module-pma-host     Module host-side                          |
| 10        MODULE            0               PMA         1          module-pma-line      Module line-side                           |
+----------------------------------------------------------------------------------------------------------------------------------------+

Block layout is reported via --interface-capabilities. The block-id
from this output is then used as the block parameter in --phy-test
and --set-loopback command.

+        name: instance
+        type: u32
+        doc: |
+          Identifies the hardware entity when multiple instances of
+          the same component exist in the interface. The driver
+          assigns instance numbers sequentially based on position in
+          the physical path. Defaults to 0 when only one instance of
+          a given component exists.
+          For PHY: instance 0 is the internal/host-side PHY,
+          instance 1 is an external PHY further along the path
+          toward the line side.
+          For MAC: instance 0 is the host-facing MAC, instance 1 is
+          a secondary MAC further along the data path (e.g., behind
+          an embedded switch).
+      -
+        name: name
+        type: string
+        doc: |
+          Driver-chosen label for this block. Naming convention:
+          <instance>-<component>-<sublayer>[-<depth>]
+          where depth qualifier (host/line) is included when multiple
+          depths exist for the same (component, instance, sublayer).
+          Examples: "host-mac", "host-phy-pcs", "host-phy-pma",
+          "host-phy-pmd", "ext-phy-pma-host", "ext-phy-pma-line",
+          "retimer-pma", "module-pma-host", "module-pma-line".

root@setup:~# ./ethtool --interface-capabilities eth15
Interface capabilities for eth15:

  Block 3: host-pma
    component: PHY
    instance: 0
    sublayer: PMA
    depth: 0
    lanes: 4
    Supported loopback: local remote
    Supported TX patterns: prbs7, prbs9, prbs11, prbs13, prbs15, prbs23, prbs31, ssprq
    Supported RX patterns: prbs7, prbs9, prbs11, prbs13, prbs15, prbs23, prbs31
    Supported tests: bert error-inject

Single lane on host PHY (instance=0, block 3):
          ethtool --phy-test eth0 block 3 lane 0 tx-pattern prbs31

External PHY or retimer (instance=1, e.g. block 6):
          ethtool --phy-test eth0 block 6 lane 0 tx-pattern prbs31
          ethtool --show-phy-test eth0 block 6 lane 0

- Shubham 

RE: Ethtool : PRBS feature

[Das, Shubham]

Hi Andrew, Maxime, Alexander, Lee,

Just following up on this point.

We've added an instance field to handle multiple PHYs/components
within a netdev and included examples in the latest revision.

I'd appreciate your feedback on this approach.

Thanks,
Shubham

Re: Ethtool : PRBS feature

[Alexander Duyck]

On Fri, Aug 7, 2026 at 4:19 AM Das, Shubham <shubham.das@intel.com> wrote:
>
> Hi Andrew, Maxime, Alexander, Lee,
>
> Just following up on this point.
>
> We've added an instance field to handle multiple PHYs/components
> within a netdev and included examples in the latest revision.
>
> I'd appreciate your feedback on this approach.
>
> Thanks,
> Shubham

Honestly I would probably defer to Andrew or Maxime on this as most of
the DSA stuff is much more their wheelhouse than mine.

Also rather than submitting a snippet you might just resubmit the full
patch with your changes as an RFC as it provides the full context on
what we are reviewing.

Re: Ethtool : PRBS feature

[Andrew Lunn]

> Honestly I would probably defer to Andrew or Maxime on this as most of
> the DSA stuff is much more their wheelhouse than mine.

Sorry, too many patches recently, too many newbies using AI without
the knowledge to properly steer it, etc, so i've not really been
following along with this thread.

> Also rather than submitting a snippet you might just resubmit the full
> patch with your changes as an RFC as it provides the full context on
> what we are reviewing.

+1

	Andrew