From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 401C9C2BA19 for ; Tue, 21 Apr 2020 08:37:52 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1DB3420B1F for ; Tue, 21 Apr 2020 08:37:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1587458272; bh=OHxIgROj4IF3rf5g0fXl4TEIyeeWRkA4FYDLGZXpeuo=; h=Date:From:To:Cc:Subject:References:In-Reply-To:List-ID:From; b=E2uievAymCrYmjawbxW6LQCuUNR1vi6g2hfCdh3X2q2P/Qjdixsfd6CbVYMaLSUEN n8Eh61B/43NymKGvueM0HOsDZRADn4CqW7H7GHyAkwomowqA4pvewSHS9kNra7nGKh cPaR6UPIfHFCg2PobF1ZtRNKOo8CumYVG8RA1xvM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728285AbgDUIhv (ORCPT ); Tue, 21 Apr 2020 04:37:51 -0400 Received: from mail.kernel.org ([198.145.29.99]:47492 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726018AbgDUIhu (ORCPT ); Tue, 21 Apr 2020 04:37:50 -0400 Received: from localhost (83-86-89-107.cable.dynamic.v4.ziggo.nl [83.86.89.107]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 65BEE2098B; Tue, 21 Apr 2020 08:37:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1587458269; bh=OHxIgROj4IF3rf5g0fXl4TEIyeeWRkA4FYDLGZXpeuo=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=ebfcx3qwQ9NM0N+I0taXmMPUlX2of9Ui0JjWoaD3AY9EqHloANpy+IWK6W6SNOavx OU7JADfFOv8PuWQtg5mbUkIAJmi6cuJ9TE4buMBVWjn/z6LHywVM+8ZrAvU7sOSMwn pj+ohd1BCE5Hrka9A+5TQCeuwTeNncDSo8N0mcyw= Date: Tue, 21 Apr 2020 10:37:47 +0200 From: Greg KH To: Jeff Kirsher Cc: davem@davemloft.net, Dave Ertman , netdev@vger.kernel.org, linux-rdma@vger.kernel.org, nhorman@redhat.com, sassmann@redhat.com, jgg@ziepe.ca, parav@mellanox.com, galpress@amazon.com, selvin.xavier@broadcom.com, sriharsha.basavapatna@broadcom.com, benve@cisco.com, bharat@chelsio.com, xavier.huwei@huawei.com, yishaih@mellanox.com, leonro@mellanox.com, mkalderon@marvell.com, aditr@vmware.com, ranjani.sridharan@linux.intel.com, pierre-louis.bossart@linux.intel.com, Kiran Patil , Andrew Bowers Subject: Re: [net-next v2 1/9] Implementation of Virtual Bus Message-ID: <20200421083747.GC716720@kroah.com> References: <20200421080235.6515-1-jeffrey.t.kirsher@intel.com> <20200421080235.6515-2-jeffrey.t.kirsher@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20200421080235.6515-2-jeffrey.t.kirsher@intel.com> Sender: linux-rdma-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rdma@vger.kernel.org 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 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 "." 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 . > + > +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? Bad documentation is worse than no documentation for things like this... greg k-h