PCI: Add pci_suspend_retains_context() to check if device state is preserved during...

PCI: Add pci_suspend_retains_context() to check if device state is preserved during suspend

Currently, PCI endpoint drivers (e.g. nvme) use pm_suspend_via_firmware()
to check whether device state is preserved during system suspend.  If
firmware will be invoked at the end of suspend, we don't know whether
devices will retain their internal state.

But device context might be lost due to platform issues as well.  Having
those checks in endpoint drivers will not scale and will cause a lot of
code duplication.

Add pci_suspend_retains_context() as a sole point of truth that the
endpoint drivers can rely on to check whether they can expect the device
context to be retained or not.

If pci_suspend_retains_context() returns 'false', drivers need to prepare
for context loss by performing actions such as resetting the device, saving
the context, shutting it down etc. If it returns 'true', drivers do not
need to perform any special action and can leave the device in active
state.

Right now, this API only incorporates pm_suspend_via_firmware(), but will
be extended in future commits.

Signed-off-by: Manivannan Sadhasivam <manivannan.sadhasivam@oss.qualcomm.com>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://patch.msgid.link/20260519-l1ss-fix-v2-1-b2c3a4bdeb15@oss.qualcomm.com