Re: Ethtool : PRBS feature

[Lee Trager <lee@trager.us>]

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