lib/librte_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
  63          */
  64         uint32_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 iov segments completed
  80          */
  81         uint32_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  *  dma channel feature bit definition
  88  */
  89 struct rte_vhost_async_features {
  90         union {
  91                 uint32_t intval;
  92                 struct {
  93                         uint32_t async_inorder:1;
  94                         uint32_t resvd_0:15;
  95                         uint32_t async_threshold:12;
  96                         uint32_t resvd_1:4;
  97                 };
  98         };
  99 };
 100
 101 /**
 102  * register a async channel for vhost
 103  *
 104  * @param vid
 105  *  vhost device id async channel to be attached to
 106  * @param queue_id
 107  *  vhost queue id async channel to be attached to
 108  * @param features
 109  *  DMA channel feature bit
 110  *    b0       : DMA supports inorder data transfer
 111  *    b1  - b15: reserved
 112  *    b16 - b27: Packet length threshold for DMA transfer
 113  *    b28 - b31: reserved
 114  * @param ops
 115  *  DMA operation callbacks
 116  * @return
 117  *  0 on success, -1 on failures
 118  */
 119 __rte_experimental
 120 int rte_vhost_async_channel_register(int vid, uint16_t queue_id,
 121         uint32_t features, struct rte_vhost_async_channel_ops *ops);
 122
 123 /**
 124  * unregister a dma channel for vhost
 125  *
 126  * @param vid
 127  *  vhost device id DMA channel to be detached
 128  * @param queue_id
 129  *  vhost queue id DMA channel to be detached
 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  * This function submit enqueue data to async engine. This function has
 138  * no guranttee to the transfer completion upon return. Applications
 139  * should poll transfer status by rte_vhost_poll_enqueue_completed()
 140  *
 141  * @param vid
 142  *  id of vhost device to enqueue data
 143  * @param queue_id
 144  *  queue id to enqueue data
 145  * @param pkts
 146  *  array of packets to be enqueued
 147  * @param count
 148  *  packets num to be enqueued
 149  * @return
 150  *  num of packets enqueued
 151  */
 152 __rte_experimental
 153 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
 154                 struct rte_mbuf **pkts, uint16_t count);
 155
 156 /**
 157  * This function check async completion status for a specific vhost
 158  * device queue. Packets which finish copying (enqueue) operation
 159  * will be returned in an array.
 160  *
 161  * @param vid
 162  *  id of vhost device to enqueue data
 163  * @param queue_id
 164  *  queue id to enqueue data
 165  * @param pkts
 166  *  blank array to get return packet pointer
 167  * @param count
 168  *  size of the packet array
 169  * @return
 170  *  num of packets returned
 171  */
 172 __rte_experimental
 173 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
 174                 struct rte_mbuf **pkts, uint16_t count);
 175
 176 #endif /* _RTE_VHOST_ASYNC_H_ */