drivers/bus/vmbus/rte_bus_vmbus.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright (c) 2018, Microsoft Corporation.
   3  * All Rights Reserved.
   4  */
   5
   6 #ifndef _VMBUS_H_
   7 #define _VMBUS_H_
   8
   9 /**
  10  * @file
  11  *
  12  * VMBUS Interface
  13  */
  14 #ifdef __cplusplus
  15 extern "C" {
  16 #endif
  17
  18 #include <stdio.h>
  19 #include <stdlib.h>
  20 #include <limits.h>
  21 #include <stdbool.h>
  22 #include <errno.h>
  23 #include <stdint.h>
  24 #include <inttypes.h>
  25
  26 #include <rte_compat.h>
  27 #include <rte_uuid.h>
  28 #include <rte_debug.h>
  29 #include <rte_interrupts.h>
  30 #include <rte_dev.h>
  31 #include <rte_vmbus_reg.h>
  32
  33 /* Forward declarations */
  34 struct rte_vmbus_device;
  35 struct rte_vmbus_driver;
  36 struct rte_vmbus_bus;
  37 struct vmbus_channel;
  38 struct vmbus_mon_page;
  39
  40 RTE_TAILQ_HEAD(rte_vmbus_device_list, rte_vmbus_device);
  41 RTE_TAILQ_HEAD(rte_vmbus_driver_list, rte_vmbus_driver);
  42
  43 /* VMBus iterators */
  44 #define FOREACH_DEVICE_ON_VMBUS(p)      \
  45         RTE_TAILQ_FOREACH(p, &(rte_vmbus_bus.device_list), next)
  46
  47 #define FOREACH_DRIVER_ON_VMBUS(p)      \
  48         RTE_TAILQ_FOREACH(p, &(rte_vmbus_bus.driver_list), next)
  49
  50 /** Maximum number of VMBUS resources. */
  51 enum hv_uio_map {
  52         HV_TXRX_RING_MAP = 0,
  53         HV_INT_PAGE_MAP,
  54         HV_MON_PAGE_MAP,
  55         HV_RECV_BUF_MAP,
  56         HV_SEND_BUF_MAP
  57 };
  58 #define VMBUS_MAX_RESOURCE 5
  59
  60 /**
  61  * A structure describing a VMBUS device.
  62  */
  63 struct rte_vmbus_device {
  64         RTE_TAILQ_ENTRY(rte_vmbus_device) next; /**< Next probed VMBUS device */
  65         const struct rte_vmbus_driver *driver; /**< Associated driver */
  66         struct rte_device device;              /**< Inherit core device */
  67         rte_uuid_t device_id;                  /**< VMBUS device id */
  68         rte_uuid_t class_id;                   /**< VMBUS device type */
  69         uint32_t relid;                        /**< id for primary */
  70         uint8_t monitor_id;                    /**< monitor page */
  71         int uio_num;                           /**< UIO device number */
  72         uint32_t *int_page;                    /**< VMBUS interrupt page */
  73         struct vmbus_channel *primary;         /**< VMBUS primary channel */
  74         struct vmbus_mon_page *monitor_page;   /**< VMBUS monitor page */
  75
  76         struct rte_intr_handle *intr_handle;    /**< Interrupt handle */
  77         struct rte_mem_resource resource[VMBUS_MAX_RESOURCE];
  78 };
  79
  80 /**
  81  * Initialization function for the driver called during VMBUS probing.
  82  */
  83 typedef int (vmbus_probe_t)(struct rte_vmbus_driver *,
  84                             struct rte_vmbus_device *);
  85
  86 /**
  87  * Initialization function for the driver called during hot plugging.
  88  */
  89 typedef int (vmbus_remove_t)(struct rte_vmbus_device *);
  90
  91 /**
  92  * A structure describing a VMBUS driver.
  93  */
  94 struct rte_vmbus_driver {
  95         RTE_TAILQ_ENTRY(rte_vmbus_driver) next; /**< Next in list. */
  96         struct rte_driver driver;
  97         struct rte_vmbus_bus *bus;          /**< VM bus reference. */
  98         vmbus_probe_t *probe;               /**< Device Probe function. */
  99         vmbus_remove_t *remove;             /**< Device Remove function. */
 100
 101         const rte_uuid_t *id_table;         /**< ID table. */
 102 };
 103
 104
 105 /**
 106  * Structure describing the VM bus
 107  */
 108 struct rte_vmbus_bus {
 109         struct rte_bus bus;               /**< Inherit the generic class */
 110         struct rte_vmbus_device_list device_list;  /**< List of devices */
 111         struct rte_vmbus_driver_list driver_list;  /**< List of drivers */
 112 };
 113
 114 /**
 115  * Scan the content of the VMBUS bus, and the devices in the devices
 116  * list
 117  *
 118  * @return
 119  *  0 on success, negative on error
 120  */
 121 int rte_vmbus_scan(void);
 122
 123 /**
 124  * Probe the VMBUS bus
 125  *
 126  * @return
 127  *   - 0 on success.
 128  *   - !0 on error.
 129  */
 130 int rte_vmbus_probe(void);
 131
 132 /**
 133  * Map the VMBUS device resources in user space virtual memory address
 134  *
 135  * @param dev
 136  *   A pointer to a rte_vmbus_device structure describing the device
 137  *   to use
 138  *
 139  * @return
 140  *   0 on success, negative on error and positive if no driver
 141  *   is found for the device.
 142  */
 143 int rte_vmbus_map_device(struct rte_vmbus_device *dev);
 144
 145 /**
 146  * Unmap this device
 147  *
 148  * @param dev
 149  *   A pointer to a rte_vmbus_device structure describing the device
 150  *   to use
 151  */
 152 void rte_vmbus_unmap_device(struct rte_vmbus_device *dev);
 153
 154 /**
 155  * Get connection to primary VMBUS channel
 156  *
 157  * @param device
 158  *   A pointer to a rte_vmbus_device structure describing the device
 159  * @param chan
 160  *   A pointer to a VMBUS channel pointer that will be filled.
 161  * @return
 162  *   - 0 Success; channel opened.
 163  *   - -ENOMEM: Not enough memory available.
 164  *   - -EINVAL: Regions could not be mapped.
 165  */
 166 int rte_vmbus_chan_open(struct rte_vmbus_device *device,
 167                         struct vmbus_channel **chan);
 168
 169 /**
 170  * Free connection to VMBUS channel
 171  *
 172  * @param chan
 173  *    VMBUS channel
 174  */
 175 void rte_vmbus_chan_close(struct vmbus_channel *chan);
 176
 177 /**
 178  * Gets the maximum number of channels supported on device
 179  *
 180  * @param device
 181  *   A pointer to a rte_vmbus_device structure describing the device
 182  * @return
 183  *   Number of channels available.
 184  */
 185 int rte_vmbus_max_channels(const struct rte_vmbus_device *device);
 186
 187 /**
 188  * Get a connection to new secondary vmbus channel
 189  *
 190  * @param primary
 191  *   A pointer to primary VMBUS channel
 192  * @param chan
 193  *   A pointer to a secondary VMBUS channel pointer that will be filled.
 194  * @return
 195  *   - 0 Success; channel opened.
 196  *   - -ENOMEM: Not enough memory available.
 197  *   - -EINVAL: Regions could not be mapped.
 198  */
 199 int rte_vmbus_subchan_open(struct vmbus_channel *primary,
 200                            struct vmbus_channel **new_chan);
 201
 202 /**
 203  * Disable IRQ for device
 204  *
 205  * @param device
 206  *    VMBUS device
 207  */
 208 void rte_vmbus_irq_mask(struct rte_vmbus_device *device);
 209
 210 /**
 211  * Enable IRQ for device
 212  *
 213  * @param device
 214  *    VMBUS device
 215  */
 216 void rte_vmbus_irq_unmask(struct rte_vmbus_device *device);
 217
 218 /**
 219  * Read (and wait) for IRQ
 220  *
 221  * @param device
 222  *    VMBUS device
 223  */
 224 int rte_vmbus_irq_read(struct rte_vmbus_device *device);
 225
 226 /**
 227  * Test if channel is empty
 228  *
 229  * @param channel
 230  *      Pointer to vmbus_channel structure.
 231  * @return
 232  *      Return true if no data present in incoming ring.
 233  */
 234 bool rte_vmbus_chan_rx_empty(const struct vmbus_channel *channel);
 235
 236 /**
 237  * Send the specified buffer on the given channel
 238  *
 239  * @param channel
 240  *      Pointer to vmbus_channel structure.
 241  * @param type
 242  *      Type of packet that is being send e.g. negotiate, time
 243  *      packet etc.
 244  * @param data
 245  *      Pointer to the buffer to send
 246  * @param dlen
 247  *      Number of bytes of data to send
 248  * @param xact
 249  *      Identifier of the request
 250  * @param flags
 251  *      Message type inband, rxbuf, gpa
 252  * @param need_sig
 253  *      Is host signal tx is required (optional)
 254  *
 255  * Sends data in buffer directly to hyper-v via the vmbus
 256  */
 257 int rte_vmbus_chan_send(struct vmbus_channel *channel, uint16_t type,
 258                         void *data, uint32_t dlen,
 259                         uint64_t xact, uint32_t flags, bool *need_sig);
 260
 261 /**
 262  * Explicitly signal host that data is available
 263  *
 264  * @param
 265  *      Pointer to vmbus_channel structure.
 266  *
 267  * Used when batching multiple sends and only signaling host
 268  * after the last send.
 269  */
 270 void rte_vmbus_chan_signal_tx(const struct vmbus_channel *channel);
 271
 272 /* Structure for scatter/gather I/O */
 273 struct iova_list {
 274         rte_iova_t      addr;
 275         uint32_t        len;
 276 };
 277 #define MAX_PAGE_BUFFER_COUNT           32
 278
 279 /**
 280  * Send a scattered buffer on the given channel
 281  *
 282  * @param channel
 283  *      Pointer to vmbus_channel structure.
 284  * @param type
 285  *      Type of packet that is being send e.g. negotiate, time
 286  *      packet etc.
 287  * @param gpa
 288  *      Array of buffers to send
 289  * @param gpacnt
 290  *      Number of elements in iov
 291  * @param data
 292  *      Pointer to the buffer additional data to send
 293  * @param dlen
 294  *       Maximum size of what the buffer will hold
 295  * @param xact
 296  *      Identifier of the request
 297  * @param flags
 298  *      Message type inband, rxbuf, gpa
 299  * @param need_sig
 300  *      Is host signal tx is required (optional)
 301  *
 302  * Sends data in buffer directly to hyper-v via the vmbus
 303  */
 304 int rte_vmbus_chan_send_sglist(struct vmbus_channel *channel,
 305                                struct vmbus_gpa gpa[], uint32_t gpacnt,
 306                                void *data, uint32_t dlen,
 307                                uint64_t xact, bool *need_sig);
 308 /**
 309  * Receive response to request on the given channel
 310  * skips the channel header.
 311  *
 312  * @param channel
 313  *      Pointer to vmbus_channel structure.
 314  * @param data
 315  *      Pointer to the buffer you want to receive the data into.
 316  * @param len
 317  *      Pointer to size of receive buffer (in/out)
 318  * @param
 319  *      Pointer to received transaction_id
 320  * @return
 321  *   On success, returns 0
 322  *   On failure, returns negative errno.
 323  */
 324 int rte_vmbus_chan_recv(struct vmbus_channel *chan,
 325                         void *data, uint32_t *len,
 326                         uint64_t *request_id);
 327
 328 /**
 329  * Receive response to request on the given channel
 330  * includes the channel header.
 331  *
 332  * @param channel
 333  *      Pointer to vmbus_channel structure.
 334  * @param data
 335  *      Pointer to the buffer you want to receive the data into.
 336  * @param len
 337  *      Pointer to size of receive buffer (in/out)
 338  * @return
 339  *   On success, returns number of bytes read.
 340  *   On failure, returns negative errno.
 341  */
 342 int rte_vmbus_chan_recv_raw(struct vmbus_channel *chan,
 343                             void *data, uint32_t *len);
 344
 345 /**
 346  * Notify host of bytes read (after recv_raw)
 347  * Signals host if required.
 348  *
 349  * @param channel
 350  *      Pointer to vmbus_channel structure.
 351  * @param bytes_read
 352  *      Number of bytes read since last signal
 353  */
 354 void rte_vmbus_chan_signal_read(struct vmbus_channel *chan, uint32_t bytes_read);
 355
 356 /**
 357  * Determine sub channel index of the given channel
 358  *
 359  * @param channel
 360  *      Pointer to vmbus_channel structure.
 361  * @return
 362  *   Sub channel index (0 for primary)
 363  */
 364 uint16_t rte_vmbus_sub_channel_index(const struct vmbus_channel *chan);
 365
 366 /**
 367  * Set the host monitor latency hint
 368  *
 369  * @param dev
 370  *    VMBUS device
 371  * @param chan
 372  *      Pointer to vmbus_channel structure.
 373  * @param latency
 374  *      Approximate wait period between hypervisor examinations of
 375  *      the trigger page (in nanoseconds).
 376  */
 377 void rte_vmbus_set_latency(const struct rte_vmbus_device *dev,
 378                            const struct vmbus_channel *chan,
 379                            uint32_t latency);
 380
 381 /**
 382  * Register a VMBUS driver.
 383  *
 384  * @param driver
 385  *   A pointer to a rte_vmbus_driver structure describing the driver
 386  *   to be registered.
 387  */
 388 void rte_vmbus_register(struct rte_vmbus_driver *driver);
 389
 390 /**
 391  * For debug dump contents of ring buffer.
 392  *
 393  * @param channel
 394  *      Pointer to vmbus_channel structure.
 395  */
 396 void rte_vmbus_chan_dump(FILE *f, const struct vmbus_channel *chan);
 397
 398 /**
 399  * Unregister a VMBUS driver.
 400  *
 401  * @param driver
 402  *   A pointer to a rte_vmbus_driver structure describing the driver
 403  *   to be unregistered.
 404  */
 405 void rte_vmbus_unregister(struct rte_vmbus_driver *driver);
 406
 407 /** Helper for VMBUS device registration from driver instance */
 408 #define RTE_PMD_REGISTER_VMBUS(nm, vmbus_drv)           \
 409         RTE_INIT(vmbusinitfn_ ##nm)                     \
 410         {                                               \
 411                 (vmbus_drv).driver.name = RTE_STR(nm);  \
 412                 rte_vmbus_register(&vmbus_drv);         \
 413         }                                               \
 414         RTE_PMD_EXPORT_NAME(nm, __COUNTER__)
 415
 416 #ifdef __cplusplus
 417 }
 418 #endif
 419
 420 #endif /* _VMBUS_H_ */