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 <stdint.h>
   9
  10 #include <rte_compat.h>
  11 #include <rte_mbuf.h>
  12
  13 /**
  14  * Register an async channel for a vhost queue
  15  *
  16  * @param vid
  17  *  vhost device id async channel to be attached to
  18  * @param queue_id
  19  *  vhost queue id async channel to be attached to
  20  * @return
  21  *  0 on success, -1 on failures
  22  */
  23 __rte_experimental
  24 int rte_vhost_async_channel_register(int vid, uint16_t queue_id);
  25
  26 /**
  27  * Unregister an async channel for a vhost queue
  28  *
  29  * @param vid
  30  *  vhost device id async channel to be detached from
  31  * @param queue_id
  32  *  vhost queue id async channel to be detached from
  33  * @return
  34  *  0 on success, -1 on failures
  35  */
  36 __rte_experimental
  37 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
  38
  39 /**
  40  * Register an async channel for a vhost queue without performing any
  41  * locking
  42  *
  43  * @note This function does not perform any locking, and is only safe to
  44  *       call in vhost callback functions.
  45  *
  46  * @param vid
  47  *  vhost device id async channel to be attached to
  48  * @param queue_id
  49  *  vhost queue id async channel to be attached to
  50  * @return
  51  *  0 on success, -1 on failures
  52  */
  53 __rte_experimental
  54 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id);
  55
  56 /**
  57  * Unregister an async channel for a vhost queue without performing any
  58  * locking
  59  *
  60  * @note This function does not perform any locking, and is only safe to
  61  *       call in vhost callback functions.
  62  *
  63  * @param vid
  64  *  vhost device id async channel to be detached from
  65  * @param queue_id
  66  *  vhost queue id async channel to be detached from
  67  * @return
  68  *  0 on success, -1 on failures
  69  */
  70 __rte_experimental
  71 int rte_vhost_async_channel_unregister_thread_unsafe(int vid,
  72                 uint16_t queue_id);
  73
  74 /**
  75  * This function submits enqueue packets to async copy engine. Users
  76  * need to poll transfer status by rte_vhost_poll_enqueue_completed()
  77  * for successfully enqueued packets.
  78  *
  79  * @param vid
  80  *  id of vhost device to enqueue data
  81  * @param queue_id
  82  *  queue id to enqueue data
  83  * @param pkts
  84  *  array of packets to be enqueued
  85  * @param count
  86  *  packets num to be enqueued
  87  * @param dma_id
  88  *  the identifier of DMA device
  89  * @param vchan_id
  90  *  the identifier of virtual DMA channel
  91  * @return
  92  *  num of packets enqueued
  93  */
  94 __rte_experimental
  95 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
  96                 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
  97                 uint16_t vchan_id);
  98
  99 /**
 100  * This function checks async completion status for a specific vhost
 101  * device queue. Packets which finish copying (enqueue) operation
 102  * will be returned in an array.
 103  *
 104  * @param vid
 105  *  id of vhost device to enqueue data
 106  * @param queue_id
 107  *  queue id to enqueue data
 108  * @param pkts
 109  *  blank array to get return packet pointer
 110  * @param count
 111  *  size of the packet array
 112  * @param dma_id
 113  *  the identifier of DMA device
 114  * @param vchan_id
 115  *  the identifier of virtual DMA channel
 116  * @return
 117  *  num of packets returned
 118  */
 119 __rte_experimental
 120 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
 121                 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
 122                 uint16_t vchan_id);
 123
 124 /**
 125  * This function returns the amount of in-flight packets for the vhost
 126  * queue which uses async channel acceleration.
 127  *
 128  * @param vid
 129  *  id of vhost device to enqueue data
 130  * @param queue_id
 131  *  queue id to enqueue data
 132  * @return
 133  *  the amount of in-flight packets on success; -1 on failure
 134  */
 135 __rte_experimental
 136 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id);
 137
 138 /**
 139  * This function checks async completion status and clear packets for
 140  * a specific vhost device queue. Packets which are inflight will be
 141  * returned in an array.
 142  *
 143  * @note This function does not perform any locking
 144  *
 145  * @param vid
 146  *  ID of vhost device to clear data
 147  * @param queue_id
 148  *  Queue id to clear data
 149  * @param pkts
 150  *  Blank array to get return packet pointer
 151  * @param count
 152  *  Size of the packet array
 153  * @param dma_id
 154  *  the identifier of DMA device
 155  * @param vchan_id
 156  *  the identifier of virtual DMA channel
 157  * @return
 158  *  Number of packets returned
 159  */
 160 __rte_experimental
 161 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id,
 162                 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id,
 163                 uint16_t vchan_id);
 164
 165 /**
 166  * The DMA vChannels used in asynchronous data path must be configured
 167  * first. So this function needs to be called before enabling DMA
 168  * acceleration for vring. If this function fails, the given DMA vChannel
 169  * cannot be used in asynchronous data path.
 170  *
 171  * DMA devices used in data-path must belong to DMA devices given in this
 172  * function. Application is free to use DMA devices passed to this function
 173  * for non-vhost scenarios, but will have to ensure the Vhost library is not
 174  * using the channel at the same time.
 175  *
 176  * @param dma_id
 177  *  the identifier of DMA device
 178  * @param vchan_id
 179  *  the identifier of virtual DMA channel
 180  * @return
 181  *  0 on success, and -1 on failure
 182  */
 183 __rte_experimental
 184 int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id);
 185
 186 #endif /* _RTE_VHOST_ASYNC_H_ */