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