1 /*-
2 * Copyright (c) 2013 Chris Torek <torek @ torek net>
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright
11 * notice, this list of conditions and the following disclaimer in the
12 * documentation and/or other materials provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 * SUCH DAMAGE.
25 *
26 * $FreeBSD$
27 */
28
29 /**
30 * @file virtio.h
31 *
32 * @brief Virtio Backend Service (VBS) APIs for ACRN Project
33 */
34
35 #ifndef _VIRTIO_H_
36 #define _VIRTIO_H_
37
38 /*
39 * These are derived from several virtio specifications.
40 *
41 * Some useful links:
42 * https://github.com/rustyrussell/virtio-spec
43 * http://people.redhat.com/pbonzini/virtio-spec.pdf
44 */
45
46 /*
47 * A virtual device has zero or more "virtual queues" (virtqueue).
48 * Each virtqueue uses at least two 4096-byte pages, laid out thus:
49 *
50 * +-----------------------------------------------+
51 * | "desc": <N> descriptors, 16 bytes each |
52 * | ----------------------------------------- |
53 * | "avail": 2 uint16; <N> uint16; 1 uint16 |
54 * | ----------------------------------------- |
55 * | pad to 4k boundary |
56 * +-----------------------------------------------+
57 * | "used": 2 x uint16; <N> elems; 1 uint16 |
58 * | ----------------------------------------- |
59 * | pad to 4k boundary |
60 * +-----------------------------------------------+
61 *
62 * The number <N> that appears here is always a power of two and is
63 * limited to no more than 32768 (as it must fit in a 16-bit field).
64 * If <N> is sufficiently large, the above will occupy more than
65 * two pages. In any case, all pages must be physically contiguous
66 * within the guest's physical address space.
67 *
68 * The <N> 16-byte "desc" descriptors consist of a 64-bit guest
69 * physical address <addr>, a 32-bit length <len>, a 16-bit
70 * <flags>, and a 16-bit <next> field (all in guest byte order).
71 *
72 * There are three flags that may be set :
73 * NEXT descriptor is chained, so use its "next" field
74 * WRITE descriptor is for host to write into guest RAM
75 * (else host is to read from guest RAM)
76 * INDIRECT descriptor address field is (guest physical)
77 * address of a linear array of descriptors
78 *
79 * Unless INDIRECT is set, <len> is the number of bytes that may
80 * be read/written from guest physical address <addr>. If
81 * INDIRECT is set, WRITE is ignored and <len> provides the length
82 * of the indirect descriptors (and <len> must be a multiple of
83 * 16). Note that NEXT may still be set in the main descriptor
84 * pointing to the indirect, and should be set in each indirect
85 * descriptor that uses the next descriptor (these should generally
86 * be numbered sequentially). However, INDIRECT must not be set
87 * in the indirect descriptors. Upon reaching an indirect descriptor
88 * without a NEXT bit, control returns to the direct descriptors.
89 *
90 * Except inside an indirect, each <next> value must be in the
91 * range [0 .. N) (i.e., the half-open interval). (Inside an
92 * indirect, each <next> must be in the range [0 .. <len>/16).)
93 *
94 * The "avail" data structures reside in the same pages as the
95 * "desc" structures since both together are used by the device to
96 * pass information to the hypervisor's virtual driver. These
97 * begin with a 16-bit <flags> field and 16-bit index <idx>, then
98 * have <N> 16-bit <ring> values, followed by one final 16-bit
99 * field <used_event>. The <N> <ring> entries are simply indices
100 * indices into the descriptor ring (and thus must meet the same
101 * constraints as each <next> value). However, <idx> is counted
102 * up from 0 (initially) and simply wraps around after 65535; it
103 * is taken mod <N> to find the next available entry.
104 *
105 * The "used" ring occupies a separate page or pages, and contains
106 * values written from the virtual driver back to the guest OS.
107 * This begins with a 16-bit <flags> and 16-bit <idx>, then there
108 * are <N> "vring_used" elements, followed by a 16-bit <avail_event>.
109 * The <N> "vring_used" elements consist of a 32-bit <id> and a
110 * 32-bit <len> (tlen below). The <id> is simply the index of
111 * the head of a descriptor chain the guest made available
112 * earlier, and the <len> is the number of bytes actually written,
113 * e.g., in the case of a network driver that provided a large
114 * receive buffer but received only a small amount of data.
115 *
116 * The two event fields, <used_event> and <avail_event>, in the
117 * avail and used rings (respectively -- note the reversal!), are
118 * always provided, but are used only if the virtual device
119 * negotiates the VIRTIO_RING_F_EVENT_IDX feature during feature
120 * negotiation. Similarly, both rings provide a flag --
121 * ACRN_VRING_AVAIL_F_NO_INTERRUPT and ACRN_VRING_USED_F_NO_NOTIFY -- in
122 * their <flags> field, indicating that the guest does not need an
123 * interrupt, or that the hypervisor driver does not need a
124 * notify, when descriptors are added to the corresponding ring.
125 * (These are provided only for interrupt optimization and need
126 * not be implemented.)
127 */
128
129 #include <linux/virtio_ring.h>
130 #include <linux/virtio_config.h>
131 #include <linux/virtio_pci.h>
132
133 #include "types.h"
134 #include "timer.h"
135 #include "iothread.h"
136
137 /**
138 * @brief virtio API
139 *
140 * @defgroup acrn_virtio virtio API
141 * @{
142 */
143
144 enum {
145 BACKEND_UNKNOWN = 0,
146 BACKEND_VBSU,
147 BACKEND_VBSK,
148 BACKEND_VHOST,
149 BACKEND_MAX
150 };
151
152 /*
153 * The address of any given virtual queue is determined by a single
154 * Page Frame Number register. The guest writes the PFN into the
155 * PCI config space. However, a device that has two or more
156 * virtqueues can have a different PFN, and size, for each queue.
157 * The number of queues is determinable via the PCI config space
158 * VTCFG_R_QSEL register. Writes to QSEL select the queue: 0 means
159 * queue #0, 1 means queue#1, etc. Once a queue is selected, the
160 * remaining PFN and QNUM registers refer to that queue.
161 *
162 * QNUM is a read-only register containing a nonzero power of two
163 * that indicates the (hypervisor's) queue size. Or, if reading it
164 * produces zero, the hypervisor does not have a corresponding
165 * queue. (The number of possible queues depends on the virtual
166 * device. The block device has just one; the network device
167 * provides either two -- 0 = receive, 1 = transmit -- or three,
168 * with 2 = control.)
169 *
170 * PFN is a read/write register giving the physical page address of
171 * the virtqueue in guest memory (the guest must allocate enough space
172 * based on the hypervisor's provided QNUM).
173 *
174 * QNOTIFY is effectively write-only: when the guest writes a queue
175 * number to the register, the hypervisor should scan the specified
176 * virtqueue. (Reading QNOTIFY currently always gets 0).
177 */
178
179 /*
180 * PFN register shift amount
181 */
182 #define VRING_PAGE_BITS 12
183
184 /*
185 * Virtio device types
186 */
187 #define VIRTIO_TYPE_NET 1
188 #define VIRTIO_TYPE_BLOCK 2
189 #define VIRTIO_TYPE_CONSOLE 3
190 #define VIRTIO_TYPE_ENTROPY 4
191 #define VIRTIO_TYPE_BALLOON 5
192 #define VIRTIO_TYPE_IOMEMORY 6
193 #define VIRTIO_TYPE_RPMSG 7
194 #define VIRTIO_TYPE_SCSI 8
195 #define VIRTIO_TYPE_9P 9
196 #define VIRTIO_TYPE_INPUT 18
197
198 /*
199 * ACRN virtio device types
200 * Experimental IDs start at 0xFFFF and work down
201 */
202 #define VIRTIO_TYPE_RPMB 0xFFFF
203 #define VIRTIO_TYPE_HECI 0xFFFE
204 #define VIRTIO_TYPE_AUDIO 0xFFFD
205 #define VIRTIO_TYPE_IPU 0xFFFC
206 #define VIRTIO_TYPE_TSN 0xFFFB
207 #define VIRTIO_TYPE_HYPERDMABUF 0xFFFA
208 #define VIRTIO_TYPE_HDCP 0xFFF9
209 #define VIRTIO_TYPE_COREU 0xFFF8
210 #define VIRTIO_TYPE_GPIO 0xFFF7
211 #define VIRTIO_TYPE_I2C 0xFFF6
212 #define VIRTIO_TYPE_GPU 0x1100
213
214 /*
215 * PCI vendor/device IDs
216 */
217 #define INTEL_VENDOR_ID 0x8086
218 #define ORACLE_VENDOR_ID 0x108E
219 #define VIRTIO_VENDOR 0x1AF4
220 #define VIRTIO_DEV_NET 0x1000
221 #define VIRTIO_DEV_BLOCK 0x1001
222 #define VIRTIO_DEV_CONSOLE 0x1003
223 #define VIRTIO_DEV_RANDOM 0x1005
224 #define VIRTIO_DEV_GPU 0x1050
225 #define VIRTIO_DEV_VSOCK 0x1053
226 #define VIRTIO_DEV_I2C 0x1062
227
228 /*
229 * ACRN virtio device IDs
230 */
231 #define VIRTIO_DEV_RPMB 0x8601
232 #define VIRTIO_DEV_HECI 0x8602
233 #define VIRTIO_DEV_AUDIO 0x8603
234 #define VIRTIO_DEV_IPU 0x8604
235 #define VIRTIO_DEV_TSN 0x8605
236 #define VIRTIO_DEV_HYPERDMABUF 0x8606
237 #define VIRTIO_DEV_HDCP 0x8607
238 #define VIRTIO_DEV_COREU 0x8608
239 #define VIRTIO_DEV_GPIO 0x8609
240
241 /*
242 * VIRTIO_CONFIG_S_NEEDS_RESET is not defined
243 * in some environments's virtio_config.h
244 */
245 #ifndef VIRTIO_CONFIG_S_NEEDS_RESET
246 #define VIRTIO_CONFIG_S_NEEDS_RESET 0x40
247 #endif
248
249 /*
250 * Bits in VIRTIO_PCI_ISR. These apply only if not using MSI-X.
251 *
252 * (We don't [yet?] ever use CONF_CHANGED.)
253 */
254 #define VIRTIO_PCI_ISR_QUEUES 0x01
255 /* re-scan queues */
256
257 struct vmctx;
258 struct pci_vdev;
259 struct virtio_vq_info;
260
261 /*
262 * A virtual device, with some number (possibly 0) of virtual
263 * queues and some size (possibly 0) of configuration-space
264 * registers private to the device. The virtio_base should come
265 * at the front of each "derived class", so that a pointer to the
266 * virtio_base is also a pointer to the more specific, derived-
267 * from-virtio driver's virtio_base struct.
268 *
269 * Note: inside each hypervisor virtio driver, changes to these
270 * data structures must be locked against other threads, if any.
271 * Except for PCI config space register read/write, we assume each
272 * driver does the required locking, but we need a pointer to the
273 * lock (if there is one) for PCI config space read/write ops.
274 *
275 * When the guest reads or writes the device's config space, the
276 * generic layer checks for operations on the special registers
277 * described above. If the offset of the register(s) being read
278 * or written is past the CFG area (CFG0 or CFG1), the request is
279 * passed on to the virtual device, after subtracting off the
280 * generic-layer size. (So, drivers can just use the offset as
281 * an offset into "struct config", for instance.)
282 *
283 * (The virtio layer also makes sure that the read or write is to/
284 * from a "good" config offset, hence cfgsize, and on BAR #0.
285 * However, the driver must verify the read or write size and offset
286 * and that no one is writing a readonly register.)
287 *
288 * The BROKED flag ("this thing done gone and broked") is for future
289 * use.
290 */
291 #define VIRTIO_USE_MSIX 0x01
292 #define VIRTIO_EVENT_IDX 0x02 /* use the event-index values */
293 #define VIRTIO_BROKED 0x08 /* ??? */
294
295 /*
296 * virtio pci device bar layout
297 * 0 : legacy PIO bar
298 * 1 : MSIX bar
299 * 2 : modern PIO bar, used as notify
300 * 4+5 : modern 64-bit MMIO bar
301 *
302 * pci bar layout for legacy/modern/transitional devices
303 * legacy : (0) + (1)
304 * modern (no pio notify) : (1) + (4+5)
305 * modern (with pio notify) : (1) + (2) + (4+5)
306 * transitional (no pio notify) : (0) + (1) + (4+5)
307 * transitional (with pio notify) : (0) + (1) + (2) + (4+5)
308 */
309 #define VIRTIO_LEGACY_PIO_BAR_IDX 0
310 #define VIRTIO_MODERN_PIO_BAR_IDX 2
311 #define VIRTIO_MODERN_MMIO_BAR_IDX 4
312
313 /*
314 * region layout in modern mmio bar
315 * one 4KB region for one capability
316 */
317 #define VIRTIO_CAP_COMMON_OFFSET 0x0000
318 #define VIRTIO_CAP_COMMON_SIZE 0x1000
319 #define VIRTIO_CAP_ISR_OFFSET 0x1000
320 #define VIRTIO_CAP_ISR_SIZE 0x1000
321 #define VIRTIO_CAP_DEVICE_OFFSET 0x2000
322 #define VIRTIO_CAP_DEVICE_SIZE 0x1000
323 #define VIRTIO_CAP_NOTIFY_OFFSET 0x3000
324 #define VIRTIO_CAP_NOTIFY_SIZE 0x1000
325
326 #define VIRTIO_MODERN_MEM_BAR_SIZE (VIRTIO_CAP_NOTIFY_OFFSET + \
327 VIRTIO_CAP_NOTIFY_SIZE)
328
329 /* 4-byte notify register for one virtqueue */
330 #define VIRTIO_MODERN_NOTIFY_OFF_MULT 4
331
332 /* Common configuration */
333 #define VIRTIO_PCI_CAP_COMMON_CFG 1
334 /* Notifications */
335 #define VIRTIO_PCI_CAP_NOTIFY_CFG 2
336 /* ISR access */
337 #define VIRTIO_PCI_CAP_ISR_CFG 3
338 /* Device specific configuration */
339 #define VIRTIO_PCI_CAP_DEVICE_CFG 4
340 /* PCI configuration access */
341 #define VIRTIO_PCI_CAP_PCI_CFG 5
342
343 /**
344 * @brief Base component to any virtio device
345 */
346 struct virtio_base {
347 struct virtio_ops *vops; /**< virtio operations */
348 int flags; /**< VIRTIO_* flags from above */
349 bool iothread;
350 pthread_mutex_t *mtx; /**< POSIX mutex, if any */
351 struct pci_vdev *dev; /**< PCI device instance */
352 uint64_t negotiated_caps; /**< negotiated capabilities */
353 uint64_t device_caps; /**< device capabilities */
354 struct virtio_vq_info *queues; /**< one per nvq */
355 int curq; /**< current queue */
356 uint8_t status; /**< value from last status write */
357 uint8_t isr; /**< ISR flags, if not MSI-X */
358 uint16_t msix_cfg_idx; /**< MSI-X vector for config event */
359 uint32_t legacy_pio_bar_idx; /**< index of legacy pio bar */
360 uint32_t modern_pio_bar_idx; /**< index of modern pio bar */
361 uint32_t modern_mmio_bar_idx; /**< index of modern mmio bar */
362 uint8_t config_generation; /**< configuration generation */
363 uint32_t device_feature_select; /**< current selected device feature */
364 uint32_t driver_feature_select; /**< current selected guest feature */
365 int cfg_coff; /**< PCI cfg access capability offset */
366 int backend_type; /**< VBSU, VBSK or VHOST */
367 struct acrn_timer polling_timer; /**< timer for polling mode */
368 int polling_in_progress; /**< The polling status */
369 };
370
371 #define VIRTIO_BASE_LOCK(vb) \
372 do { \
373 if (vb->mtx) \
374 pthread_mutex_lock(vb->mtx); \
375 } while (0)
376
377 #define VIRTIO_BASE_UNLOCK(vb) \
378 do { \
379 if (vb->mtx) \
380 pthread_mutex_unlock(vb->mtx); \
381 } while (0)
382
383 /**
384 * @brief Virtio specific operation functions for this type of virtio device
385 */
386 struct virtio_ops {
387 const char *name; /**< name of driver (for diagnostics) */
388 int nvq; /**< number of virtual queues */
389 size_t cfgsize; /**< size of dev-specific config regs */
390 void (*reset)(void *);
391 /**< called on virtual device reset */
392 void (*qnotify)(void *, struct virtio_vq_info *);
393 /**< called on QNOTIFY if no VQ notify */
394 int (*cfgread)(void *, int, int, uint32_t *);
395 /**< to read config regs */
396 int (*cfgwrite)(void *, int, int, uint32_t);
397 /**< to write config regs */
398 void (*apply_features)(void *, uint64_t);
399 /**< to apply negotiated features */
400 void (*set_status)(void *, uint64_t);
401 /**< called to set device status */
402 };
403
404 #define VQ_ALLOC 0x01 /* set once we have a pfn */
405 #define VQ_BROKED 0x02 /* ??? */
406 /**
407 * @brief Virtqueue data structure
408 *
409 * Data structure allocated (statically) per virtual queue.
410 *
411 * Drivers may change qsize after a reset. When the guest OS
412 * requests a device reset, the hypervisor first calls
413 * vb->vo->reset(); then the data structure below is
414 * reinitialized (for each virtqueue: vb->vo->nvq).
415 *
416 * The remaining fields should only be fussed-with by the generic
417 * code.
418 *
419 * Note: the addresses of desc, avail, and vq_used are all
420 * computable from each other, but it's a lot simpler if we just
421 * keep a pointer to each one. The event indices are similarly
422 * (but more easily) computable, and this time we'll compute them:
423 * they're just XX_ring[N].
424 */
425 struct virtio_iothread {
426 struct virtio_base *base;
427 int idx;
428 int kick_fd;
429 bool ioevent_started;
430 struct iothread_ctx *ioctx;
431 struct iothread_mevent iomvt;
432 void (*iothread_run)(void *, struct virtio_vq_info *);
433 };
434
435 struct virtio_vq_info {
436 uint16_t qsize; /**< size of this queue (a power of 2) */
437 void (*notify)(void *, struct virtio_vq_info *);
438 /**< called instead of notify, if not NULL */
439
440 struct virtio_base *base;
441 /**< backpointer to virtio_base */
442 uint16_t num; /**< the num'th queue in the virtio_base */
443 pthread_mutex_t mtx; /**< per queue mutex */
444
445 uint16_t flags; /**< flags (see above) */
446 uint16_t last_avail; /**< a recent value of avail->idx */
447 uint16_t save_used; /**< saved used->idx; see vq_endchains */
448 uint16_t msix_idx; /**< MSI-X index, or VIRTIO_MSI_NO_VECTOR */
449
450 uint32_t pfn; /**< PFN of virt queue (not shifted!) */
451 struct virtio_iothread viothrd;
452
453 volatile struct vring_desc *desc;
454 /**< descriptor array */
455 volatile struct vring_avail *avail;
456 /**< the "avail" ring */
457 volatile struct vring_used *used;
458 /**< the "used" ring */
459
460 uint32_t gpa_desc[2]; /**< gpa of descriptors */
461 uint32_t gpa_avail[2]; /**< gpa of avail_ring */
462 uint32_t gpa_used[2]; /**< gpa of used_ring */
463 bool enabled; /**< whether the virtqueue is enabled */
464 };
465
466 /* as noted above, these are sort of backwards, name-wise */
467 #define VQ_AVAIL_EVENT_IDX(vq) \
468 (*(volatile uint16_t *)&(vq)->used->ring[(vq)->qsize])
469 #define VQ_USED_EVENT_IDX(vq) \
470 ((vq)->avail->ring[(vq)->qsize])
471
472 /**
473 * @brief Is this ring ready for I/O?
474 *
475 * @param vq Pointer to struct virtio_vq_info.
476 *
477 * @return false on not ready and true on ready.
478 */
479 static inline bool
vq_ring_ready(struct virtio_vq_info * vq)480 vq_ring_ready(struct virtio_vq_info *vq)
481 {
482 return ((vq->flags & VQ_ALLOC) == VQ_ALLOC);
483 }
484
485 /**
486 * @brief Are there "available" descriptors?
487 *
488 * This does not count how many, just returns true if there is any.
489 *
490 * @param vq Pointer to struct virtio_vq_info.
491 *
492 * @return false on not available and true on available.
493 */
494 static inline bool
vq_has_descs(struct virtio_vq_info * vq)495 vq_has_descs(struct virtio_vq_info *vq)
496 {
497 bool ret = false;
498 if (vq_ring_ready(vq) && vq->last_avail != vq->avail->idx) {
499 if ((uint16_t)((u_int)vq->avail->idx - vq->last_avail) > vq->qsize)
500 pr_err ("%s: no valid descriptor\n", vq->base->vops->name);
501 else
502 ret = true;
503 }
504 return ret;
505
506 }
507
508 /**
509 * @brief Deliver an interrupt to guest on the given virtqueue.
510 *
511 * The interrupt could be MSI-X or a generic MSI interrupt.
512 *
513 * @param vb Pointer to struct virtio_base.
514 * @param vq Pointer to struct virtio_vq_info.
515 */
516 static inline void
vq_interrupt(struct virtio_base * vb,struct virtio_vq_info * vq)517 vq_interrupt(struct virtio_base *vb, struct virtio_vq_info *vq)
518 {
519 if (pci_msix_enabled(vb->dev))
520 pci_generate_msix(vb->dev, vq->msix_idx);
521 else {
522 VIRTIO_BASE_LOCK(vb);
523 vb->isr |= VIRTIO_PCI_ISR_QUEUES;
524 pci_generate_msi(vb->dev, 0);
525 pci_lintr_assert(vb->dev);
526 VIRTIO_BASE_UNLOCK(vb);
527 }
528 }
529
530 /**
531 * @brief Deliver an config changed interrupt to guest.
532 *
533 * MSI-X or a generic MSI interrupt with config changed event.
534 *
535 * @param vb Pointer to struct virtio_base.
536 */
537 static inline void
virtio_config_changed(struct virtio_base * vb)538 virtio_config_changed(struct virtio_base *vb)
539 {
540 if (!(vb->status & VIRTIO_CONFIG_S_DRIVER_OK))
541 return;
542
543 vb->config_generation++;
544
545 if (pci_msix_enabled(vb->dev))
546 pci_generate_msix(vb->dev, vb->msix_cfg_idx);
547 else {
548 VIRTIO_BASE_LOCK(vb);
549 vb->isr |= VIRTIO_PCI_ISR_CONFIG;
550 pci_generate_msi(vb->dev, 0);
551 pci_lintr_assert(vb->dev);
552 VIRTIO_BASE_UNLOCK(vb);
553 }
554 }
555
556 struct iovec;
557
558 /**
559 * @brief Link a virtio_base to its constants, the virtio device,
560 * and the PCI emulation.
561 *
562 * @param base Pointer to struct virtio_base.
563 * @param vops Pointer to struct virtio_ops.
564 * @param pci_virtio_dev Pointer to instance of certain virtio device.
565 * @param dev Pointer to struct pci_vdev which emulates a PCI device.
566 * @param queues Pointer to struct virtio_vq_info, normally an array.
567 * @param backend_type can be VBSU, VBSK or VHOST
568 */
569 void virtio_linkup(struct virtio_base *base, struct virtio_ops *vops,
570 void *pci_virtio_dev, struct pci_vdev *dev,
571 struct virtio_vq_info *queues,
572 int backend_type);
573
574 /**
575 * @brief Get the virtio poll parameters
576 *
577 * @param optarg Pointer to parameters string.
578 *
579 * @return fail -1 success 0
580 */
581 int acrn_parse_virtio_poll_interval(const char *optarg);
582
583 /**
584 * @brief Initialize MSI-X vector capabilities if we're to use MSI-X,
585 * or MSI capabilities if not.
586 *
587 * Wrapper function for virtio_intr_init() for cases we directly use
588 * BAR 1 for MSI-X capabilities.
589 *
590 * @param base Pointer to struct virtio_base.
591 * @param use_msix If using MSI-X.
592 *
593 * @return 0 on success and non-zero on fail.
594 */
595 int virtio_interrupt_init(struct virtio_base *base, int use_msix);
596
597 /**
598 * @brief Initialize MSI-X vector capabilities if we're to use MSI-X,
599 * or MSI capabilities if not.
600 *
601 * We assume we want one MSI-X vector per queue, here, plus one
602 * for the config vec.
603 *
604 * @param base Pointer to struct virtio_base.
605 * @param barnum Which BAR[0..5] to use.
606 * @param use_msix If using MSI-X.
607 *
608 * @return 0 on success and non-zero on fail.
609 */
610 int virtio_intr_init(struct virtio_base *base, int barnum, int use_msix);
611
612 /**
613 * @brief Reset device (device-wide).
614 *
615 * This erases all queues, i.e., all the queues become invalid.
616 * But we don't wipe out the internal pointers, by just clearing
617 * the VQ_ALLOC flag.
618 *
619 * It resets negotiated features to "none".
620 * If MSI-X is enabled, this also resets all the vectors to NO_VECTOR.
621 *
622 * @param base Pointer to struct virtio_base.
623 */
624 void virtio_reset_dev(struct virtio_base *base);
625
626 /**
627 * @brief Set I/O BAR (usually 0) to map PCI config registers.
628 *
629 * @param base Pointer to struct virtio_base.
630 * @param barnum Which BAR[0..5] to use.
631 */
632 void virtio_set_io_bar(struct virtio_base *base, int barnum);
633
634 /**
635 * @brief Walk through the chain of descriptors involved in a request
636 * and put them into a given iov[] array.
637 *
638 * @param vq Pointer to struct virtio_vq_info.
639 * @param pidx Pointer to available ring position.
640 * @param iov Pointer to iov[] array prepared by caller.
641 * @param n_iov Size of iov[] array.
642 * @param flags Pointer to a uint16_t array which will contain flag of
643 * each descriptor.
644 *
645 * @return number of descriptors.
646 */
647 int vq_getchain(struct virtio_vq_info *vq, uint16_t *pidx,
648 struct iovec *iov, int n_iov, uint16_t *flags);
649
650 /**
651 * @brief Return the currently-first request chain back to the
652 * available ring.
653 *
654 * @param vq Pointer to struct virtio_vq_info.
655 */
656 void vq_retchain(struct virtio_vq_info *vq);
657
658 /**
659 * @brief Return specified request chain to the guest,
660 * setting its I/O length to the provided value.
661 *
662 * @param vq Pointer to struct virtio_vq_info.
663 * @param idx Pointer to available ring position, returned by vq_getchain().
664 * @param iolen Number of data bytes to be returned to frontend.
665 */
666 void vq_relchain(struct virtio_vq_info *vq, uint16_t idx, uint32_t iolen);
667
668 /**
669 * @brief Driver has finished processing "available" chains and calling
670 * vq_relchain on each one.
671 *
672 * If driver used all the available chains, used_all_avail need to be set to 1.
673 *
674 * @param vq Pointer to struct virtio_vq_info.
675 * @param used_all_avail Flag indicating if driver used all available chains.
676 */
677 void vq_endchains(struct virtio_vq_info *vq, int used_all_avail);
678
679 /**
680 * @brief Helper function for clearing used ring flags.
681 *
682 * Driver should always use this helper function to clear used ring flags.
683 * For virtio poll mode, in order to avoid trap, we should never really
684 * clear used ring flags.
685 *
686 * @param base Pointer to struct virtio_base.
687 * @param vq Pointer to struct virtio_vq_info.
688 */
689 void vq_clear_used_ring_flags(struct virtio_base *base, struct virtio_vq_info *vq);
690
691 /**
692 * @brief Handle PCI configuration space reads.
693 *
694 * Handle virtio standard register reads, and dispatch other reads to
695 * actual virtio device driver.
696 *
697 * @param ctx Pointer to struct vmctx representing VM context.
698 * @param vcpu VCPU ID.
699 * @param dev Pointer to struct pci_vdev which emulates a PCI device.
700 * @param baridx Which BAR[0..5] to use.
701 * @param offset Register offset in bytes within a BAR region.
702 * @param size Access range in bytes.
703 *
704 * @return register value.
705 */
706 uint64_t virtio_pci_read(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
707 int baridx, uint64_t offset, int size);
708
709 /**
710 * @brief Handle PCI configuration space writes.
711 *
712 * Handle virtio standard register writes, and dispatch other writes to
713 * actual virtio device driver.
714 *
715 * @param ctx Pointer to struct vmctx representing VM context.
716 * @param vcpu VCPU ID.
717 * @param dev Pointer to struct pci_vdev which emulates a PCI device.
718 * @param baridx Which BAR[0..5] to use.
719 * @param offset Register offset in bytes within a BAR region.
720 * @param size Access range in bytes.
721 * @param value Data value to be written into register.
722 */
723 void virtio_pci_write(struct vmctx *ctx, int vcpu, struct pci_vdev *dev,
724 int baridx, uint64_t offset, int size, uint64_t value);
725
726 /**
727 * @brief Set modern BAR (usually 4) to map PCI config registers.
728 *
729 * Set modern MMIO BAR (usually 4) to map virtio 1.0 capabilities and optional
730 * set modern PIO BAR (usually 2) to map notify capability. This interface is
731 * only valid for modern virtio.
732 *
733 * @param base Pointer to struct virtio_base.
734 * @param use_notify_pio Whether use pio for notify capability.
735 *
736 * @return 0 on success and non-zero on fail.
737 */
738 int virtio_set_modern_bar(struct virtio_base *base, bool use_notify_pio);
739
740 /**
741 * @}
742 */
743 /* FIXME: Fix the assumption about the zero offset in virtio_pci_cap.
744 * Should not export the internal virtio APIs.
745 */
746 void virtio_common_cfg_write(struct pci_vdev *dev,
747 uint64_t offset, int size, uint64_t value);
748 void virtio_device_cfg_write(struct pci_vdev *dev,
749 uint64_t offset, int size, uint64_t value);
750 void virtio_notify_cfg_write(struct pci_vdev *dev,
751 uint64_t offset, int size, uint64_t value);
752 uint32_t virtio_common_cfg_read(
753 struct pci_vdev *dev, uint64_t offset, int size);
754 uint32_t virtio_isr_cfg_read(
755 struct pci_vdev *dev, uint64_t offset, int size);
756 uint32_t virtio_device_cfg_read(
757 struct pci_vdev *dev, uint64_t offset, int size);
758 int virtio_set_modern_pio_bar(
759 struct virtio_base *base, int barnum);
760
761 int virtio_register_ioeventfd(struct virtio_base *base, int idx, bool is_register, int fd);
762 #endif /* _VIRTIO_H_ */
763