diff mbox series

[net-next,v2,2/8] ethtool: Expand Ethernet Power Equipment with c33 (PoE) alongside PoDL

Message ID 20231201-feature_poe-v2-2-56d8cac607fa@bootlin.com (mailing list archive)
State Changes Requested
Delegated to: Netdev Maintainers
Headers show
Series net: Add support for Power over Ethernet (PoE) | expand

Checks

Context Check Description
netdev/series_format success Posting correctly formatted
netdev/tree_selection success Clearly marked for net-next
netdev/ynl success Generated files up to date; no warnings/errors;
netdev/fixes_present success Fixes tag not required for -next series
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 2929 this patch: 2929
netdev/cc_maintainers warning 2 maintainers not CCed: keescook@chromium.org vladimir.oltean@nxp.com
netdev/build_clang success Errors and warnings before: 1275 this patch: 1275
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 3139 this patch: 3139
netdev/checkpatch warning WARNING: Non-standard signature: Sponsored-by: WARNING: added, moved or deleted file(s), does MAINTAINERS need updating? WARNING: line length of 82 exceeds 80 columns
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Kory Maincent Dec. 1, 2023, 5:10 p.m. UTC
In the current PSE interface for Ethernet Power Equipment, support is
limited to PoDL. This patch extends the interface to accommodate the
objects specified in IEEE 802.3-2022 145.2 for Power sourcing
Equipment (PSE).

The following objects are now supported and considered mandatory:
- IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus
- IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
- IEEE 802.3-2022 30.9.1.2.1 aPSEAdminControl

To avoid confusion between "PoDL PSE" and "PoE PSE", which have similar
names but distinct values, we have followed the suggestion of Oleksij
Rempel and Andrew Lunn to maintain separate naming schemes for each,
using c33 (clause 33) prefix for "PoE PSE".
You can find more details in the discussion threads here:
https://lore.kernel.org/netdev/20230912110637.GI780075@pengutronix.de/
https://lore.kernel.org/netdev/2539b109-72ad-470a-9dae-9f53de4f64ec@lunn.ch/

Sponsored-by: Dent Project <dentproject@linuxfoundation.org>
Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
---

Changes in v2:
- Rename all the PoE variables and enum with a c33 prefix.
- Add documentation, thanks to Oleksij for having written one.
---
 Documentation/networking/pse-pd/introduction.rst | 73 ++++++++++++++++++++++++
 include/linux/pse-pd/pse.h                       |  9 +++
 include/uapi/linux/ethtool.h                     | 43 ++++++++++++++
 include/uapi/linux/ethtool_netlink.h             |  3 +
 4 files changed, 128 insertions(+)

Comments

Andrew Lunn Dec. 3, 2023, 6:27 p.m. UTC | #1
> +++ b/Documentation/networking/pse-pd/introduction.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Power Sourcing Equipment (PSE) in IEEE 802.3 Standard
> +=====================================================
> +
> +Overview
> +--------
> +
> +Power Sourcing Equipment (PSE) is essential in networks for delivering power
> +along with data over Ethernet cables. It usually refers to devices like
> +switches and hubs that supply power to Powered Devices (PDs) such as IP
> +cameras, VoIP phones, and wireless access points.
> +
> +PSE vs. PoDL PSE
> +----------------
> +
> +PSE in the IEEE 802.3 standard generally refers to equipment that provides
> +power alongside data over Ethernet cables, typically associated with Power over
> +Ethernet (PoE).
> +
> +PoDL PSE, or Power over Data Lines PSE, specifically denotes PSEs operating
> +with single balanced twisted-pair PHYs, as per Clause 104 of IEEE 802.3. PoDL
> +is significant in contexts like automotive and industrial controls where power
> +and data delivery over a single pair is advantageous.
> +
> +IEEE 802.3-2018 Addendums and Related Clauses
> +----------------------------------------------
> +
> +Key addenda to the IEEE 802.3-2018 standard relevant to power delivery over
> +Ethernet are as follows:
> +
> +- **802.3af (Approved in 2003-06-12)**: Known as PoE in the market, detailed in
> +  Clause 33, delivering up to 15.4W of power.
> +- **802.3at (Approved in 2009-09-11)**: Marketed as PoE+, enhancing PoE as
> +  covered in Clause 33, increasing power delivery to up to 30W.
> +- **802.3bt (Approved in 2018-09-27)**: Known as 4PPoE in the market, outlined
> +  in Clause 33. Type 3 delivers up to 60W, and Type 4 up to 100W.
> +- **802.3bu (Approved in 2016-12-07)**: Formerly referred to as PoDL, detailed
> +  in Clause 104. Introduces Classes 0 - 9. Class 9 PoDL PSE delivers up to ~65W
> +
> +Kernel Naming Convention Recommendations
> +----------------------------------------
> +
> +For clarity and consistency within the Linux kernel's networking subsystem, the
> +following naming conventions are recommended:
> +
> +- For general PSE (PoE) code, use "c33_pse" key words. For example:
> +  ``enum ethtool_c33_pse_admin_state c33_admin_control;``.
> +  This aligns with Clause 33, encompassing various PoE forms.
> +
> +- For PoDL PSE - specific code, use "podl_pse". For example:
> +  ``enum ethtool_podl_pse_admin_state podl_admin_control;`` to differentiate
> +  PoDL PSE settings according to Clause 104.
> +
> +Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
> +-------------------------------------------------------------------------------------------
> +
> +Clause 33 of the IEEE 802.3 standard defines the functional and electrical
> +characteristics of Powered Device (PD) and Power Sourcing Equipment (PSE).
> +These entities enable power delivery using the same generic cabling as for data
> +transmission, integrating power with data communication for devices such as
> +10BASE-T, 100BASE-TX, or 1000BASE-T.
> +
> +Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
> +-------------------------------------------------------------------------------------------
> +
> +Clause 104 of the IEEE 802.3 standard delineates the functional and electrical
> +characteristics of PoDL Powered Devices (PDs) and PoDL Power Sourcing Equipment
> +(PSEs). These are designed for use with single balanced twisted-pair Ethernet
> +Physical Layers. In this clause, 'PSE' refers specifically to PoDL PSE, and
> +'PD' to PoDL PD. The key intent is to provide devices with a unified interface
> +for both data and the power required to process this data over a single
> +balanced twisted-pair Ethernet connection.

This is a nice summary of the different standard and naming. Thanks
for adding this.

The c33 prefix is not ideal in terms of 'marketing', but we now have a
clear structure for how these two different schemes are
same/different.

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew
Oleksij Rempel Dec. 4, 2023, 12:27 p.m. UTC | #2
On Fri, Dec 01, 2023 at 06:10:24PM +0100, Kory Maincent wrote:
> In the current PSE interface for Ethernet Power Equipment, support is
> limited to PoDL. This patch extends the interface to accommodate the
> objects specified in IEEE 802.3-2022 145.2 for Power sourcing
> Equipment (PSE).
> 
> The following objects are now supported and considered mandatory:
> - IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus
> - IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
> - IEEE 802.3-2022 30.9.1.2.1 aPSEAdminControl
> 
> To avoid confusion between "PoDL PSE" and "PoE PSE", which have similar
> names but distinct values, we have followed the suggestion of Oleksij
> Rempel and Andrew Lunn to maintain separate naming schemes for each,
> using c33 (clause 33) prefix for "PoE PSE".
> You can find more details in the discussion threads here:
> https://lore.kernel.org/netdev/20230912110637.GI780075@pengutronix.de/
> https://lore.kernel.org/netdev/2539b109-72ad-470a-9dae-9f53de4f64ec@lunn.ch/
> 
> Sponsored-by: Dent Project <dentproject@linuxfoundation.org>
> Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>

Reviewed-by: Oleksij Rempel <o.rempel@pengutronix.de>

Thx!

> ---
> 
> Changes in v2:
> - Rename all the PoE variables and enum with a c33 prefix.
> - Add documentation, thanks to Oleksij for having written one.
> ---
>  Documentation/networking/pse-pd/introduction.rst | 73 ++++++++++++++++++++++++
>  include/linux/pse-pd/pse.h                       |  9 +++
>  include/uapi/linux/ethtool.h                     | 43 ++++++++++++++
>  include/uapi/linux/ethtool_netlink.h             |  3 +
>  4 files changed, 128 insertions(+)
> 
> diff --git a/Documentation/networking/pse-pd/introduction.rst b/Documentation/networking/pse-pd/introduction.rst
> new file mode 100644
> index 000000000000..e213083b9aff
> --- /dev/null
> +++ b/Documentation/networking/pse-pd/introduction.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Power Sourcing Equipment (PSE) in IEEE 802.3 Standard
> +=====================================================
> +
> +Overview
> +--------
> +
> +Power Sourcing Equipment (PSE) is essential in networks for delivering power
> +along with data over Ethernet cables. It usually refers to devices like
> +switches and hubs that supply power to Powered Devices (PDs) such as IP
> +cameras, VoIP phones, and wireless access points.
> +
> +PSE vs. PoDL PSE
> +----------------
> +
> +PSE in the IEEE 802.3 standard generally refers to equipment that provides
> +power alongside data over Ethernet cables, typically associated with Power over
> +Ethernet (PoE).
> +
> +PoDL PSE, or Power over Data Lines PSE, specifically denotes PSEs operating
> +with single balanced twisted-pair PHYs, as per Clause 104 of IEEE 802.3. PoDL
> +is significant in contexts like automotive and industrial controls where power
> +and data delivery over a single pair is advantageous.
> +
> +IEEE 802.3-2018 Addendums and Related Clauses
> +----------------------------------------------
> +
> +Key addenda to the IEEE 802.3-2018 standard relevant to power delivery over
> +Ethernet are as follows:
> +
> +- **802.3af (Approved in 2003-06-12)**: Known as PoE in the market, detailed in
> +  Clause 33, delivering up to 15.4W of power.
> +- **802.3at (Approved in 2009-09-11)**: Marketed as PoE+, enhancing PoE as
> +  covered in Clause 33, increasing power delivery to up to 30W.
> +- **802.3bt (Approved in 2018-09-27)**: Known as 4PPoE in the market, outlined
> +  in Clause 33. Type 3 delivers up to 60W, and Type 4 up to 100W.
> +- **802.3bu (Approved in 2016-12-07)**: Formerly referred to as PoDL, detailed
> +  in Clause 104. Introduces Classes 0 - 9. Class 9 PoDL PSE delivers up to ~65W
> +
> +Kernel Naming Convention Recommendations
> +----------------------------------------
> +
> +For clarity and consistency within the Linux kernel's networking subsystem, the
> +following naming conventions are recommended:
> +
> +- For general PSE (PoE) code, use "c33_pse" key words. For example:
> +  ``enum ethtool_c33_pse_admin_state c33_admin_control;``.
> +  This aligns with Clause 33, encompassing various PoE forms.
> +
> +- For PoDL PSE - specific code, use "podl_pse". For example:
> +  ``enum ethtool_podl_pse_admin_state podl_admin_control;`` to differentiate
> +  PoDL PSE settings according to Clause 104.
> +
> +Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
> +-------------------------------------------------------------------------------------------
> +
> +Clause 33 of the IEEE 802.3 standard defines the functional and electrical
> +characteristics of Powered Device (PD) and Power Sourcing Equipment (PSE).
> +These entities enable power delivery using the same generic cabling as for data
> +transmission, integrating power with data communication for devices such as
> +10BASE-T, 100BASE-TX, or 1000BASE-T.
> +
> +Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
> +-------------------------------------------------------------------------------------------
> +
> +Clause 104 of the IEEE 802.3 standard delineates the functional and electrical
> +characteristics of PoDL Powered Devices (PDs) and PoDL Power Sourcing Equipment
> +(PSEs). These are designed for use with single balanced twisted-pair Ethernet
> +Physical Layers. In this clause, 'PSE' refers specifically to PoDL PSE, and
> +'PD' to PoDL PD. The key intent is to provide devices with a unified interface
> +for both data and the power required to process this data over a single
> +balanced twisted-pair Ethernet connection.
> diff --git a/include/linux/pse-pd/pse.h b/include/linux/pse-pd/pse.h
> index 199cf4ae3cf2..be4e5754eb24 100644
> --- a/include/linux/pse-pd/pse.h
> +++ b/include/linux/pse-pd/pse.h
> @@ -17,9 +17,12 @@ struct pse_controller_dev;
>   *
>   * @podl_admin_control: set PoDL PSE admin control as described in
>   *	IEEE 802.3-2018 30.15.1.2.1 acPoDLPSEAdminControl
> + * @c33_admin_control: set PSE admin control as described in
> + *	IEEE 802.3-2022 30.9.1.2.1 acPSEAdminControl
>   */
>  struct pse_control_config {
>  	enum ethtool_podl_pse_admin_state podl_admin_control;
> +	enum ethtool_c33_pse_admin_state c33_admin_control;
>  };
>  
>  /**
> @@ -29,10 +32,16 @@ struct pse_control_config {
>   *	functions. IEEE 802.3-2018 30.15.1.1.2 aPoDLPSEAdminState
>   * @podl_pw_status: power detection status of the PoDL PSE.
>   *	IEEE 802.3-2018 30.15.1.1.3 aPoDLPSEPowerDetectionStatus:
> + * @c33_admin_state: operational state of the PSE
> + *	functions. IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
> + * @c33_pw_status: power detection status of the PSE.
> + *	IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus:
>   */
>  struct pse_control_status {
>  	enum ethtool_podl_pse_admin_state podl_admin_state;
>  	enum ethtool_podl_pse_pw_d_status podl_pw_status;
> +	enum ethtool_c33_pse_admin_state c33_admin_state;
> +	enum ethtool_c33_pse_pw_d_status c33_pw_status;
>  };
>  
>  /**
> diff --git a/include/uapi/linux/ethtool.h b/include/uapi/linux/ethtool.h
> index f7fba0dc87e5..1d1631f009fa 100644
> --- a/include/uapi/linux/ethtool.h
> +++ b/include/uapi/linux/ethtool.h
> @@ -752,6 +752,49 @@ enum ethtool_module_power_mode {
>  	ETHTOOL_MODULE_POWER_MODE_HIGH,
>  };
>  
> +/**
> + * enum ethtool_c33_pse_admin_state - operational state of the PoDL PSE
> + *	functions. IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
> + * @ETHTOOL_C33_PSE_ADMIN_STATE_UNKNOWN: state of PSE functions is unknown
> + * @ETHTOOL_C33_PSE_ADMIN_STATE_DISABLED: PSE functions are disabled
> + * @ETHTOOL_C33_PSE_ADMIN_STATE_ENABLED: PSE functions are enabled
> + */
> +enum ethtool_c33_pse_admin_state {
> +	ETHTOOL_C33_PSE_ADMIN_STATE_UNKNOWN = 1,
> +	ETHTOOL_C33_PSE_ADMIN_STATE_DISABLED,
> +	ETHTOOL_C33_PSE_ADMIN_STATE_ENABLED,
> +};
> +
> +/**
> + * enum ethtool_c33_pse_pw_d_status - power detection status of the PSE.
> + *	IEEE 802.3-2022 30.9.1.1.3 aPoDLPSEPowerDetectionStatus:
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_UNKNOWN: PSE status is unknown
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_DISABLED: "The enumeration “disabled”
> + *	indicates that the PSE State diagram is in the state DISABLED."
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_SEARCHING: "The enumeration “searching”
> + *	indicates the PSE State diagram is in a state other than those
> + *	listed."
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_DELIVERING: "The enumeration
> + *	“deliveringPower” indicates that the PSE State diagram is in the
> + *	state POWER_ON."
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_TEST: "The enumeration “test” indicates that
> + *	the PSE State diagram is in the state TEST_MODE."
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_FAULT: "The enumeration “fault” indicates that
> + *	the PSE State diagram is in the state TEST_ERROR."
> + * @ETHTOOL_C33_PSE_PW_D_STATUS_OTHERFAULT: "The enumeration “otherFault”
> + *	indicates that the PSE State diagram is in the state IDLE due to
> + *	the variable error_condition = true."
> + */
> +enum ethtool_c33_pse_pw_d_status {
> +	ETHTOOL_C33_PSE_PW_D_STATUS_UNKNOWN = 1,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_DISABLED,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_SEARCHING,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_DELIVERING,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_TEST,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_FAULT,
> +	ETHTOOL_C33_PSE_PW_D_STATUS_OTHERFAULT,
> +};
> +
>  /**
>   * enum ethtool_podl_pse_admin_state - operational state of the PoDL PSE
>   *	functions. IEEE 802.3-2018 30.15.1.1.2 aPoDLPSEAdminState
> diff --git a/include/uapi/linux/ethtool_netlink.h b/include/uapi/linux/ethtool_netlink.h
> index 73e2c10dc2cc..ba805285e408 100644
> --- a/include/uapi/linux/ethtool_netlink.h
> +++ b/include/uapi/linux/ethtool_netlink.h
> @@ -895,6 +895,9 @@ enum {
>  	ETHTOOL_A_PODL_PSE_ADMIN_STATE,		/* u32 */
>  	ETHTOOL_A_PODL_PSE_ADMIN_CONTROL,	/* u32 */
>  	ETHTOOL_A_PODL_PSE_PW_D_STATUS,		/* u32 */
> +	ETHTOOL_A_C33_PSE_ADMIN_STATE,		/* u32 */
> +	ETHTOOL_A_C33_PSE_ADMIN_CONTROL,	/* u32 */
> +	ETHTOOL_A_C33_PSE_PW_D_STATUS,		/* u32 */
>  
>  	/* add new constants above here */
>  	__ETHTOOL_A_PSE_CNT,
> 
> -- 
> 2.25.1
> 
> 
>
Bagas Sanjaya Dec. 6, 2023, 2:45 a.m. UTC | #3
On Fri, Dec 01, 2023 at 06:10:24PM +0100, Kory Maincent wrote:
> In the current PSE interface for Ethernet Power Equipment, support is
> limited to PoDL. This patch extends the interface to accommodate the
> objects specified in IEEE 802.3-2022 145.2 for Power sourcing
> Equipment (PSE).
> 
> The following objects are now supported and considered mandatory:
> - IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus
> - IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
> - IEEE 802.3-2022 30.9.1.2.1 aPSEAdminControl
> 
> To avoid confusion between "PoDL PSE" and "PoE PSE", which have similar
> names but distinct values, we have followed the suggestion of Oleksij
> Rempel and Andrew Lunn to maintain separate naming schemes for each,
> using c33 (clause 33) prefix for "PoE PSE".
> You can find more details in the discussion threads here:
> https://lore.kernel.org/netdev/20230912110637.GI780075@pengutronix.de/
> https://lore.kernel.org/netdev/2539b109-72ad-470a-9dae-9f53de4f64ec@lunn.ch/
> 
> Sponsored-by: Dent Project <dentproject@linuxfoundation.org>
> Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
> ---
> 
> Changes in v2:
> - Rename all the PoE variables and enum with a c33 prefix.
> - Add documentation, thanks to Oleksij for having written one.
> ---
>  Documentation/networking/pse-pd/introduction.rst | 73 ++++++++++++++++++++++++
>  include/linux/pse-pd/pse.h                       |  9 +++
>  include/uapi/linux/ethtool.h                     | 43 ++++++++++++++
>  include/uapi/linux/ethtool_netlink.h             |  3 +
>  4 files changed, 128 insertions(+)
> 
> diff --git a/Documentation/networking/pse-pd/introduction.rst b/Documentation/networking/pse-pd/introduction.rst
> new file mode 100644
> index 000000000000..e213083b9aff
> --- /dev/null
> +++ b/Documentation/networking/pse-pd/introduction.rst
> @@ -0,0 +1,73 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Power Sourcing Equipment (PSE) in IEEE 802.3 Standard
> +=====================================================
> +
> +Overview
> +--------
> +
> +Power Sourcing Equipment (PSE) is essential in networks for delivering power
> +along with data over Ethernet cables. It usually refers to devices like
> +switches and hubs that supply power to Powered Devices (PDs) such as IP
> +cameras, VoIP phones, and wireless access points.
> +
> +PSE vs. PoDL PSE
> +----------------
> +
> +PSE in the IEEE 802.3 standard generally refers to equipment that provides
> +power alongside data over Ethernet cables, typically associated with Power over
> +Ethernet (PoE).
> +
> +PoDL PSE, or Power over Data Lines PSE, specifically denotes PSEs operating
> +with single balanced twisted-pair PHYs, as per Clause 104 of IEEE 802.3. PoDL
> +is significant in contexts like automotive and industrial controls where power
> +and data delivery over a single pair is advantageous.
> +
> +IEEE 802.3-2018 Addendums and Related Clauses
> +----------------------------------------------
> +
> +Key addenda to the IEEE 802.3-2018 standard relevant to power delivery over
> +Ethernet are as follows:
> +
> +- **802.3af (Approved in 2003-06-12)**: Known as PoE in the market, detailed in
> +  Clause 33, delivering up to 15.4W of power.
> +- **802.3at (Approved in 2009-09-11)**: Marketed as PoE+, enhancing PoE as
> +  covered in Clause 33, increasing power delivery to up to 30W.
> +- **802.3bt (Approved in 2018-09-27)**: Known as 4PPoE in the market, outlined
> +  in Clause 33. Type 3 delivers up to 60W, and Type 4 up to 100W.
> +- **802.3bu (Approved in 2016-12-07)**: Formerly referred to as PoDL, detailed
> +  in Clause 104. Introduces Classes 0 - 9. Class 9 PoDL PSE delivers up to ~65W
> +
> +Kernel Naming Convention Recommendations
> +----------------------------------------
> +
> +For clarity and consistency within the Linux kernel's networking subsystem, the
> +following naming conventions are recommended:
> +
> +- For general PSE (PoE) code, use "c33_pse" key words. For example:
> +  ``enum ethtool_c33_pse_admin_state c33_admin_control;``.
> +  This aligns with Clause 33, encompassing various PoE forms.
> +
> +- For PoDL PSE - specific code, use "podl_pse". For example:
> +  ``enum ethtool_podl_pse_admin_state podl_admin_control;`` to differentiate
> +  PoDL PSE settings according to Clause 104.
> +
> +Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
> +-------------------------------------------------------------------------------------------
> +
> +Clause 33 of the IEEE 802.3 standard defines the functional and electrical
> +characteristics of Powered Device (PD) and Power Sourcing Equipment (PSE).
> +These entities enable power delivery using the same generic cabling as for data
> +transmission, integrating power with data communication for devices such as
> +10BASE-T, 100BASE-TX, or 1000BASE-T.
> +
> +Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
> +-------------------------------------------------------------------------------------------
> +
> +Clause 104 of the IEEE 802.3 standard delineates the functional and electrical
> +characteristics of PoDL Powered Devices (PDs) and PoDL Power Sourcing Equipment
> +(PSEs). These are designed for use with single balanced twisted-pair Ethernet
> +Physical Layers. In this clause, 'PSE' refers specifically to PoDL PSE, and
> +'PD' to PoDL PD. The key intent is to provide devices with a unified interface
> +for both data and the power required to process this data over a single
> +balanced twisted-pair Ethernet connection.

I get many htmldocs warnings:

```
Documentation/networking/pse-pd/introduction.rst:56: WARNING: Title underline too short.

Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
-------------------------------------------------------------------------------------------
Documentation/networking/pse-pd/introduction.rst:56: WARNING: Title underline too short.

Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
-------------------------------------------------------------------------------------------
Documentation/networking/pse-pd/introduction.rst:65: WARNING: Title underline too short.

Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
-------------------------------------------------------------------------------------------
Documentation/networking/pse-pd/introduction.rst:65: WARNING: Title underline too short.

Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
-------------------------------------------------------------------------------------------
looking for now-outdated files... none found
pickling environment... done
checking consistency... Documentation/networking/pse-pd/introduction.rst: WARNING: document isn't included in any toctree
```

I have to fix them up:

---- >8 ----
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 683eb42309cc5b..3900c6885cfc7d 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -88,6 +88,7 @@ Contents:
    phonet
    pktgen
    plip
+   pse-pd/index
    ppp_generic
    proc_net_tcp
    radiotap-headers
diff --git a/Documentation/networking/pse-pd/index.rst b/Documentation/networking/pse-pd/index.rst
new file mode 100644
index 00000000000000..18197bc7303dc9
--- /dev/null
+++ b/Documentation/networking/pse-pd/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Power Sourcing Equipment (PSE) Documentation
+============================================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
diff --git a/Documentation/networking/pse-pd/introduction.rst b/Documentation/networking/pse-pd/introduction.rst
index e213083b9aff2d..e3d3faaef717f2 100644
--- a/Documentation/networking/pse-pd/introduction.rst
+++ b/Documentation/networking/pse-pd/introduction.rst
@@ -24,7 +24,7 @@ is significant in contexts like automotive and industrial controls where power
 and data delivery over a single pair is advantageous.
 
 IEEE 802.3-2018 Addendums and Related Clauses
-----------------------------------------------
+---------------------------------------------
 
 Key addenda to the IEEE 802.3-2018 standard relevant to power delivery over
 Ethernet are as follows:
@@ -53,7 +53,7 @@ following naming conventions are recommended:
   PoDL PSE settings according to Clause 104.
 
 Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
--------------------------------------------------------------------------------------------
+---------------------------------------------------------------------------------------------
 
 Clause 33 of the IEEE 802.3 standard defines the functional and electrical
 characteristics of Powered Device (PD) and Power Sourcing Equipment (PSE).
@@ -62,7 +62,7 @@ transmission, integrating power with data communication for devices such as
 10BASE-T, 100BASE-TX, or 1000BASE-T.
 
 Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
--------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------
 
 Clause 104 of the IEEE 802.3 standard delineates the functional and electrical
 characteristics of PoDL Powered Devices (PDs) and PoDL Power Sourcing Equipment

Thanks.
kernel test robot Dec. 6, 2023, 4:23 a.m. UTC | #4
Hi Kory,

kernel test robot noticed the following build warnings:

[auto build test WARNING on net-next/main]

url:    https://github.com/intel-lab-lkp/linux/commits/Kory-Maincent/ethtool-Expand-Ethernet-Power-Equipment-with-c33-PoE-alongside-PoDL/20231202-021033
base:   net-next/main
patch link:    https://lore.kernel.org/r/20231201-feature_poe-v2-2-56d8cac607fa%40bootlin.com
patch subject: [PATCH net-next v2 2/8] ethtool: Expand Ethernet Power Equipment with c33 (PoE) alongside PoDL
reproduce: (https://download.01.org/0day-ci/archive/20231206/202312061223.iHikO4O3-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202312061223.iHikO4O3-lkp@intel.com/

All warnings (new ones prefixed by >>):

>> Documentation/networking/pse-pd/introduction.rst:56: WARNING: Title underline too short.

vim +56 Documentation/networking/pse-pd/introduction.rst

    46	
    47	- For general PSE (PoE) code, use "c33_pse" key words. For example:
    48	  ``enum ethtool_c33_pse_admin_state c33_admin_control;``.
    49	  This aligns with Clause 33, encompassing various PoE forms.
    50	
    51	- For PoDL PSE - specific code, use "podl_pse". For example:
    52	  ``enum ethtool_podl_pse_admin_state podl_admin_control;`` to differentiate
    53	  PoDL PSE settings according to Clause 104.
    54	
    55	Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
  > 56	-------------------------------------------------------------------------------------------
    57
Kory Maincent Dec. 6, 2023, 8:35 a.m. UTC | #5
On Wed, 6 Dec 2023 09:45:44 +0700
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> On Fri, Dec 01, 2023 at 06:10:24PM +0100, Kory Maincent wrote:
> > In the current PSE interface for Ethernet Power Equipment, support is
> > limited to PoDL. This patch extends the interface to accommodate the
> > objects specified in IEEE 802.3-2022 145.2 for Power sourcing
> > Equipment (PSE).
> > 
> > The following objects are now supported and considered mandatory:
> > - IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus
> > - IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
> > - IEEE 802.3-2022 30.9.1.2.1 aPSEAdminControl
> > 
> > To avoid confusion between "PoDL PSE" and "PoE PSE", which have similar
> > names but distinct values, we have followed the suggestion of Oleksij
> > Rempel and Andrew Lunn to maintain separate naming schemes for each,
> > using c33 (clause 33) prefix for "PoE PSE".
> > You can find more details in the discussion threads here:
> > https://lore.kernel.org/netdev/20230912110637.GI780075@pengutronix.de/
> > https://lore.kernel.org/netdev/2539b109-72ad-470a-9dae-9f53de4f64ec@lunn.ch/
> > 
> > Sponsored-by: Dent Project <dentproject@linuxfoundation.org>
> > Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
> > ---
> > 
> > Changes in v2:
> > - Rename all the PoE variables and enum with a c33 prefix.
> > - Add documentation, thanks to Oleksij for having written one.
> > ---

> 
> I get many htmldocs warnings:

Oops sorry, I forgot to run the documentation build.
Thanks for your reviews!

Regards,
diff mbox series

Patch

diff --git a/Documentation/networking/pse-pd/introduction.rst b/Documentation/networking/pse-pd/introduction.rst
new file mode 100644
index 000000000000..e213083b9aff
--- /dev/null
+++ b/Documentation/networking/pse-pd/introduction.rst
@@ -0,0 +1,73 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+
+Power Sourcing Equipment (PSE) in IEEE 802.3 Standard
+=====================================================
+
+Overview
+--------
+
+Power Sourcing Equipment (PSE) is essential in networks for delivering power
+along with data over Ethernet cables. It usually refers to devices like
+switches and hubs that supply power to Powered Devices (PDs) such as IP
+cameras, VoIP phones, and wireless access points.
+
+PSE vs. PoDL PSE
+----------------
+
+PSE in the IEEE 802.3 standard generally refers to equipment that provides
+power alongside data over Ethernet cables, typically associated with Power over
+Ethernet (PoE).
+
+PoDL PSE, or Power over Data Lines PSE, specifically denotes PSEs operating
+with single balanced twisted-pair PHYs, as per Clause 104 of IEEE 802.3. PoDL
+is significant in contexts like automotive and industrial controls where power
+and data delivery over a single pair is advantageous.
+
+IEEE 802.3-2018 Addendums and Related Clauses
+----------------------------------------------
+
+Key addenda to the IEEE 802.3-2018 standard relevant to power delivery over
+Ethernet are as follows:
+
+- **802.3af (Approved in 2003-06-12)**: Known as PoE in the market, detailed in
+  Clause 33, delivering up to 15.4W of power.
+- **802.3at (Approved in 2009-09-11)**: Marketed as PoE+, enhancing PoE as
+  covered in Clause 33, increasing power delivery to up to 30W.
+- **802.3bt (Approved in 2018-09-27)**: Known as 4PPoE in the market, outlined
+  in Clause 33. Type 3 delivers up to 60W, and Type 4 up to 100W.
+- **802.3bu (Approved in 2016-12-07)**: Formerly referred to as PoDL, detailed
+  in Clause 104. Introduces Classes 0 - 9. Class 9 PoDL PSE delivers up to ~65W
+
+Kernel Naming Convention Recommendations
+----------------------------------------
+
+For clarity and consistency within the Linux kernel's networking subsystem, the
+following naming conventions are recommended:
+
+- For general PSE (PoE) code, use "c33_pse" key words. For example:
+  ``enum ethtool_c33_pse_admin_state c33_admin_control;``.
+  This aligns with Clause 33, encompassing various PoE forms.
+
+- For PoDL PSE - specific code, use "podl_pse". For example:
+  ``enum ethtool_podl_pse_admin_state podl_admin_control;`` to differentiate
+  PoDL PSE settings according to Clause 104.
+
+Summary of Clause 33: Data Terminal Equipment (DTE) Power via Media Dependent Interface (MDI)
+-------------------------------------------------------------------------------------------
+
+Clause 33 of the IEEE 802.3 standard defines the functional and electrical
+characteristics of Powered Device (PD) and Power Sourcing Equipment (PSE).
+These entities enable power delivery using the same generic cabling as for data
+transmission, integrating power with data communication for devices such as
+10BASE-T, 100BASE-TX, or 1000BASE-T.
+
+Summary of Clause 104: Power over Data Lines (PoDL) of Single Balanced Twisted-Pair Ethernet
+-------------------------------------------------------------------------------------------
+
+Clause 104 of the IEEE 802.3 standard delineates the functional and electrical
+characteristics of PoDL Powered Devices (PDs) and PoDL Power Sourcing Equipment
+(PSEs). These are designed for use with single balanced twisted-pair Ethernet
+Physical Layers. In this clause, 'PSE' refers specifically to PoDL PSE, and
+'PD' to PoDL PD. The key intent is to provide devices with a unified interface
+for both data and the power required to process this data over a single
+balanced twisted-pair Ethernet connection.
diff --git a/include/linux/pse-pd/pse.h b/include/linux/pse-pd/pse.h
index 199cf4ae3cf2..be4e5754eb24 100644
--- a/include/linux/pse-pd/pse.h
+++ b/include/linux/pse-pd/pse.h
@@ -17,9 +17,12 @@  struct pse_controller_dev;
  *
  * @podl_admin_control: set PoDL PSE admin control as described in
  *	IEEE 802.3-2018 30.15.1.2.1 acPoDLPSEAdminControl
+ * @c33_admin_control: set PSE admin control as described in
+ *	IEEE 802.3-2022 30.9.1.2.1 acPSEAdminControl
  */
 struct pse_control_config {
 	enum ethtool_podl_pse_admin_state podl_admin_control;
+	enum ethtool_c33_pse_admin_state c33_admin_control;
 };
 
 /**
@@ -29,10 +32,16 @@  struct pse_control_config {
  *	functions. IEEE 802.3-2018 30.15.1.1.2 aPoDLPSEAdminState
  * @podl_pw_status: power detection status of the PoDL PSE.
  *	IEEE 802.3-2018 30.15.1.1.3 aPoDLPSEPowerDetectionStatus:
+ * @c33_admin_state: operational state of the PSE
+ *	functions. IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
+ * @c33_pw_status: power detection status of the PSE.
+ *	IEEE 802.3-2022 30.9.1.1.5 aPSEPowerDetectionStatus:
  */
 struct pse_control_status {
 	enum ethtool_podl_pse_admin_state podl_admin_state;
 	enum ethtool_podl_pse_pw_d_status podl_pw_status;
+	enum ethtool_c33_pse_admin_state c33_admin_state;
+	enum ethtool_c33_pse_pw_d_status c33_pw_status;
 };
 
 /**
diff --git a/include/uapi/linux/ethtool.h b/include/uapi/linux/ethtool.h
index f7fba0dc87e5..1d1631f009fa 100644
--- a/include/uapi/linux/ethtool.h
+++ b/include/uapi/linux/ethtool.h
@@ -752,6 +752,49 @@  enum ethtool_module_power_mode {
 	ETHTOOL_MODULE_POWER_MODE_HIGH,
 };
 
+/**
+ * enum ethtool_c33_pse_admin_state - operational state of the PoDL PSE
+ *	functions. IEEE 802.3-2022 30.9.1.1.2 aPSEAdminState
+ * @ETHTOOL_C33_PSE_ADMIN_STATE_UNKNOWN: state of PSE functions is unknown
+ * @ETHTOOL_C33_PSE_ADMIN_STATE_DISABLED: PSE functions are disabled
+ * @ETHTOOL_C33_PSE_ADMIN_STATE_ENABLED: PSE functions are enabled
+ */
+enum ethtool_c33_pse_admin_state {
+	ETHTOOL_C33_PSE_ADMIN_STATE_UNKNOWN = 1,
+	ETHTOOL_C33_PSE_ADMIN_STATE_DISABLED,
+	ETHTOOL_C33_PSE_ADMIN_STATE_ENABLED,
+};
+
+/**
+ * enum ethtool_c33_pse_pw_d_status - power detection status of the PSE.
+ *	IEEE 802.3-2022 30.9.1.1.3 aPoDLPSEPowerDetectionStatus:
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_UNKNOWN: PSE status is unknown
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_DISABLED: "The enumeration “disabled”
+ *	indicates that the PSE State diagram is in the state DISABLED."
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_SEARCHING: "The enumeration “searching”
+ *	indicates the PSE State diagram is in a state other than those
+ *	listed."
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_DELIVERING: "The enumeration
+ *	“deliveringPower” indicates that the PSE State diagram is in the
+ *	state POWER_ON."
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_TEST: "The enumeration “test” indicates that
+ *	the PSE State diagram is in the state TEST_MODE."
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_FAULT: "The enumeration “fault” indicates that
+ *	the PSE State diagram is in the state TEST_ERROR."
+ * @ETHTOOL_C33_PSE_PW_D_STATUS_OTHERFAULT: "The enumeration “otherFault”
+ *	indicates that the PSE State diagram is in the state IDLE due to
+ *	the variable error_condition = true."
+ */
+enum ethtool_c33_pse_pw_d_status {
+	ETHTOOL_C33_PSE_PW_D_STATUS_UNKNOWN = 1,
+	ETHTOOL_C33_PSE_PW_D_STATUS_DISABLED,
+	ETHTOOL_C33_PSE_PW_D_STATUS_SEARCHING,
+	ETHTOOL_C33_PSE_PW_D_STATUS_DELIVERING,
+	ETHTOOL_C33_PSE_PW_D_STATUS_TEST,
+	ETHTOOL_C33_PSE_PW_D_STATUS_FAULT,
+	ETHTOOL_C33_PSE_PW_D_STATUS_OTHERFAULT,
+};
+
 /**
  * enum ethtool_podl_pse_admin_state - operational state of the PoDL PSE
  *	functions. IEEE 802.3-2018 30.15.1.1.2 aPoDLPSEAdminState
diff --git a/include/uapi/linux/ethtool_netlink.h b/include/uapi/linux/ethtool_netlink.h
index 73e2c10dc2cc..ba805285e408 100644
--- a/include/uapi/linux/ethtool_netlink.h
+++ b/include/uapi/linux/ethtool_netlink.h
@@ -895,6 +895,9 @@  enum {
 	ETHTOOL_A_PODL_PSE_ADMIN_STATE,		/* u32 */
 	ETHTOOL_A_PODL_PSE_ADMIN_CONTROL,	/* u32 */
 	ETHTOOL_A_PODL_PSE_PW_D_STATUS,		/* u32 */
+	ETHTOOL_A_C33_PSE_ADMIN_STATE,		/* u32 */
+	ETHTOOL_A_C33_PSE_ADMIN_CONTROL,	/* u32 */
+	ETHTOOL_A_C33_PSE_PW_D_STATUS,		/* u32 */
 
 	/* add new constants above here */
 	__ETHTOOL_A_PSE_CNT,