include: drivers: ptp_clock: clarify ptp_clock_rate_adjust function

It's not very clear about the function of ptp_clock_rate_adjust in doc.
Previously, all device drivers used it to adjust rate ratio relatively
based on current frequency.

When PI servo was introduced in PTP and gPTP stacks, NXP ENET PTP driver
started to use it to adjust rate ratio based on its nominal frequency.

Rate ratio adjustment based on nominal frequency with PI servo could
get stable frequency control. So, let's clarify ptp_clock_rate_adjust
adjusting rate ratio based on nominal frequency, and convert other
device drivers.

Signed-off-by: Yangbo Lu <[email protected]>

Author: yangbolu1991

doc/releases/migration-guide-4.3.rst

@@ -82,6 +82,15 @@ Display
   This has now been fixed. Boards and applications that were tested or developed based on the
   previous sample may be affected by this change (see :github:`79996` for more information).
 
+PTP Clock
+*********
+
+* The doc of :c:func:`ptp_clock_rate_adjust` API didn't provide proper and clear function description.
+  Drivers implemented it to adjust rate ratio relatively based on current frequency.
+  Now PI servo is introduced in both PTP and gPTP, and this API function is changed to use for rate
+  ratio adjusting based on nominal frequency. Drivers implementing :c:func:`ptp_clock_rate_adjust`
+  should be adjusted to account for the new behavior.
+
 Other subsystems
 ****************
 

include/zephyr/drivers/ptp_clock.h

@@ -82,10 +82,10 @@ static inline int ptp_clock_adjust(const struct device *dev, int increment)
 }
 
 /**
- * @brief Adjust the PTP clock time change rate when compared to its neighbor.
+ * @brief Adjust the PTP clock rate ratio based on its nominal frequency
  *
  * @param dev PTP clock device
- * @param rate Rate of the clock time change
+ * @param rate Rate ratio based on its nominal frequency
  *
  * @return 0 if ok, <0 if error
  */