Commit b28efb93 authored by Andrew Lunn's avatar Andrew Lunn Committed by Jakub Kicinski
Browse files

net: ethtool: Add attributes for cable test reports 



Add the attributes needed to report cable test results to userspace.
The reports are expected to be per twisted pair. A nested property per
pair can report the result of the cable test. A nested property can
also report the length of the cable to any fault.

v2:
Grammar fixes
Change length from u16 to u32
s/DEV/HEADER/g
Add status attributes
Rename pairs from numbers to letters.

v3:
Fixed example in document
Add ETHTOOL_A_CABLE_NEST_* enum
Add ETHTOOL_MSG_CABLE_TEST_NTF to documentation

Signed-off-by: default avatarAndrew Lunn <andrew@lunn.ch>
Reviewed-by: default avatarFlorian Fainelli <f.fainelli@gmail.com>
Reviewed-by: default avatarMichal Kubecek <mkubecek@suse.cz>
Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 11ca3c42

Documentation/networking/ethtool-netlink.rst

+41 −0
Original line number Diff line number Diff line
@@ -236,6 +236,7 @@ Kernel to userspace: 
  ``ETHTOOL_MSG_EEE_GET_REPLY``         EEE settings

  ``ETHTOOL_MSG_EEE_NTF``               EEE settings

  ``ETHTOOL_MSG_TSINFO_GET_REPLY``	timestamping info

  ``ETHTOOL_MSG_CABLE_TEST_NTF``        Cable test results

  ===================================== =================================



``GET`` requests are sent by userspace applications to retrieve device
@@ -970,6 +971,46 @@ Request contents: 
  ``ETHTOOL_A_CABLE_TEST_HEADER``       nested  request header

  ====================================  ======  ==========================



Notification contents:



An Ethernet cable typically contains 1, 2 or 4 pairs. The length of

the pair can only be measured when there is a fault in the pair and

hence a reflection. Information about the fault may not be available,

depending on the specific hardware. Hence the contents of the notify

message are mostly optional. The attributes can be repeated an

arbitrary number of times, in an arbitrary order, for an arbitrary

number of pairs.



The example shows the notification sent when the test is completed for

a T2 cable, i.e. two pairs. One pair is OK and hence has no length

information. The second pair has a fault and does have length

information.



 +---------------------------------------------+--------+---------------------+

 | ``ETHTOOL_A_CABLE_TEST_HEADER``             | nested | reply header        |

 +---------------------------------------------+--------+---------------------+

 | ``ETHTOOL_A_CABLE_TEST_STATUS``             | u8     | completed           |

 +---------------------------------------------+--------+---------------------+

 | ``ETHTOOL_A_CABLE_TEST_NTF_NEST``           | nested | all the results     |

 +-+-------------------------------------------+--------+---------------------+

 | | ``ETHTOOL_A_CABLE_NEST_RESULT``           | nested | cable test result   |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR``        | u8     | pair number         |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE``        | u8     | result code         |

 +-+-+-----------------------------------------+--------+---------------------+

 | | ``ETHTOOL_A_CABLE_NEST_RESULT``           | nested | cable test results  |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_RESULTS_PAIR``        | u8     | pair number         |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_RESULTS_CODE``        | u8     | result code         |

 +-+-+-----------------------------------------+--------+---------------------+

 | | ``ETHTOOL_A_CABLE_NEST_FAULT_LENGTH``     | nested | cable length        |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR``   | u8     | pair number         |

 +-+-+-----------------------------------------+--------+---------------------+

 | | | ``ETHTOOL_A_CABLE_FAULT_LENGTH_CM``     | u32    | length in cm        |

 +-+-+-----------------------------------------+--------+---------------------+



Request translation

===================

include/uapi/linux/ethtool_netlink.h

+59 −0
Original line number Diff line number Diff line
@@ -75,6 +75,7 @@ enum { 
	ETHTOOL_MSG_EEE_GET_REPLY,

	ETHTOOL_MSG_EEE_NTF,

	ETHTOOL_MSG_TSINFO_GET_REPLY,

	ETHTOOL_MSG_CABLE_TEST_NTF,



	/* add new constants above here */

	__ETHTOOL_MSG_KERNEL_CNT,
@@ -417,6 +418,64 @@ enum { 
	ETHTOOL_A_CABLE_TEST_MAX = __ETHTOOL_A_CABLE_TEST_CNT - 1

};



/* CABLE TEST NOTIFY */

enum {

	ETHTOOL_A_CABLE_RESULT_CODE_UNSPEC,

	ETHTOOL_A_CABLE_RESULT_CODE_OK,

	ETHTOOL_A_CABLE_RESULT_CODE_OPEN,

	ETHTOOL_A_CABLE_RESULT_CODE_SAME_SHORT,

	ETHTOOL_A_CABLE_RESULT_CODE_CROSS_SHORT,

};



enum {

	ETHTOOL_A_CABLE_PAIR_A,

	ETHTOOL_A_CABLE_PAIR_B,

	ETHTOOL_A_CABLE_PAIR_C,

	ETHTOOL_A_CABLE_PAIR_D,

};



enum {

	ETHTOOL_A_CABLE_RESULT_UNSPEC,

	ETHTOOL_A_CABLE_RESULT_PAIR,		/* u8 ETHTOOL_A_CABLE_PAIR_ */

	ETHTOOL_A_CABLE_RESULT_CODE,		/* u8 ETHTOOL_A_CABLE_RESULT_CODE_ */



	__ETHTOOL_A_CABLE_RESULT_CNT,

	ETHTOOL_A_CABLE_RESULT_MAX = (__ETHTOOL_A_CABLE_RESULT_CNT - 1)

};



enum {

	ETHTOOL_A_CABLE_FAULT_LENGTH_UNSPEC,

	ETHTOOL_A_CABLE_FAULT_LENGTH_PAIR,	/* u8 ETHTOOL_A_CABLE_PAIR_ */

	ETHTOOL_A_CABLE_FAULT_LENGTH_CM,	/* u32 */



	__ETHTOOL_A_CABLE_FAULT_LENGTH_CNT,

	ETHTOOL_A_CABLE_FAULT_LENGTH_MAX = (__ETHTOOL_A_CABLE_FAULT_LENGTH_CNT - 1)

};



enum {

	ETHTOOL_A_CABLE_TEST_NTF_STATUS_UNSPEC,

	ETHTOOL_A_CABLE_TEST_NTF_STATUS_STARTED,

	ETHTOOL_A_CABLE_TEST_NTF_STATUS_COMPLETED

};



enum {

	ETHTOOL_A_CABLE_NEST_UNSPEC,

	ETHTOOL_A_CABLE_NEST_RESULT,		/* nest - ETHTOOL_A_CABLE_RESULT_ */

	ETHTOOL_A_CABLE_NEST_FAULT_LENGTH,	/* nest - ETHTOOL_A_CABLE_FAULT_LENGTH_ */

	__ETHTOOL_A_CABLE_NEST_CNT,

	ETHTOOL_A_CABLE_NEST_MAX = (__ETHTOOL_A_CABLE_NEST_CNT - 1)

};



enum {

	ETHTOOL_A_CABLE_TEST_NTF_UNSPEC,

	ETHTOOL_A_CABLE_TEST_NTF_HEADER,	/* nest - ETHTOOL_A_HEADER_* */

	ETHTOOL_A_CABLE_TEST_NTF_STATUS,	/* u8 - _STARTED/_COMPLETE */

	ETHTOOL_A_CABLE_TEST_NTF_NEST,		/* nest - of results: */



	__ETHTOOL_A_CABLE_TEST_NTF_CNT,

	ETHTOOL_A_CABLE_TEST_NTF_MAX = (__ETHTOOL_A_CABLE_TEST_NTF_CNT - 1)

};



/* generic netlink info */

#define ETHTOOL_GENL_NAME "ethtool"

#define ETHTOOL_GENL_VERSION 1

CRA Git | Maintained and supported by SUSTech CRA and CCSE