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