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