lib/librte_vhost/rte_vdpa.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_VDPA_H_
   6 #define _RTE_VDPA_H_
   7
   8 /**
   9  * @file
  10  *
  11  * Device specific vhost lib
  12  */
  13
  14 /** Maximum name length for statistics counters */
  15 #define RTE_VDPA_STATS_NAME_SIZE 64
  16
  17 struct rte_vdpa_device;
  18
  19 /**
  20  * A vDPA device statistic structure
  21  *
  22  * This structure is used by rte_vdpa_stats_get() to provide
  23  * statistics from the HW vDPA device.
  24  *
  25  * It maps a name id, corresponding to an index in the array returned
  26  * by rte_vdpa_get_stats_names, to a statistic value.
  27  */
  28 struct rte_vdpa_stat {
  29         uint64_t id;        /**< The index in stats name array */
  30         uint64_t value;     /**< The statistic counter value */
  31 };
  32
  33 /**
  34  * A name element for statistics
  35  *
  36  * An array of this structure is returned by rte_vdpa_get_stats_names
  37  * It lists the names of extended statistics for a PMD. The rte_vdpa_stat
  38  * structure references these names by their array index
  39  */
  40 struct rte_vdpa_stat_name {
  41         char name[RTE_VDPA_STATS_NAME_SIZE]; /**< The statistic name */
  42 };
  43
  44 /**
  45  * @warning
  46  * @b EXPERIMENTAL: this API may change without prior notice
  47  *
  48  * Find the device id of a vdpa device from its name
  49  *
  50  * @param name
  51  *  the vdpa device name
  52  * @return
  53  *  vDPA device pointer on success, NULL on failure
  54  */
  55 __rte_experimental
  56 struct rte_vdpa_device *
  57 rte_vdpa_find_device_by_name(const char *name);
  58
  59 /**
  60  * @warning
  61  * @b EXPERIMENTAL: this API may change without prior notice
  62  *
  63  * Get the generic device from the vdpa device
  64  *
  65  * @param vdpa_dev
  66  *  the vdpa device pointer
  67  * @return
  68  *  generic device pointer on success, NULL on failure
  69  */
  70 __rte_experimental
  71 struct rte_device *
  72 rte_vdpa_get_rte_device(struct rte_vdpa_device *vdpa_dev);
  73
  74 /**
  75  * @warning
  76  * @b EXPERIMENTAL: this API may change without prior notice
  77  *
  78  * Get number of queue pairs supported by the vDPA device
  79  *
  80  * @param dev
  81  *  vDP device pointer
  82  * @param queue_num
  83  *  pointer on where the number of queue is stored
  84  * @return
  85  *  0 on success, -1 on failure
  86  */
  87 __rte_experimental
  88 int
  89 rte_vdpa_get_queue_num(struct rte_vdpa_device *dev, uint32_t *queue_num);
  90
  91 /**
  92  * @warning
  93  * @b EXPERIMENTAL: this API may change without prior notice
  94  *
  95  * Get the Virtio features supported by the vDPA device
  96  *
  97  * @param dev
  98  *  vDP device pointer
  99  * @param features
 100  *  pointer on where the supported features are stored
 101  * @return
 102  *  0 on success, -1 on failure
 103  */
 104 __rte_experimental
 105 int
 106 rte_vdpa_get_features(struct rte_vdpa_device *dev, uint64_t *features);
 107
 108 /**
 109  * @warning
 110  * @b EXPERIMENTAL: this API may change without prior notice
 111  *
 112  * Get the Vhost-user protocol features supported by the vDPA device
 113  *
 114  * @param dev
 115  *  vDP device pointer
 116  * @param features
 117  *  pointer on where the supported protocol features are stored
 118  * @return
 119  *  0 on success, -1 on failure
 120  */
 121 __rte_experimental
 122 int
 123 rte_vdpa_get_protocol_features(struct rte_vdpa_device *dev, uint64_t *features);
 124
 125 /**
 126  * @warning
 127  * @b EXPERIMENTAL: this API may change without prior notice
 128  *
 129  * Synchronize the used ring from mediated ring to guest, log dirty
 130  * page for each writeable buffer, caller should handle the used
 131  * ring logging before device stop.
 132  *
 133  * @param vid
 134  *  vhost device id
 135  * @param qid
 136  *  vhost queue id
 137  * @param vring_m
 138  *  mediated virtio ring pointer
 139  * @return
 140  *  number of synced used entries on success, -1 on failure
 141  */
 142 __rte_experimental
 143 int
 144 rte_vdpa_relay_vring_used(int vid, uint16_t qid, void *vring_m);
 145
 146 /**
 147  * @warning
 148  * @b EXPERIMENTAL: this API may change without prior notice
 149  *
 150  * Retrieve names of statistics of a vDPA device.
 151  *
 152  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 153  * by array index: stats_names[i].name => stats[i].value
 154  *
 155  * And the array index is same with id field of 'struct rte_vdpa_stat':
 156  * stats[i].id == i
 157  *
 158  * @param dev
 159  *  vDPA device pointer
 160  * @param stats_names
 161  *   array of at least size elements to be filled.
 162  *   If set to NULL, the function returns the required number of elements.
 163  * @param size
 164  *   The number of elements in stats_names array.
 165  * @return
 166  *   A negative value on error, otherwise the number of entries filled in the
 167  *   stats name array.
 168  */
 169 __rte_experimental
 170 int
 171 rte_vdpa_get_stats_names(struct rte_vdpa_device *dev,
 172                 struct rte_vdpa_stat_name *stats_names,
 173                 unsigned int size);
 174
 175 /**
 176  * @warning
 177  * @b EXPERIMENTAL: this API may change without prior notice
 178  *
 179  * Retrieve statistics of a vDPA device.
 180  *
 181  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 182  * by array index: stats_names[i].name => stats[i].value
 183  *
 184  * And the array index is same with id field of 'struct rte_vdpa_stat':
 185  * stats[i].id == i
 186  *
 187  * @param dev
 188  *  vDPA device pointer
 189  * @param qid
 190  *  queue id
 191  * @param stats
 192  *   A pointer to a table of structure of type rte_vdpa_stat to be filled with
 193  *   device statistics ids and values.
 194  * @param n
 195  *   The number of elements in stats array.
 196  * @return
 197  *   A negative value on error, otherwise the number of entries filled in the
 198  *   stats table.
 199  */
 200 __rte_experimental
 201 int
 202 rte_vdpa_get_stats(struct rte_vdpa_device *dev, uint16_t qid,
 203                 struct rte_vdpa_stat *stats, unsigned int n);
 204 /**
 205  * @warning
 206  * @b EXPERIMENTAL: this API may change without prior notice
 207  *
 208  * Reset statistics of a vDPA device.
 209  *
 210  * @param dev
 211  *  vDPA device pointer
 212  * @param qid
 213  *  queue id
 214  * @return
 215  *   0 on success, a negative value on error.
 216  */
 217 __rte_experimental
 218 int
 219 rte_vdpa_reset_stats(struct rte_vdpa_device *dev, uint16_t qid);
 220 #endif /* _RTE_VDPA_H_ */