Although we are declaring `pm->enable`as bitfield, it ends up using
more memory due memory alignment.
Since we already have an atomic variable for device flags, this commit
adds a new flag to indicates whether or not device runtime is enabled.
Doing it we are saving some extra bits and avoiding need to lock the
mutex in several situations since we can atomically check if pm
runtime is enabled on a given device.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
The device PM subsystem _depends_ on device, not vice-versa. Devices
only hold a reference to struct pm_device now, and initialize this
reference with the value provided in Z_DEVICE_DEFINE. This requirement
can be solved with a forward struct declaration, meaning there is no
need to include device PM headers.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The macro has been moved to the pm/device.h header, being now called by
the Z_PM_DEVICE_DEFINE macro. This means that a slot will only be
created if the device uses PM, thus reducing memory usage.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Devices PM callback receive an action and not a state. Add a new API
that receives an action instead of a state.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
It is well known that PM subsystem has never been optimized in terms of
resource usage. The situation is particularly bad in case the PM runtime
API is enabled. What this patch does is to move the responsability of PM
resource definition to the device like this:
- Device is responsible to define PM resources, using a new set of
macros: PM_DEVICE_*DEFINE().
- DEVICE_*DEFINE macro accepts a reference to the device PM state, which
can be obtained using PM_DEVICE_*REF() set of macros. This
allows device to initialize the dev->pm reference.
This method decouples a bit more PM from devices since devices just keep
a reference to the device PM state. It also means that future PM changes
will have less chances to impact all devices, but only devices that
support PM.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Rename the macro used to initialize the runtime fields to
Z_PM_DEVICE_RUNTIME_INIT (emphasize it is internal and follows parent
macro naming).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Z_PM_DEVICE_INIT is used as a static initializer, so all non-specified
fields will already be set to zero.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a dummy implementation for the wakeup API, so that it can still be
used when no PM_DEVICE is enabled.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The PM flags are only used internally, so there is no need to include
them in the documentation.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Document the deprecated functions and macros, tag them with @deprecated
command to inform about the replacement.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
- Add a new `subsys_pm` group, part of `subsys`
- Improve group naming
- Include conditional code using __DOXYGEN__, it allows to have better
control of inclusion.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This patch refactors the runtime API to make it more clear and simple.
Relevant changes:
- API uses the action callback in a direct manner, avoiding unnecessary
overhead.
- API documentation has been improved to include detailed return error
codes.
- pm_runtime_disable() is now synchronous (to simplify possible error
paths) and returns error in case it fails. It is also safe to disable
in pre-kernel now.
- pm_runtime_put(_async)() will return -EALREADY if called with usage
count at zero (result of an unbalanced get/put call sequence)
- A transitional state has been added back. This makes code more
readable, and avoids using atomics (not required).
TODO:
- Solve in a better manner the asynchronous suspend error path (now
"solved" using asserts).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
As discussed in issues/38619, this commit aims to simplify device
power management. It was removed PM_DEVICE_SATE_LOW_POWER.
The power subsystem now doesn't need to figure out which device state to
use of a given system power state. It just suspend and resume devices.
Devices now just need to respond to ACTIVE and SUSPEND and OFF actions
and they are free to use any particular substate they have when the
subsystem asks to suspend. They also don't need to worry about states
transitions (unless they have multiple substates) because the system
will just request them to suspend if they are active and vice-versa.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
rebase
- Rename to "action" to make its purpose more clear
- Use the _cb suffix to align with naming used for callbacks in other
areas.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
PM_DEVICE_STATE_RESUMING and PM_DEVICE_STATE_SUSPENDING
are transitional states and are only used in device runtime. Remove it
and use device flag to keep track of a transition.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
The Z_DEVICE_STATE_DEFINE macro was conditioned by CONFIG_PM_DEVICE.
This is a problem if one day we have other conditional fields in the
device state field that need to be initialized. The approach has been
changed to have an always existing initializer for the PM field, that is
a no-op if device PM is not enabled.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Create a utility macro to initialize struct pm_device. The initializer
is kept in the pm/device.h header.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Introduce a new API to allow devices capable of wake up the system
register themselves was wake up sources. This permits applications to
select the most appropriate way to wake up the system when it is
suspended.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Just using a simple atomic for flags instead of using an array.
While is neat using ATOMIC_DEFINE for future proof. The reality is
that it brings some problem for the wakeup source implementation
that needs to statically initialize it during the device definition.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Add support for FORCE_SUSPEND and LOW_POWER actions. Even though these
actions have no clear meaning, they are added for compatibility until
their associated states are discussed. Their usage in new code should be
discouraged until the associated states are clarified.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Instead of passing target states, use actions for device PM control.
Actions represent better the meaning of the callback argument.
Furthermore, they are more future proof as they can be suitable for
other PM actions that have no direct mapping to a state. If we compare
with Linux, we could have a multi-stage suspend/resume. Such scenario
would not have a good mapping when using target states.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a type and documentation for the device PM control callback. This
way possible return codes and its meaning are documented.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The verb tense for the suspended state was not consistent with other
states. The likely reason: state was being used as a command/action.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
If the device is already at the given state, do not call the device PM
control function. This makes sure that devices are only called to change
from one state to another.
Even though asynchronous device PM is completely broken, transitional
states are considered too.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Improve the docstrings of the pm_device_state_set function and change to
shorter argument variable names.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The device PM subsystem already holds the device state, so there is no
need to keep duplicates inside the device. The pm_device_state_get has
been refactored to just return the device state. Note that this is still
not safe, but the same applied to the previous implementation. This
problem will be addressed later.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add old APIs marked as deprecated. The API keep the same behavior as
before, so external users have time to migrate their codebase.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Busy check APIs now return boolean type. Due to that change, the
function names have also been adjusted. The common name pattern for
boolean check type APIs is "PREFIX_is_CONDITION". For example,
"pm_device_is_busy". pm_device_busy_check has been renamed to
pm_device_is_busy and pm_device_any_busy_check to pm_device_is_any_busy.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
- Use an enum for the available flags
- Use ATOMIC_DEFINE macro to declare the flag bit field
- Improve naming
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The following device busy APIs:
- device_busy_set()
- device_busy_clear()
- device_busy_check()
- device_any_busy_check()
were used for device PM, so they have been moved to the pm subsystem.
This means they are now prefixed with `pm_` and are defined in
`pm/device.h`.
If device PM is not enabled dummy functions are now provided that do
nothing or return `-ENOSYS`, meaning that the functionality is not
available.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The callback is not used anymore, so just delete it from the pm_control
callback signature.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Move all PM_DEVICE_STATE_* definitions to an enum. The
PM_DEVICE_STATE_SET and PM_DEVICE_STATE_GET definitions have been kept
out of the enum since they do not represent any state. However, their
name has not been changed since they will be removed soon.
All drivers and tests have been adjusted accordingly.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Since we are using mutex to protect critical sections and mutexes are
reentrant, it is possible to get rid of atomic for the state because
we can lock the mutex in device_pm_callback.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Protect critical sections using the mutex.
The mutex is required to use the conditional variable and since we
need to atomically check the pm state and the workqueue before wait
the condition, it is necessary to protect them using the same mutex.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
Protect critical sessions using the spinlock available. The atomic
usage was not properly protecting the critical section and was
possible to have a race condition between the usage check and state
set.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
