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 #include <stdbool.h>
  15
  16 #include <rte_pci.h>
  17 #include "rte_vhost.h"
  18
  19 #define MAX_VDPA_NAME_LEN 128
  20
  21 /** Maximum name length for statistics counters */
  22 #define RTE_VDPA_STATS_NAME_SIZE 64
  23
  24 /**
  25  * A vDPA device statistic structure
  26  *
  27  * This structure is used by rte_vdpa_stats_get() to provide
  28  * statistics from the HW vDPA device.
  29  *
  30  * It maps a name id, corresponding to an index in the array returned
  31  * by rte_vdpa_get_stats_names, to a statistic value.
  32  */
  33 struct rte_vdpa_stat {
  34         uint64_t id;        /**< The index in stats name array */
  35         uint64_t value;     /**< The statistic counter value */
  36 };
  37
  38 /**
  39  * A name element for statistics
  40  *
  41  * An array of this structure is returned by rte_vdpa_get_stats_names
  42  * It lists the names of extended statistics for a PMD. The rte_vdpa_stat
  43  * structure references these names by their array index
  44  */
  45 struct rte_vdpa_stat_name {
  46         char name[RTE_VDPA_STATS_NAME_SIZE]; /**< The statistic name */
  47 };
  48
  49 /**
  50  * vdpa device operations
  51  */
  52 struct rte_vdpa_dev_ops {
  53         /** Get capabilities of this device */
  54         int (*get_queue_num)(int did, uint32_t *queue_num);
  55
  56         /** Get supported features of this device */
  57         int (*get_features)(int did, uint64_t *features);
  58
  59         /** Get supported protocol features of this device */
  60         int (*get_protocol_features)(int did, uint64_t *protocol_features);
  61
  62         /** Driver configure/close the device */
  63         int (*dev_conf)(int vid);
  64         int (*dev_close)(int vid);
  65
  66         /** Enable/disable this vring */
  67         int (*set_vring_state)(int vid, int vring, int state);
  68
  69         /** Set features when changed */
  70         int (*set_features)(int vid);
  71
  72         /** Destination operations when migration done */
  73         int (*migration_done)(int vid);
  74
  75         /** Get the vfio group fd */
  76         int (*get_vfio_group_fd)(int vid);
  77
  78         /** Get the vfio device fd */
  79         int (*get_vfio_device_fd)(int vid);
  80
  81         /** Get the notify area info of the queue */
  82         int (*get_notify_area)(int vid, int qid,
  83                         uint64_t *offset, uint64_t *size);
  84
  85         /** Get statistics name */
  86         int (*get_stats_names)(int did, struct rte_vdpa_stat_name *stats_names,
  87                                unsigned int size);
  88
  89         /** Get statistics of the queue */
  90         int (*get_stats)(int did, int qid, struct rte_vdpa_stat *stats,
  91                          unsigned int n);
  92
  93         /** Reset statistics of the queue */
  94         int (*reset_stats)(int did, int qid);
  95
  96         /** Reserved for future extension */
  97         void *reserved[2];
  98 };
  99
 100 /**
 101  * vdpa device structure includes device address and device operations.
 102  */
 103 struct rte_vdpa_device {
 104         /** Generic device information */
 105         struct rte_device *device;
 106         /** vdpa device operations */
 107         struct rte_vdpa_dev_ops *ops;
 108 } __rte_cache_aligned;
 109
 110 /**
 111  * @warning
 112  * @b EXPERIMENTAL: this API may change without prior notice
 113  *
 114  * Register a vdpa device
 115  *
 116  * @param addr
 117  *  the vdpa device address
 118  * @param ops
 119  *  the vdpa device operations
 120  * @return
 121  *  device id on success, -1 on failure
 122  */
 123 __rte_experimental
 124 int
 125 rte_vdpa_register_device(struct rte_device *rte_dev,
 126                 struct rte_vdpa_dev_ops *ops);
 127
 128 /**
 129  * @warning
 130  * @b EXPERIMENTAL: this API may change without prior notice
 131  *
 132  * Unregister a vdpa device
 133  *
 134  * @param did
 135  *  vdpa device id
 136  * @return
 137  *  device id on success, -1 on failure
 138  */
 139 __rte_experimental
 140 int
 141 rte_vdpa_unregister_device(int did);
 142
 143 /**
 144  * @warning
 145  * @b EXPERIMENTAL: this API may change without prior notice
 146  *
 147  * Find the device id of a vdpa device from its name
 148  *
 149  * @param name
 150  *  the vdpa device name
 151  * @return
 152  *  device id on success, -1 on failure
 153  */
 154 __rte_experimental
 155 int
 156 rte_vdpa_find_device_id_by_name(const char *name);
 157
 158 /**
 159  * @warning
 160  * @b EXPERIMENTAL: this API may change without prior notice
 161  *
 162  * Find the device id of a vdpa device
 163  *
 164  * @param addr
 165  *  the vdpa device address
 166  * @return
 167  *  device id on success, -1 on failure
 168  */
 169 __rte_experimental
 170 int
 171 rte_vdpa_find_device_id(struct rte_vdpa_device *dev);
 172
 173 /**
 174  * @warning
 175  * @b EXPERIMENTAL: this API may change without prior notice
 176  *
 177  * Find a vdpa device based on device id
 178  *
 179  * @param did
 180  *  device id
 181  * @return
 182  *  rte_vdpa_device on success, NULL on failure
 183  */
 184 __rte_experimental
 185 struct rte_vdpa_device *
 186 rte_vdpa_get_device(int did);
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change without prior notice
 191  *
 192  * Get current available vdpa device number
 193  *
 194  * @return
 195  *  available vdpa device number
 196  */
 197 __rte_experimental
 198 int
 199 rte_vdpa_get_device_num(void);
 200
 201 /**
 202  * @warning
 203  * @b EXPERIMENTAL: this API may change without prior notice
 204  *
 205  * Enable/Disable host notifier mapping for a vdpa port.
 206  *
 207  * @param vid
 208  *  vhost device id
 209  * @param enable
 210  *  true for host notifier map, false for host notifier unmap
 211  * @return
 212  *  0 on success, -1 on failure
 213  */
 214 __rte_experimental
 215 int
 216 rte_vhost_host_notifier_ctrl(int vid, bool enable);
 217
 218 /**
 219  * @warning
 220  * @b EXPERIMENTAL: this API may change without prior notice
 221  *
 222  * Synchronize the used ring from mediated ring to guest, log dirty
 223  * page for each writeable buffer, caller should handle the used
 224  * ring logging before device stop.
 225  *
 226  * @param vid
 227  *  vhost device id
 228  * @param qid
 229  *  vhost queue id
 230  * @param vring_m
 231  *  mediated virtio ring pointer
 232  * @return
 233  *  number of synced used entries on success, -1 on failure
 234  */
 235 __rte_experimental
 236 int
 237 rte_vdpa_relay_vring_used(int vid, uint16_t qid, void *vring_m);
 238
 239 /**
 240  * @warning
 241  * @b EXPERIMENTAL: this API may change without prior notice
 242  *
 243  * Retrieve names of statistics of a vDPA device.
 244  *
 245  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 246  * by array index: stats_names[i].name => stats[i].value
 247  *
 248  * And the array index is same with id field of 'struct rte_vdpa_stat':
 249  * stats[i].id == i
 250  *
 251  * @param did
 252  *  device id
 253  * @param stats_names
 254  *   array of at least size elements to be filled.
 255  *   If set to NULL, the function returns the required number of elements.
 256  * @param size
 257  *   The number of elements in stats_names array.
 258  * @return
 259  *   A negative value on error, otherwise the number of entries filled in the
 260  *   stats name array.
 261  */
 262 __rte_experimental
 263 int
 264 rte_vdpa_get_stats_names(int did, struct rte_vdpa_stat_name *stats_names,
 265                          unsigned int size);
 266
 267 /**
 268  * @warning
 269  * @b EXPERIMENTAL: this API may change without prior notice
 270  *
 271  * Retrieve statistics of a vDPA device.
 272  *
 273  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 274  * by array index: stats_names[i].name => stats[i].value
 275  *
 276  * And the array index is same with id field of 'struct rte_vdpa_stat':
 277  * stats[i].id == i
 278  *
 279  * @param did
 280  *  device id
 281  * @param qid
 282  *  queue id
 283  * @param stats
 284  *   A pointer to a table of structure of type rte_vdpa_stat to be filled with
 285  *   device statistics ids and values.
 286  * @param n
 287  *   The number of elements in stats array.
 288  * @return
 289  *   A negative value on error, otherwise the number of entries filled in the
 290  *   stats table.
 291  */
 292 __rte_experimental
 293 int
 294 rte_vdpa_get_stats(int did, uint16_t qid, struct rte_vdpa_stat *stats,
 295                    unsigned int n);
 296 /**
 297  * @warning
 298  * @b EXPERIMENTAL: this API may change without prior notice
 299  *
 300  * Reset statistics of a vDPA device.
 301  *
 302  * @param did
 303  *  device id
 304  * @param qid
 305  *  queue id
 306  * @return
 307  *   0 on success, a negative value on error.
 308  */
 309 __rte_experimental
 310 int
 311 rte_vdpa_reset_stats(int did, uint16_t qid);
 312 #endif /* _RTE_VDPA_H_ */