[PATCH net-next 0/2] PSE: Improve documentation clarity

[PATCH net-next 0/2] PSE: Improve documentation clarity

[Kory Maincent]

Thanks to new PSE driver being proposed on the mailinglist figured out
there was some unclear documentation, which lead the developer on the
wrong path. Clarify these documentation.

The changes focus on clarifying the setup_pi_matrix callback behavior
and improving device tree binding descriptions, particularly around
channel-to-PI mapping relationships that are critical for proper PSE
controller integration.

Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
---
Kory Maincent (2):
      dt-bindings: pse: tps23881: Clarify channels property description
      net: pse-pd: tps23881: Clarify setup_pi_matrix callback documentation

 Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml | 10 ++++++----
 include/linux/pse-pd/pse.h                                    |  8 +++++++-
 2 files changed, 13 insertions(+), 5 deletions(-)
---
base-commit: 0341e1290e40a14ba8c955b9681c739dc2f14e99
change-id: 20250619-poe_doc_improve-d28921dc200e

Best regards,
--  
Köry Maincent, Bootlin
Embedded Linux and kernel engineering
https://bootlin.com

[PATCH net-next 1/2] dt-bindings: pse: tps23881: Clarify channels property description

[Kory Maincent]

Improve the channels property description to better explain the
relationship between physical delivery channels and PSE PI pairsets.
The previous description was unclear about how channels are referenced
and used in the port matrix mapping.

Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
---
 Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml b/Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml
index 3a5f960d8489..bb1ee3398655 100644
--- a/Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml
+++ b/Documentation/devicetree/bindings/net/pse-pd/ti,tps23881.yaml
@@ -30,10 +30,12 @@ properties:
     maxItems: 1
 
   channels:
-    description: each set of 8 ports can be assigned to one physical
-      channels or two for PoE4. This parameter describes the configuration
-      of the ports conversion matrix that establishes relationship between
-      the logical ports and the physical channels.
+    description: |
+      Defines the 8 physical delivery channels on the controller that can
+      be referenced by PSE PIs through their "pairsets" property. The actual
+      port matrix mapping is created when PSE PIs reference these channels in
+      their pairsets. For 4-pair operation, two channels from the same group
+      (0-3 or 4-7) must be referenced by a single PSE PI.
     type: object
     additionalProperties: false
 

-- 
2.43.0

[PATCH net-next 2/2] net: pse-pd: tps23881: Clarify setup_pi_matrix callback documentation

[Kory Maincent]

Improve the setup_pi_matrix callback documentation to clarify its purpose
and usage. The enhanced description explains that PSE PI devicetree nodes
are pre-parsed before this callback is invoked, and drivers should utilize
pcdev->pi[x]->pairset[y].np to map PSE controller hardware ports to their
corresponding Power Interfaces.

This clarification helps driver implementers understand the callback's
role in establishing the hardware-to-PI relationship mapping.

Signed-off-by: Kory Maincent <kory.maincent@bootlin.com>
---
 include/linux/pse-pd/pse.h | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/include/linux/pse-pd/pse.h b/include/linux/pse-pd/pse.h
index e5f305cef82e..4e5696cfade7 100644
--- a/include/linux/pse-pd/pse.h
+++ b/include/linux/pse-pd/pse.h
@@ -159,7 +159,13 @@ struct ethtool_pse_control_status {
 /**
  * struct pse_controller_ops - PSE controller driver callbacks
  *
- * @setup_pi_matrix: setup PI matrix of the PSE controller
+ * @setup_pi_matrix: Setup PI matrix of the PSE controller.
+ *		     The PSE PIs devicetree nodes have already been parsed by
+ *		     of_load_pse_pis() and the pcdev->pi[x]->pairset[y].np
+ *		     populated. This callback should establish the
+ *		     relationship between the PSE controller hardware ports
+ *		     and the PSE Power Interfaces, either through software
+ *		     mapping or hardware configuration.
  * @pi_get_admin_state: Get the operational state of the PSE PI. This ops
  *			is mandatory.
  * @pi_get_pw_status: Get the power detection status of the PSE PI. This

-- 
2.43.0

Re: [PATCH net-next 0/2] PSE: Improve documentation clarity

[patchwork-bot+netdevbpf]

Hello:

This series was applied to netdev/net-next.git (main)
by Paolo Abeni <pabeni@redhat.com>:

On Fri, 20 Jun 2025 12:02:38 +0200 you wrote:
> Thanks to new PSE driver being proposed on the mailinglist figured out
> there was some unclear documentation, which lead the developer on the
> wrong path. Clarify these documentation.
> 
> The changes focus on clarifying the setup_pi_matrix callback behavior
> and improving device tree binding descriptions, particularly around
> channel-to-PI mapping relationships that are critical for proper PSE
> controller integration.
> 
> [...]

Here is the summary with links:
  - [net-next,1/2] dt-bindings: pse: tps23881: Clarify channels property description
    https://git.kernel.org/netdev/net-next/c/42fa8f17e453
  - [net-next,2/2] net: pse-pd: tps23881: Clarify setup_pi_matrix callback documentation
    https://git.kernel.org/netdev/net-next/c/dad51ea09040

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html