kern/57576: pmf(9) suspend/resume semantic guarantees are incoherent

[campbell+netbsd%mumble.net@localhost]

>Number:         57576
>Category:       kern
>Synopsis:       pmf(9) suspend/resume semantic guarantees are incoherent
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          sw-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Aug 09 07:35:00 +0000 2023
>Originator:     Taylor R Campbell
>Release:        current
>Organization:
The NetBSD Foundation (failed).
>Environment:
>Description:
1. If a suspend function fails, will the resume function be called on system resume?
2. If a suspend function fails, will the resume function ever be called before the next call to the suspend function?
3. If a suspend function fails, will it be called again on the next attempt to suspend the system?
4. If a resume function fails, will the suspend function be called on the next attempt to suspend the system?
5. If a resume function fails, will it ever be called again?

These are essential parts of the API contract and need to be clearly spelled out so drivers can handle all the cases they need to handle.

It's not clear that it's even useful for suspend functions to be able to fail.  When suspend is requested, it is absolutely critical for the system to be put in a low-power state, even if that state is just powered off in the event of a bug -- the physical hardware is likely to be put in a backpack or somewhere with inadequate heat dissipation, so failure to enter a low-power state can cause damage to the physical hardware itself.
>How-To-Repeat:
code inspection
>Fix:
1. Decide answers to questions.
2. Document them in pmf(9).
3. Audit all drivers for reliance on the answers.