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