Diagnostic Concept for Investigating Twisted Pair Ethernet Variants at OSI Layer 1

꼬임쌍 이더넷 계층 1 진단 개념

이 문서는 `GPL-2.0` 라이선스를 따릅니다.

OSI 계층 1에서 꼬임쌍 이더넷 변형을 조사하기 위한 진단 개념

소개

이 문서는 두 주요 독자를 대상으로 합니다.

사용자와 시스템 관리자는 불안정한 링크, 속도 저하, 원인을 알 수 없는 네트워크 문제를 만났을 때 단계별 문제 해결 흐름을 따라 흔한 꼬임쌍 이더넷 계층 1 문제를 찾고 해결할 수 있습니다.

네트워크 드라이버와 PHY 지원을 다루는 커널 개발자는 진단 절차와 Linux 커널 진단 인터페이스를 확장하거나 개선할 영역을 파악해 향후 개선 우선순위를 정할 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

Diagnostic Concept for Investigating Twisted Pair Ethernet Variants at OSI Layer 1
==================================================================================

Introduction
------------

This documentation is designed for two primary audiences:

1. **Users and System Administrators**: For those dealing with real-world
   Ethernet issues, this guide provides a practical, step-by-step
   troubleshooting flow to help identify and resolve common problems in Twisted
   Pair Ethernet at OSI Layer 1. If you're facing unstable links, speed drops,
   or mysterious network issues, jump right into the step-by-step guide and
   follow it through to find your solution.

2. **Kernel Developers**: For developers working with network drivers and PHY
   support, this documentation outlines the diagnostic process and highlights
   areas where the Linux kernel’s diagnostic interfaces could be extended or
   improved. By understanding the diagnostic flow, developers can better
   prioritize future enhancements.

Linux 진단 범위와 시나리오

Linux에서 수행하는 단계별 진단 안내서(일반 이더넷)

이 안내서는 SPE(Single-Pair Ethernet), MPE(Multi-Pair Ethernet), PoDL(Power over Data Line), PoE(Clause 33 PSE)를 포함한 여러 이더넷 환경에서 링크 안정성과 감지를 중심으로 일반적인 문제 해결 시나리오를 다룹니다.

대상 환경은 Linux 커널 6.11 이상, ethtool 6.10 이상, iproute2 6.4.0 이상입니다. 링크 상대편에 접근하기 어렵거나 전혀 접근할 수 없는 상황을 가정해 로컬 진단에 집중합니다.

Step-by-Step Diagnostic Guide from Linux (General Ethernet)
-----------------------------------------------------------

This diagnostic guide covers common Ethernet troubleshooting scenarios,
focusing on **link stability and detection** across different Ethernet
environments, including **Single-Pair Ethernet (SPE)** and **Multi-Pair
Ethernet (MPE)**, as well as power delivery technologies like **PoDL** (Power
over Data Line) and **PoE** (Clause 33 PSE).

The guide is designed to help users diagnose physical layer (Layer 1) issues on
systems running **Linux kernel version 6.11 or newer**, utilizing **ethtool
version 6.10 or later** and **iproute2 version 6.4.0 or later**.

In this guide, we assume that users may have **limited or no access to the link
partner** and will focus on diagnosing issues locally.

Diagnostic Scenarios
~~~~~~~~~~~~~~~~~~~~

- **Link is up and stable, but no data transfer**: If the link is stable but
  there are issues with data transmission, refer to the **OSI Layer 2
  Troubleshooting Guide**.

- **Link is unstable**: Link resets, speed drops, or other fluctuations
  indicate potential issues at the hardware or physical layer.

- **No link detected**: The interface is up, but no link is established.

인터페이스 관리 상태 확인

인터페이스 상태 확인

먼저 이더넷 인터페이스가 관리상 up 상태인지 확인합니다. `ethtool`은 링크와 PHY 상태를 보여 주지만 인터페이스 관리 상태는 보여 주지 않으므로, 출력의 꺾쇠괄호 안에 상태를 표시하는 `ip` 명령을 사용합니다.

`<NO-CARRIER,BROADCAST,MULTICAST,UP>`에서 `UP`은 관리상 up, `NO-CARRIER`는 관리상 up이지만 물리 링크를 감지하지 못했다는 뜻입니다. `<BROADCAST,MULTICAST>`만 보이면 관리상 down입니다.

명령: `ip link show dev <interface>`

4: eth0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 ...
   link/ether 88:14:2b:00:96:f2 brd ff:ff:ff:ff:ff:ff

출력에 `UP`이 있으면 시스템이 물리 링크 형성을 시도하고 있습니다. `NO-CARRIER`도 있으면 케이블 결함, 구성 오류, 링크 상대편 미연결 같은 계층 1 문제일 수 있으므로 링크 상태와 PHY 구성을 검사합니다.

`UP`이 없고 `<BROADCAST,MULTICAST>` 같은 상태만 있으면 다음 명령으로 인터페이스를 올립니다.

ip link set dev <interface> up

관리상 up인데 `NO-CARRIER`이면 물리 계층 문제 진단으로 이동합니다. down 상태를 올렸다면 다음 단계 전에 이 확인을 반복해 새 상태를 검증합니다.

`UP`이 있고 `NO-CARRIER`가 없으면 물리 링크가 성공적으로 형성된 것입니다. 정상 동작한다면 계층 1 진단을 마칩니다. 링크는 있지만 데이터가 흐르지 않으면 VLAN·MAC 같은 계층 2, IP·라우팅·ARP 같은 계층 3, 방화벽·서비스 같은 계층 4 이상을 진단합니다.

링크가 자주 재설정되거나 끊기면 케이블 결함, 간섭, 전력 공급 문제 같은 물리 계층 원인일 수 있으므로 다음 단계로 진행합니다.

Verify Interface Status
~~~~~~~~~~~~~~~~~~~~~~~

Begin by verifying the status of the Ethernet interface to check if it is
administratively up. Unlike `ethtool`, which provides information on the link
and PHY status, it does not show the **administrative state** of the interface.
To check this, you should use the `ip` command, which describes the interface
state within the angle brackets `"<>"` in its output.

For example, in the output `<NO-CARRIER,BROADCAST,MULTICAST,UP>`, the important
keywords are:

- **UP**: The interface is in the administrative "UP" state.
- **NO-CARRIER**: The interface is administratively up, but no physical link is
  detected.

If the output shows `<BROADCAST,MULTICAST>`, this indicates the interface is in
the administrative "DOWN" state.

- **Command:** `ip link show dev <interface>`

- **Expected Output:**

  .. code-block:: bash

     4: eth0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 ...
        link/ether 88:14:2b:00:96:f2 brd ff:ff:ff:ff:ff:ff

- **Interpreting the Output:**

  - **Administrative UP State**:

    - If the output contains **"UP"**, the interface is administratively up,
      and the system is trying to establish a physical link.

    - If you also see **"NO-CARRIER"**, it means the physical link has not been
      detected, indicating potential Layer 1 issues like a cable fault,
      misconfiguration, or no connection at the link partner. In this case,
      proceed to the **Inspect Link Status and PHY Configuration** section.

  - **Administrative DOWN State**:

    - If the output lacks **"UP"** and shows only states like
      **"<BROADCAST,MULTICAST>"**, it means the interface is administratively
      down. In this case, bring the interface up using the following command:

      .. code-block:: bash

         ip link set dev <interface> up

- **Next Steps**:

  - If the interface is **administratively up** but shows **NO-CARRIER**,
    proceed to the **Inspect Link Status and PHY Configuration** section to
    troubleshoot potential physical layer issues.

  - If the interface was **administratively down** and you have brought it up,
    ensure to **repeat this verification step** to confirm the new state of the
    interface before proceeding

  - **If the interface is up and the link is detected**:

    - If the output shows **"UP"** and there is **no `NO-CARRIER`**, the
      interface is administratively up, and the physical link has been
      successfully established. If everything is working as expected, the Layer
      1 diagnostics are complete, and no further action is needed.

    - If the interface is up and the link is detected but **no data is being
      transferred**, the issue is likely beyond Layer 1, and you should proceed
      with diagnosing the higher layers of the OSI model. This may involve
      checking Layer 2 configurations (such as VLANs or MAC address issues),
      Layer 3 settings (like IP addresses, routing, or ARP), or Layer 4 and
      above (firewalls, services, etc.).

    - If the **link is unstable** or **frequently resetting or dropping**, this
      may indicate a physical layer issue such as a faulty cable, interference,
      or power delivery problems. In this case, proceed with the next step in
      this guide.

링크 상태와 PHY 구성 검사

링크 상태와 PHY 구성 검사

`ethtool -I`로 링크 상태, PHY 구성, 지원 링크 모드, `Link Down Events` 같은 통계를 확인합니다. 속도 불일치, duplex 문제, 링크 불안정을 진단하는 핵심 단계입니다.

SPE와 MPE 모두 이 단계에서 링크 정보를 수집합니다. SPE는 일반적으로 자동 협상 없이 단일 속도·모드를 지원하지만 `10BaseT1L`은 예외입니다. MPE는 보통 여러 링크 모드와 자동 협상을 지원합니다.

명령: `ethtool -I <interface>`

SPE 예제에서는 `100baseT1/Full`, 100Mb/s, full duplex, 자동 협상 off, forced slave, `SQI: 7/7`, 링크 감지 yes, link-down 2회를 확인할 수 있습니다.

MPE 예제에서는 10/100baseT half·full 지원, 양쪽 자동 협상, 상대편 광고 모드, 100Mb/s full duplex, 링크 감지 yes, link-down 1회를 확인할 수 있습니다.

`ethtool` 출력을 수집해 저장한 뒤 다음 진단 단계로 이동합니다.

Inspect Link Status and PHY Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use `ethtool -I` to check the link status, PHY configuration, supported link
modes, and additional statistics such as the **Link Down Events** counter. This
step is essential for diagnosing Layer 1 problems such as speed mismatches,
duplex issues, and link instability.

For both **Single-Pair Ethernet (SPE)** and **Multi-Pair Ethernet (MPE)**
devices, you will use this step to gather key details about the link. **SPE**
links generally support a single speed and mode without autonegotiation (with
the exception of **10BaseT1L**), while **MPE** devices typically support
multiple link modes and autonegotiation.

- **Command:** `ethtool -I <interface>`

- **Example Output for SPE Interface (Non-autonegotiation)**:

  .. code-block:: bash

     Settings for spe4:
         Supported ports: [ TP ]
         Supported link modes:   100baseT1/Full
         Supported pause frame use: No
         Supports auto-negotiation: No
         Supported FEC modes: Not reported
         Advertised link modes: Not applicable
         Advertised pause frame use: No
         Advertised auto-negotiation: No
         Advertised FEC modes: Not reported
         Speed: 100Mb/s
         Duplex: Full
         Auto-negotiation: off
         master-slave cfg: forced slave
         master-slave status: slave
         Port: Twisted Pair
         PHYAD: 6
         Transceiver: external
         MDI-X: Unknown
         Supports Wake-on: d
         Wake-on: d
         Link detected: yes
         SQI: 7/7
         Link Down Events: 2

- **Example Output for MPE Interface (Autonegotiation)**:

  .. code-block:: bash

     Settings for eth1:
         Supported ports: [ TP    MII ]
         Supported link modes:   10baseT/Half 10baseT/Full
                                 100baseT/Half 100baseT/Full
         Supported pause frame use: Symmetric Receive-only
         Supports auto-negotiation: Yes
         Supported FEC modes: Not reported
         Advertised link modes:  10baseT/Half 10baseT/Full
                                 100baseT/Half 100baseT/Full
         Advertised pause frame use: Symmetric Receive-only
         Advertised auto-negotiation: Yes
         Advertised FEC modes: Not reported
         Link partner advertised link modes:  10baseT/Half 10baseT/Full
                                              100baseT/Half 100baseT/Full
         Link partner advertised pause frame use: Symmetric Receive-only
         Link partner advertised auto-negotiation: Yes
         Link partner advertised FEC modes: Not reported
         Speed: 100Mb/s
         Duplex: Full
         Auto-negotiation: on
         Port: Twisted Pair
         PHYAD: 10
         Transceiver: internal
         MDI-X: Unknown
         Supports Wake-on: pg
         Wake-on: p
         Link detected: yes
         Link Down Events: 1

- **Next Steps**:

  - Record the output provided by `ethtool`, particularly noting the
    **master-slave status**, **speed**, **duplex**, and other relevant fields.
    This information will be useful for further analysis or troubleshooting.
    Once the **ethtool** output has been collected and stored, move on to the
    next diagnostic step.

PoDL·PoE 전력 공급 확인

전력 공급 확인(PoDL 또는 PoE)

시스템이 PoDL·PoE를 구현하지 않았거나 PSE를 전용 사용자 공간 소프트웨어·외부 도구로 관리한다면 이 단계를 건너뜁니다. 대신 LED, 멀티미터, 공급업체 소프트웨어로 전력을 확인합니다.

Linux가 PoDL 또는 PoE를 직접 관리한다면 `ethtool --show-pse <interface>`로 공급 상태를 확인합니다.

가용 전력 한도가 링크 상대편에 부족하면 다음 명령으로 높일 수 있습니다.

ethtool --set-pse <interface> c33-pse-avail-pw-limit <limit>
ethtool --set-pse eth1 c33-pse-avail-pw-limit 18000
ethtool --show-pse eth1

조정 뒤에는 `Clause 33 PSE Available Power Limit: 18000`처럼 새 한도가 표시되어야 합니다.

PoE·PoDL을 쓰지 않으면 다음 진단으로 이동합니다. Linux PSE-PD 프레임워크 밖에서 제어한다면 공급업체 문서와 외부 도구를 사용해야 하며 이 문서의 범위를 벗어납니다.

`PSE Admin State`가 disabled이면 PoDL은 `ethtool --set-pse <devname> podl-pse-admin-control enable`, Clause 33 PoE는 `ethtool --set-pse <devname> c33-pse-admin-control enable`로 활성화한 뒤 전력 확인 단계 처음부터 다시 검사합니다.

`Power Detection Status`가 `delivering power`가 아니고 `over current` 같은 값을 보이면 케이블 단락, 부족한 공급 전력, PSE 자체 결함을 조사합니다. 전력은 공급되지만 링크가 없다면 케이블 진단과 PHY 구성 검사를 진행합니다.

Check Power Delivery (PoDL or PoE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If it is known that **PoDL** or **PoE** is **not implemented** on the system,
or the **PSE** (Power Sourcing Equipment) is managed by proprietary user-space
software or external tools, you can skip this step. In such cases, verify power
delivery through alternative methods, such as checking hardware indicators
(LEDs), using multimeters, or consulting vendor-specific software for
monitoring power status.

If **PoDL** or **PoE** is implemented and managed directly by Linux, follow
these steps to ensure power is being delivered correctly:

- **Command:** `ethtool --show-pse <interface>`

- **Expected Output Examples**:

  1. **PSE Not Supported**:

     If no PSE is attached or the interface does not support PSE, the following
     output is expected:

     .. code-block:: bash

        netlink error: No PSE is attached
        netlink error: Operation not supported

  2. **PoDL (Single-Pair Ethernet)**:

     When PoDL is implemented, you might see the following attributes:

     .. code-block:: bash

        PSE attributes for eth1:
        PoDL PSE Admin State: enabled
        PoDL PSE Power Detection Status: delivering power

  3. **PoE (Clause 33 PSE)**:

     For standard PoE, the output may look like this:

     .. code-block:: bash

        PSE attributes for eth1:
        Clause 33 PSE Admin State: enabled
        Clause 33 PSE Power Detection Status: delivering power
        Clause 33 PSE Available Power Limit: 18000

- **Adjust Power Limit (if needed)**:

  - Sometimes, the available power limit may not be sufficient for the link
    partner. You can increase the power limit as needed.

  - **Command:** `ethtool --set-pse <interface> c33-pse-avail-pw-limit <limit>`

    Example:

    .. code-block:: bash

      ethtool --set-pse eth1 c33-pse-avail-pw-limit 18000
      ethtool --show-pse eth1

    **Expected Output** after adjusting the power limit:

    .. code-block:: bash

      Clause 33 PSE Available Power Limit: 18000


- **Next Steps**:

  - **PoE or PoDL Not Used**: If **PoE** or **PoDL** is not implemented or used
    on the system, proceed to the next diagnostic step, as power delivery is
    not relevant for this setup.

  - **PoE or PoDL Controlled Externally**: If **PoE** or **PoDL** is used but
    is not managed by the Linux kernel's **PSE-PD** framework (i.e., it is
    controlled by proprietary user-space software or external tools), this part
    is out of scope for this documentation. Please consult vendor-specific
    documentation or external tools for monitoring and managing power delivery.

  - **PSE Admin State Disabled**:

    - If the `PSE Admin State:` is **disabled**, enable it by running one of
      the following commands:

      .. code-block:: bash

         ethtool --set-pse <devname> podl-pse-admin-control enable

      or, for Clause 33 PSE (PoE):

         ethtool --set-pse <devname> c33-pse-admin-control enable

    - After enabling the PSE Admin State, return to the start of the **Check
      Power Delivery (PoDL or PoE)** step to recheck the power delivery status.

  - **Power Not Delivered**: If the `Power Detection Status` shows something
    other than "delivering power" (e.g., `over current`), troubleshoot the
    **PSE**. Check for potential issues such as a short circuit in the cable,
    insufficient power delivery, or a fault in the PSE itself.

  - **Power Delivered but No Link**: If power is being delivered but no link is
    established, proceed with further diagnostics by performing **Cable
    Diagnostics** or reviewing the **Inspect Link Status and PHY
    Configuration** steps to identify any underlying issues with the physical
    link or settings.

SPE·MPE 케이블 진단

케이블 진단

`ethtool --cable-test <interface>`로 open circuit, short, impedance mismatch, noise 같은 물리 계층 결함을 시험합니다. 결과는 케이블 상태, 사용 기술, 링크 상대편 상태에 따라 달라질 수 있습니다.

SPE 예제의 `Pair A, fault length: 25.00m`와 `Pair A code Open Circuit`는 보고 거리 근처의 단선이나 케이블 결함을 뜻할 수 있지만 상대편 상태의 영향도 받습니다.

MPE 예제에서 Pair A와 B는 `OK`, Pair C는 `Open Circuit`입니다. A와 B에서 자동 협상을 사용 중이면 케이블 시험이 방해받을 수도 있습니다.

Cable test completed for device eth1.
Pair A, fault length: 25.00m
Pair A code Open Circuit

Cable test completed for device eth0.
Pair A code OK
Pair B code OK
Pair C code Open Circuit

각 결과의 자세한 해석은 다음 문제 해결 절을 따릅니다.

Cable Diagnostics
~~~~~~~~~~~~~~~~~

Use `ethtool` to test for physical layer issues such as cable faults. The test
results can vary depending on the cable's condition, the technology in use, and
the state of the link partner. The results from the cable test will help in
diagnosing issues like open circuits, shorts, impedance mismatches, and
noise-related problems.

- **Command:** `ethtool --cable-test <interface>`

The following are the typical outputs for **Single-Pair Ethernet (SPE)** and
**Multi-Pair Ethernet (MPE)**:

- **For Single-Pair Ethernet (SPE)**:
  - **Expected Output (SPE)**:

  .. code-block:: bash

    Cable test completed for device eth1.
    Pair A, fault length: 25.00m
    Pair A code Open Circuit

  This indicates an open circuit or cable fault at the reported distance, but
  results can be influenced by the link partner's state. Refer to the
  **"Troubleshooting Based on Cable Test Results"** section for further
  interpretation of these results.

- **For Multi-Pair Ethernet (MPE)**:
  - **Expected Output (MPE)**:

  .. code-block:: bash

    Cable test completed for device eth0.
    Pair A code OK
    Pair B code OK
    Pair C code Open Circuit

  Here, Pair C is reported as having an open circuit, while Pairs A and B are
  functioning correctly. However, if autonegotiation is in use on Pairs A and
  B, the cable test may be disrupted. Refer to the **"Troubleshooting Based on
  Cable Test Results"** section for a detailed explanation of these issues and
  how to resolve them.

For detailed descriptions of the different possible cable test results, please
refer to the **"Troubleshooting Based on Cable Test Results"** section.

케이블 시험의 한계와 오탐

케이블 시험 결과에 따른 문제 해결

케이블 시험 정확도와 신뢰성은 로컬 하드웨어와 링크 상대편의 능력·특성에 크게 좌우되며 구현마다 상당히 다를 수 있습니다.

현재 구현에는 실제 물리 상태를 정확히 반영하지 못하는 사각지대가 있습니다. `Open Circuit`은 케이블 손상·분리뿐 아니라 정상 케이블의 상대편 전원이 꺼졌을 때도 나올 수 있습니다. 일부 PHY는 상대편이 forced slave이면 실제 단락이 없어도 `Short within Pair`를 보고할 수 있습니다.

커널 UAPI가 하드웨어 특성에 따른 추가 맥락이나 가능한 변형을 제공하도록 확장하면 해석이 쉬워집니다. 이런 특성은 하드웨어별로 다르므로 커널 드라이버가 각 결과의 잠재적 오탐 플래그나 힌트를 제공하기에 적합합니다.

개선 전까지는 한계를 인지하고 필요하면 케이블을 직접 검사해 오탐 여부를 확인해야 합니다.

Troubleshooting Based on Cable Test Results
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After running the cable test, the results can help identify specific issues in
the physical connection. However, it is important to note that **cable testing
results heavily depend on the capabilities and characteristics of both the
local hardware and the link partner**. The accuracy and reliability of the
results can vary significantly between different hardware implementations.

In some cases, this can introduce **blind spots** in the current cable testing
implementation, where certain results may not accurately reflect the actual
physical state of the cable. For example:

- An **Open Circuit** result might not only indicate a damaged or disconnected
  cable but also occur if the cable is properly attached to a powered-down link
  partner.

- Some PHYs may report a **Short within Pair** if the link partner is in
  **forced slave mode**, even though there is no actual short in the cable.

To help users interpret the results more effectively, it could be beneficial to
extend the **kernel UAPI** (User API) to provide additional context or
**possible variants** of issues based on the hardware’s characteristics. Since
these quirks are often hardware-specific, the **kernel driver** would be an
ideal source of such information. By providing flags or hints related to
potential false positives for each test result, users would have a better
understanding of what to verify and where to investigate further.

Until such improvements are made, users should be aware of these limitations
and manually verify cable issues as needed. Physical inspections may help
resolve uncertainties related to false positive results.

케이블 시험 결과별 조치

The results can be one of the following:

- **OK**:

  - The cable is functioning correctly, and no issues were detected.

  - **Next Steps**: If you are still experiencing issues, it might be related
    to higher-layer problems, such as duplex mismatches or speed negotiation,
    which are not physical-layer issues.

  - **Special Case for `BaseT1` (1000/100/10BaseT1)**: In `BaseT1` systems, an
    "OK" result typically also means that the link is up and likely in **slave
    mode**, since cable tests usually only pass in this mode. For some
    **10BaseT1L** PHYs, an "OK" result may occur even if the cable is too long
    for the PHY's configured range (for example, when the range is configured
    for short-distance mode).

- **Open Circuit**:

  - An **Open Circuit** result typically indicates that the cable is damaged or
    disconnected at the reported fault length. Consider these possibilities:

    - If the link partner is in **admin down** state or powered off, you might
      still get an "Open Circuit" result even if the cable is functional.

    - **Next Steps**: Inspect the cable at the fault length for visible damage
      or loose connections. Verify the link partner is powered on and in the
      correct mode.

- **Short within Pair**:

  - A **Short within Pair** indicates an unintended connection within the same
    pair of wires, typically caused by physical damage to the cable.

    - **Next Steps**: Replace or repair the cable and check for any physical
      damage or improperly crimped connectors.

- **Short to Another Pair**:

  - A **Short to Another Pair** means the wires from different pairs are
    shorted, which could occur due to physical damage or incorrect wiring.

    - **Next Steps**: Replace or repair the damaged cable. Inspect the cable for
      incorrect terminations or pinched wiring.

- **Impedance Mismatch**:

  - **Impedance Mismatch** indicates a reflection caused by an impedance
    discontinuity in the cable. This can happen when a part of the cable has
    abnormal impedance (e.g., when different cable types are spliced together
    or when there is a defect in the cable).

    - **Next Steps**: Check the cable quality and ensure consistent impedance
      throughout its length. Replace any sections of the cable that do not meet
      specifications.

- **Noise**:

  - **Noise** means that the Time Domain Reflectometry (TDR) test could not
    complete due to excessive noise on the cable, which can be caused by
    interference from electromagnetic sources.

    - **Next Steps**: Identify and eliminate sources of electromagnetic
      interference (EMI) near the cable. Consider using shielded cables or
      rerouting the cable away from noise sources.

- **Resolution Not Possible**:

  - **Resolution Not Possible** means that the TDR test could not detect the
    issue due to the resolution limitations of the test or because the fault is
    beyond the distance that the test can measure.

    - **Next Steps**: Inspect the cable manually if possible, or use alternative
      diagnostic tools that can handle greater distances or higher resolution.

- **Unknown**:

  - An **Unknown** result may occur when the test cannot classify the fault or
    when a specific issue is outside the scope of the tool's detection
    capabilities.

    - **Next Steps**: Re-run the test, verify the link partner's state, and inspect
      the cable manually if necessary.

링크 상대편과 자동 협상 확인

링크 상대편 PHY 구성 확인

케이블 시험은 통과했지만 링크가 정상 동작하지 않으면 상대편 PHY 구성을 확인합니다. 속도, duplex, master-slave 역할 불일치는 연결 문제를 일으킬 수 있습니다.

자동 협상 불일치

양쪽이 자동 협상을 지원한다면 양쪽에서 켜고 지원하는 모든 링크 모드를 광고해야 합니다. 불일치는 연결 실패나 성능 저하를 일으킵니다. 다음 명령은 기본 설정으로 되돌려 모든 기본 링크 모드를 광고합니다.

ethtool -s <interface> autoneg on

`ethtool <interface>`로 양쪽이 호환 모드를 광고하는지 확인합니다. 자동 협상이 꺼졌다면 속도와 duplex가 같은지 확인합니다. 지원 모드보다 광고 모드가 적으면 상대편과 겹치는 모드가 줄고, 공통 모드가 없으면 링크가 형성되지 않습니다.

한쪽은 자동 협상이고 다른 쪽은 구형 장비처럼 강제 링크 모드인 결합 불일치에서는 현대 PHY가 강제 모드를 감지하려 시도합니다. 링크가 생겨도 상대편 광고 모드가 비어 있고 상대편 자동 협상은 `no`이거나 표시되지 않을 수 있습니다.

이 감지는 항상 신뢰할 수 있지 않습니다. 현대 PHY가 상대편의 full duplex 설정과 달리 half duplex를 기본 선택할 수 있고, 상대편이 강제 모드를 바꾸면 down/up cycle 전까지 제대로 동작하지 않는 PHY도 있습니다.

감지 문제를 피하려면 양쪽을 같은 고정 속도와 duplex로 설정합니다.

ethtool -s <interface> speed 1000 duplex full autoneg off

Verify Link Partner PHY Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the cable test passes but the link is still not functioning correctly, it’s
essential to verify the configuration of the link partner’s PHY. Mismatches in
speed, duplex settings, or master-slave roles can cause connection issues.

Autonegotiation Mismatch
^^^^^^^^^^^^^^^^^^^^^^^^

- If both link partners support autonegotiation, ensure that autonegotiation is
  enabled on both sides and that all supported link modes are advertised. A
  mismatch can lead to connectivity problems or sub optimal performance.

- **Quick Fix:** Reset autonegotiation to the default settings, which will
  advertise all default link modes:

  .. code-block:: bash

     ethtool -s <interface> autoneg on

- **Command to check configuration:** `ethtool <interface>`

- **Expected Output:** Ensure that both sides advertise compatible link modes.
  If autonegotiation is off, verify that both link partners are configured for
  the same speed and duplex.

  The following example shows a case where the local PHY advertises fewer link
  modes than it supports. This will reduce the number of overlapping link modes
  with the link partner. In the worst case, there will be no common link modes,
  and the link will not be created:

  .. code-block:: bash

     Settings for eth0:
        Supported link modes:  1000baseT/Full, 100baseT/Full
        Advertised link modes: 1000baseT/Full
        Speed: 1000Mb/s
        Duplex: Full
        Auto-negotiation: on

Combined Mode Mismatch (Autonegotiation on One Side, Forced on the Other)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- One possible issue occurs when one side is using **autonegotiation** (as in
  most modern systems), and the other side is set to a **forced link mode**
  (e.g., older hardware with single-speed hubs). In such cases, modern PHYs
  will attempt to detect the forced mode on the other side. If the link is
  established, you may notice:

  - **No or empty "Link partner advertised link modes"**.

  - **"Link partner advertised auto-negotiation:"** will be **"no"** or not
    present.

- This type of detection does not always work reliably:

  - Typically, the modern PHY will default to **Half Duplex**, even if the link
    partner is actually configured for **Full Duplex**.

  - Some PHYs may not work reliably if the link partner switches from one
    forced mode to another. In this case, only a down/up cycle may help.

- **Next Steps**: Set both sides to the same fixed speed and duplex mode to
  avoid potential detection issues.

  .. code-block:: bash

     ethtool -s <interface> speed 1000 duplex full autoneg off

Master·slave 역할 불일치

Master/Slave 역할 불일치(BaseT1과 1000BaseT PHY)

1000BaseT1·100BaseT1 같은 BaseT1은 한 장치를 master, 다른 장치를 slave로 구성해야 링크가 형성됩니다. 1000BaseT도 역할을 구성할 수 있어 같은 문제가 생길 수 있습니다.

1000BaseT는 자동 협상 중 역할이나 역할 선호도를 협상합니다. 특정 역할에서 동작하지 못하는 하드웨어 한계나 버그가 있으면 드라이버가 forced master·forced slave를 설정하거나 preferred 같은 약한 선호를 줄 수 있습니다. 양쪽이 같은 문제로 같은 강제 역할을 가지면 링크를 만들 수 없습니다.

하드웨어 제한이 있다면 한쪽은 master, 다른 쪽은 slave로 맞추거나 forced 대신 preferred를 사용하고, 드라이버 제한과 강제 모드를 확인합니다.

ethtool -s <interface> master-slave forced-master
ethtool -s <interface> master-slave forced-master speed 1000 duplex full autoneg off
ethtool <interface>

현재 상태는 `master-slave cfg: forced-master`, `master-slave status: master`처럼 표시됩니다.

알려진 하드웨어 문제로 특정 모드가 강제된다면 드라이버 소스와 하드웨어 문서를 확인해 양쪽 역할이 호환되는지 검증하고, 둘 다 같은 모드라면 한쪽을 조정합니다.

Master/Slave Role Mismatch (BaseT1 and 1000BaseT PHYs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- In **BaseT1** systems (e.g., 1000BaseT1, 100BaseT1), link establishment
  requires that one device is configured as **master** and the other as
  **slave**. A mismatch in this master-slave configuration can prevent the link
  from being established. However, **1000BaseT** also supports configurable
  master/slave roles and can face similar issues.

- **Role Preference in 1000BaseT**: The **1000BaseT** specification allows link
  partners to negotiate master-slave roles or role preferences during
  autonegotiation. Some PHYs have hardware limitations or bugs that prevent
  them from functioning properly in certain roles. In such cases, drivers may
  force these PHYs into a specific role (e.g., **forced master** or **forced
  slave**) or try a weaker option by setting preferences. If both link partners
  have the same issue and are forced into the same mode (e.g., both forced into
  master mode), they will not be able to establish a link.

- **Next Steps**: Ensure that one side is configured as **master** and the
  other as **slave** to avoid this issue, particularly when hardware
  limitations are involved, or try the weaker **preferred** option instead of
  **forced**. Check for any driver-related restrictions or forced modes.

- **Command to force master/slave mode**:

  .. code-block:: bash

     ethtool -s <interface> master-slave forced-master

  or:

  .. code-block:: bash

     ethtool -s <interface> master-slave forced-master speed 1000 duplex full autoneg off


- **Check the current master/slave status**:

  .. code-block:: bash

     ethtool <interface>

  Example Output:

  .. code-block:: bash

     master-slave cfg: forced-master
     master-slave status: master

- **Hardware Bugs and Driver Forcing**: If a known hardware issue forces the
  PHY into a specific mode, it’s essential to check the driver source code or
  hardware documentation for details. Ensure that the roles are compatible
  across both link partners, and if both PHYs are forced into the same mode,
  adjust one side accordingly to resolve the mismatch.

링크 재설정과 속도 저하 감시

링크 재설정과 속도 저하 감시

잦은 재설정과 속도 저하는 케이블, PHY 구성, 환경 요인의 문제일 수 있습니다. 사용자 공간에서 downshift나 속도 변화를 직접 감시하는 완전히 통일된 방법은 아직 없지만, 드라이버 지원 여부에 따라 커널 로그와 `ethtool`이 정보를 제공합니다.

커널 로그는 downshift를 포함한 링크 상태 변화와 속도·duplex를 기록할 수 있습니다.

dmesg -w | grep "Link is Up\|Link is Down"
eth0: Link is Up - 100Mbps/Full (downshifted) - flow control rx/tx
eth0: Link is Down

이 출력은 링크가 형성되었지만 더 높은 속도에서 downshift되었음을 뜻합니다. 모든 드라이버와 PHY가 이를 보고하지는 않습니다.

최신 커널과 ethtool에서는 `ethtool -I <interface>`의 `Link Down Events` counter로 링크 끊김 횟수를 추적할 수 있습니다. 값이 5라면 링크가 5회 끊긴 것이며 케이블이나 환경 문제를 더 조사해야 합니다.

downshift 횟수를 직접 얻지 못해도 `ethtool <interface>`로 현재 speed, duplex, 자동 협상, 링크 감지 상태를 확인할 수 있습니다. 기대값과 불일치하면 문제가 있을 수 있습니다.

Monitor Link Resets and Speed Drops
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the link is unstable, showing frequent resets or speed drops, this may
indicate issues with the cable, PHY configuration, or environmental factors.
While there is still no completely unified way in Linux to directly monitor
downshift events or link speed changes via user space tools, both the Linux
kernel logs and `ethtool` can provide valuable insights, especially if the
driver supports reporting such events.

- **Monitor Kernel Logs for Link Resets and Speed Drops**:

  - The Linux kernel will print link status changes, including downshift
    events, in the system logs. These messages typically include speed changes,
    duplex mode, and downshifted link speed (if the driver supports it).

  - **Command to monitor kernel logs in real-time:**

    .. code-block:: bash

      dmesg -w | grep "Link is Up\|Link is Down"

  - Example Output (if a downshift occurs):

    .. code-block:: bash

      eth0: Link is Up - 100Mbps/Full (downshifted) - flow control rx/tx
      eth0: Link is Down

    This indicates that the link has been established but has downshifted from
    a higher speed.

  - **Note**: Not all drivers or PHYs support downshift reporting, so you may
    not see this information for all devices.

- **Monitor Link Down Events Using `ethtool`**:

  - Starting with the latest kernel and `ethtool` versions, you can track
    **Link Down Events** using the `ethtool -I` command. This will provide
    counters for link drops, helping to diagnose link instability issues if
    supported by the driver.

  - **Command to monitor link down events:**

    .. code-block:: bash

      ethtool -I <interface>

  - Example Output (if supported):

    .. code-block:: bash

      PSE attributes for eth1:
      Link Down Events: 5

    This indicates that the link has dropped 5 times. Frequent link down events
    may indicate cable or environmental issues that require further
    investigation.

- **Check Link Status and Speed**:

  - Even though downshift counts or events are not easily tracked, you can
    still use `ethtool` to manually check the current link speed and status.

  - **Command:** `ethtool <interface>`

  - **Expected Output:**

    .. code-block:: bash

      Speed: 1000Mb/s
      Duplex: Full
      Auto-negotiation: on
      Link detected: yes

    Any inconsistencies in the expected speed or duplex setting could indicate
    an issue.

EEE 격리와 오류 counter 비교

진단을 위해 Energy-Efficient Ethernet(EEE) 비활성화

EEE는 저전력 상태 진입·이탈 때문에 링크 불안정의 원인이 될 수 있습니다. 진단 목적으로만 일시적으로 EEE를 꺼서 원인인지 확인할 수 있으며, 전력 관리를 일반적으로 끄라는 권고가 아닙니다.

ethtool --set-eee <interface> eee off

EEE를 끄자 안정화된다면 유지보수 담당자에게 버그로 보고해 드라이버가 EEE를 올바르게 처리하도록 수정해야 합니다. 영구 비활성화는 해결책으로 간주하면 안 됩니다.

오류 counter 감시

통합 인터페이스를 지원하면 `ethtool -S <interface> --all-groups`로 표준화된 `phydev-RxFrames`, `phydev-RxErrors`, `phydev-TxFrames`, `phydev-TxErrors`를 얻습니다.

지원하지 않으면 `ethtool -S <interface>`로 MAC·PHY counter를 얻습니다. `rx_crc_errors`, `tx_errors`, `rx_frame_errors` 같은 비표준 PHY 이름은 드라이버마다 달라 해석이 필요합니다.

의미 있는 counter가 없으면 케이블 상태를 직접 확인하거나 링크 up/down 커널 로그를 사용합니다.

PHY와 MAC이 보고한 송신·수신 frame 수를 비교합니다. 샘플링 속도 차이나 PHY·MAC의 UP/DOWN 동기 차이 때문에 작은 차이는 생길 수 있지만, 큰 차이는 MAC과 PHY 사이 데이터 경로 문제를 나타냅니다.

- **Disable Energy-Efficient Ethernet (EEE) for Diagnostics**:

  - **EEE** (Energy-Efficient Ethernet) can be a source of link instability due
    to transitions in and out of low-power states. For diagnostic purposes, it
    may be useful to **temporarily** disable EEE to determine if it is
    contributing to link instability. This is **not a generic recommendation**
    for disabling power management.

  - **Next Steps**: Disable EEE and monitor if the link becomes stable. If
    disabling EEE resolves the issue, report the bug so that the driver can be
    fixed.

  - **Command:**

    .. code-block:: bash

      ethtool --set-eee <interface> eee off

  - **Important**: If disabling EEE resolves the instability, the issue should
    be reported to the maintainers as a bug, and the driver should be corrected
    to handle EEE properly without causing instability. Disabling EEE
    permanently should not be seen as a solution.

- **Monitor Error Counters**:

  - Use `ethtool -S <interface> --all-groups` to retrieve standardized interface
    statistics if the driver supports the unified interface:

  - **Command:** `ethtool -S <interface> --all-groups`

  - **Example Output (if supported)**:

    .. code-block:: bash

      phydev-RxFrames: 100391
      phydev-RxErrors: 0
      phydev-TxFrames: 9
      phydev-TxErrors: 0

  - If the unified interface is not supported, use `ethtool -S <interface>` to
    retrieve MAC and PHY counters. Note that non-standardized PHY counter names
    vary by driver and must be interpreted accordingly:

  - **Command:** `ethtool -S <interface>`

  - **Example Output (if supported)**:

    .. code-block:: bash

      rx_crc_errors: 123
      tx_errors: 45
      rx_frame_errors: 78

  - **Note**: If no meaningful error counters are available or if counters are
    not supported, you may need to rely on physical inspections (e.g., cable
    condition) or kernel log messages (e.g., link up/down events) to further
    diagnose the issue.

  - **Compare Counters**:

    - Compare the egress and ingress frame counts reported by the PHY and MAC.

    - A small difference may occur due to sampling rate differences between the
      MAC and PHY drivers, or if the PHY and MAC are not always fully
      synchronized in their UP or DOWN states.

    - Significant discrepancies indicate potential issues in the data path
      between the MAC and PHY.

모든 단계로도 해결되지 않을 때

모든 방법이 실패할 때

케이블을 확인하고 로그를 감시하고 EEE를 껐는데도 해결되지 않을 수 있습니다. PHY에 문서화되지 않은 고유 동작이 있거나, 문제가 간헐적으로 잠복했다가 사라지거나, 아직 해결 방법이 개발되지 않았을 가능성이 있습니다.

새롭거나 특이한 문제와 창의적인 진단 방법을 발견했다면 결과를 공유하고 이 문서를 확장하는 것이 마지막 단계입니다. 재부팅으로 해결될 때도 있지만 그렇지 않으면 더 깊이 조사하거나 버그를 보고해야 합니다.

When All Else Fails...
~~~~~~~~~~~~~~~~~~~~~~

So you've checked the cables, monitored the logs, disabled EEE, and still...
nothing? Don’t worry, you’re not alone. Sometimes, Ethernet gremlins just don’t
want to cooperate.

But before you throw in the towel (or the Ethernet cable), take a deep breath.
It’s always possible that:

1. Your PHY has a unique, undocumented personality.

2. The problem is lying dormant, waiting for just the right moment to magically
   resolve itself (hey, it happens!).

3. Or, it could be that the ultimate solution simply hasn’t been invented yet.

If none of the above bring you comfort, there’s one final step: contribute! If
you've uncovered new or unusual issues, or have creative diagnostic methods,
feel free to share your findings and extend this documentation. Together, we
can hunt down every elusive network issue - one twisted pair at a time.

Remember: sometimes the solution is just a reboot away, but if not, it’s time to
dig deeper - or report that bug!