From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by dpdk.org (Postfix) with ESMTP id 81D141B14D for ; Fri, 12 Oct 2018 10:51:50 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga105.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 12 Oct 2018 01:51:49 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,371,1534834800"; d="scan'208";a="98779149" Received: from yexl-server.sh.intel.com ([10.67.110.207]) by orsmga001.jf.intel.com with ESMTP; 12 Oct 2018 01:51:47 -0700 From: Xiaolong Ye To: dev@dpdk.org, Maxime Coquelin , Tiwei Bie , Zhihong Wang , Ferruh Yigit Cc: xiao.w.wang@intel.com, Xiaolong Ye Date: Fri, 12 Oct 2018 16:52:21 +0800 Message-Id: <20181012085221.55769-1-xiaolong.ye@intel.com> X-Mailer: git-send-email 2.17.1 Subject: [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 08:51:51 -0000 As APIs in rte_vdpa.h are public, we need to add doxygen comments to all APIs and structures. Signed-off-by: Xiaolong Ye --- 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_ */ -- 2.17.1