cavs: pm: improve PM_RUNTIME_HOST_DMA_L1 documentation

[kv2019i]

Reword doxygen comments and change the private helper function
names to better reflect the actual implementation. No functional
change.

The PM_RUNTIME_HOST_DMA_L1 resource is used to coordinate host DMA
users, so that DMI link is kept in L1 until all users are ready to
activate the link. This is a bit unusual usage of runtime-pm interface
in that a 'put on a resource' triggers transition to higher power state,
so this deserves some more documentation.

Signed-off-by: Kai Vehmanen kai.vehmanen@linux.intel.com

[marc-hb]

thanks @kv2019i , this was incredibly confusing indeed.

So platform_pm_runtime_get(PM_RUNTIME_HOST_DMA_L1, ... helps maintains DMA in the lower power state for longer, but platform_pm_runtime_get(SOMETHING_ELSE, ... helps maintain something else in the higher power state? If correct then this could use a couple more comments.

I found related discussions in #2664, #3135 and #3223

[marc-hb]

Also confused by this: cavs_pm_runtime_enable_dsp() sets pprd->dsp_d0 to false, but then cavs_pm_runtime_is_active_dsp() returns pprd->dsp_d0

So "enable" and "active" are opposite of each other, correct?

https://thesofproject.github.io/latest/developer_guides/firmware/pm-runtime/pm-dsp-core.html

Power management = the land of double and triple negations.

[lgirdwood]

CI is known issue with kernel suspend.

[marc-hb]

Additional comments in #4441