Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Mon, 27 Jun 2022 12:06:21 -0700
From:   Matthias Kaehlcke <mka@chromium.org>
To:     Alan Stern <stern@rowland.harvard.edu>
Cc:     Doug Anderson <dianders@chromium.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Rob Herring <robh+dt@kernel.org>,
        Frank Rowand <frowand.list@gmail.com>,
        Mathias Nyman <mathias.nyman@intel.com>,
        Felipe Balbi <balbi@kernel.org>,
        Michal Simek <michal.simek@xilinx.com>,
        LKML <linux-kernel@vger.kernel.org>,
        Krzysztof Kozlowski <krzk@kernel.org>,
        Stephen Boyd <swboyd@chromium.org>,
        "open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS" 
        <devicetree@vger.kernel.org>, Bastien Nocera <hadess@hadess.net>,
        Peter Chen <peter.chen@kernel.org>,
        Ravi Chandra Sadineni <ravisadineni@chromium.org>,
        Roger Quadros <rogerq@kernel.org>,
        Linux USB List <linux-usb@vger.kernel.org>,
        Geert Uytterhoeven <geert+renesas@glider.be>,
        Souradeep Chowdhury <quic_schowdhu@quicinc.com>
Subject: Re: [PATCH v22 2/3] usb: misc: Add onboard_usb_hub driver
Message-ID: <Yrn/rfrzSWod5SCT@google.com>
References: <Yqub17iT4O7aqFMi@google.com>
 <CAD=FV=VEztPLhsrJecZUdyHCW7ZfFTVvxyqY5CqRVv2mWyrLog@mail.gmail.com>
 <YquoSMiQS+RG8rOM@google.com>
 <CAD=FV=W81pSEUbzw2ZQgs_TJ9MLnHQHiDopZXZ6bHdS7QMzAyA@mail.gmail.com>
 <YqvMffveCPiKQEUk@google.com>
 <CAD=FV=UJOStPfRR3Hq2DmRBSH-HCtZ16hAU9eVH5w6Hm=WSJRQ@mail.gmail.com>
 <YqytDNB2y4+qT8GD@google.com>
 <CAD=FV=UT0XtMjZ9syQPGXeTEaUrwGTb_LgDow+cofgmx4D30VA@mail.gmail.com>
 <Yrnzl8k81f9JTMIQ@google.com>
 <Yrn8y4GGZm+NyXIi@rowland.harvard.edu>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
In-Reply-To: <Yrn8y4GGZm+NyXIi@rowland.harvard.edu>
Precedence: bulk

On Mon, Jun 27, 2022 at 02:54:03PM -0400, Alan Stern wrote:
> On Mon, Jun 27, 2022 at 11:14:47AM -0700, Matthias Kaehlcke wrote:
> > Maybe a bit more verbose documentation like this could help:
> > 
> >   Some background about the logic in this function, which can be a bit hard
> >   to follow:
> > 
> >   Root hubs don't have dedicated device tree nodes, but use the node of their
> >   HCD. The primary and secondary HCD are usually represented by a single DT
> >   node. That means the root hubs of the primary and secondary HCD share the
> >   same device tree node (the HCD node). As a result this function can be
> >   called twice with the same DT node for root hubs. We only want to create a
> >   single platform device for each physical onboard hub, hence for root hubs
> >   the loop is only executed for the primary hub. Since the function scans
> 
> By "primary hub", you mean "root hub for the primary HCD", right?  This 
> should be clarified.

Ok, thanks for the suggestion!

> >   through all child nodes it still creates pdevs for onboard hubs connected
> >   to the secondary hub if needed.
> 
> And likewise for "secondary hub".
>
> > 
> >   Further there must be only one platform device for onboard hubs with a
> >   companion hub (the hub is a single physical device). To achieve this two
> 
> What do you mean by "companion hub"?  I think you are using the wrong 
> word here.  If you're talking about the relation between the two logical 
> hubs (one attached to the SuperSpeed bus and one attached to the 
> Low/Full/High-speed bus) within a physical USB-3 hub, the correct term 
> for this is "peer".  See the existing usages in hub.h, hub.c, and 
> port.c.
> 
> "Companion" refers to something completely different (i.e., the UHCI or 
> OHCI controllers that handle Low/Full-speed connections on behalf of a 
> High-speed EHCI controller).

Yes it's the relation between the two logical hub. The term 'companion-hub'
stems from the binding and has been around since v6 of this series. I guess
we should update the binding if the terminology isn't correct.