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