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