lib/vhost/rte_vhost_async.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2020 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_VHOST_ASYNC_H_
   6 #define _RTE_VHOST_ASYNC_H_
   7
   8 #include "rte_vhost.h"
   9
  10 /**
  11  * iovec
  12  */
  13 struct rte_vhost_iovec {
  14         void *src_addr;
  15         void *dst_addr;
  16         size_t len;
  17 };
  18
  19 /**
  20  * iovec iterator
  21  */
  22 struct rte_vhost_iov_iter {
  23         /** pointer to the iovec array */
  24         struct rte_vhost_iovec *iov;
  25         /** number of iovec in this iterator */
  26         unsigned long nr_segs;
  27 };
  28
  29 /**
  30  * dma transfer status
  31  */
  32 struct rte_vhost_async_status {
  33         /** An array of application specific data for source memory */
  34         uintptr_t *src_opaque_data;
  35         /** An array of application specific data for destination memory */
  36         uintptr_t *dst_opaque_data;
  37 };
  38
  39 /**
  40  * dma operation callbacks to be implemented by applications
  41  */
  42 struct rte_vhost_async_channel_ops {
  43         /**
  44          * instruct async engines to perform copies for a batch of packets
  45          *
  46          * @param vid
  47          *  id of vhost device to perform data copies
  48          * @param queue_id
  49          *  queue id to perform data copies
  50          * @param iov_iter
  51          *  an array of IOV iterators
  52          * @param opaque_data
  53          *  opaque data pair sending to DMA engine
  54          * @param count
  55          *  number of elements in the "descs" array
  56          * @return
  57          *  number of IOV iterators processed, negative value means error
  58          */
  59         int32_t (*transfer_data)(int vid, uint16_t queue_id,
  60                 struct rte_vhost_iov_iter *iov_iter,
  61                 struct rte_vhost_async_status *opaque_data,
  62                 uint16_t count);
  63         /**
  64          * check copy-completed packets from the async engine
  65          * @param vid
  66          *  id of vhost device to check copy completion
  67          * @param queue_id
  68          *  queue id to check copy completion
  69          * @param opaque_data
  70          *  buffer to receive the opaque data pair from DMA engine
  71          * @param max_packets
  72          *  max number of packets could be completed
  73          * @return
  74          *  number of async descs completed, negative value means error
  75          */
  76         int32_t (*check_completed_copies)(int vid, uint16_t queue_id,
  77                 struct rte_vhost_async_status *opaque_data,
  78                 uint16_t max_packets);
  79 };
  80
  81 /**
  82  *  async channel features
  83  */
  84 enum {
  85         RTE_VHOST_ASYNC_INORDER = 1U << 0,
  86 };
  87
  88 /**
  89  *  async channel configuration
  90  */
  91 struct rte_vhost_async_config {
  92         uint32_t features;
  93         uint32_t rsvd[2];
  94 };
  95
  96 /**
  97  * Register an async channel for a vhost queue
  98  *
  99  * @param vid
 100  *  vhost device id async channel to be attached to
 101  * @param queue_id
 102  *  vhost queue id async channel to be attached to
 103  * @param config
 104  *  Async channel configuration structure
 105  * @param ops
 106  *  Async channel operation callbacks
 107  * @return
 108  *  0 on success, -1 on failures
 109  */
 110 __rte_experimental
 111 int rte_vhost_async_channel_register(int vid, uint16_t queue_id,
 112         struct rte_vhost_async_config config,
 113         struct rte_vhost_async_channel_ops *ops);
 114
 115 /**
 116  * Unregister an async channel for a vhost queue
 117  *
 118  * @param vid
 119  *  vhost device id async channel to be detached from
 120  * @param queue_id
 121  *  vhost queue id async channel to be detached from
 122  * @return
 123  *  0 on success, -1 on failures
 124  */
 125 __rte_experimental
 126 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
 127
 128 /**
 129  * Register an async channel for a vhost queue without performing any
 130  * locking
 131  *
 132  * @note This function does not perform any locking, and is only safe to
 133  *       call in vhost callback functions.
 134  *
 135  * @param vid
 136  *  vhost device id async channel to be attached to
 137  * @param queue_id
 138  *  vhost queue id async channel to be attached to
 139  * @param config
 140  *  Async channel configuration
 141  * @param ops
 142  *  Async channel operation callbacks
 143  * @return
 144  *  0 on success, -1 on failures
 145  */
 146 __rte_experimental
 147 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id,
 148         struct rte_vhost_async_config config,
 149         struct rte_vhost_async_channel_ops *ops);
 150
 151 /**
 152  * Unregister an async channel for a vhost queue without performing any
 153  * locking
 154  *
 155  * @note This function does not perform any locking, and is only safe to
 156  *       call in vhost callback functions.
 157  *
 158  * @param vid
 159  *  vhost device id async channel to be detached from
 160  * @param queue_id
 161  *  vhost queue id async channel to be detached from
 162  * @return
 163  *  0 on success, -1 on failures
 164  */
 165 __rte_experimental
 166 int rte_vhost_async_channel_unregister_thread_unsafe(int vid,
 167                 uint16_t queue_id);
 168
 169 /**
 170  * This function submits enqueue packets to async copy engine. Users
 171  * need to poll transfer status by rte_vhost_poll_enqueue_completed()
 172  * for successfully enqueued packets.
 173  *
 174  * @param vid
 175  *  id of vhost device to enqueue data
 176  * @param queue_id
 177  *  queue id to enqueue data
 178  * @param pkts
 179  *  array of packets to be enqueued
 180  * @param count
 181  *  packets num to be enqueued
 182  * @return
 183  *  num of packets enqueued
 184  */
 185 __rte_experimental
 186 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
 187                 struct rte_mbuf **pkts, uint16_t count);
 188
 189 /**
 190  * This function checks async completion status for a specific vhost
 191  * device queue. Packets which finish copying (enqueue) operation
 192  * will be returned in an array.
 193  *
 194  * @param vid
 195  *  id of vhost device to enqueue data
 196  * @param queue_id
 197  *  queue id to enqueue data
 198  * @param pkts
 199  *  blank array to get return packet pointer
 200  * @param count
 201  *  size of the packet array
 202  * @return
 203  *  num of packets returned
 204  */
 205 __rte_experimental
 206 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
 207                 struct rte_mbuf **pkts, uint16_t count);
 208
 209 /**
 210  * This function returns the amount of in-flight packets for the vhost
 211  * queue which uses async channel acceleration.
 212  *
 213  * @param vid
 214  *  id of vhost device to enqueue data
 215  * @param queue_id
 216  *  queue id to enqueue data
 217  * @return
 218  *  the amount of in-flight packets on success; -1 on failure
 219  */
 220 __rte_experimental
 221 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id);
 222
 223 /**
 224  * This function checks async completion status and clear packets for
 225  * a specific vhost device queue. Packets which are inflight will be
 226  * returned in an array.
 227  *
 228  * @note This function does not perform any locking
 229  *
 230  * @param vid
 231  *  ID of vhost device to clear data
 232  * @param queue_id
 233  *  Queue id to clear data
 234  * @param pkts
 235  *  Blank array to get return packet pointer
 236  * @param count
 237  *  Size of the packet array
 238  * @return
 239  *  Number of packets returned
 240  */
 241 __rte_experimental
 242 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id,
 243                 struct rte_mbuf **pkts, uint16_t count);
 244
 245 #endif /* _RTE_VHOST_ASYNC_H_ */