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         /** Generic device information */
 109         struct rte_device *device;
 110         /** vdpa device operations */
 111         struct rte_vdpa_dev_ops *ops;
 112 } __rte_cache_aligned;
 113
 114 /**
 115  * @warning
 116  * @b EXPERIMENTAL: this API may change without prior notice
 117  *
 118  * Register a vdpa device
 119  *
 120  * @param addr
 121  *  the vdpa device address
 122  * @param ops
 123  *  the vdpa device operations
 124  * @return
 125  *  vDPA device pointer on success, NULL on failure
 126  */
 127 __rte_experimental
 128 struct rte_vdpa_device *
 129 rte_vdpa_register_device(struct rte_device *rte_dev,
 130                 struct rte_vdpa_dev_ops *ops);
 131
 132 /**
 133  * @warning
 134  * @b EXPERIMENTAL: this API may change without prior notice
 135  *
 136  * Unregister a vdpa device
 137  *
 138  * @param did
 139  *  vDPA device pointer
 140  * @return
 141  *  device id on success, -1 on failure
 142  */
 143 __rte_experimental
 144 int
 145 rte_vdpa_unregister_device(struct rte_vdpa_device *);
 146
 147 /**
 148  * @warning
 149  * @b EXPERIMENTAL: this API may change without prior notice
 150  *
 151  * Find the device id of a vdpa device from its name
 152  *
 153  * @param name
 154  *  the vdpa device name
 155  * @return
 156  *  vDPA device pointer on success, NULL on failure
 157  */
 158 __rte_experimental
 159 struct rte_vdpa_device *
 160 rte_vdpa_find_device_by_name(const char *name);
 161
 162 /**
 163  * @warning
 164  * @b EXPERIMENTAL: this API may change without prior notice
 165  *
 166  * Get the generic device from the vdpa device
 167  *
 168  * @param vdpa_dev
 169  *  the vdpa device pointer
 170  * @return
 171  *  generic device pointer on success, NULL on failure
 172  */
 173 __rte_experimental
 174 struct rte_device *
 175 rte_vdpa_get_rte_device(struct rte_vdpa_device *vdpa_dev);
 176
 177 /**
 178  * @warning
 179  * @b EXPERIMENTAL: this API may change without prior notice
 180  *
 181  * Find the device id of a vdpa device
 182  *
 183  * @param addr
 184  *  the vdpa device address
 185  * @return
 186  *  device id on success, -1 on failure
 187  */
 188 __rte_experimental
 189 int
 190 rte_vdpa_find_device_id(struct rte_vdpa_device *dev);
 191
 192 /**
 193  * @warning
 194  * @b EXPERIMENTAL: this API may change without prior notice
 195  *
 196  * Find a vdpa device based on device id
 197  *
 198  * @param did
 199  *  device id
 200  * @return
 201  *  rte_vdpa_device on success, NULL on failure
 202  */
 203 __rte_experimental
 204 struct rte_vdpa_device *
 205 rte_vdpa_get_device(int did);
 206
 207 /**
 208  * @warning
 209  * @b EXPERIMENTAL: this API may change without prior notice
 210  *
 211  * Get current available vdpa device number
 212  *
 213  * @return
 214  *  available vdpa device number
 215  */
 216 __rte_experimental
 217 int
 218 rte_vdpa_get_device_num(void);
 219
 220 /**
 221  * @warning
 222  * @b EXPERIMENTAL: this API may change without prior notice
 223  *
 224  * Enable/Disable host notifier mapping for a vdpa port.
 225  *
 226  * @param vid
 227  *  vhost device id
 228  * @param enable
 229  *  true for host notifier map, false for host notifier unmap
 230  * @return
 231  *  0 on success, -1 on failure
 232  */
 233 __rte_experimental
 234 int
 235 rte_vhost_host_notifier_ctrl(int vid, bool enable);
 236
 237 /**
 238  * @warning
 239  * @b EXPERIMENTAL: this API may change without prior notice
 240  *
 241  * Synchronize the used ring from mediated ring to guest, log dirty
 242  * page for each writeable buffer, caller should handle the used
 243  * ring logging before device stop.
 244  *
 245  * @param vid
 246  *  vhost device id
 247  * @param qid
 248  *  vhost queue id
 249  * @param vring_m
 250  *  mediated virtio ring pointer
 251  * @return
 252  *  number of synced used entries on success, -1 on failure
 253  */
 254 __rte_experimental
 255 int
 256 rte_vdpa_relay_vring_used(int vid, uint16_t qid, void *vring_m);
 257
 258 /**
 259  * @warning
 260  * @b EXPERIMENTAL: this API may change without prior notice
 261  *
 262  * Retrieve names of statistics of a vDPA device.
 263  *
 264  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 265  * by array index: stats_names[i].name => stats[i].value
 266  *
 267  * And the array index is same with id field of 'struct rte_vdpa_stat':
 268  * stats[i].id == i
 269  *
 270  * @param dev
 271  *  vDPA device pointer
 272  * @param stats_names
 273  *   array of at least size elements to be filled.
 274  *   If set to NULL, the function returns the required number of elements.
 275  * @param size
 276  *   The number of elements in stats_names array.
 277  * @return
 278  *   A negative value on error, otherwise the number of entries filled in the
 279  *   stats name array.
 280  */
 281 __rte_experimental
 282 int
 283 rte_vdpa_get_stats_names(struct rte_vdpa_device *dev,
 284                 struct rte_vdpa_stat_name *stats_names,
 285                 unsigned int size);
 286
 287 /**
 288  * @warning
 289  * @b EXPERIMENTAL: this API may change without prior notice
 290  *
 291  * Retrieve statistics of a vDPA device.
 292  *
 293  * There is an assumption that 'stat_names' and 'stats' arrays are matched
 294  * by array index: stats_names[i].name => stats[i].value
 295  *
 296  * And the array index is same with id field of 'struct rte_vdpa_stat':
 297  * stats[i].id == i
 298  *
 299  * @param dev
 300  *  vDPA device pointer
 301  * @param qid
 302  *  queue id
 303  * @param stats
 304  *   A pointer to a table of structure of type rte_vdpa_stat to be filled with
 305  *   device statistics ids and values.
 306  * @param n
 307  *   The number of elements in stats array.
 308  * @return
 309  *   A negative value on error, otherwise the number of entries filled in the
 310  *   stats table.
 311  */
 312 __rte_experimental
 313 int
 314 rte_vdpa_get_stats(struct rte_vdpa_device *dev, uint16_t qid,
 315                 struct rte_vdpa_stat *stats, unsigned int n);
 316 /**
 317  * @warning
 318  * @b EXPERIMENTAL: this API may change without prior notice
 319  *
 320  * Reset statistics of a vDPA device.
 321  *
 322  * @param dev
 323  *  vDPA device pointer
 324  * @param qid
 325  *  queue id
 326  * @return
 327  *   0 on success, a negative value on error.
 328  */
 329 __rte_experimental
 330 int
 331 rte_vdpa_reset_stats(struct rte_vdpa_device *dev, uint16_t qid);
 332 #endif /* _RTE_VDPA_H_ */