On Tue, Jun 8, 2021 at 7:35 AM Christoph Hellwig <hch@xxxxxx> wrote: > > On Mon, Jun 07, 2021 at 12:31:55PM -0500, Mario Limonciello wrote: > > +/** > > + * 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". > > + * @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. > > + * > > + */ > > 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). > Also no need for the empty-ish line at the end. Right.
