Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 7 May 2020 08:41:45 +0200
From:   Greg Kroah-Hartman <gregkh@linuxfoundation.org>
To:     Andy Shevchenko <andy.shevchenko@gmail.com>
Cc:     Alan Cooper <alcooperx@gmail.com>,
        ": Linux Kernel Mailing List" <linux-kernel@vger.kernel.org>,
        Alan Stern <stern@rowland.harvard.edu>,
        BCM Kernel Feedback <bcm-kernel-feedback-list@broadcom.com>,
        DTML <devicetree@vger.kernel.org>,
        Krzysztof Kozlowski <krzk@kernel.org>,
        USB list <linux-usb@vger.kernel.org>,
        Mathias Nyman <mathias.nyman@intel.com>,
        Rob Herring <robh+dt@kernel.org>,
        Yoshihiro Shimoda <yoshihiro.shimoda.uh@renesas.com>,
        Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Subject: Re: [PATCH v6 3/4] usb: ehci: Add new EHCI driver for Broadcom STB
 SoC's
Message-ID: <20200507064145.GB777100@kroah.com>
References: <20200430111258.6091-1-alcooperx@gmail.com>
 <20200430111258.6091-4-alcooperx@gmail.com>
 <20200505110036.GB93160@kroah.com>
 <CAOGqxeXboYz2OQhgJsYmH5_7qEwKeWR5AA4Ljq_iFdSX=H2fkA@mail.gmail.com>
 <CAHp75VeA8JnsJgEgkv0wivinsxvk51JTVyaPhmLhsjzkqZYR8A@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CAHp75VeA8JnsJgEgkv0wivinsxvk51JTVyaPhmLhsjzkqZYR8A@mail.gmail.com>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Thu, May 07, 2020 at 12:01:16AM +0300, Andy Shevchenko wrote:
> On Wed, May 6, 2020 at 11:23 PM Alan Cooper <alcooperx@gmail.com> wrote:
> > On Tue, May 5, 2020 at 7:00 AM Greg Kroah-Hartman
> > <gregkh@linuxfoundation.org> wrote:
> > > On Thu, Apr 30, 2020 at 07:12:57AM -0400, Al Cooper wrote:
> 
> ...
> 
> > > > +     /* Hook the hub control routine to work around a bug */
> > >
> > > What bug?  This feels wrong.
> >
> > The bug is explained in a comment above the ehci_brcm_hub_control()
> > routine as follows:
> > /*
> >  * ehci_brcm_hub_control
> >  * Intercept echi-hcd request to complete RESUME and align it to the start
> >  * of the next microframe.
> >  * If RESUME is complete too late in the microframe, host controller
> >  * detects babble on suspended port and resets the port afterwards.
> >  * This s/w workaround allows to avoid this problem.
> >  * See SWLINUX-1909 for more details
> >  */
> > I'll remove the internal bug tracking reference from the comment.
> 
> I guess you may leave the internal bug reference. I can tell from my
> experience that's hard to understand what was going on in the driver
> in years perspective. It will help whoever in this company have a
> chance to look after the driver.

"internal bug references" mean nothing to the 99% of the people that can
see this.  Document the heck out of what this is instead please.

greg k-h