| 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 |
> +++ 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
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 > > >
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.
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
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 --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,
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(+)