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