[PATCH v3 22/29] vhost: remove experimental from some API's

[Maxime Coquelin]

On 10/19/23 18:55, Stephen Hemminger wrote:
> All API's that before 22.11 release should have experimental
> tag removed.
> 
> Signed-off-by: Stephen Hemminger <stephen at networkplumber.org>
> ---
>   lib/vhost/rte_vhost.h        |  5 ----
>   lib/vhost/rte_vhost_async.h  | 19 --------------
>   lib/vhost/rte_vhost_crypto.h |  1 -
>   lib/vhost/version.map        | 51 ++++++++++++++----------------------
>   4 files changed, 19 insertions(+), 57 deletions(-)
> 
> diff --git a/lib/vhost/rte_vhost.h b/lib/vhost/rte_vhost.h
> index fec650b1dbba..db92f0534431 100644
> --- a/lib/vhost/rte_vhost.h
> +++ b/lib/vhost/rte_vhost.h
> @@ -509,7 +509,6 @@ rte_vhost_driver_get_vdpa_device(const char *path);
>    * @return
>    *  0 on success, -1 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_driver_get_vdpa_dev_type(const char *path, uint32_t *type);
>   
> @@ -648,7 +647,6 @@ int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
>    * @return
>    *  0 on success, -1 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_get_negotiated_protocol_features(int vid,
>   					   uint64_t *protocol_features);
> @@ -960,7 +958,6 @@ int rte_vhost_vring_call(int vid, uint16_t vring_idx);
>    * @return
>    *  0 on success, -1 on failure, -EAGAIN for another retry
>    */
> -__rte_experimental
>   int rte_vhost_vring_call_nonblock(int vid, uint16_t vring_idx);
>   
>   /**
> @@ -987,7 +984,6 @@ uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
>    * @return
>    *  0 on success, -1 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_get_monitor_addr(int vid, uint16_t queue_id,
>   		struct rte_vhost_power_monitor_cond *pmc);
> @@ -1102,7 +1098,6 @@ rte_vhost_get_vdpa_device(int vid);
>    * @return
>    *  0 on success, < 0 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_backend_config_change(int vid, bool need_reply);
>   
> diff --git a/lib/vhost/rte_vhost_async.h b/lib/vhost/rte_vhost_async.h
> index 8f190dd44b1b..3370026415fb 100644
> --- a/lib/vhost/rte_vhost_async.h
> +++ b/lib/vhost/rte_vhost_async.h
> @@ -24,7 +24,6 @@ extern "C" {
>    * @return
>    *  0 on success, -1 on failures
>    */
> -__rte_experimental
>   int rte_vhost_async_channel_register(int vid, uint16_t queue_id);
>   
>   /**
> @@ -37,7 +36,6 @@ int rte_vhost_async_channel_register(int vid, uint16_t queue_id);
>    * @return
>    *  0 on success, -1 on failures
>    */
> -__rte_experimental
>   int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
>   
>   /**
> @@ -54,7 +52,6 @@ int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
>    * @return
>    *  0 on success, -1 on failures
>    */
> -__rte_experimental
>   int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id);
>   
>   /**
> @@ -71,7 +68,6 @@ int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id);
>    * @return
>    *  0 on success, -1 on failures
>    */
> -__rte_experimental
>   int rte_vhost_async_channel_unregister_thread_unsafe(int vid,
>   		uint16_t queue_id);
>   
> @@ -95,7 +91,6 @@ int rte_vhost_async_channel_unregister_thread_unsafe(int vid,
>    * @return
>    *  num of packets enqueued
>    */
> -__rte_experimental
>   uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
>   		struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
>   		uint16_t vchan_id);
> @@ -120,7 +115,6 @@ uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
>    * @return
>    *  num of packets returned
>    */
> -__rte_experimental
>   uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
>   		struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
>   		uint16_t vchan_id);
> @@ -136,7 +130,6 @@ uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
>    * @return
>    *  the amount of in-flight packets on success; -1 on failure
>    */
> -__rte_experimental
>   int rte_vhost_async_get_inflight(int vid, uint16_t queue_id);
>   
>   /**
> @@ -153,7 +146,6 @@ int rte_vhost_async_get_inflight(int vid, uint16_t queue_id);
>    * @return
>    * the amount of in-flight packets on success; -1 on failure
>    */
> -__rte_experimental
>   int rte_vhost_async_get_inflight_thread_unsafe(int vid, uint16_t queue_id);
>   
>   /**
> @@ -178,7 +170,6 @@ int rte_vhost_async_get_inflight_thread_unsafe(int vid, uint16_t queue_id);
>    * @return
>    *  Number of packets returned
>    */
> -__rte_experimental
>   uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id,
>   		struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
>   		uint16_t vchan_id);
> @@ -203,7 +194,6 @@ uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id,
>    * @return
>    *  Number of packets returned
>    */
> -__rte_experimental
>   uint16_t rte_vhost_clear_queue(int vid, uint16_t queue_id,
>   		struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
>   		uint16_t vchan_id);
> @@ -226,13 +216,9 @@ uint16_t rte_vhost_clear_queue(int vid, uint16_t queue_id,
>    * @return
>    *  0 on success, and -1 on failure
>    */
> -__rte_experimental
>   int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id);
>   
>   /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
> - *
>    * This function tries to receive packets from the guest with offloading
>    * copies to the DMA vChannels. Successfully dequeued packets are returned
>    * in "pkts". The other packets that their copies are submitted to
> @@ -260,16 +246,12 @@ int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id);
>    * @return
>    *  Number of successfully dequeued packets
>    */
> -__rte_experimental
>   uint16_t
>   rte_vhost_async_try_dequeue_burst(int vid, uint16_t queue_id,
>   	struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count,
>   	int *nr_inflight, int16_t dma_id, uint16_t vchan_id);
>   
>   /**
> - * @warning
> - * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
> - *
>    * Unconfigure DMA vChannel in Vhost asynchronous data path.
>    * This function should be called when the specified DMA vChannel is no longer
>    * used by the Vhost library. Before this function is called, make sure there
> @@ -282,7 +264,6 @@ rte_vhost_async_try_dequeue_burst(int vid, uint16_t queue_id,
>    * @return
>    *  0 on success, and -1 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_async_dma_unconfigure(int16_t dma_id, uint16_t vchan_id);
>   

I think we should wait before remove experimental tag on all the Vhost
async APIs. Indeed, it was intended to be used by OVS, but the proposed
architecture was nacked by the OVS maintainers. I'm not aware of any
other user of these APIs.

So we are not sure the proposed API is a good fit.
Furthermore, it is not clear the team who implemented Vhost Async are
still going to maintain it.

Chenbo, what do you think?

Thanks,
Maxime

> diff --git a/lib/vhost/rte_vhost_crypto.h b/lib/vhost/rte_vhost_crypto.h
> index 2b01ecda0880..71a30ba202be 100644
> --- a/lib/vhost/rte_vhost_crypto.h
> +++ b/lib/vhost/rte_vhost_crypto.h
> @@ -40,7 +40,6 @@ enum rte_vhost_crypto_zero_copy {
>    * @return
>    *  0 on success, -1 on failure
>    */
> -__rte_experimental
>   int
>   rte_vhost_crypto_driver_start(const char *path);
>   
> diff --git a/lib/vhost/version.map b/lib/vhost/version.map
> index 5bc133dafda2..9696c4d91fe8 100644
> --- a/lib/vhost/version.map
> +++ b/lib/vhost/version.map
> @@ -9,10 +9,23 @@ DPDK_24 {
>   	rte_vdpa_get_stats;
>   	rte_vdpa_get_stats_names;
>   	rte_vdpa_reset_stats;
> +	rte_vhost_async_channel_register;
> +	rte_vhost_async_channel_register_thread_unsafe;
> +	rte_vhost_async_channel_unregister;
> +	rte_vhost_async_channel_unregister_thread_unsafe;
> +	rte_vhost_async_dma_configure;
> +	rte_vhost_async_dma_unconfigure;
> +	rte_vhost_async_get_inflight;
> +	rte_vhost_async_get_inflight_thread_unsafe;
> +	rte_vhost_async_try_dequeue_burst;
>   	rte_vhost_avail_entries;
> +	rte_vhost_backend_config_change;
> +	rte_vhost_clear_queue;
> +	rte_vhost_clear_queue_thread_unsafe;
>   	rte_vhost_clr_inflight_desc_packed;
>   	rte_vhost_clr_inflight_desc_split;
>   	rte_vhost_crypto_create;
> +	rte_vhost_crypto_driver_start;
>   	rte_vhost_crypto_fetch_requests;
>   	rte_vhost_crypto_finalize_requests;
>   	rte_vhost_crypto_free;
> @@ -26,6 +39,7 @@ DPDK_24 {
>   	rte_vhost_driver_get_features;
>   	rte_vhost_driver_get_protocol_features;
>   	rte_vhost_driver_get_queue_num;
> +	rte_vhost_driver_get_vdpa_dev_type;
>   	rte_vhost_driver_get_vdpa_device;
>   	rte_vhost_driver_register;
>   	rte_vhost_driver_set_features;
> @@ -38,8 +52,10 @@ DPDK_24 {
>   	rte_vhost_get_ifname;
>   	rte_vhost_get_log_base;
>   	rte_vhost_get_mem_table;
> +	rte_vhost_get_monitor_addr;
>   	rte_vhost_get_mtu;
>   	rte_vhost_get_negotiated_features;
> +	rte_vhost_get_negotiated_protocol_features;
>   	rte_vhost_get_numa_node;
>   	rte_vhost_get_vdpa_device;
>   	rte_vhost_get_vhost_ring_inflight;
> @@ -49,14 +65,17 @@ DPDK_24 {
>   	rte_vhost_get_vring_num;
>   	rte_vhost_log_used_vring;
>   	rte_vhost_log_write;
> +	rte_vhost_poll_enqueue_completed;
>   	rte_vhost_rx_queue_count;
>   	rte_vhost_set_inflight_desc_packed;
>   	rte_vhost_set_inflight_desc_split;
>   	rte_vhost_set_last_inflight_io_packed;
>   	rte_vhost_set_last_inflight_io_split;
>   	rte_vhost_set_vring_base;
> +	rte_vhost_submit_enqueue_burst;
>   	rte_vhost_va_from_guest_pa;
>   	rte_vhost_vring_call;
> +	rte_vhost_vring_call_nonblock;
>   	rte_vhost_vring_stats_get;
>   	rte_vhost_vring_stats_get_names;
>   	rte_vhost_vring_stats_reset;
> @@ -67,38 +86,6 @@ DPDK_24 {
>   EXPERIMENTAL {
>   	global:
>   
> -	rte_vhost_crypto_driver_start;
> -	rte_vhost_backend_config_change;
> -	rte_vhost_async_channel_register;
> -	rte_vhost_async_channel_unregister;
> -	rte_vhost_submit_enqueue_burst;
> -	rte_vhost_poll_enqueue_completed;
> -
> -	# added in 21.05
> -	rte_vhost_get_negotiated_protocol_features;
> -
> -	# added in 21.08
> -	rte_vhost_async_get_inflight;
> -	rte_vhost_async_channel_register_thread_unsafe;
> -	rte_vhost_async_channel_unregister_thread_unsafe;
> -	rte_vhost_clear_queue_thread_unsafe;
> -
> -	# added in 21.11
> -	rte_vhost_get_monitor_addr;
> -
> -	# added in 22.03
> -	rte_vhost_async_dma_configure;
> -
> -	# added in 22.07
> -	rte_vhost_async_get_inflight_thread_unsafe;
> -	rte_vhost_async_try_dequeue_burst;
> -	rte_vhost_driver_get_vdpa_dev_type;
> -	rte_vhost_clear_queue;
> -
> -	# added in 22.11
> -	rte_vhost_async_dma_unconfigure;
> -	rte_vhost_vring_call_nonblock;
> -
>   	# added in 23.07
>   	rte_vhost_driver_set_max_queue_num;
>   	rte_vhost_notify_guest;