* [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header
@ 2018-10-12 8:52 Xiaolong Ye
2018-10-12 16:05 ` Maxime Coquelin
2018-10-16 8:37 ` Maxime Coquelin
0 siblings, 2 replies; 3+ messages in thread
From: Xiaolong Ye @ 2018-10-12 8:52 UTC (permalink / raw)
To: dev, Maxime Coquelin, Tiwei Bie, Zhihong Wang, Ferruh Yigit
Cc: xiao.w.wang, Xiaolong Ye
As APIs in rte_vdpa.h are public, we need to add doxygen comments
to all APIs and structures.
Signed-off-by: Xiaolong Ye <xiaolong.ye@intel.com>
---
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header
2018-10-12 8:52 [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header Xiaolong Ye
@ 2018-10-12 16:05 ` Maxime Coquelin
2018-10-16 8:37 ` Maxime Coquelin
1 sibling, 0 replies; 3+ messages in thread
From: Maxime Coquelin @ 2018-10-12 16:05 UTC (permalink / raw)
To: Xiaolong Ye, dev, Tiwei Bie, Zhihong Wang, Ferruh Yigit; +Cc: xiao.w.wang
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 <xiaolong.ye@intel.com>
Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>
> ---
>
> 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_ */
>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header
2018-10-12 8:52 [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header Xiaolong Ye
2018-10-12 16:05 ` Maxime Coquelin
@ 2018-10-16 8:37 ` Maxime Coquelin
1 sibling, 0 replies; 3+ messages in thread
From: Maxime Coquelin @ 2018-10-16 8:37 UTC (permalink / raw)
To: Xiaolong Ye, dev, Tiwei Bie, Zhihong Wang, Ferruh Yigit; +Cc: xiao.w.wang
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 <xiaolong.ye@intel.com>
> ---
>
> 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(-)
>
Applied to dpdk-next-virtio/master.
Thanks,
Maxime
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2018-10-16 8:37 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-10-12 8:52 [dpdk-dev] [PATCH v2] vhost: add doxygen comment to vDPA header Xiaolong Ye
2018-10-12 16:05 ` Maxime Coquelin
2018-10-16 8:37 ` Maxime Coquelin
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).