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