From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by dpdk.org (Postfix) with ESMTP id 970A81B9F1 for ; Fri, 12 Oct 2018 18:06:00 +0200 (CEST) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id B5FB53003C4D; Fri, 12 Oct 2018 16:05:59 +0000 (UTC) Received: from [10.36.112.48] (ovpn-112-48.ams2.redhat.com [10.36.112.48]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 07E977B5EF; Fri, 12 Oct 2018 16:05:56 +0000 (UTC) To: Xiaolong Ye , dev@dpdk.org, Tiwei Bie , Zhihong Wang , Ferruh Yigit Cc: xiao.w.wang@intel.com References: <20181012085221.55769-1-xiaolong.ye@intel.com> From: Maxime Coquelin Message-ID: <27b6ce30-7c37-f50f-1066-8d3d5a09bc6a@redhat.com> Date: Fri, 12 Oct 2018 18:05:54 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 MIME-Version: 1.0 In-Reply-To: <20181012085221.55769-1-xiaolong.ye@intel.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.44]); Fri, 12 Oct 2018 16:05:59 +0000 (UTC) Subject: Re: [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 12 Oct 2018 16:06:01 -0000 On 10/12/2018 10:52 AM, Xiaolong Ye wrote: > As APIs in rte_vdpa.h are public, we need to add doxygen comments > to all APIs and structures. > > Signed-off-by: Xiaolong Ye Reviewed-by: Maxime Coquelin > --- > > changes from v1: > 1. add descriptions for all fields of structs > 2. add warning section for all __rte_experimental API > > > doc/api/doxy-api-index.md | 1 + > lib/librte_vhost/rte_vdpa.h | 96 +++++++++++++++++++++++++++++++------ > 2 files changed, 83 insertions(+), 14 deletions(-) > > diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md > index 9584ccb4c..a3039d168 100644 > --- a/doc/api/doxy-api-index.md > +++ b/doc/api/doxy-api-index.md > @@ -37,6 +37,7 @@ The public API headers are grouped by topics: > [softnic] (@ref rte_eth_softnic.h), > [bond] (@ref rte_eth_bond.h), > [vhost] (@ref rte_vhost.h), > + [vdpa] (@ref rte_vdpa.h), > [KNI] (@ref rte_kni.h), > [ixgbe] (@ref rte_pmd_ixgbe.h), > [i40e] (@ref rte_pmd_i40e.h), > diff --git a/lib/librte_vhost/rte_vdpa.h b/lib/librte_vhost/rte_vdpa.h > index b8223e337..daac09394 100644 > --- a/lib/librte_vhost/rte_vdpa.h > +++ b/lib/librte_vhost/rte_vdpa.h > @@ -21,70 +21,138 @@ enum vdpa_addr_type { > VDPA_ADDR_MAX > }; > > +/** > + * vdpa device address > + */ > struct rte_vdpa_dev_addr { > + /** vdpa address type */ > enum vdpa_addr_type type; > + > + /** vdpa pci address */ > union { > uint8_t __dummy[64]; > struct rte_pci_addr pci_addr; > }; > }; > > +/** > + * vdpa device operations > + */ > struct rte_vdpa_dev_ops { > - /* Get capabilities of this device */ > + /** Get capabilities of this device */ > int (*get_queue_num)(int did, uint32_t *queue_num); > + > + /** Get supported features of this device */ > int (*get_features)(int did, uint64_t *features); > + > + /** Get supported protocol features of this device */ > int (*get_protocol_features)(int did, uint64_t *protocol_features); > > - /* Driver configure/close the device */ > + /** Driver configure/close the device */ > int (*dev_conf)(int vid); > int (*dev_close)(int vid); > > - /* Enable/disable this vring */ > + /** Enable/disable this vring */ > int (*set_vring_state)(int vid, int vring, int state); > > - /* Set features when changed */ > + /** Set features when changed */ > int (*set_features)(int vid); > > - /* Destination operations when migration done */ > + /** Destination operations when migration done */ > int (*migration_done)(int vid); > > - /* Get the vfio group fd */ > + /** Get the vfio group fd */ > int (*get_vfio_group_fd)(int vid); > > - /* Get the vfio device fd */ > + /** Get the vfio device fd */ > int (*get_vfio_device_fd)(int vid); > > - /* Get the notify area info of the queue */ > + /** Get the notify area info of the queue */ > int (*get_notify_area)(int vid, int qid, > uint64_t *offset, uint64_t *size); > > - /* Reserved for future extension */ > + /** Reserved for future extension */ > void *reserved[5]; > }; > > +/** > + * vdpa device structure includes device address and device operations. > + */ > struct rte_vdpa_device { > + /** vdpa device address */ > struct rte_vdpa_dev_addr addr; > + /** vdpa device operations */ > struct rte_vdpa_dev_ops *ops; > } __rte_cache_aligned; > > -/* Register a vdpa device, return did if successful, -1 on failure */ > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Register a vdpa device > + * > + * @param addr > + * the vdpa device address > + * @parm ops > + * the vdpa device operations > + * @return > + * device id on success, -1 on failure > + */ > int __rte_experimental > rte_vdpa_register_device(struct rte_vdpa_dev_addr *addr, > struct rte_vdpa_dev_ops *ops); > > -/* Unregister a vdpa device, return -1 on failure */ > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Unregister a vdpa device > + * > + * @param did > + * vdpa device id > + * @return > + * device id on success, -1 on failure > + */ > int __rte_experimental > rte_vdpa_unregister_device(int did); > > -/* Find did of a vdpa device, return -1 on failure */ > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Find the device id of a vdpa device > + * > + * @param addr > + * the vdpa device address > + * @return > + * device id on success, -1 on failure > + */ > int __rte_experimental > rte_vdpa_find_device_id(struct rte_vdpa_dev_addr *addr); > > -/* Find a vdpa device based on did */ > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Find a vdpa device based on device id > + * > + * @param did > + * device id > + * @return > + * rte_vdpa_device on success, NULL on failure > + */ > struct rte_vdpa_device * __rte_experimental > rte_vdpa_get_device(int did); > > -/* Get current available vdpa device number */ > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Get current available vdpa device number > + * > + * @return > + * available vdpa device number > + */ > int __rte_experimental > rte_vdpa_get_device_num(void); > #endif /* _RTE_VDPA_H_ */ >