On 6/8/2021 06:20, Rafael J. Wysocki wrote:

On Tue, Jun 8, 2021 at 7:35 AM Christoph Hellwig [off-list ref] wrote:

quoted

On Mon, Jun 07, 2021 at 12:31:55PM -0500, Mario Limonciello wrote:

quoted

+/**
+ * acpi_storage_d3 - Check if a storage device should use D3.

Let's be specific about what D3 means here in the first place and
that's D3hot AFAICS.

And the comment should be something like "Check whether or not to use
D3hot in the suspend path".

Actually it can be D3hot or D3cold.  Microsoft's documentation doesn't 
indicate it's D3hot.  On the AMD platforms that prompted some of these 
changes it's D3cold.

quoted

quoted

+ * @dev: Device to check
+ *
+ * Returns %true if @dev should be put into D3 when the ->suspend method is
+ * called, else %false.  The name of this function is somewhat misleading
+ * as it has nothing to do with storage except for the name of the ACPI
+ * property.  On some platforms resume will not work if this hint is ignored.

I would write it this way:

"Return %true if the platform firmware wants @dev to be programmed
into D3hot in the suspend path, or %false when there is no specific
preference. On some platforms, if this hint is ignored, @dev may
remain unresponsive after suspending the platform as a whole."

And I'm not sure if it is necessary to mention "storage" in this comment at all.

Is your thought here in not mentioning "storage" that this symbol may be 
overloaded in the future to look at more than just the StorageD3Enable 
property and used for other things too?

quoted

quoted

+ *
+ */

I still do not like this comment.  There is nothing about only using this
for storage devices.  It is specific to a PCIe slot, and if I plug
something that is not a storage device into it the same restrictions
still apply.

Originally, it was about storage devices IIUC (and that's why the
property name is what it is).
 > IIRC PCIe link management was broken in some NVMe drives and putting
them into D3hot would allow the link to go down later and it would
never go up again.  So you-know-who decided to avoid using D3hot for
all NVMe drives and they were generally characterized as "storage".
Alas, that turned out to break other things depending on the devices
being put into D3hot (like PS_ON) so the property was invented to
allow OEMs to mark the configurations including the devices that
actually worked (and Linux was/is on the receiving end). And
originally the property applied to the endpoint device under the root
port it was present for (my personal opinion about this doesn't really
matter, so let me avoid wasting time on expressing it).

Now, it evidently has been re-purposed to mark PCIe root ports that
require devices under them to be put into D3hot in the suspend path
(and it now means any device under the root port with this property,
at least in some cases).

quoted

Also no need for the empty-ish line at the end.

Right.