device_pm: clarify and document usage

[chris-schra]

As I'm currently writing a low power driver for a NB-IoT modem I'm trying to do device power management right. I've already implemented the "legacy" (?) device power management API but wonder what the idle device power management is about.
I've read the documentation and the code but it still isn't clear to me how to work with it.

Let's use an example. The modem - like most of them - is working with AT commands via UART, so I've added an internal function to send commands to the modem on top of @mike-scott 's work like so:

static int quectel_mdm_send(struct modem_cmd *response_handlers, size_t handler_cmds_len,
							const u8_t *send_cmd, int timeout)
{
	bool awake_before = mdata.awake;
	int ret = 0;

	/* check if modem was sleeping */
	if(!awake_before)
	{
		if(!quectel_mdm_wake())
		{
			return -ENODEV;
		}
	}

	modem_cmd_send(&mctx.iface, &mctx.cmd_handler,
				   response_handlers, handler_cmds_len, send_cmd, &mdata.sem_response,
				   MDM_CMD_TIMEOUT);

	if(!awake_before)
	{
		/* send back to sleep */
		quectel_mdm_sleep();
	}

	return ret;
}

I'm checking if the modem was "awake" (reachable via UART) before the user requested to send an AT command - otherwise, if it's not awake, the UART is asleep and a timeout will happen. I want to be convenient here, so I added the check (for myself as well).
But what will happen is that if someone sends two consecutive commands we'll wake up and send to sleep the modem twice, effectively consuming more power compared to just keeping it on. Of course, there are two options:

• remove the convenience check and force the user to use device_pm API
• add an "idle timeout" which gets restarted after every device activity

And because of the "idle timeout" I remembered to have seen a "DEVICE_IDLE_PM" and thought it might be it: a mechanism where I can tell the system "Okay, this device had some activity, if there's no more activity for 2 seconds, let me sleep". But that's wrong.

So, what's DEVICE_IDLE_PM about and what are the advantages over DEVICE_PM?

[pabigot]

Device Idle Power Management was added in #13382. There are no in-tree users, but I understand this is being used by proprietary applications supported by Intel. The API is underdefined and probably not compatible with current visions for device power management, which involve general mechanisms for recording dependencies with the expectation that services with no dependencies automatically transition to a low power state. Core technologies intended to support communicating these dependencies are described at https://docs.zephyrproject.org/latest/reference/resource_management/index.html and #24781.

In other words: it's not there, don't use it. #24230 includes some relevant discussion, which is somewhat coupled to #24228.

The history of the slack conversation in the #powermanagement channel supporting this understanding is no longer visible, but I believe it included agreement that a more flexible API could supersede this in the future.

I'm going to close this because I don't think there's any action to be done here: nobody can document the device idle PM API because nobody uses it in-tree, and though we don't have a roll-up issue for all the problems with device PM this isn't going to be that. Comment and re-open if you disagree.

[pabigot]

Apparently this is still a thing, so I'm reopening it so the folks who are responsible for this API can decide whether it needs to be addressed.

[pabigot]

@wentongwu @nashif

[tbursztyka]

We need to replace this. Idle PM is certainly a feature to have, but not the way it was done.
( I am actually surprised the original PR got merged at the time. I mean, reading this: b4eb42f#r265216377 or this: b4eb42f#r265216676 )

[pabigot]

@tbursztyka IIRC #13382 was a release blocker for LTS.

[gmarull]

There's a guide now https://docs.zephyrproject.org/latest/services/pm/device_runtime.html If not sufficient, please, open a new issue describing what you need/miss.