[v3,1/2] dt-bindings: usb: Add binding for discrete onboard USB hubs

Discrete onboard USB hubs (an example for such a hub is the Realtek
RTS5411) need to be powered and may require initialization of other
resources (like GPIOs or clocks) to work properly. This adds a device
tree binding for these hubs.

Signed-off-by: Matthias Kaehlcke <mka@chromium.org>
---

Changes in v3:
- updated commit message
- removed recursive reference to $self
- adjusted 'compatible' definition to support multiple entries
- changed USB controller phandle to be a node

Changes in v2:
- removed 'wakeup-source' and 'power-off-in-suspend' properties
- consistently use spaces for indentation in example

 .../bindings/usb/onboard_usb_hub.yaml         | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/onboard_usb_hub.yaml

On Wed, Sep 23, 2020 at 06:10:12PM -0700, Matthias Kaehlcke wrote:
> The main issue this driver addresses is that a USB hub needs to be
> powered before it can be discovered. For discrete onboard hubs (an
> example for such a hub is the Realtek RTS5411) this is often solved
> by supplying the hub with an 'always-on' regulator, which is kind
> of a hack. Some onboard hubs may require further initialization
> steps, like changing the state of a GPIO or enabling a clock, which
> requires even more hacks. This driver creates a platform device
> representing the hub which performs the necessary initialization.
> Currently it only supports switching on a single regulator, support
> for multiple regulators or other actions can be added as needed.
> Different initialization sequences can be supported based on the
> compatible string.
> 
> Besides performing the initialization the driver can be configured
> to power the hub off during system suspend. This can help to extend
> battery life on battery powered devices which have no requirements
> to keep the hub powered during suspend. The driver can also be
> configured to leave the hub powered when a wakeup capable USB device
> is connected when suspending, and power it off otherwise.
> 
> Technically the driver consists of two drivers, the platform driver
> described above and a very thin USB driver that subclasses the
> generic driver. The purpose of this driver is to provide the platform
> driver with the USB devices corresponding to the hub(s) (a hub
> controller may provide multiple 'logical' hubs, e.g. one to support
> USB 2.0 and another for USB 3.x).
> 
> Co-developed-by: Ravi Chandra Sadineni <ravisadineni@chromium.org>
> Signed-off-by: Ravi Chandra Sadineni <ravisadineni@chromium.org>
> Signed-off-by: Matthias Kaehlcke <mka@chromium.org>
> ---

> --- a/drivers/usb/misc/Kconfig
> +++ b/drivers/usb/misc/Kconfig
> @@ -275,3 +275,19 @@ config USB_CHAOSKEY
>  
>  	  To compile this driver as a module, choose M here: the
>  	  module will be called chaoskey.
> +
> +config USB_ONBOARD_HUB
> +	tristate "Onboard USB hub support"
> +	depends on OF || COMPILE_TEST
> +	help
> +	  Say Y here if you want to support discrete onboard USB hubs that
> +	  don't require an additional control bus for initialization (an

... but does require nontrivial form of initialization, such as
enabling a power regulator.


> +static void onboard_hub_remove_usbdev(struct onboard_hub *hub, struct usb_device *udev)
> +{
> +	struct udev_node *node;
> +
> +	smp_rmb();
> +	if (hub->going_away) {
> +		/*
> +		 * We are most likely being called as a result of unbinding a USB device from
> +		 * onboard_hub_remove(). This function also holds the lock and iterates over
> +		 * 'udev_list'. Skip deleting the node in this case to avoid a self deadlock,
> +		 * keeping the node in the list isn't a problem, since the device is about to go
> +		 * away.
> +		 */
> +		return;
> +	}

This part has a suspicious look.  For one thing, there's no comment
explaining the purpose of the smp_rmb().  For another, that barrier
doesn't seem to pair with any other memory barrier in the driver.

I get that you want to avoid self-deadlock here.  But there must be a
better way.  See below.

> +static int onboard_hub_remove(struct platform_device *pdev)
> +{
> +	struct onboard_hub *hub = dev_get_drvdata(&pdev->dev);
> +	struct udev_node *node;
> +
> +	hub->going_away = true;
> +
> +	mutex_lock(&hub->lock);
> +
> +	/* unbind the USB devices to avoid dangling references to this device */
> +	list_for_each_entry(node, &hub->udev_list, list)
> +		device_release_driver(&node->udev->dev);
> +
> +	mutex_unlock(&hub->lock);

Alternative approach:

	/* unbind the USB devices to avoid dangling references to this device */
	mutex_lock(&hub->lock);
	while (!list_empty(&hub->udev_list)) {
		node = list_first_entry(&hub->udev_list, struct udev_node, list);
		udev = node->udev;

		/*
		 * Unbinding the driver will call onboard_hub_remove_usbdev(),
		 * which acquires hub->lock.  We must release the lock first.
		 */
		usb_get_device(udev);
		mutex_unlock(&hub->lock);
		device_release_driver(&udev->dev);
		usb_put_device(udev);
		mutex_lock(&hub->lock);
	}
	mutex_unlock(&hub->lock);

> +static int onboard_hub_usbdev_probe(struct usb_device *udev)
> +{
> +	struct device *dev = &udev->dev;
> +	struct onboard_hub *hub;
> +
> +	/* ignore supported hubs without device tree node */
> +	if (!dev->of_node)
> +		return -ENODEV;
> +
> +	hub = _find_onboard_hub(dev);
> +	if (IS_ERR(hub))
> +		return PTR_ERR(dev);

hub, not dev.

Alan Stern

Hi Alan,

On Thu, Sep 24, 2020 at 11:27:58AM -0400, Alan Stern wrote:
> On Wed, Sep 23, 2020 at 06:10:12PM -0700, Matthias Kaehlcke wrote:
> > The main issue this driver addresses is that a USB hub needs to be
> > powered before it can be discovered. For discrete onboard hubs (an
> > example for such a hub is the Realtek RTS5411) this is often solved
> > by supplying the hub with an 'always-on' regulator, which is kind
> > of a hack. Some onboard hubs may require further initialization
> > steps, like changing the state of a GPIO or enabling a clock, which
> > requires even more hacks. This driver creates a platform device
> > representing the hub which performs the necessary initialization.
> > Currently it only supports switching on a single regulator, support
> > for multiple regulators or other actions can be added as needed.
> > Different initialization sequences can be supported based on the
> > compatible string.
> > 
> > Besides performing the initialization the driver can be configured
> > to power the hub off during system suspend. This can help to extend
> > battery life on battery powered devices which have no requirements
> > to keep the hub powered during suspend. The driver can also be
> > configured to leave the hub powered when a wakeup capable USB device
> > is connected when suspending, and power it off otherwise.
> > 
> > Technically the driver consists of two drivers, the platform driver
> > described above and a very thin USB driver that subclasses the
> > generic driver. The purpose of this driver is to provide the platform
> > driver with the USB devices corresponding to the hub(s) (a hub
> > controller may provide multiple 'logical' hubs, e.g. one to support
> > USB 2.0 and another for USB 3.x).
> > 
> > Co-developed-by: Ravi Chandra Sadineni <ravisadineni@chromium.org>
> > Signed-off-by: Ravi Chandra Sadineni <ravisadineni@chromium.org>
> > Signed-off-by: Matthias Kaehlcke <mka@chromium.org>
> > ---
> 
> > --- a/drivers/usb/misc/Kconfig
> > +++ b/drivers/usb/misc/Kconfig
> > @@ -275,3 +275,19 @@ config USB_CHAOSKEY
> >  
> >  	  To compile this driver as a module, choose M here: the
> >  	  module will be called chaoskey.
> > +
> > +config USB_ONBOARD_HUB
> > +	tristate "Onboard USB hub support"
> > +	depends on OF || COMPILE_TEST
> > +	help
> > +	  Say Y here if you want to support discrete onboard USB hubs that
> > +	  don't require an additional control bus for initialization (an
> 
> ... but does require nontrivial form of initialization, such as
> enabling a power regulator.

ok, I'll add that

> > +static void onboard_hub_remove_usbdev(struct onboard_hub *hub, struct usb_device *udev)
> > +{
> > +	struct udev_node *node;
> > +
> > +	smp_rmb();
> > +	if (hub->going_away) {
> > +		/*
> > +		 * We are most likely being called as a result of unbinding a USB device from
> > +		 * onboard_hub_remove(). This function also holds the lock and iterates over
> > +		 * 'udev_list'. Skip deleting the node in this case to avoid a self deadlock,
> > +		 * keeping the node in the list isn't a problem, since the device is about to go
> > +		 * away.
> > +		 */
> > +		return;
> > +	}
> 
> This part has a suspicious look.  For one thing, there's no comment
> explaining the purpose of the smp_rmb().  For another, that barrier
> doesn't seem to pair with any other memory barrier in the driver.

IIUC the mutex_lock() in onboard_hub_remove() is an implicit barrier, but
it is indeed not obvious from looking at the code.

> I get that you want to avoid self-deadlock here.  But there must be a
> better way.  See below.

I wasn't super happy about this either ...

> > +static int onboard_hub_remove(struct platform_device *pdev)
> > +{
> > +	struct onboard_hub *hub = dev_get_drvdata(&pdev->dev);
> > +	struct udev_node *node;
> > +
> > +	hub->going_away = true;
> > +
> > +	mutex_lock(&hub->lock);
> > +
> > +	/* unbind the USB devices to avoid dangling references to this device */
> > +	list_for_each_entry(node, &hub->udev_list, list)
> > +		device_release_driver(&node->udev->dev);
> > +
> > +	mutex_unlock(&hub->lock);
> 
> Alternative approach:
> 
> 	/* unbind the USB devices to avoid dangling references to this device */
> 	mutex_lock(&hub->lock);
> 	while (!list_empty(&hub->udev_list)) {
> 		node = list_first_entry(&hub->udev_list, struct udev_node, list);
> 		udev = node->udev;
> 
> 		/*
> 		 * Unbinding the driver will call onboard_hub_remove_usbdev(),
> 		 * which acquires hub->lock.  We must release the lock first.
> 		 */
> 		usb_get_device(udev);
> 		mutex_unlock(&hub->lock);
> 		device_release_driver(&udev->dev);
> 		usb_put_device(udev);
> 		mutex_lock(&hub->lock);
> 	}
> 	mutex_unlock(&hub->lock);
>

Thanks, that should work. I also thought about unlocking the mutex before
calling device_release_driver(), but that wouldn't be the right thing when
using list_for_each_entry(_safe). The alternative loop style allows for it.

> > +static int onboard_hub_usbdev_probe(struct usb_device *udev)
> > +{
> > +	struct device *dev = &udev->dev;
> > +	struct onboard_hub *hub;
> > +
> > +	/* ignore supported hubs without device tree node */
> > +	if (!dev->of_node)
> > +		return -ENODEV;
> > +
> > +	hub = _find_onboard_hub(dev);
> > +	if (IS_ERR(hub))
> > +		return PTR_ERR(dev);
> 
> hub, not dev.

ugh, yes