Message-ID: <20240327161607.GQ403975@kernel.org>
Date: Wed, 27 Mar 2024 16:16:07 +0000
From: Simon Horman <horms@...nel.org>
To: Bartosz Golaszewski <brgl@...ev.pl>
Cc: Marcel Holtmann <marcel@...tmann.org>,
	Luiz Augusto von Dentz <luiz.dentz@...il.com>,
	"David S . Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
	Conor Dooley <conor+dt@...nel.org>, Kalle Valo <kvalo@...nel.org>,
	Bjorn Andersson <andersson@...nel.org>,
	Konrad Dybcio <konrad.dybcio@...aro.org>,
	Liam Girdwood <lgirdwood@...il.com>,
	Mark Brown <broonie@...nel.org>,
	Catalin Marinas <catalin.marinas@....com>,
	Will Deacon <will@...nel.org>, Bjorn Helgaas <bhelgaas@...gle.com>,
	Saravana Kannan <saravanak@...gle.com>,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Arnd Bergmann <arnd@...db.de>,
	Neil Armstrong <neil.armstrong@...aro.org>,
	Marek Szyprowski <m.szyprowski@...sung.com>,
	Alex Elder <elder@...aro.org>,
	Srini Kandagatla <srinivas.kandagatla@...aro.org>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	Abel Vesa <abel.vesa@...aro.org>,
	Manivannan Sadhasivam <mani@...nel.org>,
	Lukas Wunner <lukas@...ner.de>,
	Dmitry Baryshkov <dmitry.baryshkov@...aro.org>,
	linux-bluetooth@...r.kernel.org, netdev@...r.kernel.org,
	devicetree@...r.kernel.org, linux-kernel@...r.kernel.org,
	linux-wireless@...r.kernel.org, linux-arm-msm@...r.kernel.org,
	linux-arm-kernel@...ts.infradead.org, linux-pci@...r.kernel.org,
	linux-pm@...r.kernel.org,
	Bartosz Golaszewski <bartosz.golaszewski@...aro.org>
Subject: Re: [PATCH v6 12/16] PCI/pwrctl: add PCI power control core code

On Mon, Mar 25, 2024 at 02:16:20PM +0100, Bartosz Golaszewski wrote:
> From: Bartosz Golaszewski <bartosz.golaszewski@...aro.org>
> 
> Some PCI devices must be powered-on before they can be detected on the
> bus. Introduce a simple framework reusing the existing PCI OF
> infrastructure.
> 
> The way this works is: a DT node representing a PCI device connected to
> the port can be matched against its power control platform driver. If
> the match succeeds, the driver is responsible for powering-up the device
> and calling pcie_pwrctl_device_set_ready() which will trigger a PCI bus
> rescan as well as subscribe to PCI bus notifications.
> 
> When the device is detected and created, we'll make it consume the same
> DT node that the platform device did. When the device is bound, we'll
> create a device link between it and the parent power control device.
> 
> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@...aro.org>

Hi Bartosz,

some minor Kernel doc nits from my side.

...

> diff --git a/drivers/pci/pwrctl/core.c b/drivers/pci/pwrctl/core.c

...

> +/**
> + * devm_pci_pwrctl_device_set_ready - Managed variant of
> + * pci_pwrctl_device_set_ready().
> + *

nit: @dev should be documented here

> + * @pwrctl: PCI power control data
> + *
> + * Returns:
> + * 0 on success, negative error number on error.
> + */
> +int devm_pci_pwrctl_device_set_ready(struct device *dev,
> +				     struct pci_pwrctl *pwrctl)
> +{
> +	int ret;
> +
> +	ret = pci_pwrctl_device_set_ready(pwrctl);
> +	if (ret)
> +		return ret;
> +
> +	return devm_add_action_or_reset(dev,
> +					devm_pci_pwrctl_device_unset_ready,
> +					pwrctl);
> +}
> +EXPORT_SYMBOL_GPL(devm_pci_pwrctl_device_set_ready);
> +
> +MODULE_AUTHOR("Bartosz Golaszewski <bartosz.golaszewski@...aro.org>");
> +MODULE_DESCRIPTION("PCI Device Power Control core driver");
> +MODULE_LICENSE("GPL");
> diff --git a/include/linux/pci-pwrctl.h b/include/linux/pci-pwrctl.h
> new file mode 100644
> index 000000000000..ae8324ea7eeb
> --- /dev/null
> +++ b/include/linux/pci-pwrctl.h
> @@ -0,0 +1,51 @@
> +/* SPDX-License-Identifier: GPL-2.0-only */
> +/*
> + * Copyright (C) 2024 Linaro Ltd.
> + */
> +
> +#ifndef __PCI_PWRCTL_H__
> +#define __PCI_PWRCTL_H__
> +
> +#include <linux/notifier.h>
> +
> +struct device;
> +struct device_link;
> +
> +/*
> + * This is a simple framework for solving the issue of PCI devices that require
> + * certain resources (regulators, GPIOs, clocks) to be enabled before the
> + * device can actually be detected on the PCI bus.
> + *
> + * The idea is to reuse the platform bus to populate OF nodes describing the
> + * PCI device and its resources, let these platform devices probe and enable
> + * relevant resources and then trigger a rescan of the PCI bus allowing for the
> + * same device (with a second associated struct device) to be registered with
> + * the PCI subsystem.
> + *
> + * To preserve a correct hierarchy for PCI power management and device reset,
> + * we create a device link between the power control platform device (parent)
> + * and the supplied PCI device (child).
> + */
> +
> +/**
> + * struct pci_pwrctl - PCI device power control context.
> + * @dev - Address of the power controlling device.

nit: I think this should be "@dev: " rather than "@dev - "
     As is, "./scripts/kernel-doc -none" complains.
> + *
> + * An object of this type must be allocated by the PCI power control device and
> + * passed to the pwrctl subsystem to trigger a bus rescan and setup a device
> + * link with the device once it's up.
> + */
> +struct pci_pwrctl {
> +	struct device *dev;
> +
> +	/* Private, don't use. */

I think Private needs to be followed by a ':' rather than a ',' to keep
kernel-doc happy.

> +	struct notifier_block nb;
> +	struct device_link *link;
> +};
> +
> +int pci_pwrctl_device_set_ready(struct pci_pwrctl *pwrctl);
> +void pci_pwrctl_device_unset_ready(struct pci_pwrctl *pwrctl);
> +int devm_pci_pwrctl_device_set_ready(struct device *dev,
> +				     struct pci_pwrctl *pwrctl);
> +
> +#endif /* __PCI_PWRCTL_H__ */
> -- 
> 2.40.1
> 
> 

Powered by blists - more mailing lists