[v3,8/8] PM / doc: Update device documentation for devices in IRQ safe PM domains

Message ID 1476467276-75094-9-git-send-email-lina.iyer@linaro.org
State New
Headers show

Commit Message

Lina Iyer Oct. 14, 2016, 5:47 p.m.
Update documentation to reflect the changes made to support IRQ safe PM
domains.

Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

---
 Documentation/power/devices.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Comments

Rafael J. Wysocki Oct. 21, 2016, 1:07 p.m. | #1
On Fri, Oct 14, 2016 at 7:47 PM, Lina Iyer <lina.iyer@linaro.org> wrote:
> Update documentation to reflect the changes made to support IRQ safe PM

> domains.

>

> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

> ---

>  Documentation/power/devices.txt | 9 ++++++++-

>  1 file changed, 8 insertions(+), 1 deletion(-)

>

> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

> index 8ba6625..0401b53 100644

> --- a/Documentation/power/devices.txt

> +++ b/Documentation/power/devices.txt

> @@ -607,7 +607,14 @@ individually.  Instead, a set of devices sharing a power resource can be put

>  into a low-power state together at the same time by turning off the shared

>  power resource.  Of course, they also need to be put into the full-power state

>  together, by turning the shared power resource on.  A set of devices with this

> -property is often referred to as a power domain.

> +property is often referred to as a power domain. A power domain may also be

> +nested inside another power domain.

> +

> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

> +on/off even when the IRQs are disabled. An IRQ-safe device in a domain will

> +disallow power management on the domain, unless the domain is also defined as

> +IRQ-safe. The restriction this framework imposes on the parent domain of an

> +IRQ-safe domain is that it must also be defined as IRQ-safe.


I would put this paragraph below, before the last paragraph in the section.

Also I suppose that a domain should only be defined as "IRQ-safe" if
all of the devices in it are "IRQ-safe" (or there will be problems at
least in principle).  If that is the case, it should be stated clearly
in the paragraph you are adding as well.

Thanks,
Rafael
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lina Iyer Oct. 21, 2016, 3:23 p.m. | #2
On Fri, Oct 21 2016 at 07:07 -0600, Rafael J. Wysocki wrote:
>On Fri, Oct 14, 2016 at 7:47 PM, Lina Iyer <lina.iyer@linaro.org> wrote:

>> Update documentation to reflect the changes made to support IRQ safe PM

>> domains.

>>

>> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

>> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

>> ---

>>  Documentation/power/devices.txt | 9 ++++++++-

>>  1 file changed, 8 insertions(+), 1 deletion(-)

>>

>> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

>> index 8ba6625..0401b53 100644

>> --- a/Documentation/power/devices.txt

>> +++ b/Documentation/power/devices.txt

>> @@ -607,7 +607,14 @@ individually.  Instead, a set of devices sharing a power resource can be put

>>  into a low-power state together at the same time by turning off the shared

>>  power resource.  Of course, they also need to be put into the full-power state

>>  together, by turning the shared power resource on.  A set of devices with this

>> -property is often referred to as a power domain.

>> +property is often referred to as a power domain. A power domain may also be

>> +nested inside another power domain.

>> +

>> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

>> +on/off even when the IRQs are disabled. An IRQ-safe device in a domain will

>> +disallow power management on the domain, unless the domain is also defined as

>> +IRQ-safe. The restriction this framework imposes on the parent domain of an

>> +IRQ-safe domain is that it must also be defined as IRQ-safe.

>

>I would put this paragraph below, before the last paragraph in the section.

>

OK.

>Also I suppose that a domain should only be defined as "IRQ-safe" if

>all of the devices in it are "IRQ-safe" (or there will be problems at

>least in principle).  If that is the case, it should be stated clearly

>in the paragraph you are adding as well.

>

Will add.

Thanks,
Lina
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Rafael J. Wysocki Oct. 22, 2016, 12:26 a.m. | #3
On Friday, October 21, 2016 03:52:55 PM Lina Iyer wrote:
> Update documentation to reflect the changes made to support IRQ safe PM

> domains.

> 

> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

> ---

> Changes since v3:

> - Moved para to the end of the section

> - Added clause for all IRQ safe devices in a domain

> - Cleanup explanation of nested domains

> ---

>  Documentation/power/devices.txt | 11 ++++++++++-

>  1 file changed, 10 insertions(+), 1 deletion(-)

> 

> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

> index 8ba6625..9218ce6 100644

> --- a/Documentation/power/devices.txt

> +++ b/Documentation/power/devices.txt

> @@ -607,7 +607,9 @@ individually.  Instead, a set of devices sharing a power resource can be put

>  into a low-power state together at the same time by turning off the shared

>  power resource.  Of course, they also need to be put into the full-power state

>  together, by turning the shared power resource on.  A set of devices with this

> -property is often referred to as a power domain.

> +property is often referred to as a power domain. A power domain may also be

> +nested inside another power domain. The nested domain is referred to as the

> +sub-domain of the parent domain.

>  

>  Support for power domains is provided through the pm_domain field of struct

>  device.  This field is a pointer to an object of type struct dev_pm_domain,

> @@ -629,6 +631,13 @@ support for power domains into subsystem-level callbacks, for example by

>  modifying the platform bus type.  Other platforms need not implement it or take

>  it into account in any way.

>  

> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

> +on/off even when the IRQs are disabled.


What IRQ-safe means for devices is that their runtime PM callbacks may be
invoked with interrupts disabled on the local CPU.  I guess the meaning of
IRQ-safe for PM domains is analogous, but the above isn't precise enough to me.

> An IRQ-safe device in a domain will

> +disallow power management on the domain, unless the domain is also defined as

> +IRQ-safe. In other words, a domain containing all IRQ-safe devices must also

> +be defined as IRQ-safe. Another restriction this framework imposes on the

> +parent domain of an IRQ-safe domain is that the parent domain must also be

> +defined as IRQ-safe.


What about this:

"Devices may be defined as IRQ-safe which indicates to the PM core that their
runtime PM callbacks may be invoked with disabled interrupts (see
Documentation/power/runtime_pm.txt for more information).  If an IRQ-safe
device belongs to a PM domain, the runtime PM of the domain will be disallowed,
unless the domain itself is defined as IRQ-safe.  However, a PM domain can only
be defined as IRQ-safe if all of the devices in it are IRQ-safe.  Moreover, if
an IRQ-safe domain has a parent domain, the runtime PM of the parent is only
allowed if the parent itself is IRQ-safe too with the additional restriction
that all child domains of an IRQ-safe parent must also be IRQ-safe."

Does it actually reflect what the code does?

Thanks,
Rafael

--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lina Iyer Oct. 24, 2016, 4:16 p.m. | #4
On Sat, Oct 22 2016 at 18:19 -0600, Rafael J. Wysocki wrote:
>On Friday, October 21, 2016 03:52:55 PM Lina Iyer wrote:

>> Update documentation to reflect the changes made to support IRQ safe PM

>> domains.

>>

>> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

>> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

>> ---

>> Changes since v3:

>> - Moved para to the end of the section

>> - Added clause for all IRQ safe devices in a domain

>> - Cleanup explanation of nested domains

>> ---

>>  Documentation/power/devices.txt | 11 ++++++++++-

>>  1 file changed, 10 insertions(+), 1 deletion(-)

>>

>> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

>> index 8ba6625..9218ce6 100644

>> --- a/Documentation/power/devices.txt

>> +++ b/Documentation/power/devices.txt

>> @@ -607,7 +607,9 @@ individually.  Instead, a set of devices sharing a power resource can be put

>>  into a low-power state together at the same time by turning off the shared

>>  power resource.  Of course, they also need to be put into the full-power state

>>  together, by turning the shared power resource on.  A set of devices with this

>> -property is often referred to as a power domain.

>> +property is often referred to as a power domain. A power domain may also be

>> +nested inside another power domain. The nested domain is referred to as the

>> +sub-domain of the parent domain.

>>

>>  Support for power domains is provided through the pm_domain field of struct

>>  device.  This field is a pointer to an object of type struct dev_pm_domain,

>> @@ -629,6 +631,13 @@ support for power domains into subsystem-level callbacks, for example by

>>  modifying the platform bus type.  Other platforms need not implement it or take

>>  it into account in any way.

>>

>> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

>> +on/off even when the IRQs are disabled.

>

>What IRQ-safe means for devices is that their runtime PM callbacks may be

>invoked with interrupts disabled on the local CPU.  I guess the meaning of

>IRQ-safe for PM domains is analogous, but the above isn't precise enough to me.

>

>> An IRQ-safe device in a domain will

>> +disallow power management on the domain, unless the domain is also defined as

>> +IRQ-safe. In other words, a domain containing all IRQ-safe devices must also

>> +be defined as IRQ-safe. Another restriction this framework imposes on the

>> +parent domain of an IRQ-safe domain is that the parent domain must also be

>> +defined as IRQ-safe.

>

>What about this:

>

>"Devices may be defined as IRQ-safe which indicates to the PM core that their

>runtime PM callbacks may be invoked with disabled interrupts (see

>Documentation/power/runtime_pm.txt for more information).  If an IRQ-safe

>device belongs to a PM domain, the runtime PM of the domain will be disallowed,

>unless the domain itself is defined as IRQ-safe.  However, a PM domain can only

>be defined as IRQ-safe if all of the devices in it are IRQ-safe. 

>

This is correct. But the last line may need a bit of modification. If
all devices in a PM domain are IRQ-safe and the domain is NOT, then it
it is a valid combination just that the domain would never do runtime
PM.

> Moreover, if

>an IRQ-safe domain has a parent domain, the runtime PM of the parent is only

>allowed if the parent itself is IRQ-safe too with the additional restriction

>that all child domains of an IRQ-safe parent must also be IRQ-safe."

>

>Does it actually reflect what the code does?

>

Yes, this precisely reflects the code.

Thanks,
Lina
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lina Iyer Oct. 24, 2016, 9:17 p.m. | #5
On Mon, Oct 24 2016 at 15:15 -0600, Rafael J. Wysocki wrote:
>On Monday, October 24, 2016 10:16:05 AM Lina Iyer wrote:

>> On Sat, Oct 22 2016 at 18:19 -0600, Rafael J. Wysocki wrote:

>> >On Friday, October 21, 2016 03:52:55 PM Lina Iyer wrote:

>> >> Update documentation to reflect the changes made to support IRQ safe PM

>> >> domains.

>> >>

>> >> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

>> >> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

>> >> ---

>> >> Changes since v3:

>> >> - Moved para to the end of the section

>> >> - Added clause for all IRQ safe devices in a domain

>> >> - Cleanup explanation of nested domains

>> >> ---

>> >>  Documentation/power/devices.txt | 11 ++++++++++-

>> >>  1 file changed, 10 insertions(+), 1 deletion(-)

>> >>

>> >> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

>> >> index 8ba6625..9218ce6 100644

>> >> --- a/Documentation/power/devices.txt

>> >> +++ b/Documentation/power/devices.txt

>> >> @@ -607,7 +607,9 @@ individually.  Instead, a set of devices sharing a power resource can be put

>> >>  into a low-power state together at the same time by turning off the shared

>> >>  power resource.  Of course, they also need to be put into the full-power state

>> >>  together, by turning the shared power resource on.  A set of devices with this

>> >> -property is often referred to as a power domain.

>> >> +property is often referred to as a power domain. A power domain may also be

>> >> +nested inside another power domain. The nested domain is referred to as the

>> >> +sub-domain of the parent domain.

>> >>

>> >>  Support for power domains is provided through the pm_domain field of struct

>> >>  device.  This field is a pointer to an object of type struct dev_pm_domain,

>> >> @@ -629,6 +631,13 @@ support for power domains into subsystem-level callbacks, for example by

>> >>  modifying the platform bus type.  Other platforms need not implement it or take

>> >>  it into account in any way.

>> >>

>> >> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

>> >> +on/off even when the IRQs are disabled.

>> >

>> >What IRQ-safe means for devices is that their runtime PM callbacks may be

>> >invoked with interrupts disabled on the local CPU.  I guess the meaning of

>> >IRQ-safe for PM domains is analogous, but the above isn't precise enough to me.

>> >

>> >> An IRQ-safe device in a domain will

>> >> +disallow power management on the domain, unless the domain is also defined as

>> >> +IRQ-safe. In other words, a domain containing all IRQ-safe devices must also

>> >> +be defined as IRQ-safe. Another restriction this framework imposes on the

>> >> +parent domain of an IRQ-safe domain is that the parent domain must also be

>> >> +defined as IRQ-safe.

>> >

>> >What about this:

>> >

>> >"Devices may be defined as IRQ-safe which indicates to the PM core that their

>> >runtime PM callbacks may be invoked with disabled interrupts (see

>> >Documentation/power/runtime_pm.txt for more information).  If an IRQ-safe

>> >device belongs to a PM domain, the runtime PM of the domain will be disallowed,

>> >unless the domain itself is defined as IRQ-safe.  However, a PM domain can only

>> >be defined as IRQ-safe if all of the devices in it are IRQ-safe.

>> >

>> This is correct. But the last line may need a bit of modification. If

>> all devices in a PM domain are IRQ-safe and the domain is NOT, then it

>> it is a valid combination just that the domain would never do runtime

>> PM.

>

>That doesn't contradict the last sentence of mine above.  I guess what you mean

>is that having a non-IRQ-safe device in an IRQ-safe domain is a valid

>configuration.  I wonder how it works then. :-)

>

>In any case, what about changing that sentence to something like:

>

>"However, it only makes sense to define a PM domain as IRQ-safe if all devices

>in it are IRQ-safe."

>

That's precise. I will add your para instead of mine to the
documentation.

Thanks,
Lina
>

--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Rafael J. Wysocki Oct. 24, 2016, 9:22 p.m. | #6
On Monday, October 24, 2016 10:16:05 AM Lina Iyer wrote:
> On Sat, Oct 22 2016 at 18:19 -0600, Rafael J. Wysocki wrote:

> >On Friday, October 21, 2016 03:52:55 PM Lina Iyer wrote:

> >> Update documentation to reflect the changes made to support IRQ safe PM

> >> domains.

> >>

> >> Signed-off-by: Lina Iyer <lina.iyer@linaro.org>

> >> Acked-by: Ulf Hansson <ulf.hansson@linaro.org>

> >> ---

> >> Changes since v3:

> >> - Moved para to the end of the section

> >> - Added clause for all IRQ safe devices in a domain

> >> - Cleanup explanation of nested domains

> >> ---

> >>  Documentation/power/devices.txt | 11 ++++++++++-

> >>  1 file changed, 10 insertions(+), 1 deletion(-)

> >>

> >> diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt

> >> index 8ba6625..9218ce6 100644

> >> --- a/Documentation/power/devices.txt

> >> +++ b/Documentation/power/devices.txt

> >> @@ -607,7 +607,9 @@ individually.  Instead, a set of devices sharing a power resource can be put

> >>  into a low-power state together at the same time by turning off the shared

> >>  power resource.  Of course, they also need to be put into the full-power state

> >>  together, by turning the shared power resource on.  A set of devices with this

> >> -property is often referred to as a power domain.

> >> +property is often referred to as a power domain. A power domain may also be

> >> +nested inside another power domain. The nested domain is referred to as the

> >> +sub-domain of the parent domain.

> >>

> >>  Support for power domains is provided through the pm_domain field of struct

> >>  device.  This field is a pointer to an object of type struct dev_pm_domain,

> >> @@ -629,6 +631,13 @@ support for power domains into subsystem-level callbacks, for example by

> >>  modifying the platform bus type.  Other platforms need not implement it or take

> >>  it into account in any way.

> >>

> >> +Devices and PM domains may be defined as IRQ-safe, if they can be powered

> >> +on/off even when the IRQs are disabled.

> >

> >What IRQ-safe means for devices is that their runtime PM callbacks may be

> >invoked with interrupts disabled on the local CPU.  I guess the meaning of

> >IRQ-safe for PM domains is analogous, but the above isn't precise enough to me.

> >

> >> An IRQ-safe device in a domain will

> >> +disallow power management on the domain, unless the domain is also defined as

> >> +IRQ-safe. In other words, a domain containing all IRQ-safe devices must also

> >> +be defined as IRQ-safe. Another restriction this framework imposes on the

> >> +parent domain of an IRQ-safe domain is that the parent domain must also be

> >> +defined as IRQ-safe.

> >

> >What about this:

> >

> >"Devices may be defined as IRQ-safe which indicates to the PM core that their

> >runtime PM callbacks may be invoked with disabled interrupts (see

> >Documentation/power/runtime_pm.txt for more information).  If an IRQ-safe

> >device belongs to a PM domain, the runtime PM of the domain will be disallowed,

> >unless the domain itself is defined as IRQ-safe.  However, a PM domain can only

> >be defined as IRQ-safe if all of the devices in it are IRQ-safe. 

> >

> This is correct. But the last line may need a bit of modification. If

> all devices in a PM domain are IRQ-safe and the domain is NOT, then it

> it is a valid combination just that the domain would never do runtime

> PM.


That doesn't contradict the last sentence of mine above.  I guess what you mean
is that having a non-IRQ-safe device in an IRQ-safe domain is a valid
configuration.  I wonder how it works then. :-)

In any case, what about changing that sentence to something like:

"However, it only makes sense to define a PM domain as IRQ-safe if all devices
in it are IRQ-safe."

Thanks,
Rafael

--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch

diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt
index 8ba6625..0401b53 100644
--- a/Documentation/power/devices.txt
+++ b/Documentation/power/devices.txt
@@ -607,7 +607,14 @@  individually.  Instead, a set of devices sharing a power resource can be put
 into a low-power state together at the same time by turning off the shared
 power resource.  Of course, they also need to be put into the full-power state
 together, by turning the shared power resource on.  A set of devices with this
-property is often referred to as a power domain.
+property is often referred to as a power domain. A power domain may also be
+nested inside another power domain.
+
+Devices and PM domains may be defined as IRQ-safe, if they can be powered
+on/off even when the IRQs are disabled. An IRQ-safe device in a domain will
+disallow power management on the domain, unless the domain is also defined as
+IRQ-safe. The restriction this framework imposes on the parent domain of an
+IRQ-safe domain is that it must also be defined as IRQ-safe.
 
 Support for power domains is provided through the pm_domain field of struct
 device.  This field is a pointer to an object of type struct dev_pm_domain,