net: pse-pd: tps23881: Clarify setup_pi_matrix callback documentation

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>
Link: https://patch.msgid.link/20250620-poe_doc_improve-v1-2-96357bb95d52@bootlin.com
Signed-off-by: Paolo Abeni <pabeni@redhat.com>

diff --git a/include/linux/pse-pd/pse.h b/include/linux/pse-pd/pse.h
index e5f305cef82e7a2c2cae7d82aa954daed7a76bce..4e5696cfade7cc5f6e6c0e8edbaae26cddbe9d03 100644 (file)
--- 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