Message-ID: <61CC2BC414934749BD9F5BF3D5D940449866D956@ORSMSX112.amr.corp.intel.com>
Date:   Tue, 21 Apr 2020 08:50:47 +0000
From:   "Kirsher, Jeffrey T" <jeffrey.t.kirsher@...el.com>
To:     Greg KH <gregkh@...uxfoundation.org>
CC:     "davem@...emloft.net" <davem@...emloft.net>,
        "Ertman, David M" <david.m.ertman@...el.com>,
        "netdev@...r.kernel.org" <netdev@...r.kernel.org>,
        "linux-rdma@...r.kernel.org" <linux-rdma@...r.kernel.org>,
        "nhorman@...hat.com" <nhorman@...hat.com>,
        "sassmann@...hat.com" <sassmann@...hat.com>,
        "jgg@...pe.ca" <jgg@...pe.ca>,
        "parav@...lanox.com" <parav@...lanox.com>,
        "galpress@...zon.com" <galpress@...zon.com>,
        "selvin.xavier@...adcom.com" <selvin.xavier@...adcom.com>,
        "sriharsha.basavapatna@...adcom.com" 
        <sriharsha.basavapatna@...adcom.com>,
        "benve@...co.com" <benve@...co.com>,
        "bharat@...lsio.com" <bharat@...lsio.com>,
        "xavier.huwei@...wei.com" <xavier.huwei@...wei.com>,
        "yishaih@...lanox.com" <yishaih@...lanox.com>,
        "leonro@...lanox.com" <leonro@...lanox.com>,
        "mkalderon@...vell.com" <mkalderon@...vell.com>,
        "aditr@...are.com" <aditr@...are.com>,
        "ranjani.sridharan@...ux.intel.com" 
        <ranjani.sridharan@...ux.intel.com>,
        "pierre-louis.bossart@...ux.intel.com" 
        <pierre-louis.bossart@...ux.intel.com>,
        "Patil, Kiran" <kiran.patil@...el.com>,
        "Bowers, AndrewX" <andrewx.bowers@...el.com>
Subject: RE: [net-next v2 1/9] Implementation of Virtual Bus

> -----Original Message-----
> From: Greg KH <gregkh@...uxfoundation.org>
> Sent: Tuesday, April 21, 2020 01:38
> To: Kirsher, Jeffrey T <jeffrey.t.kirsher@...el.com>
> Cc: davem@...emloft.net; Ertman, David M <david.m.ertman@...el.com>;
> netdev@...r.kernel.org; linux-rdma@...r.kernel.org; nhorman@...hat.com;
> sassmann@...hat.com; jgg@...pe.ca; parav@...lanox.com;
> galpress@...zon.com; selvin.xavier@...adcom.com;
> sriharsha.basavapatna@...adcom.com; benve@...co.com;
> bharat@...lsio.com; xavier.huwei@...wei.com; yishaih@...lanox.com;
> leonro@...lanox.com; mkalderon@...vell.com; aditr@...are.com;
> ranjani.sridharan@...ux.intel.com; pierre-louis.bossart@...ux.intel.com; Patil,
> Kiran <kiran.patil@...el.com>; Bowers, AndrewX
> <andrewx.bowers@...el.com>
> Subject: Re: [net-next v2 1/9] Implementation of Virtual Bus
> 
> On Tue, Apr 21, 2020 at 01:02:27AM -0700, Jeff Kirsher wrote:
> > --- /dev/null
> > +++ b/Documentation/driver-api/virtual_bus.rst
> > @@ -0,0 +1,62 @@
> > +===============================
> > +Virtual Bus Devices and Drivers
> > +===============================
> > +
> > +See <linux/virtual_bus.h> for the models for virtbus_device and
> virtbus_driver.
> > +This bus is meant to be a lightweight software based bus to attach
> > +generic devices and drivers to so that a chunk of data can be passed
> between them.
> > +
> > +One use case example is an RDMA driver needing to connect with
> > +several different types of PCI LAN devices to be able to request
> > +resources from them (queue sets).  Each LAN driver that supports RDMA
> > +will register a virtbus_device on the virtual bus for each physical
> > +function.  The RDMA driver will register as a virtbus_driver on the
> > +virtual bus to be matched up with multiple virtbus_devices and
> > +receive a pointer to a struct containing the callbacks that the PCI
> > +LAN drivers support for registering with them.
> > +
> > +Sections in this document:
> > +        Virtbus devices
> > +        Virtbus drivers
> > +        Device Enumeration
> > +        Device naming and driver binding
> > +        Virtual Bus API entry points
> > +
> > +Virtbus devices
> > +~~~~~~~~~~~~~~~
> > +Virtbus_devices support the minimal device functionality.  Devices
> > +will accept a name, and then, when added to the virtual bus, an
> > +automatically generated index is concatenated onto it for the
> virtbus_device->name.
> > +
> > +Virtbus drivers
> > +~~~~~~~~~~~~~~~
> > +Virtbus drivers register with the virtual bus to be matched with
> > +virtbus devices.  They expect to be registered with a probe and
> > +remove callback, and also support shutdown, suspend, and resume
> > +callbacks.  They otherwise follow the standard driver behavior of
> > +having discovery and enumeration handled in the bus infrastructure.
> > +
> > +Virtbus drivers register themselves with the API entry point
> > +virtbus_register_driver and unregister with virtbus_unregister_driver.
> > +
> > +Device Enumeration
> > +~~~~~~~~~~~~~~~~~~
> > +Enumeration is handled automatically by the bus infrastructure via
> > +the ida_simple methods.
> > +
> > +Device naming and driver binding
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +The virtbus_device.dev.name is the canonical name for the device. It
> > +is built from two other parts:
> > +
> > +        - virtbus_device.name (also used for matching).
> > +        - virtbus_device.id (generated automatically from ida_simple
> > + calls)
> > +
> > +Virtbus device IDs are always in "<name>.<instance>" format.
> > +Instances are automatically selected through an ida_simple_get so are
> positive integers.
> > +Name is taken from the device name field.
> > +
> > +Driver IDs are simple <name>.
> > +
> > +Need to extract the name from the Virtual Device compare to name of
> > +the driver.
> 
> Why is this document even needed?
> 
> I understand the goal of documenting how to use this and such, but the above
> document does none of that.  The last sentance here doesn't even make sense
> to me.
> 
> How about tieing it into the kerneldoc functions that you have created in the .c
> file, to create something that actually is useful?  As it is, the above text doesn't
> describe anything to me that I could actually use, did it help someone who
> wants to use this api that you know of?
[Kirsher, Jeffrey T] 

Thank you for the feedback, I will work with David to fix the documentation so
that it is useful to you.
 
> Bad documentation is worse than no documentation for things like this...
> 
> greg k-h

Powered by blists - more mailing lists