Add documentation for the device_pm_callback_{start, end} events
under the "Subsystem Trace Points: power" section.

Signed-off-by: Yo-Jung (Leo) Lin <0xff07@gmail.com>
---
 Documentation/trace/events-power.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/trace/events-power.rst b/Documentation/trace/events-power.rst
index f45bf11fa88d..7031954f7ed3 100644
--- a/Documentation/trace/events-power.rst
+++ b/Documentation/trace/events-power.rst
@@ -102,3 +102,30 @@ And, there are events used for CPU latency QoS add/update/remove request.
   pm_qos_remove_request     "value=%d"
 
 The parameter is the value to be added/updated/removed.
+
+5. Device PM callback events
+============================
+The device PM callback events are placed right before and after an invocation of
+a device PM callback during a system-wide suspend/resume attempt.
+::
+
+  device_pm_callback_start     "%s %s, parent: %s, %s[%s]"
+  device_pm_callback_end       "%s %s, err=%d"
+
+The first two parameters in both events are the same. They are:
+
+  - The name of the driver.
+  - The device whose PM callbacks get called.
+
+For device_pm_callback_start, the rest of the parameters are:
+
+  - The parent device of the device (if any).
+  - Level in the power management hierarchy the callback belongs to (e.g. power
+    domain, type, class, bus, driver). Some stages (e.g. early, late, noirq)
+    will also be explicitly mentioned in this string.
+  - The ongoing PM event. You may find definitions of those events in the
+    PM_EVENT_* macros in include/linux/pm.h
+
+For device_pm_callback_end, the only remaining parameter is:
+
+  - The return value of the PM callback.
-- 
2.43.0

This needs an ack from one of the power management maintainers.

-- Steve


On Sun, 22 Sep 2024 21:26:28 +0800
"Yo-Jung (Leo) Lin" <0xff07@gmail.com> wrote:

> Add documentation for the device_pm_callback_{start, end} events
> under the "Subsystem Trace Points: power" section.
> 
> Signed-off-by: Yo-Jung (Leo) Lin <0xff07@gmail.com>
> ---
>  Documentation/trace/events-power.rst | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
> 
> diff --git a/Documentation/trace/events-power.rst b/Documentation/trace/events-power.rst
> index f45bf11fa88d..7031954f7ed3 100644
> --- a/Documentation/trace/events-power.rst
> +++ b/Documentation/trace/events-power.rst
> @@ -102,3 +102,30 @@ And, there are events used for CPU latency QoS add/update/remove request.
>    pm_qos_remove_request     "value=%d"
>  
>  The parameter is the value to be added/updated/removed.
> +
> +5. Device PM callback events
> +============================
> +The device PM callback events are placed right before and after an invocation of
> +a device PM callback during a system-wide suspend/resume attempt.
> +::
> +
> +  device_pm_callback_start     "%s %s, parent: %s, %s[%s]"
> +  device_pm_callback_end       "%s %s, err=%d"
> +
> +The first two parameters in both events are the same. They are:
> +
> +  - The name of the driver.
> +  - The device whose PM callbacks get called.
> +
> +For device_pm_callback_start, the rest of the parameters are:
> +
> +  - The parent device of the device (if any).
> +  - Level in the power management hierarchy the callback belongs to (e.g. power
> +    domain, type, class, bus, driver). Some stages (e.g. early, late, noirq)
> +    will also be explicitly mentioned in this string.
> +  - The ongoing PM event. You may find definitions of those events in the
> +    PM_EVENT_* macros in include/linux/pm.h
> +
> +For device_pm_callback_end, the only remaining parameter is:
> +
> +  - The return value of the PM callback.

Hi Rafael and the PM maintainers,

On Thu, Sep 26, 2024 at 12:59 PM Steven Rostedt <rostedt@goodmis.org> wrote:
>
>
> This needs an ack from one of the power management maintainers.
>
> -- Steve
>
>
> On Sun, 22 Sep 2024 21:26:28 +0800
> "Yo-Jung (Leo) Lin" <0xff07@gmail.com> wrote:
>
> > Add documentation for the device_pm_callback_{start, end} events
> > under the "Subsystem Trace Points: power" section.
> >
> > Signed-off-by: Yo-Jung (Leo) Lin <0xff07@gmail.com>
> > ---
> >  Documentation/trace/events-power.rst | 27 +++++++++++++++++++++++++++
> >  1 file changed, 27 insertions(+)
> >
> > diff --git a/Documentation/trace/events-power.rst b/Documentation/trace/events-power.rst
> > index f45bf11fa88d..7031954f7ed3 100644
> > --- a/Documentation/trace/events-power.rst
> > +++ b/Documentation/trace/events-power.rst
> > @@ -102,3 +102,30 @@ And, there are events used for CPU latency QoS add/update/remove request.
> >    pm_qos_remove_request     "value=%d"
> >
> >  The parameter is the value to be added/updated/removed.
> > +
> > +5. Device PM callback events
> > +============================
> > +The device PM callback events are placed right before and after an invocation of
> > +a device PM callback during a system-wide suspend/resume attempt.
> > +::
> > +
> > +  device_pm_callback_start     "%s %s, parent: %s, %s[%s]"
> > +  device_pm_callback_end       "%s %s, err=%d"
> > +
> > +The first two parameters in both events are the same. They are:
> > +
> > +  - The name of the driver.
> > +  - The device whose PM callbacks get called.
> > +
> > +For device_pm_callback_start, the rest of the parameters are:
> > +
> > +  - The parent device of the device (if any).
> > +  - Level in the power management hierarchy the callback belongs to (e.g. power
> > +    domain, type, class, bus, driver). Some stages (e.g. early, late, noirq)
> > +    will also be explicitly mentioned in this string.
> > +  - The ongoing PM event. You may find definitions of those events in the
> > +    PM_EVENT_* macros in include/linux/pm.h
> > +
> > +For device_pm_callback_end, the only remaining parameter is:
> > +
> > +  - The return value of the PM callback.
>

I think it'll be helpful to have your feedback on this documentation
proposal. Would you kindly help take a look? I believe that any
feedback would be really helpful. Thank you!

Best,
Leo