PM: Add constraint API

[ceolin]

This will replace the pm_ctrl_* API.

[pabigot]

Before we go too far down the path of size-checked increments I'd like to see that discussed.

Also if we're using a mutex we need to document that people can't set constraints from interrupts or before POST_KERNEL. Which, I suspect, is probably a restriction we should not impose.

[ceolin]

@pabigot thanks for reviewing it. Regarding mutex usage, I can remove them if I assume that the input is always right, but I don't like this idea, right now this is just checking if the given state is a valid one, but we may want to check if the state is defined by the target. I can change it to spin look and allows using from an interrupt context.

Why do you think it is bad constraint allowing use this API only after POST_KERNEL ?

[pabigot]

Why do you think it is bad constraint allowing use this API only after POST_KERNEL ?

When drivers start up pre-kernel they may want to set constraints to prevent themselves from being shut down.

[ceolin]

@pabigot I just kept the current implementation but changed API names to align with what you've discussed. Would you mind take a look again ?

[pabigot]

I continue to believe the documentation on this API is horrifically poor (what does "set a constraint" actually mean in terms of its effect on the system behavior?), but as a refactoring PR it's ok.

[ceolin]

@nashif would you mind take a look ? Also, CI failed for not clear reason.

[ceolin]

I continue to believe the documentation on this API is horrifically poor (what does "set a constraint" actually mean in terms of its effect on the system behavior?), but as a refactoring PR it's ok.

agree, will address it in another pr.

[andyross]

Seems fine. I agree that naming cleanup without a doc rewrite might be getting ahead of ourselves. But no reason not to merge.

[erwango]

One point is not clear to me on this API. Not sure if this is the right pace to discuss. Please discard this comment if this isn't.
When setting a constraint on a particular state, should we assume the same constraint should be used on "deeper sleep states", or is the caller expected to call all related states where the constrain apply?

What about substates ?

[pabigot]

I think we need to wait to discuss that, since this PR is just renaming stuff, but:

• I'm not sure if we can assume a strict linear ordering such that if you block a transition to STANDBY you implicitly block transition to SUSPEND_TO_RAM and other "lower" states. Need to see what the prior art does.
• yes, constraints are going to have to take substates into account, either explicitly or through some other back door.