Rusty Russell | c3c53a0 | 2011-08-15 10:15:10 +0930 | [diff] [blame^] | 1 | [Generated file: see http://ozlabs.org/~rusty/virtio-spec/] |
| 2 | Virtio PCI Card Specification |
| 3 | v0.9.1 DRAFT |
| 4 | - |
| 5 | |
| 6 | Rusty Russell <rusty@rustcorp.com.au>IBM Corporation (Editor) |
| 7 | |
| 8 | 2011 August 1. |
| 9 | |
| 10 | Purpose and Description |
| 11 | |
| 12 | This document describes the specifications of the “virtio” family |
| 13 | of PCI[LaTeX Command: nomenclature] devices. These are devices |
| 14 | are found in virtual environments[LaTeX Command: nomenclature], |
| 15 | yet by design they are not all that different from physical PCI |
| 16 | devices, and this document treats them as such. This allows the |
| 17 | guest to use standard PCI drivers and discovery mechanisms. |
| 18 | |
| 19 | The purpose of virtio and this specification is that virtual |
| 20 | environments and guests should have a straightforward, efficient, |
| 21 | standard and extensible mechanism for virtual devices, rather |
| 22 | than boutique per-environment or per-OS mechanisms. |
| 23 | |
| 24 | Straightforward: Virtio PCI devices use normal PCI mechanisms |
| 25 | of interrupts and DMA which should be familiar to any device |
| 26 | driver author. There is no exotic page-flipping or COW |
| 27 | mechanism: it's just a PCI device.[footnote: |
| 28 | This lack of page-sharing implies that the implementation of the |
| 29 | device (e.g. the hypervisor or host) needs full access to the |
| 30 | guest memory. Communication with untrusted parties (i.e. |
| 31 | inter-guest communication) requires copying. |
| 32 | ] |
| 33 | |
| 34 | Efficient: Virtio PCI devices consist of rings of descriptors |
| 35 | for input and output, which are neatly separated to avoid cache |
| 36 | effects from both guest and device writing to the same cache |
| 37 | lines. |
| 38 | |
| 39 | Standard: Virtio PCI makes no assumptions about the environment |
| 40 | in which it operates, beyond supporting PCI. In fact the virtio |
| 41 | devices specified in the appendices do not require PCI at all: |
| 42 | they have been implemented on non-PCI buses.[footnote: |
| 43 | The Linux implementation further separates the PCI virtio code |
| 44 | from the specific virtio drivers: these drivers are shared with |
| 45 | the non-PCI implementations (currently lguest and S/390). |
| 46 | ] |
| 47 | |
| 48 | Extensible: Virtio PCI devices contain feature bits which are |
| 49 | acknowledged by the guest operating system during device setup. |
| 50 | This allows forwards and backwards compatibility: the device |
| 51 | offers all the features it knows about, and the driver |
| 52 | acknowledges those it understands and wishes to use. |
| 53 | |
| 54 | Virtqueues |
| 55 | |
| 56 | The mechanism for bulk data transport on virtio PCI devices is |
| 57 | pretentiously called a virtqueue. Each device can have zero or |
| 58 | more virtqueues: for example, the network device has one for |
| 59 | transmit and one for receive. |
| 60 | |
| 61 | Each virtqueue occupies two or more physically-contiguous pages |
| 62 | (defined, for the purposes of this specification, as 4096 bytes), |
| 63 | and consists of three parts: |
| 64 | |
| 65 | |
| 66 | +-------------------+-----------------------------------+-----------+ |
| 67 | | Descriptor Table | Available Ring (padding) | Used Ring | |
| 68 | +-------------------+-----------------------------------+-----------+ |
| 69 | |
| 70 | |
| 71 | When the driver wants to send buffers to the device, it puts them |
| 72 | in one or more slots in the descriptor table, and writes the |
| 73 | descriptor indices into the available ring. It then notifies the |
| 74 | device. When the device has finished with the buffers, it writes |
| 75 | the descriptors into the used ring, and sends an interrupt. |
| 76 | |
| 77 | Specification |
| 78 | |
| 79 | PCI Discovery |
| 80 | |
| 81 | Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 |
| 82 | through 0x103F inclusive is a virtio device[footnote: |
| 83 | The actual value within this range is ignored |
| 84 | ]. The device must also have a Revision ID of 0 to match this |
| 85 | specification. |
| 86 | |
| 87 | The Subsystem Device ID indicates which virtio device is |
| 88 | supported by the device. The Subsystem Vendor ID should reflect |
| 89 | the PCI Vendor ID of the environment (it's currently only used |
| 90 | for informational purposes by the guest). |
| 91 | |
| 92 | |
| 93 | +----------------------+--------------------+---------------+ |
| 94 | | Subsystem Device ID | Virtio Device | Specification | |
| 95 | +----------------------+--------------------+---------------+ |
| 96 | +----------------------+--------------------+---------------+ |
| 97 | | 1 | network card | Appendix C | |
| 98 | +----------------------+--------------------+---------------+ |
| 99 | | 2 | block device | Appendix D | |
| 100 | +----------------------+--------------------+---------------+ |
| 101 | | 3 | console | Appendix E | |
| 102 | +----------------------+--------------------+---------------+ |
| 103 | | 4 | entropy source | Appendix F | |
| 104 | +----------------------+--------------------+---------------+ |
| 105 | | 5 | memory ballooning | Appendix G | |
| 106 | +----------------------+--------------------+---------------+ |
| 107 | | 6 | ioMemory | - | |
| 108 | +----------------------+--------------------+---------------+ |
| 109 | | 9 | 9P transport | - | |
| 110 | +----------------------+--------------------+---------------+ |
| 111 | |
| 112 | |
| 113 | Device Configuration |
| 114 | |
| 115 | To configure the device, we use the first I/O region of the PCI |
| 116 | device. This contains a virtio header followed by a |
| 117 | device-specific region. |
| 118 | |
| 119 | There may be different widths of accesses to the I/O region; the “ |
| 120 | natural” access method for each field in the virtio header must |
| 121 | be used (i.e. 32-bit accesses for 32-bit fields, etc), but the |
| 122 | device-specific region can be accessed using any width accesses, |
| 123 | and should obtain the same results. |
| 124 | |
| 125 | Note that this is possible because while the virtio header is PCI |
| 126 | (i.e. little) endian, the device-specific region is encoded in |
| 127 | the native endian of the guest (where such distinction is |
| 128 | applicable). |
| 129 | |
| 130 | Device Initialization Sequence |
| 131 | |
| 132 | We start with an overview of device initialization, then expand |
| 133 | on the details of the device and how each step is preformed. |
| 134 | |
| 135 | Reset the device. This is not required on initial start up. |
| 136 | |
| 137 | The ACKNOWLEDGE status bit is set: we have noticed the device. |
| 138 | |
| 139 | The DRIVER status bit is set: we know how to drive the device. |
| 140 | |
| 141 | Device-specific setup, including reading the Device Feature |
| 142 | Bits, discovery of virtqueues for the device, optional MSI-X |
| 143 | setup, and reading and possibly writing the virtio |
| 144 | configuration space. |
| 145 | |
| 146 | The subset of Device Feature Bits understood by the driver is |
| 147 | written to the device. |
| 148 | |
| 149 | The DRIVER_OK status bit is set. |
| 150 | |
| 151 | The device can now be used (ie. buffers added to the |
| 152 | virtqueues)[footnote: |
| 153 | Historically, drivers have used the device before steps 5 and 6. |
| 154 | This is only allowed if the driver does not use any features |
| 155 | which would alter this early use of the device. |
| 156 | ] |
| 157 | |
| 158 | If any of these steps go irrecoverably wrong, the guest should |
| 159 | set the FAILED status bit to indicate that it has given up on the |
| 160 | device (it can reset the device later to restart if desired). |
| 161 | |
| 162 | We now cover the fields required for general setup in detail. |
| 163 | |
| 164 | Virtio Header |
| 165 | |
| 166 | The virtio header looks as follows: |
| 167 | |
| 168 | |
| 169 | +------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+ |
| 170 | | Bits || 32 | 32 | 32 | 16 | 16 | 16 | 8 | 8 | |
| 171 | +------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+ |
| 172 | | Read/Write || R | R+W | R+W | R | R+W | R+W | R+W | R | |
| 173 | +------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+ |
| 174 | | Purpose || Device | Guest | Queue | Queue | Queue | Queue | Device | ISR | |
| 175 | | || Features bits 0:31 | Features bits 0:31 | Address | Size | Select | Notify | Status | Status | |
| 176 | +------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+ |
| 177 | |
| 178 | |
| 179 | If MSI-X is enabled for the device, two additional fields |
| 180 | immediately follow this header: |
| 181 | |
| 182 | |
| 183 | +------------++----------------+--------+ |
| 184 | | Bits || 16 | 16 | |
| 185 | +----------------+--------+ |
| 186 | +------------++----------------+--------+ |
| 187 | | Read/Write || R+W | R+W | |
| 188 | +------------++----------------+--------+ |
| 189 | | Purpose || Configuration | Queue | |
| 190 | | (MSI-X) || Vector | Vector | |
| 191 | +------------++----------------+--------+ |
| 192 | |
| 193 | |
| 194 | Finally, if feature bits (VIRTIO_F_FEATURES_HI) this is |
| 195 | immediately followed by two additional fields: |
| 196 | |
| 197 | |
| 198 | +------------++----------------------+---------------------- |
| 199 | | Bits || 32 | 32 |
| 200 | +------------++----------------------+---------------------- |
| 201 | | Read/Write || R | R+W |
| 202 | +------------++----------------------+---------------------- |
| 203 | | Purpose || Device | Guest |
| 204 | | || Features bits 32:63 | Features bits 32:63 |
| 205 | +------------++----------------------+---------------------- |
| 206 | |
| 207 | |
| 208 | Immediately following these general headers, there may be |
| 209 | device-specific headers: |
| 210 | |
| 211 | |
| 212 | +------------++--------------------+ |
| 213 | | Bits || Device Specific | |
| 214 | +--------------------+ |
| 215 | +------------++--------------------+ |
| 216 | | Read/Write || Device Specific | |
| 217 | +------------++--------------------+ |
| 218 | | Purpose || Device Specific... | |
| 219 | | || | |
| 220 | +------------++--------------------+ |
| 221 | |
| 222 | |
| 223 | Device Status |
| 224 | |
| 225 | The Device Status field is updated by the guest to indicate its |
| 226 | progress. This provides a simple low-level diagnostic: it's most |
| 227 | useful to imagine them hooked up to traffic lights on the console |
| 228 | indicating the status of each device. |
| 229 | |
| 230 | The device can be reset by writing a 0 to this field, otherwise |
| 231 | at least one bit should be set: |
| 232 | |
| 233 | ACKNOWLEDGE (1) Indicates that the guest OS has found the |
| 234 | device and recognized it as a valid virtio device. |
| 235 | |
| 236 | DRIVER (2) Indicates that the guest OS knows how to drive the |
| 237 | device. Under Linux, drivers can be loadable modules so there |
| 238 | may be a significant (or infinite) delay before setting this |
| 239 | bit. |
| 240 | |
| 241 | DRIVER_OK (3) Indicates that the driver is set up and ready to |
| 242 | drive the device. |
| 243 | |
| 244 | FAILED (8) Indicates that something went wrong in the guest, |
| 245 | and it has given up on the device. This could be an internal |
| 246 | error, or the driver didn't like the device for some reason, or |
| 247 | even a fatal error during device operation. The device must be |
| 248 | reset before attempting to re-initialize. |
| 249 | |
| 250 | Feature Bits |
| 251 | |
| 252 | The least significant 31 bits of the first configuration field |
| 253 | indicates the features that the device supports (the high bit is |
| 254 | reserved, and will be used to indicate the presence of future |
| 255 | feature bits elsewhere). If more than 31 feature bits are |
| 256 | supported, the device indicates so by setting feature bit 31 (see |
| 257 | [cha:Reserved-Feature-Bits]). The bits are allocated as follows: |
| 258 | |
| 259 | 0 to 23 Feature bits for the specific device type |
| 260 | |
| 261 | 24 to 40 Feature bits reserved for extensions to the queue and |
| 262 | feature negotiation mechanisms |
| 263 | |
| 264 | 41 to 63 Feature bits reserved for future extensions |
| 265 | |
| 266 | For example, feature bit 0 for a network device (i.e. Subsystem |
| 267 | Device ID 1) indicates that the device supports checksumming of |
| 268 | packets. |
| 269 | |
| 270 | The feature bits are negotiated: the device lists all the |
| 271 | features it understands in the Device Features field, and the |
| 272 | guest writes the subset that it understands into the Guest |
| 273 | Features field. The only way to renegotiate is to reset the |
| 274 | device. |
| 275 | |
| 276 | In particular, new fields in the device configuration header are |
| 277 | indicated by offering a feature bit, so the guest can check |
| 278 | before accessing that part of the configuration space. |
| 279 | |
| 280 | This allows for forwards and backwards compatibility: if the |
| 281 | device is enhanced with a new feature bit, older guests will not |
| 282 | write that feature bit back to the Guest Features field and it |
| 283 | can go into backwards compatibility mode. Similarly, if a guest |
| 284 | is enhanced with a feature that the device doesn't support, it |
| 285 | will not see that feature bit in the Device Features field and |
| 286 | can go into backwards compatibility mode (or, for poor |
| 287 | implementations, set the FAILED Device Status bit). |
| 288 | |
| 289 | Access to feature bits 32 to 63 is enabled by Guest by setting |
| 290 | feature bit 31. If this bit is unset, Device must assume that all |
| 291 | feature bits > 31 are unset. |
| 292 | |
| 293 | Configuration/Queue Vectors |
| 294 | |
| 295 | When MSI-X capability is present and enabled in the device |
| 296 | (through standard PCI configuration space) 4 bytes at byte offset |
| 297 | 20 are used to map configuration change and queue interrupts to |
| 298 | MSI-X vectors. In this case, the ISR Status field is unused, and |
| 299 | device specific configuration starts at byte offset 24 in virtio |
| 300 | header structure. When MSI-X capability is not enabled, device |
| 301 | specific configuration starts at byte offset 20 in virtio header. |
| 302 | |
| 303 | Writing a valid MSI-X Table entry number, 0 to 0x7FF, to one of |
| 304 | Configuration/Queue Vector registers, maps interrupts triggered |
| 305 | by the configuration change/selected queue events respectively to |
| 306 | the corresponding MSI-X vector. To disable interrupts for a |
| 307 | specific event type, unmap it by writing a special NO_VECTOR |
| 308 | value: |
| 309 | |
| 310 | /* Vector value used to disable MSI for queue */ |
| 311 | |
| 312 | #define VIRTIO_MSI_NO_VECTOR 0xffff |
| 313 | |
| 314 | Reading these registers returns vector mapped to a given event, |
| 315 | or NO_VECTOR if unmapped. All queue and configuration change |
| 316 | events are unmapped by default. |
| 317 | |
| 318 | Note that mapping an event to vector might require allocating |
| 319 | internal device resources, and might fail. Devices report such |
| 320 | failures by returning the NO_VECTOR value when the relevant |
| 321 | Vector field is read. After mapping an event to vector, the |
| 322 | driver must verify success by reading the Vector field value: on |
| 323 | success, the previously written value is returned, and on |
| 324 | failure, NO_VECTOR is returned. If a mapping failure is detected, |
| 325 | the driver can retry mapping with fewervectors, or disable MSI-X. |
| 326 | |
| 327 | Virtqueue Configuration |
| 328 | |
| 329 | As a device can have zero or more virtqueues for bulk data |
| 330 | transport (for example, the network driver has two), the driver |
| 331 | needs to configure them as part of the device-specific |
| 332 | configuration. |
| 333 | |
| 334 | This is done as follows, for each virtqueue a device has: |
| 335 | |
| 336 | Write the virtqueue index (first queue is 0) to the Queue |
| 337 | Select field. |
| 338 | |
| 339 | Read the virtqueue size from the Queue Size field, which is |
| 340 | always a power of 2. This controls how big the virtqueue is |
| 341 | (see below). If this field is 0, the virtqueue does not exist. |
| 342 | |
| 343 | Allocate and zero virtqueue in contiguous physical memory, on a |
| 344 | 4096 byte alignment. Write the physical address, divided by |
| 345 | 4096 to the Queue Address field.[footnote: |
| 346 | The 4096 is based on the x86 page size, but it's also large |
| 347 | enough to ensure that the separate parts of the virtqueue are on |
| 348 | separate cache lines. |
| 349 | ] |
| 350 | |
| 351 | Optionally, if MSI-X capability is present and enabled on the |
| 352 | device, select a vector to use to request interrupts triggered |
| 353 | by virtqueue events. Write the MSI-X Table entry number |
| 354 | corresponding to this vector in Queue Vector field. Read the |
| 355 | Queue Vector field: on success, previously written value is |
| 356 | returned; on failure, NO_VECTOR value is returned. |
| 357 | |
| 358 | The Queue Size field controls the total number of bytes required |
| 359 | for the virtqueue according to the following formula: |
| 360 | |
| 361 | #define ALIGN(x) (((x) + 4095) & ~4095) |
| 362 | |
| 363 | static inline unsigned vring_size(unsigned int qsz) |
| 364 | |
| 365 | { |
| 366 | |
| 367 | return ALIGN(sizeof(struct vring_desc)*qsz + sizeof(u16)*(2 |
| 368 | + qsz)) |
| 369 | |
| 370 | + ALIGN(sizeof(struct vring_used_elem)*qsz); |
| 371 | |
| 372 | } |
| 373 | |
| 374 | This currently wastes some space with padding, but also allows |
| 375 | future extensions. The virtqueue layout structure looks like this |
| 376 | (qsz is the Queue Size field, which is a variable, so this code |
| 377 | won't compile): |
| 378 | |
| 379 | struct vring { |
| 380 | |
| 381 | /* The actual descriptors (16 bytes each) */ |
| 382 | |
| 383 | struct vring_desc desc[qsz]; |
| 384 | |
| 385 | |
| 386 | |
| 387 | /* A ring of available descriptor heads with free-running |
| 388 | index. */ |
| 389 | |
| 390 | struct vring_avail avail; |
| 391 | |
| 392 | |
| 393 | |
| 394 | // Padding to the next 4096 boundary. |
| 395 | |
| 396 | char pad[]; |
| 397 | |
| 398 | |
| 399 | |
| 400 | // A ring of used descriptor heads with free-running index. |
| 401 | |
| 402 | struct vring_used used; |
| 403 | |
| 404 | }; |
| 405 | |
| 406 | A Note on Virtqueue Endianness |
| 407 | |
| 408 | Note that the endian of these fields and everything else in the |
| 409 | virtqueue is the native endian of the guest, not little-endian as |
| 410 | PCI normally is. This makes for simpler guest code, and it is |
| 411 | assumed that the host already has to be deeply aware of the guest |
| 412 | endian so such an “endian-aware” device is not a significant |
| 413 | issue. |
| 414 | |
| 415 | Descriptor Table |
| 416 | |
| 417 | The descriptor table refers to the buffers the guest is using for |
| 418 | the device. The addresses are physical addresses, and the buffers |
| 419 | can be chained via the next field. Each descriptor describes a |
| 420 | buffer which is read-only or write-only, but a chain of |
| 421 | descriptors can contain both read-only and write-only buffers. |
| 422 | |
| 423 | No descriptor chain may be more than 2^32 bytes long in total.struct vring_desc { |
| 424 | |
| 425 | /* Address (guest-physical). */ |
| 426 | |
| 427 | u64 addr; |
| 428 | |
| 429 | /* Length. */ |
| 430 | |
| 431 | u32 len; |
| 432 | |
| 433 | /* This marks a buffer as continuing via the next field. */ |
| 434 | |
| 435 | #define VRING_DESC_F_NEXT 1 |
| 436 | |
| 437 | /* This marks a buffer as write-only (otherwise read-only). */ |
| 438 | |
| 439 | #define VRING_DESC_F_WRITE 2 |
| 440 | |
| 441 | /* This means the buffer contains a list of buffer descriptors. |
| 442 | */ |
| 443 | |
| 444 | #define VRING_DESC_F_INDIRECT 4 |
| 445 | |
| 446 | /* The flags as indicated above. */ |
| 447 | |
| 448 | u16 flags; |
| 449 | |
| 450 | /* Next field if flags & NEXT */ |
| 451 | |
| 452 | u16 next; |
| 453 | |
| 454 | }; |
| 455 | |
| 456 | The number of descriptors in the table is specified by the Queue |
| 457 | Size field for this virtqueue. |
| 458 | |
| 459 | <sub:Indirect-Descriptors>Indirect Descriptors |
| 460 | |
| 461 | Some devices benefit by concurrently dispatching a large number |
| 462 | of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature can be |
| 463 | used to allow this (see [cha:Reserved-Feature-Bits]). To increase |
| 464 | ring capacity it is possible to store a table of indirect |
| 465 | descriptors anywhere in memory, and insert a descriptor in main |
| 466 | virtqueue (with flags&INDIRECT on) that refers to memory buffer |
| 467 | containing this indirect descriptor table; fields addr and len |
| 468 | refer to the indirect table address and length in bytes, |
| 469 | respectively. The indirect table layout structure looks like this |
| 470 | (len is the length of the descriptor that refers to this table, |
| 471 | which is a variable, so this code won't compile): |
| 472 | |
| 473 | struct indirect_descriptor_table { |
| 474 | |
| 475 | /* The actual descriptors (16 bytes each) */ |
| 476 | |
| 477 | struct vring_desc desc[len / 16]; |
| 478 | |
| 479 | }; |
| 480 | |
| 481 | The first indirect descriptor is located at start of the indirect |
| 482 | descriptor table (index 0), additional indirect descriptors are |
| 483 | chained by next field. An indirect descriptor without next field |
| 484 | (with flags&NEXT off) signals the end of the indirect descriptor |
| 485 | table, and transfers control back to the main virtqueue. An |
| 486 | indirect descriptor can not refer to another indirect descriptor |
| 487 | table (flags&INDIRECT must be off). A single indirect descriptor |
| 488 | table can include both read-only and write-only descriptors; |
| 489 | write-only flag (flags&WRITE) in the descriptor that refers to it |
| 490 | is ignored. |
| 491 | |
| 492 | Available Ring |
| 493 | |
| 494 | The available ring refers to what descriptors we are offering the |
| 495 | device: it refers to the head of a descriptor chain. The “flags” |
| 496 | field is currently 0 or 1: 1 indicating that we do not need an |
| 497 | interrupt when the device consumes a descriptor from the |
| 498 | available ring. Alternatively, the guest can ask the device to |
| 499 | delay interrupts until an entry with an index specified by the “ |
| 500 | used_event” field is written in the used ring (equivalently, |
| 501 | until the idx field in the used ring will reach the value |
| 502 | used_event + 1). The method employed by the device is controlled |
| 503 | by the VIRTIO_RING_F_EVENT_IDX feature bit (see [cha:Reserved-Feature-Bits] |
| 504 | ). This interrupt suppression is merely an optimization; it may |
| 505 | not suppress interrupts entirely. |
| 506 | |
| 507 | The “idx” field indicates where we would put the next descriptor |
| 508 | entry (modulo the ring size). This starts at 0, and increases. |
| 509 | |
| 510 | struct vring_avail { |
| 511 | |
| 512 | #define VRING_AVAIL_F_NO_INTERRUPT 1 |
| 513 | |
| 514 | u16 flags; |
| 515 | |
| 516 | u16 idx; |
| 517 | |
| 518 | u16 ring[qsz]; /* qsz is the Queue Size field read from device |
| 519 | */ |
| 520 | |
| 521 | u16 used_event; |
| 522 | |
| 523 | }; |
| 524 | |
| 525 | Used Ring |
| 526 | |
| 527 | The used ring is where the device returns buffers once it is done |
| 528 | with them. The flags field can be used by the device to hint that |
| 529 | no notification is necessary when the guest adds to the available |
| 530 | ring. Alternatively, the “avail_event” field can be used by the |
| 531 | device to hint that no notification is necessary until an entry |
| 532 | with an index specified by the “avail_event” is written in the |
| 533 | available ring (equivalently, until the idx field in the |
| 534 | available ring will reach the value avail_event + 1). The method |
| 535 | employed by the device is controlled by the guest through the |
| 536 | VIRTIO_RING_F_EVENT_IDX feature bit (see [cha:Reserved-Feature-Bits] |
| 537 | ). [footnote: |
| 538 | These fields are kept here because this is the only part of the |
| 539 | virtqueue written by the device |
| 540 | ]. |
| 541 | |
| 542 | Each entry in the ring is a pair: the head entry of the |
| 543 | descriptor chain describing the buffer (this matches an entry |
| 544 | placed in the available ring by the guest earlier), and the total |
| 545 | of bytes written into the buffer. The latter is extremely useful |
| 546 | for guests using untrusted buffers: if you do not know exactly |
| 547 | how much has been written by the device, you usually have to zero |
| 548 | the buffer to ensure no data leakage occurs. |
| 549 | |
| 550 | /* u32 is used here for ids for padding reasons. */ |
| 551 | |
| 552 | struct vring_used_elem { |
| 553 | |
| 554 | /* Index of start of used descriptor chain. */ |
| 555 | |
| 556 | u32 id; |
| 557 | |
| 558 | /* Total length of the descriptor chain which was used |
| 559 | (written to) */ |
| 560 | |
| 561 | u32 len; |
| 562 | |
| 563 | }; |
| 564 | |
| 565 | |
| 566 | |
| 567 | struct vring_used { |
| 568 | |
| 569 | #define VRING_USED_F_NO_NOTIFY 1 |
| 570 | |
| 571 | u16 flags; |
| 572 | |
| 573 | u16 idx; |
| 574 | |
| 575 | struct vring_used_elem ring[qsz]; |
| 576 | |
| 577 | u16 avail_event; |
| 578 | |
| 579 | }; |
| 580 | |
| 581 | Helpers for Managing Virtqueues |
| 582 | |
| 583 | The Linux Kernel Source code contains the definitions above and |
| 584 | helper routines in a more usable form, in |
| 585 | include/linux/virtio_ring.h. This was explicitly licensed by IBM |
| 586 | and Red Hat under the (3-clause) BSD license so that it can be |
| 587 | freely used by all other projects, and is reproduced (with slight |
| 588 | variation to remove Linux assumptions) in Appendix A. |
| 589 | |
| 590 | Device Operation |
| 591 | |
| 592 | There are two parts to device operation: supplying new buffers to |
| 593 | the device, and processing used buffers from the device. As an |
| 594 | example, the virtio network device has two virtqueues: the |
| 595 | transmit virtqueue and the receive virtqueue. The driver adds |
| 596 | outgoing (read-only) packets to the transmit virtqueue, and then |
| 597 | frees them after they are used. Similarly, incoming (write-only) |
| 598 | buffers are added to the receive virtqueue, and processed after |
| 599 | they are used. |
| 600 | |
| 601 | Supplying Buffers to The Device |
| 602 | |
| 603 | Actual transfer of buffers from the guest OS to the device |
| 604 | operates as follows: |
| 605 | |
| 606 | Place the buffer(s) into free descriptor(s). |
| 607 | |
| 608 | If there are no free descriptors, the guest may choose to |
| 609 | notify the device even if notifications are suppressed (to |
| 610 | reduce latency).[footnote: |
| 611 | The Linux drivers do this only for read-only buffers: for |
| 612 | write-only buffers, it is assumed that the driver is merely |
| 613 | trying to keep the receive buffer ring full, and no notification |
| 614 | of this expected condition is necessary. |
| 615 | ] |
| 616 | |
| 617 | Place the id of the buffer in the next ring entry of the |
| 618 | available ring. |
| 619 | |
| 620 | The steps (1) and (2) may be performed repeatedly if batching |
| 621 | is possible. |
| 622 | |
| 623 | A memory barrier should be executed to ensure the device sees |
| 624 | the updated descriptor table and available ring before the next |
| 625 | step. |
| 626 | |
| 627 | The available “idx” field should be increased by the number of |
| 628 | entries added to the available ring. |
| 629 | |
| 630 | A memory barrier should be executed to ensure that we update |
| 631 | the idx field before checking for notification suppression. |
| 632 | |
| 633 | If notifications are not suppressed, the device should be |
| 634 | notified of the new buffers. |
| 635 | |
| 636 | Note that the above code does not take precautions against the |
| 637 | available ring buffer wrapping around: this is not possible since |
| 638 | the ring buffer is the same size as the descriptor table, so step |
| 639 | (1) will prevent such a condition. |
| 640 | |
| 641 | In addition, the maximum queue size is 32768 (it must be a power |
| 642 | of 2 which fits in 16 bits), so the 16-bit “idx” value can always |
| 643 | distinguish between a full and empty buffer. |
| 644 | |
| 645 | Here is a description of each stage in more detail. |
| 646 | |
| 647 | Placing Buffers Into The Descriptor Table |
| 648 | |
| 649 | A buffer consists of zero or more read-only physically-contiguous |
| 650 | elements followed by zero or more physically-contiguous |
| 651 | write-only elements (it must have at least one element). This |
| 652 | algorithm maps it into the descriptor table: |
| 653 | |
| 654 | for each buffer element, b: |
| 655 | |
| 656 | Get the next free descriptor table entry, d |
| 657 | |
| 658 | Set d.addr to the physical address of the start of b |
| 659 | |
| 660 | Set d.len to the length of b. |
| 661 | |
| 662 | If b is write-only, set d.flags to VRING_DESC_F_WRITE, |
| 663 | otherwise 0. |
| 664 | |
| 665 | If there is a buffer element after this: |
| 666 | |
| 667 | Set d.next to the index of the next free descriptor element. |
| 668 | |
| 669 | Set the VRING_DESC_F_NEXT bit in d.flags. |
| 670 | |
| 671 | In practice, the d.next fields are usually used to chain free |
| 672 | descriptors, and a separate count kept to check there are enough |
| 673 | free descriptors before beginning the mappings. |
| 674 | |
| 675 | Updating The Available Ring |
| 676 | |
| 677 | The head of the buffer we mapped is the first d in the algorithm |
| 678 | above. A naive implementation would do the following: |
| 679 | |
| 680 | avail->ring[avail->idx % qsz] = head; |
| 681 | |
| 682 | However, in general we can add many descriptors before we update |
| 683 | the “idx” field (at which point they become visible to the |
| 684 | device), so we keep a counter of how many we've added: |
| 685 | |
| 686 | avail->ring[(avail->idx + added++) % qsz] = head; |
| 687 | |
| 688 | Updating The Index Field |
| 689 | |
| 690 | Once the idx field of the virtqueue is updated, the device will |
| 691 | be able to access the descriptor entries we've created and the |
| 692 | memory they refer to. This is why a memory barrier is generally |
| 693 | used before the idx update, to ensure it sees the most up-to-date |
| 694 | copy. |
| 695 | |
| 696 | The idx field always increments, and we let it wrap naturally at |
| 697 | 65536: |
| 698 | |
| 699 | avail->idx += added; |
| 700 | |
| 701 | <sub:Notifying-The-Device>Notifying The Device |
| 702 | |
| 703 | Device notification occurs by writing the 16-bit virtqueue index |
| 704 | of this virtqueue to the Queue Notify field of the virtio header |
| 705 | in the first I/O region of the PCI device. This can be expensive, |
| 706 | however, so the device can suppress such notifications if it |
| 707 | doesn't need them. We have to be careful to expose the new idx |
| 708 | value before checking the suppression flag: it's OK to notify |
| 709 | gratuitously, but not to omit a required notification. So again, |
| 710 | we use a memory barrier here before reading the flags or the |
| 711 | avail_event field. |
| 712 | |
| 713 | If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated, and if |
| 714 | the VRING_USED_F_NOTIFY flag is not set, we go ahead and write to |
| 715 | the PCI configuration space. |
| 716 | |
| 717 | If the VIRTIO_F_RING_EVENT_IDX feature is negotiated, we read the |
| 718 | avail_event field in the available ring structure. If the |
| 719 | available index crossed_the avail_event field value since the |
| 720 | last notification, we go ahead and write to the PCI configuration |
| 721 | space. The avail_event field wraps naturally at 65536 as well: |
| 722 | |
| 723 | (u16)(new_idx - avail_event - 1) < (u16)(new_idx - old_idx) |
| 724 | |
| 725 | <sub:Receiving-Used-Buffers>Receiving Used Buffers From The |
| 726 | Device |
| 727 | |
| 728 | Once the device has used a buffer (read from or written to it, or |
| 729 | parts of both, depending on the nature of the virtqueue and the |
| 730 | device), it sends an interrupt, following an algorithm very |
| 731 | similar to the algorithm used for the driver to send the device a |
| 732 | buffer: |
| 733 | |
| 734 | Write the head descriptor number to the next field in the used |
| 735 | ring. |
| 736 | |
| 737 | Update the used ring idx. |
| 738 | |
| 739 | Determine whether an interrupt is necessary: |
| 740 | |
| 741 | If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated: check |
| 742 | if f the VRING_AVAIL_F_NO_INTERRUPT flag is not set in avail- |
| 743 | >flags |
| 744 | |
| 745 | If the VIRTIO_F_RING_EVENT_IDX feature is negotiated: check |
| 746 | whether the used index crossed the used_event field value |
| 747 | since the last update. The used_event field wraps naturally |
| 748 | at 65536 as well:(u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx) |
| 749 | |
| 750 | If an interrupt is necessary: |
| 751 | |
| 752 | If MSI-X capability is disabled: |
| 753 | |
| 754 | Set the lower bit of the ISR Status field for the device. |
| 755 | |
| 756 | Send the appropriate PCI interrupt for the device. |
| 757 | |
| 758 | If MSI-X capability is enabled: |
| 759 | |
| 760 | Request the appropriate MSI-X interrupt message for the |
| 761 | device, Queue Vector field sets the MSI-X Table entry |
| 762 | number. |
| 763 | |
| 764 | If Queue Vector field value is NO_VECTOR, no interrupt |
| 765 | message is requested for this event. |
| 766 | |
| 767 | The guest interrupt handler should: |
| 768 | |
| 769 | If MSI-X capability is disabled: read the ISR Status field, |
| 770 | which will reset it to zero. If the lower bit is zero, the |
| 771 | interrupt was not for this device. Otherwise, the guest driver |
| 772 | should look through the used rings of each virtqueue for the |
| 773 | device, to see if any progress has been made by the device |
| 774 | which requires servicing. |
| 775 | |
| 776 | If MSI-X capability is enabled: look through the used rings of |
| 777 | each virtqueue mapped to the specific MSI-X vector for the |
| 778 | device, to see if any progress has been made by the device |
| 779 | which requires servicing. |
| 780 | |
| 781 | For each ring, guest should then disable interrupts by writing |
| 782 | VRING_AVAIL_F_NO_INTERRUPT flag in avail structure, if required. |
| 783 | It can then process used ring entries finally enabling interrupts |
| 784 | by clearing the VRING_AVAIL_F_NO_INTERRUPT flag or updating the |
| 785 | EVENT_IDX field in the available structure, Guest should then |
| 786 | execute a memory barrier, and then recheck the ring empty |
| 787 | condition. This is necessary to handle the case where, after the |
| 788 | last check and before enabling interrupts, an interrupt has been |
| 789 | suppressed by the device: |
| 790 | |
| 791 | vring_disable_interrupts(vq); |
| 792 | |
| 793 | for (;;) { |
| 794 | |
| 795 | if (vq->last_seen_used != vring->used.idx) { |
| 796 | |
| 797 | vring_enable_interrupts(vq); |
| 798 | |
| 799 | mb(); |
| 800 | |
| 801 | if (vq->last_seen_used != vring->used.idx) |
| 802 | |
| 803 | break; |
| 804 | |
| 805 | } |
| 806 | |
| 807 | struct vring_used_elem *e = |
| 808 | vring.used->ring[vq->last_seen_used%vsz]; |
| 809 | |
| 810 | process_buffer(e); |
| 811 | |
| 812 | vq->last_seen_used++; |
| 813 | |
| 814 | } |
| 815 | |
| 816 | Dealing With Configuration Changes |
| 817 | |
| 818 | Some virtio PCI devices can change the device configuration |
| 819 | state, as reflected in the virtio header in the PCI configuration |
| 820 | space. In this case: |
| 821 | |
| 822 | If MSI-X capability is disabled: an interrupt is delivered and |
| 823 | the second highest bit is set in the ISR Status field to |
| 824 | indicate that the driver should re-examine the configuration |
| 825 | space.Note that a single interrupt can indicate both that one |
| 826 | or more virtqueue has been used and that the configuration |
| 827 | space has changed: even if the config bit is set, virtqueues |
| 828 | must be scanned. |
| 829 | |
| 830 | If MSI-X capability is enabled: an interrupt message is |
| 831 | requested. The Configuration Vector field sets the MSI-X Table |
| 832 | entry number to use. If Configuration Vector field value is |
| 833 | NO_VECTOR, no interrupt message is requested for this event. |
| 834 | |
| 835 | Creating New Device Types |
| 836 | |
| 837 | Various considerations are necessary when creating a new device |
| 838 | type: |
| 839 | |
| 840 | How Many Virtqueues? |
| 841 | |
| 842 | It is possible that a very simple device will operate entirely |
| 843 | through its configuration space, but most will need at least one |
| 844 | virtqueue in which it will place requests. A device with both |
| 845 | input and output (eg. console and network devices described here) |
| 846 | need two queues: one which the driver fills with buffers to |
| 847 | receive input, and one which the driver places buffers to |
| 848 | transmit output. |
| 849 | |
| 850 | What Configuration Space Layout? |
| 851 | |
| 852 | Configuration space is generally used for rarely-changing or |
| 853 | initialization-time parameters. But it is a limited resource, so |
| 854 | it might be better to use a virtqueue to update configuration |
| 855 | information (the network device does this for filtering, |
| 856 | otherwise the table in the config space could potentially be very |
| 857 | large). |
| 858 | |
| 859 | Note that this space is generally the guest's native endian, |
| 860 | rather than PCI's little-endian. |
| 861 | |
| 862 | What Device Number? |
| 863 | |
| 864 | Currently device numbers are assigned quite freely: a simple |
| 865 | request mail to the author of this document or the Linux |
| 866 | virtualization mailing list[footnote: |
| 867 | |
| 868 | https://lists.linux-foundation.org/mailman/listinfo/virtualization |
| 869 | ] will be sufficient to secure a unique one. |
| 870 | |
| 871 | Meanwhile for experimental drivers, use 65535 and work backwards. |
| 872 | |
| 873 | How many MSI-X vectors? |
| 874 | |
| 875 | Using the optional MSI-X capability devices can speed up |
| 876 | interrupt processing by removing the need to read ISR Status |
| 877 | register by guest driver (which might be an expensive operation), |
| 878 | reducing interrupt sharing between devices and queues within the |
| 879 | device, and handling interrupts from multiple CPUs. However, some |
| 880 | systems impose a limit (which might be as low as 256) on the |
| 881 | total number of MSI-X vectors that can be allocated to all |
| 882 | devices. Devices and/or device drivers should take this into |
| 883 | account, limiting the number of vectors used unless the device is |
| 884 | expected to cause a high volume of interrupts. Devices can |
| 885 | control the number of vectors used by limiting the MSI-X Table |
| 886 | Size or not presenting MSI-X capability in PCI configuration |
| 887 | space. Drivers can control this by mapping events to as small |
| 888 | number of vectors as possible, or disabling MSI-X capability |
| 889 | altogether. |
| 890 | |
| 891 | Message Framing |
| 892 | |
| 893 | The descriptors used for a buffer should not effect the semantics |
| 894 | of the message, except for the total length of the buffer. For |
| 895 | example, a network buffer consists of a 10 byte header followed |
| 896 | by the network packet. Whether this is presented in the ring |
| 897 | descriptor chain as (say) a 10 byte buffer and a 1514 byte |
| 898 | buffer, or a single 1524 byte buffer, or even three buffers, |
| 899 | should have no effect. |
| 900 | |
| 901 | In particular, no implementation should use the descriptor |
| 902 | boundaries to determine the size of any header in a request.[footnote: |
| 903 | The current qemu device implementations mistakenly insist that |
| 904 | the first descriptor cover the header in these cases exactly, so |
| 905 | a cautious driver should arrange it so. |
| 906 | ] |
| 907 | |
| 908 | Device Improvements |
| 909 | |
| 910 | Any change to configuration space, or new virtqueues, or |
| 911 | behavioural changes, should be indicated by negotiation of a new |
| 912 | feature bit. This establishes clarity[footnote: |
| 913 | Even if it does mean documenting design or implementation |
| 914 | mistakes! |
| 915 | ] and avoids future expansion problems. |
| 916 | |
| 917 | Clusters of functionality which are always implemented together |
| 918 | can use a single bit, but if one feature makes sense without the |
| 919 | others they should not be gratuitously grouped together to |
| 920 | conserve feature bits. We can always extend the spec when the |
| 921 | first person needs more than 24 feature bits for their device. |
| 922 | |
| 923 | [LaTeX Command: printnomenclature] |
| 924 | |
| 925 | Appendix A: virtio_ring.h |
| 926 | |
| 927 | #ifndef VIRTIO_RING_H |
| 928 | |
| 929 | #define VIRTIO_RING_H |
| 930 | |
| 931 | /* An interface for efficient virtio implementation. |
| 932 | |
| 933 | * |
| 934 | |
| 935 | * This header is BSD licensed so anyone can use the definitions |
| 936 | |
| 937 | * to implement compatible drivers/servers. |
| 938 | |
| 939 | * |
| 940 | |
| 941 | * Copyright 2007, 2009, IBM Corporation |
| 942 | |
| 943 | * Copyright 2011, Red Hat, Inc |
| 944 | |
| 945 | * All rights reserved. |
| 946 | |
| 947 | * |
| 948 | |
| 949 | * Redistribution and use in source and binary forms, with or |
| 950 | without |
| 951 | |
| 952 | * modification, are permitted provided that the following |
| 953 | conditions |
| 954 | |
| 955 | * are met: |
| 956 | |
| 957 | * 1. Redistributions of source code must retain the above |
| 958 | copyright |
| 959 | |
| 960 | * notice, this list of conditions and the following |
| 961 | disclaimer. |
| 962 | |
| 963 | * 2. Redistributions in binary form must reproduce the above |
| 964 | copyright |
| 965 | |
| 966 | * notice, this list of conditions and the following |
| 967 | disclaimer in the |
| 968 | |
| 969 | * documentation and/or other materials provided with the |
| 970 | distribution. |
| 971 | |
| 972 | * 3. Neither the name of IBM nor the names of its contributors |
| 973 | |
| 974 | * may be used to endorse or promote products derived from |
| 975 | this software |
| 976 | |
| 977 | * without specific prior written permission. |
| 978 | |
| 979 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND |
| 980 | CONTRIBUTORS ``AS IS'' AND |
| 981 | |
| 982 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED |
| 983 | TO, THE |
| 984 | |
| 985 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A |
| 986 | PARTICULAR PURPOSE |
| 987 | |
| 988 | * ARE DISCLAIMED. IN NO EVENT SHALL IBM OR CONTRIBUTORS BE |
| 989 | LIABLE |
| 990 | |
| 991 | * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| 992 | CONSEQUENTIAL |
| 993 | |
| 994 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| 995 | SUBSTITUTE GOODS |
| 996 | |
| 997 | * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| 998 | INTERRUPTION) |
| 999 | |
| 1000 | * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| 1001 | CONTRACT, STRICT |
| 1002 | |
| 1003 | * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING |
| 1004 | IN ANY WAY |
| 1005 | |
| 1006 | * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| 1007 | POSSIBILITY OF |
| 1008 | |
| 1009 | * SUCH DAMAGE. |
| 1010 | |
| 1011 | */ |
| 1012 | |
| 1013 | |
| 1014 | |
| 1015 | /* This marks a buffer as continuing via the next field. */ |
| 1016 | |
| 1017 | #define VRING_DESC_F_NEXT 1 |
| 1018 | |
| 1019 | /* This marks a buffer as write-only (otherwise read-only). */ |
| 1020 | |
| 1021 | #define VRING_DESC_F_WRITE 2 |
| 1022 | |
| 1023 | |
| 1024 | |
| 1025 | /* The Host uses this in used->flags to advise the Guest: don't |
| 1026 | kick me |
| 1027 | |
| 1028 | * when you add a buffer. It's unreliable, so it's simply an |
| 1029 | |
| 1030 | * optimization. Guest will still kick if it's out of buffers. |
| 1031 | */ |
| 1032 | |
| 1033 | #define VRING_USED_F_NO_NOTIFY 1 |
| 1034 | |
| 1035 | /* The Guest uses this in avail->flags to advise the Host: don't |
| 1036 | |
| 1037 | * interrupt me when you consume a buffer. It's unreliable, so |
| 1038 | it's |
| 1039 | |
| 1040 | * simply an optimization. */ |
| 1041 | |
| 1042 | #define VRING_AVAIL_F_NO_INTERRUPT 1 |
| 1043 | |
| 1044 | |
| 1045 | |
| 1046 | /* Virtio ring descriptors: 16 bytes. |
| 1047 | |
| 1048 | * These can chain together via "next". */ |
| 1049 | |
| 1050 | struct vring_desc { |
| 1051 | |
| 1052 | /* Address (guest-physical). */ |
| 1053 | |
| 1054 | uint64_t addr; |
| 1055 | |
| 1056 | /* Length. */ |
| 1057 | |
| 1058 | uint32_t len; |
| 1059 | |
| 1060 | /* The flags as indicated above. */ |
| 1061 | |
| 1062 | uint16_t flags; |
| 1063 | |
| 1064 | /* We chain unused descriptors via this, too */ |
| 1065 | |
| 1066 | uint16_t next; |
| 1067 | |
| 1068 | }; |
| 1069 | |
| 1070 | |
| 1071 | |
| 1072 | struct vring_avail { |
| 1073 | |
| 1074 | uint16_t flags; |
| 1075 | |
| 1076 | uint16_t idx; |
| 1077 | |
| 1078 | uint16_t ring[]; |
| 1079 | |
| 1080 | uint16_t used_event; |
| 1081 | |
| 1082 | }; |
| 1083 | |
| 1084 | |
| 1085 | |
| 1086 | /* u32 is used here for ids for padding reasons. */ |
| 1087 | |
| 1088 | struct vring_used_elem { |
| 1089 | |
| 1090 | /* Index of start of used descriptor chain. */ |
| 1091 | |
| 1092 | uint32_t id; |
| 1093 | |
| 1094 | /* Total length of the descriptor chain which was written |
| 1095 | to. */ |
| 1096 | |
| 1097 | uint32_t len; |
| 1098 | |
| 1099 | }; |
| 1100 | |
| 1101 | |
| 1102 | |
| 1103 | struct vring_used { |
| 1104 | |
| 1105 | uint16_t flags; |
| 1106 | |
| 1107 | uint16_t idx; |
| 1108 | |
| 1109 | struct vring_used_elem ring[]; |
| 1110 | |
| 1111 | uint16_t avail_event; |
| 1112 | |
| 1113 | }; |
| 1114 | |
| 1115 | |
| 1116 | |
| 1117 | struct vring { |
| 1118 | |
| 1119 | unsigned int num; |
| 1120 | |
| 1121 | |
| 1122 | |
| 1123 | struct vring_desc *desc; |
| 1124 | |
| 1125 | struct vring_avail *avail; |
| 1126 | |
| 1127 | struct vring_used *used; |
| 1128 | |
| 1129 | }; |
| 1130 | |
| 1131 | |
| 1132 | |
| 1133 | /* The standard layout for the ring is a continuous chunk of |
| 1134 | memory which |
| 1135 | |
| 1136 | * looks like this. We assume num is a power of 2. |
| 1137 | |
| 1138 | * |
| 1139 | |
| 1140 | * struct vring { |
| 1141 | |
| 1142 | * // The actual descriptors (16 bytes each) |
| 1143 | |
| 1144 | * struct vring_desc desc[num]; |
| 1145 | |
| 1146 | * |
| 1147 | |
| 1148 | * // A ring of available descriptor heads with free-running |
| 1149 | index. |
| 1150 | |
| 1151 | * __u16 avail_flags; |
| 1152 | |
| 1153 | * __u16 avail_idx; |
| 1154 | |
| 1155 | * __u16 available[num]; |
| 1156 | |
| 1157 | * |
| 1158 | |
| 1159 | * // Padding to the next align boundary. |
| 1160 | |
| 1161 | * char pad[]; |
| 1162 | |
| 1163 | * |
| 1164 | |
| 1165 | * // A ring of used descriptor heads with free-running |
| 1166 | index. |
| 1167 | |
| 1168 | * __u16 used_flags; |
| 1169 | |
| 1170 | * __u16 EVENT_IDX; |
| 1171 | |
| 1172 | * struct vring_used_elem used[num]; |
| 1173 | |
| 1174 | * }; |
| 1175 | |
| 1176 | * Note: for virtio PCI, align is 4096. |
| 1177 | |
| 1178 | */ |
| 1179 | |
| 1180 | static inline void vring_init(struct vring *vr, unsigned int num, |
| 1181 | void *p, |
| 1182 | |
| 1183 | unsigned long align) |
| 1184 | |
| 1185 | { |
| 1186 | |
| 1187 | vr->num = num; |
| 1188 | |
| 1189 | vr->desc = p; |
| 1190 | |
| 1191 | vr->avail = p + num*sizeof(struct vring_desc); |
| 1192 | |
| 1193 | vr->used = (void *)(((unsigned long)&vr->avail->ring[num] |
| 1194 | |
| 1195 | + align-1) |
| 1196 | |
| 1197 | & ~(align - 1)); |
| 1198 | |
| 1199 | } |
| 1200 | |
| 1201 | |
| 1202 | |
| 1203 | static inline unsigned vring_size(unsigned int num, unsigned long |
| 1204 | align) |
| 1205 | |
| 1206 | { |
| 1207 | |
| 1208 | return ((sizeof(struct vring_desc)*num + |
| 1209 | sizeof(uint16_t)*(2+num) |
| 1210 | |
| 1211 | + align - 1) & ~(align - 1)) |
| 1212 | |
| 1213 | + sizeof(uint16_t)*3 + sizeof(struct |
| 1214 | vring_used_elem)*num; |
| 1215 | |
| 1216 | } |
| 1217 | |
| 1218 | |
| 1219 | |
| 1220 | static inline int vring_need_event(uint16_t event_idx, uint16_t |
| 1221 | new_idx, uint16_t old_idx) |
| 1222 | |
| 1223 | { |
| 1224 | |
| 1225 | return (uint16_t)(new_idx - event_idx - 1) < |
| 1226 | (uint16_t)(new_idx - old_idx); |
| 1227 | |
| 1228 | } |
| 1229 | |
| 1230 | #endif /* VIRTIO_RING_H */ |
| 1231 | |
| 1232 | <cha:Reserved-Feature-Bits>Appendix B: Reserved Feature Bits |
| 1233 | |
| 1234 | Currently there are five device-independent feature bits defined: |
| 1235 | |
| 1236 | VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature |
| 1237 | indicates that the driver wants an interrupt if the device runs |
| 1238 | out of available descriptors on a virtqueue, even though |
| 1239 | interrupts are suppressed using the VRING_AVAIL_F_NO_INTERRUPT |
| 1240 | flag or the used_event field. An example of this is the |
| 1241 | networking driver: it doesn't need to know every time a packet |
| 1242 | is transmitted, but it does need to free the transmitted |
| 1243 | packets a finite time after they are transmitted. It can avoid |
| 1244 | using a timer if the device interrupts it when all the packets |
| 1245 | are transmitted. |
| 1246 | |
| 1247 | VIRTIO_F_RING_INDIRECT_DESC (28) Negotiating this feature |
| 1248 | indicates that the driver can use descriptors with the |
| 1249 | VRING_DESC_F_INDIRECT flag set, as described in [sub:Indirect-Descriptors] |
| 1250 | . |
| 1251 | |
| 1252 | VIRTIO_F_RING_EVENT_IDX(29) This feature enables the used_event |
| 1253 | and the avail_event fields. If set, it indicates that the |
| 1254 | device should ignore the flags field in the available ring |
| 1255 | structure. Instead, the used_event field in this structure is |
| 1256 | used by guest to suppress device interrupts. Further, the |
| 1257 | driver should ignore the flags field in the used ring |
| 1258 | structure. Instead, the avail_event field in this structure is |
| 1259 | used by the device to suppress notifications. If unset, the |
| 1260 | driver should ignore the used_event field; the device should |
| 1261 | ignore the avail_event field; the flags field is used |
| 1262 | |
| 1263 | VIRTIO_F_BAD_FEATURE(30) This feature should never be |
| 1264 | negotiated by the guest; doing so is an indication that the |
| 1265 | guest is faulty[footnote: |
| 1266 | An experimental virtio PCI driver contained in Linux version |
| 1267 | 2.6.25 had this problem, and this feature bit can be used to |
| 1268 | detect it. |
| 1269 | ] |
| 1270 | |
| 1271 | VIRTIO_F_FEATURES_HIGH(31) This feature indicates that the |
| 1272 | device supports feature bits 32:63. If unset, feature bits |
| 1273 | 32:63 are unset. |
| 1274 | |
| 1275 | Appendix C: Network Device |
| 1276 | |
| 1277 | The virtio network device is a virtual ethernet card, and is the |
| 1278 | most complex of the devices supported so far by virtio. It has |
| 1279 | enhanced rapidly and demonstrates clearly how support for new |
| 1280 | features should be added to an existing device. Empty buffers are |
| 1281 | placed in one virtqueue for receiving packets, and outgoing |
| 1282 | packets are enqueued into another for transmission in that order. |
| 1283 | A third command queue is used to control advanced filtering |
| 1284 | features. |
| 1285 | |
| 1286 | Configuration |
| 1287 | |
| 1288 | Subsystem Device ID 1 |
| 1289 | |
| 1290 | Virtqueues 0:receiveq. 1:transmitq. 2:controlq[footnote: |
| 1291 | Only if VIRTIO_NET_F_CTRL_VQ set |
| 1292 | ] |
| 1293 | |
| 1294 | Feature bits |
| 1295 | |
| 1296 | VIRTIO_NET_F_CSUM (0) Device handles packets with partial |
| 1297 | checksum |
| 1298 | |
| 1299 | VIRTIO_NET_F_GUEST_CSUM (1) Guest handles packets with partial |
| 1300 | checksum |
| 1301 | |
| 1302 | VIRTIO_NET_F_MAC (5) Device has given MAC address. |
| 1303 | |
| 1304 | VIRTIO_NET_F_GSO (6) (Deprecated) device handles packets with |
| 1305 | any GSO type.[footnote: |
| 1306 | It was supposed to indicate segmentation offload support, but |
| 1307 | upon further investigation it became clear that multiple bits |
| 1308 | were required. |
| 1309 | ] |
| 1310 | |
| 1311 | VIRTIO_NET_F_GUEST_TSO4 (7) Guest can receive TSOv4. |
| 1312 | |
| 1313 | VIRTIO_NET_F_GUEST_TSO6 (8) Guest can receive TSOv6. |
| 1314 | |
| 1315 | VIRTIO_NET_F_GUEST_ECN (9) Guest can receive TSO with ECN. |
| 1316 | |
| 1317 | VIRTIO_NET_F_GUEST_UFO (10) Guest can receive UFO. |
| 1318 | |
| 1319 | VIRTIO_NET_F_HOST_TSO4 (11) Device can receive TSOv4. |
| 1320 | |
| 1321 | VIRTIO_NET_F_HOST_TSO6 (12) Device can receive TSOv6. |
| 1322 | |
| 1323 | VIRTIO_NET_F_HOST_ECN (13) Device can receive TSO with ECN. |
| 1324 | |
| 1325 | VIRTIO_NET_F_HOST_UFO (14) Device can receive UFO. |
| 1326 | |
| 1327 | VIRTIO_NET_F_MRG_RXBUF (15) Guest can merge receive buffers. |
| 1328 | |
| 1329 | VIRTIO_NET_F_STATUS (16) Configuration status field is |
| 1330 | available. |
| 1331 | |
| 1332 | VIRTIO_NET_F_CTRL_VQ (17) Control channel is available. |
| 1333 | |
| 1334 | VIRTIO_NET_F_CTRL_RX (18) Control channel RX mode support. |
| 1335 | |
| 1336 | VIRTIO_NET_F_CTRL_VLAN (19) Control channel VLAN filtering. |
| 1337 | |
| 1338 | Device configuration layout Two configuration fields are |
| 1339 | currently defined. The mac address field always exists (though |
| 1340 | is only valid if VIRTIO_NET_F_MAC is set), and the status field |
| 1341 | only exists if VIRTIO_NET_F_STATUS is set. Only one bit is |
| 1342 | currently defined for the status field: VIRTIO_NET_S_LINK_UP. #define VIRTIO_NET_S_LINK_UP 1 |
| 1343 | |
| 1344 | |
| 1345 | |
| 1346 | struct virtio_net_config { |
| 1347 | |
| 1348 | u8 mac[6]; |
| 1349 | |
| 1350 | u16 status; |
| 1351 | |
| 1352 | }; |
| 1353 | |
| 1354 | Device Initialization |
| 1355 | |
| 1356 | The initialization routine should identify the receive and |
| 1357 | transmission virtqueues. |
| 1358 | |
| 1359 | If the VIRTIO_NET_F_MAC feature bit is set, the configuration |
| 1360 | space “mac” entry indicates the “physical” address of the the |
| 1361 | network card, otherwise a private MAC address should be |
| 1362 | assigned. All guests are expected to negotiate this feature if |
| 1363 | it is set. |
| 1364 | |
| 1365 | If the VIRTIO_NET_F_CTRL_VQ feature bit is negotiated, identify |
| 1366 | the control virtqueue. |
| 1367 | |
| 1368 | If the VIRTIO_NET_F_STATUS feature bit is negotiated, the link |
| 1369 | status can be read from the bottom bit of the “status” config |
| 1370 | field. Otherwise, the link should be assumed active. |
| 1371 | |
| 1372 | The receive virtqueue should be filled with receive buffers. |
| 1373 | This is described in detail below in “Setting Up Receive |
| 1374 | Buffers”. |
| 1375 | |
| 1376 | A driver can indicate that it will generate checksumless |
| 1377 | packets by negotating the VIRTIO_NET_F_CSUM feature. This “ |
| 1378 | checksum offload” is a common feature on modern network cards. |
| 1379 | |
| 1380 | If that feature is negotiated, a driver can use TCP or UDP |
| 1381 | segmentation offload by negotiating the VIRTIO_NET_F_HOST_TSO4 |
| 1382 | (IPv4 TCP), VIRTIO_NET_F_HOST_TSO6 (IPv6 TCP) and |
| 1383 | VIRTIO_NET_F_HOST_UFO (UDP fragmentation) features. It should |
| 1384 | not send TCP packets requiring segmentation offload which have |
| 1385 | the Explicit Congestion Notification bit set, unless the |
| 1386 | VIRTIO_NET_F_HOST_ECN feature is negotiated.[footnote: |
| 1387 | This is a common restriction in real, older network cards. |
| 1388 | ] |
| 1389 | |
| 1390 | The converse features are also available: a driver can save the |
| 1391 | virtual device some work by negotiating these features.[footnote: |
| 1392 | For example, a network packet transported between two guests on |
| 1393 | the same system may not require checksumming at all, nor |
| 1394 | segmentation, if both guests are amenable. |
| 1395 | ] The VIRTIO_NET_F_GUEST_CSUM feature indicates that partially |
| 1396 | checksummed packets can be received, and if it can do that then |
| 1397 | the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, |
| 1398 | VIRTIO_NET_F_GUEST_UFO and VIRTIO_NET_F_GUEST_ECN are the input |
| 1399 | equivalents of the features described above. See “Receiving |
| 1400 | Packets” below. |
| 1401 | |
| 1402 | Device Operation |
| 1403 | |
| 1404 | Packets are transmitted by placing them in the transmitq, and |
| 1405 | buffers for incoming packets are placed in the receiveq. In each |
| 1406 | case, the packet itself is preceeded by a header: |
| 1407 | |
| 1408 | struct virtio_net_hdr { |
| 1409 | |
| 1410 | #define VIRTIO_NET_HDR_F_NEEDS_CSUM 1 |
| 1411 | |
| 1412 | u8 flags; |
| 1413 | |
| 1414 | #define VIRTIO_NET_HDR_GSO_NONE 0 |
| 1415 | |
| 1416 | #define VIRTIO_NET_HDR_GSO_TCPV4 1 |
| 1417 | |
| 1418 | #define VIRTIO_NET_HDR_GSO_UDP 3 |
| 1419 | |
| 1420 | #define VIRTIO_NET_HDR_GSO_TCPV6 4 |
| 1421 | |
| 1422 | #define VIRTIO_NET_HDR_GSO_ECN 0x80 |
| 1423 | |
| 1424 | u8 gso_type; |
| 1425 | |
| 1426 | u16 hdr_len; |
| 1427 | |
| 1428 | u16 gso_size; |
| 1429 | |
| 1430 | u16 csum_start; |
| 1431 | |
| 1432 | u16 csum_offset; |
| 1433 | |
| 1434 | /* Only if VIRTIO_NET_F_MRG_RXBUF: */ |
| 1435 | |
| 1436 | u16 num_buffers |
| 1437 | |
| 1438 | }; |
| 1439 | |
| 1440 | The controlq is used to control device features such as |
| 1441 | filtering. |
| 1442 | |
| 1443 | Packet Transmission |
| 1444 | |
| 1445 | Transmitting a single packet is simple, but varies depending on |
| 1446 | the different features the driver negotiated. |
| 1447 | |
| 1448 | If the driver negotiated VIRTIO_NET_F_CSUM, and the packet has |
| 1449 | not been fully checksummed, then the virtio_net_hdr's fields |
| 1450 | are set as follows. Otherwise, the packet must be fully |
| 1451 | checksummed, and flags is zero. |
| 1452 | |
| 1453 | flags has the VIRTIO_NET_HDR_F_NEEDS_CSUM set, |
| 1454 | |
| 1455 | <ite:csum_start-is-set>csum_start is set to the offset within |
| 1456 | the packet to begin checksumming, and |
| 1457 | |
| 1458 | csum_offset indicates how many bytes after the csum_start the |
| 1459 | new (16 bit ones' complement) checksum should be placed.[footnote: |
| 1460 | For example, consider a partially checksummed TCP (IPv4) packet. |
| 1461 | It will have a 14 byte ethernet header and 20 byte IP header |
| 1462 | followed by the TCP header (with the TCP checksum field 16 bytes |
| 1463 | into that header). csum_start will be 14+20 = 34 (the TCP |
| 1464 | checksum includes the header), and csum_offset will be 16. The |
| 1465 | value in the TCP checksum field will be the sum of the TCP pseudo |
| 1466 | header, so that replacing it by the ones' complement checksum of |
| 1467 | the TCP header and body will give the correct result. |
| 1468 | ] |
| 1469 | |
| 1470 | <enu:If-the-driver>If the driver negotiated |
| 1471 | VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO, and the packet requires |
| 1472 | TCP segmentation or UDP fragmentation, then the “gso_type” |
| 1473 | field is set to VIRTIO_NET_HDR_GSO_TCPV4, TCPV6 or UDP. |
| 1474 | (Otherwise, it is set to VIRTIO_NET_HDR_GSO_NONE). In this |
| 1475 | case, packets larger than 1514 bytes can be transmitted: the |
| 1476 | metadata indicates how to replicate the packet header to cut it |
| 1477 | into smaller packets. The other gso fields are set: |
| 1478 | |
| 1479 | hdr_len is a hint to the device as to how much of the header |
| 1480 | needs to be kept to copy into each packet, usually set to the |
| 1481 | length of the headers, including the transport header.[footnote: |
| 1482 | Due to various bugs in implementations, this field is not useful |
| 1483 | as a guarantee of the transport header size. |
| 1484 | ] |
| 1485 | |
| 1486 | gso_size is the size of the packet beyond that header (ie. |
| 1487 | MSS). |
| 1488 | |
| 1489 | If the driver negotiated the VIRTIO_NET_F_HOST_ECN feature, the |
| 1490 | VIRTIO_NET_HDR_GSO_ECN bit may be set in “gso_type” as well, |
| 1491 | indicating that the TCP packet has the ECN bit set.[footnote: |
| 1492 | This case is not handled by some older hardware, so is called out |
| 1493 | specifically in the protocol. |
| 1494 | ] |
| 1495 | |
| 1496 | If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature, |
| 1497 | the num_buffers field is set to zero. |
| 1498 | |
| 1499 | The header and packet are added as one output buffer to the |
| 1500 | transmitq, and the device is notified of the new entry (see [sub:Notifying-The-Device] |
| 1501 | ).[footnote: |
| 1502 | Note that the header will be two bytes longer for the |
| 1503 | VIRTIO_NET_F_MRG_RXBUF case. |
| 1504 | ] |
| 1505 | |
| 1506 | Packet Transmission Interrupt |
| 1507 | |
| 1508 | Often a driver will suppress transmission interrupts using the |
| 1509 | VRING_AVAIL_F_NO_INTERRUPT flag (see [sub:Receiving-Used-Buffers] |
| 1510 | ) and check for used packets in the transmit path of following |
| 1511 | packets. However, it will still receive interrupts if the |
| 1512 | VIRTIO_F_NOTIFY_ON_EMPTY feature is negotiated, indicating that |
| 1513 | the transmission queue is completely emptied. |
| 1514 | |
| 1515 | The normal behavior in this interrupt handler is to retrieve and |
| 1516 | new descriptors from the used ring and free the corresponding |
| 1517 | headers and packets. |
| 1518 | |
| 1519 | Setting Up Receive Buffers |
| 1520 | |
| 1521 | It is generally a good idea to keep the receive virtqueue as |
| 1522 | fully populated as possible: if it runs out, network performance |
| 1523 | will suffer. |
| 1524 | |
| 1525 | If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6 or |
| 1526 | VIRTIO_NET_F_GUEST_UFO features are used, the Guest will need to |
| 1527 | accept packets of up to 65550 bytes long (the maximum size of a |
| 1528 | TCP or UDP packet, plus the 14 byte ethernet header), otherwise |
| 1529 | 1514 bytes. So unless VIRTIO_NET_F_MRG_RXBUF is negotiated, every |
| 1530 | buffer in the receive queue needs to be at least this length [footnote: |
| 1531 | Obviously each one can be split across multiple descriptor |
| 1532 | elements. |
| 1533 | ]. |
| 1534 | |
| 1535 | If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer must be at |
| 1536 | least the size of the struct virtio_net_hdr. |
| 1537 | |
| 1538 | Packet Receive Interrupt |
| 1539 | |
| 1540 | When a packet is copied into a buffer in the receiveq, the |
| 1541 | optimal path is to disable further interrupts for the receiveq |
| 1542 | (see [sub:Receiving-Used-Buffers]) and process packets until no |
| 1543 | more are found, then re-enable them. |
| 1544 | |
| 1545 | Processing packet involves: |
| 1546 | |
| 1547 | If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature, |
| 1548 | then the “num_buffers” field indicates how many descriptors |
| 1549 | this packet is spread over (including this one). This allows |
| 1550 | receipt of large packets without having to allocate large |
| 1551 | buffers. In this case, there will be at least “num_buffers” in |
| 1552 | the used ring, and they should be chained together to form a |
| 1553 | single packet. The other buffers will not begin with a struct |
| 1554 | virtio_net_hdr. |
| 1555 | |
| 1556 | If the VIRTIO_NET_F_MRG_RXBUF feature was not negotiated, or |
| 1557 | the “num_buffers” field is one, then the entire packet will be |
| 1558 | contained within this buffer, immediately following the struct |
| 1559 | virtio_net_hdr. |
| 1560 | |
| 1561 | If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the |
| 1562 | VIRTIO_NET_HDR_F_NEEDS_CSUM bit in the “flags” field may be |
| 1563 | set: if so, the checksum on the packet is incomplete and the “ |
| 1564 | csum_start” and “csum_offset” fields indicate how to calculate |
| 1565 | it (see [ite:csum_start-is-set]). |
| 1566 | |
| 1567 | If the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options were |
| 1568 | negotiated, then the “gso_type” may be something other than |
| 1569 | VIRTIO_NET_HDR_GSO_NONE, and the “gso_size” field indicates the |
| 1570 | desired MSS (see [enu:If-the-driver]).Control Virtqueue |
| 1571 | |
| 1572 | The driver uses the control virtqueue (if VIRTIO_NET_F_VTRL_VQ is |
| 1573 | negotiated) to send commands to manipulate various features of |
| 1574 | the device which would not easily map into the configuration |
| 1575 | space. |
| 1576 | |
| 1577 | All commands are of the following form: |
| 1578 | |
| 1579 | struct virtio_net_ctrl { |
| 1580 | |
| 1581 | u8 class; |
| 1582 | |
| 1583 | u8 command; |
| 1584 | |
| 1585 | u8 command-specific-data[]; |
| 1586 | |
| 1587 | u8 ack; |
| 1588 | |
| 1589 | }; |
| 1590 | |
| 1591 | |
| 1592 | |
| 1593 | /* ack values */ |
| 1594 | |
| 1595 | #define VIRTIO_NET_OK 0 |
| 1596 | |
| 1597 | #define VIRTIO_NET_ERR 1 |
| 1598 | |
| 1599 | The class, command and command-specific-data are set by the |
| 1600 | driver, and the device sets the ack byte. There is little it can |
| 1601 | do except issue a diagnostic if the ack byte is not |
| 1602 | VIRTIO_NET_OK. |
| 1603 | |
| 1604 | Packet Receive Filtering |
| 1605 | |
| 1606 | If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can |
| 1607 | send control commands for promiscuous mode, multicast receiving, |
| 1608 | and filtering of MAC addresses. |
| 1609 | |
| 1610 | Note that in general, these commands are best-effort: unwanted |
| 1611 | packets may still arrive. |
| 1612 | |
| 1613 | Setting Promiscuous Mode |
| 1614 | |
| 1615 | #define VIRTIO_NET_CTRL_RX 0 |
| 1616 | |
| 1617 | #define VIRTIO_NET_CTRL_RX_PROMISC 0 |
| 1618 | |
| 1619 | #define VIRTIO_NET_CTRL_RX_ALLMULTI 1 |
| 1620 | |
| 1621 | The class VIRTIO_NET_CTRL_RX has two commands: |
| 1622 | VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and off, and |
| 1623 | VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and |
| 1624 | off. The command-specific-data is one byte containing 0 (off) or |
| 1625 | 1 (on). |
| 1626 | |
| 1627 | Setting MAC Address Filtering |
| 1628 | |
| 1629 | struct virtio_net_ctrl_mac { |
| 1630 | |
| 1631 | u32 entries; |
| 1632 | |
| 1633 | u8 macs[entries][ETH_ALEN]; |
| 1634 | |
| 1635 | }; |
| 1636 | |
| 1637 | |
| 1638 | |
| 1639 | #define VIRTIO_NET_CTRL_MAC 1 |
| 1640 | |
| 1641 | #define VIRTIO_NET_CTRL_MAC_TABLE_SET 0 |
| 1642 | |
| 1643 | The device can filter incoming packets by any number of |
| 1644 | destination MAC addresses.[footnote: |
| 1645 | Since there are no guarentees, it can use a hash filter |
| 1646 | orsilently switch to allmulti or promiscuous mode if it is given |
| 1647 | too many addresses. |
| 1648 | ] This table is set using the class VIRTIO_NET_CTRL_MAC and the |
| 1649 | command VIRTIO_NET_CTRL_MAC_TABLE_SET. The command-specific-data |
| 1650 | is two variable length tables of 6-byte MAC addresses. The first |
| 1651 | table contains unicast addresses, and the second contains |
| 1652 | multicast addresses. |
| 1653 | |
| 1654 | VLAN Filtering |
| 1655 | |
| 1656 | If the driver negotiates the VIRTION_NET_F_CTRL_VLAN feature, it |
| 1657 | can control a VLAN filter table in the device. |
| 1658 | |
| 1659 | #define VIRTIO_NET_CTRL_VLAN 2 |
| 1660 | |
| 1661 | #define VIRTIO_NET_CTRL_VLAN_ADD 0 |
| 1662 | |
| 1663 | #define VIRTIO_NET_CTRL_VLAN_DEL 1 |
| 1664 | |
| 1665 | Both the VIRTIO_NET_CTRL_VLAN_ADD and VIRTIO_NET_CTRL_VLAN_DEL |
| 1666 | command take a 16-bit VLAN id as the command-specific-data. |
| 1667 | |
| 1668 | Appendix D: Block Device |
| 1669 | |
| 1670 | The virtio block device is a simple virtual block device (ie. |
| 1671 | disk). Read and write requests (and other exotic requests) are |
| 1672 | placed in the queue, and serviced (probably out of order) by the |
| 1673 | device except where noted. |
| 1674 | |
| 1675 | Configuration |
| 1676 | |
| 1677 | Subsystem Device ID 2 |
| 1678 | |
| 1679 | Virtqueues 0:requestq. |
| 1680 | |
| 1681 | Feature bits |
| 1682 | |
| 1683 | VIRTIO_BLK_F_BARRIER (0) Host supports request barriers. |
| 1684 | |
| 1685 | VIRTIO_BLK_F_SIZE_MAX (1) Maximum size of any single segment is |
| 1686 | in “size_max”. |
| 1687 | |
| 1688 | VIRTIO_BLK_F_SEG_MAX (2) Maximum number of segments in a |
| 1689 | request is in “seg_max”. |
| 1690 | |
| 1691 | VIRTIO_BLK_F_GEOMETRY (4) Disk-style geometry specified in “ |
| 1692 | geometry”. |
| 1693 | |
| 1694 | VIRTIO_BLK_F_RO (5) Device is read-only. |
| 1695 | |
| 1696 | VIRTIO_BLK_F_BLK_SIZE (6) Block size of disk is in “blk_size”. |
| 1697 | |
| 1698 | VIRTIO_BLK_F_SCSI (7) Device supports scsi packet commands. |
| 1699 | |
| 1700 | VIRTIO_BLK_F_FLUSH (9) Cache flush command support. |
| 1701 | |
| 1702 | |
| 1703 | |
| 1704 | Device configuration layout The capacity of the device |
| 1705 | (expressed in 512-byte sectors) is always present. The |
| 1706 | availability of the others all depend on various feature bits |
| 1707 | as indicated above. struct virtio_blk_config { |
| 1708 | |
| 1709 | u64 capacity; |
| 1710 | |
| 1711 | u32 size_max; |
| 1712 | |
| 1713 | u32 seg_max; |
| 1714 | |
| 1715 | struct virtio_blk_geometry { |
| 1716 | |
| 1717 | u16 cylinders; |
| 1718 | |
| 1719 | u8 heads; |
| 1720 | |
| 1721 | u8 sectors; |
| 1722 | |
| 1723 | } geometry; |
| 1724 | |
| 1725 | u32 blk_size; |
| 1726 | |
| 1727 | |
| 1728 | |
| 1729 | }; |
| 1730 | |
| 1731 | Device Initialization |
| 1732 | |
| 1733 | The device size should be read from the “capacity” |
| 1734 | configuration field. No requests should be submitted which goes |
| 1735 | beyond this limit. |
| 1736 | |
| 1737 | If the VIRTIO_BLK_F_BLK_SIZE feature is negotiated, the |
| 1738 | blk_size field can be read to determine the optimal sector size |
| 1739 | for the driver to use. This does not effect the units used in |
| 1740 | the protocol (always 512 bytes), but awareness of the correct |
| 1741 | value can effect performance. |
| 1742 | |
| 1743 | If the VIRTIO_BLK_F_RO feature is set by the device, any write |
| 1744 | requests will fail. |
| 1745 | |
| 1746 | |
| 1747 | |
| 1748 | Device Operation |
| 1749 | |
| 1750 | The driver queues requests to the virtqueue, and they are used by |
| 1751 | the device (not necessarily in order). Each request is of form: |
| 1752 | |
| 1753 | struct virtio_blk_req { |
| 1754 | |
| 1755 | |
| 1756 | |
| 1757 | u32 type; |
| 1758 | |
| 1759 | u32 ioprio; |
| 1760 | |
| 1761 | u64 sector; |
| 1762 | |
| 1763 | char data[][512]; |
| 1764 | |
| 1765 | u8 status; |
| 1766 | |
| 1767 | }; |
| 1768 | |
| 1769 | If the device has VIRTIO_BLK_F_SCSI feature, it can also support |
| 1770 | scsi packet command requests, each of these requests is of form:struct virtio_scsi_pc_req { |
| 1771 | |
| 1772 | u32 type; |
| 1773 | |
| 1774 | u32 ioprio; |
| 1775 | |
| 1776 | u64 sector; |
| 1777 | |
| 1778 | char cmd[]; |
| 1779 | |
| 1780 | char data[][512]; |
| 1781 | |
| 1782 | #define SCSI_SENSE_BUFFERSIZE 96 |
| 1783 | |
| 1784 | u8 sense[SCSI_SENSE_BUFFERSIZE]; |
| 1785 | |
| 1786 | u32 errors; |
| 1787 | |
| 1788 | u32 data_len; |
| 1789 | |
| 1790 | u32 sense_len; |
| 1791 | |
| 1792 | u32 residual; |
| 1793 | |
| 1794 | u8 status; |
| 1795 | |
| 1796 | }; |
| 1797 | |
| 1798 | The type of the request is either a read (VIRTIO_BLK_T_IN), a |
| 1799 | write (VIRTIO_BLK_T_OUT), a scsi packet command |
| 1800 | (VIRTIO_BLK_T_SCSI_CMD or VIRTIO_BLK_T_SCSI_CMD_OUT[footnote: |
| 1801 | the SCSI_CMD and SCSI_CMD_OUT types are equivalent, the device |
| 1802 | does not distinguish between them |
| 1803 | ]) or a flush (VIRTIO_BLK_T_FLUSH or VIRTIO_BLK_T_FLUSH_OUT[footnote: |
| 1804 | the FLUSH and FLUSH_OUT types are equivalent, the device does not |
| 1805 | distinguish between them |
| 1806 | ]). If the device has VIRTIO_BLK_F_BARRIER feature the high bit |
| 1807 | (VIRTIO_BLK_T_BARRIER) indicates that this request acts as a |
| 1808 | barrier and that all preceeding requests must be complete before |
| 1809 | this one, and all following requests must not be started until |
| 1810 | this is complete. Note that a barrier does not flush caches in |
| 1811 | the underlying backend device in host, and thus does not serve as |
| 1812 | data consistency guarantee. Driver must use FLUSH request to |
| 1813 | flush the host cache. |
| 1814 | |
| 1815 | #define VIRTIO_BLK_T_IN 0 |
| 1816 | |
| 1817 | #define VIRTIO_BLK_T_OUT 1 |
| 1818 | |
| 1819 | #define VIRTIO_BLK_T_SCSI_CMD 2 |
| 1820 | |
| 1821 | #define VIRTIO_BLK_T_SCSI_CMD_OUT 3 |
| 1822 | |
| 1823 | #define VIRTIO_BLK_T_FLUSH 4 |
| 1824 | |
| 1825 | #define VIRTIO_BLK_T_FLUSH_OUT 5 |
| 1826 | |
| 1827 | #define VIRTIO_BLK_T_BARRIER 0x80000000 |
| 1828 | |
| 1829 | The ioprio field is a hint about the relative priorities of |
| 1830 | requests to the device: higher numbers indicate more important |
| 1831 | requests. |
| 1832 | |
| 1833 | The sector number indicates the offset (multiplied by 512) where |
| 1834 | the read or write is to occur. This field is unused and set to 0 |
| 1835 | for scsi packet commands and for flush commands. |
| 1836 | |
| 1837 | The cmd field is only present for scsi packet command requests, |
| 1838 | and indicates the command to perform. This field must reside in a |
| 1839 | single, separate read-only buffer; command length can be derived |
| 1840 | from the length of this buffer. |
| 1841 | |
| 1842 | Note that these first three (four for scsi packet commands) |
| 1843 | fields are always read-only: the data field is either read-only |
| 1844 | or write-only, depending on the request. The size of the read or |
| 1845 | write can be derived from the total size of the request buffers. |
| 1846 | |
| 1847 | The sense field is only present for scsi packet command requests, |
| 1848 | and indicates the buffer for scsi sense data. |
| 1849 | |
| 1850 | The data_len field is only present for scsi packet command |
| 1851 | requests, this field is deprecated, and should be ignored by the |
| 1852 | driver. Historically, devices copied data length there. |
| 1853 | |
| 1854 | The sense_len field is only present for scsi packet command |
| 1855 | requests and indicates the number of bytes actually written to |
| 1856 | the sense buffer. |
| 1857 | |
| 1858 | The residual field is only present for scsi packet command |
| 1859 | requests and indicates the residual size, calculated as data |
| 1860 | length - number of bytes actually transferred. |
| 1861 | |
| 1862 | The final status byte is written by the device: either |
| 1863 | VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for host or guest |
| 1864 | error or VIRTIO_BLK_S_UNSUPP for a request unsupported by host:#define VIRTIO_BLK_S_OK 0 |
| 1865 | |
| 1866 | #define VIRTIO_BLK_S_IOERR 1 |
| 1867 | |
| 1868 | #define VIRTIO_BLK_S_UNSUPP 2 |
| 1869 | |
| 1870 | Historically, devices assumed that the fields type, ioprio and |
| 1871 | sector reside in a single, separate read-only buffer; the fields |
| 1872 | errors, data_len, sense_len and residual reside in a single, |
| 1873 | separate write-only buffer; the sense field in a separate |
| 1874 | write-only buffer of size 96 bytes, by itself; the fields errors, |
| 1875 | data_len, sense_len and residual in a single write-only buffer; |
| 1876 | and the status field is a separate read-only buffer of size 1 |
| 1877 | byte, by itself. |
| 1878 | |
| 1879 | Appendix E: Console Device |
| 1880 | |
| 1881 | The virtio console device is a simple device for data input and |
| 1882 | output. A device may have one or more ports. Each port has a pair |
| 1883 | of input and output virtqueues. Moreover, a device has a pair of |
| 1884 | control IO virtqueues. The control virtqueues are used to |
| 1885 | communicate information between the device and the driver about |
| 1886 | ports being opened and closed on either side of the connection, |
| 1887 | indication from the host about whether a particular port is a |
| 1888 | console port, adding new ports, port hot-plug/unplug, etc., and |
| 1889 | indication from the guest about whether a port or a device was |
| 1890 | successfully added, port open/close, etc.. For data IO, one or |
| 1891 | more empty buffers are placed in the receive queue for incoming |
| 1892 | data and outgoing characters are placed in the transmit queue. |
| 1893 | |
| 1894 | Configuration |
| 1895 | |
| 1896 | Subsystem Device ID 3 |
| 1897 | |
| 1898 | Virtqueues 0:receiveq(port0). 1:transmitq(port0), 2:control |
| 1899 | receiveq[footnote: |
| 1900 | Ports 2 onwards only if VIRTIO_CONSOLE_F_MULTIPORT is set |
| 1901 | ], 3:control transmitq, 4:receiveq(port1), 5:transmitq(port1), |
| 1902 | ... |
| 1903 | |
| 1904 | Feature bits |
| 1905 | |
| 1906 | VIRTIO_CONSOLE_F_SIZE (0) Configuration cols and rows fields |
| 1907 | are valid. |
| 1908 | |
| 1909 | VIRTIO_CONSOLE_F_MULTIPORT(1) Device has support for multiple |
| 1910 | ports; configuration fields nr_ports and max_nr_ports are |
| 1911 | valid and control virtqueues will be used. |
| 1912 | |
| 1913 | Device configuration layout The size of the console is supplied |
| 1914 | in the configuration space if the VIRTIO_CONSOLE_F_SIZE feature |
| 1915 | is set. Furthermore, if the VIRTIO_CONSOLE_F_MULTIPORT feature |
| 1916 | is set, the maximum number of ports supported by the device can |
| 1917 | be fetched.struct virtio_console_config { |
| 1918 | |
| 1919 | u16 cols; |
| 1920 | |
| 1921 | u16 rows; |
| 1922 | |
| 1923 | |
| 1924 | |
| 1925 | u32 max_nr_ports; |
| 1926 | |
| 1927 | }; |
| 1928 | |
| 1929 | Device Initialization |
| 1930 | |
| 1931 | If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver |
| 1932 | can read the console dimensions from the configuration fields. |
| 1933 | |
| 1934 | If the VIRTIO_CONSOLE_F_MULTIPORT feature is negotiated, the |
| 1935 | driver can spawn multiple ports, not all of which may be |
| 1936 | attached to a console. Some could be generic ports. In this |
| 1937 | case, the control virtqueues are enabled and according to the |
| 1938 | max_nr_ports configuration-space value, the appropriate number |
| 1939 | of virtqueues are created. A control message indicating the |
| 1940 | driver is ready is sent to the host. The host can then send |
| 1941 | control messages for adding new ports to the device. After |
| 1942 | creating and initializing each port, a |
| 1943 | VIRTIO_CONSOLE_PORT_READY control message is sent to the host |
| 1944 | for that port so the host can let us know of any additional |
| 1945 | configuration options set for that port. |
| 1946 | |
| 1947 | The receiveq for each port is populated with one or more |
| 1948 | receive buffers. |
| 1949 | |
| 1950 | Device Operation |
| 1951 | |
| 1952 | For output, a buffer containing the characters is placed in the |
| 1953 | port's transmitq.[footnote: |
| 1954 | Because this is high importance and low bandwidth, the current |
| 1955 | Linux implementation polls for the buffer to be used, rather than |
| 1956 | waiting for an interrupt, simplifying the implementation |
| 1957 | significantly. However, for generic serial ports with the |
| 1958 | O_NONBLOCK flag set, the polling limitation is relaxed and the |
| 1959 | consumed buffers are freed upon the next write or poll call or |
| 1960 | when a port is closed or hot-unplugged. |
| 1961 | ] |
| 1962 | |
| 1963 | When a buffer is used in the receiveq (signalled by an |
| 1964 | interrupt), the contents is the input to the port associated |
| 1965 | with the virtqueue for which the notification was received. |
| 1966 | |
| 1967 | If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a |
| 1968 | configuration change interrupt may occur. The updated size can |
| 1969 | be read from the configuration fields. |
| 1970 | |
| 1971 | If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT |
| 1972 | feature, active ports are announced by the host using the |
| 1973 | VIRTIO_CONSOLE_PORT_ADD control message. The same message is |
| 1974 | used for port hot-plug as well. |
| 1975 | |
| 1976 | If the host specified a port `name', a sysfs attribute is |
| 1977 | created with the name filled in, so that udev rules can be |
| 1978 | written that can create a symlink from the port's name to the |
| 1979 | char device for port discovery by applications in the guest. |
| 1980 | |
| 1981 | Changes to ports' state are effected by control messages. |
| 1982 | Appropriate action is taken on the port indicated in the |
| 1983 | control message. The layout of the structure of the control |
| 1984 | buffer and the events associated are:struct virtio_console_control { |
| 1985 | |
| 1986 | uint32_t id; /* Port number */ |
| 1987 | |
| 1988 | uint16_t event; /* The kind of control event */ |
| 1989 | |
| 1990 | uint16_t value; /* Extra information for the event */ |
| 1991 | |
| 1992 | }; |
| 1993 | |
| 1994 | |
| 1995 | |
| 1996 | /* Some events for the internal messages (control packets) */ |
| 1997 | |
| 1998 | |
| 1999 | |
| 2000 | #define VIRTIO_CONSOLE_DEVICE_READY 0 |
| 2001 | |
| 2002 | #define VIRTIO_CONSOLE_PORT_ADD 1 |
| 2003 | |
| 2004 | #define VIRTIO_CONSOLE_PORT_REMOVE 2 |
| 2005 | |
| 2006 | #define VIRTIO_CONSOLE_PORT_READY 3 |
| 2007 | |
| 2008 | #define VIRTIO_CONSOLE_CONSOLE_PORT 4 |
| 2009 | |
| 2010 | #define VIRTIO_CONSOLE_RESIZE 5 |
| 2011 | |
| 2012 | #define VIRTIO_CONSOLE_PORT_OPEN 6 |
| 2013 | |
| 2014 | #define VIRTIO_CONSOLE_PORT_NAME 7 |
| 2015 | |
| 2016 | Appendix F: Entropy Device |
| 2017 | |
| 2018 | The virtio entropy device supplies high-quality randomness for |
| 2019 | guest use. |
| 2020 | |
| 2021 | Configuration |
| 2022 | |
| 2023 | Subsystem Device ID 4 |
| 2024 | |
| 2025 | Virtqueues 0:requestq. |
| 2026 | |
| 2027 | Feature bits None currently defined |
| 2028 | |
| 2029 | Device configuration layout None currently defined. |
| 2030 | |
| 2031 | Device Initialization |
| 2032 | |
| 2033 | The virtqueue is initialized |
| 2034 | |
| 2035 | Device Operation |
| 2036 | |
| 2037 | When the driver requires random bytes, it places the descriptor |
| 2038 | of one or more buffers in the queue. It will be completely filled |
| 2039 | by random data by the device. |
| 2040 | |
| 2041 | Appendix G: Memory Balloon Device |
| 2042 | |
| 2043 | The virtio memory balloon device is a primitive device for |
| 2044 | managing guest memory: the device asks for a certain amount of |
| 2045 | memory, and the guest supplies it (or withdraws it, if the device |
| 2046 | has more than it asks for). This allows the guest to adapt to |
| 2047 | changes in allowance of underlying physical memory. If the |
| 2048 | feature is negotiated, the device can also be used to communicate |
| 2049 | guest memory statistics to the host. |
| 2050 | |
| 2051 | Configuration |
| 2052 | |
| 2053 | Subsystem Device ID 5 |
| 2054 | |
| 2055 | Virtqueues 0:inflateq. 1:deflateq. 2:statsq.[footnote: |
| 2056 | Only if VIRTIO_BALLON_F_STATS_VQ set |
| 2057 | ] |
| 2058 | |
| 2059 | Feature bits |
| 2060 | |
| 2061 | VIRTIO_BALLOON_F_MUST_TELL_HOST (0) Host must be told before |
| 2062 | pages from the balloon are used. |
| 2063 | |
| 2064 | VIRTIO_BALLOON_F_STATS_VQ (1) A virtqueue for reporting guest |
| 2065 | memory statistics is present. |
| 2066 | |
| 2067 | Device configuration layout Both fields of this configuration |
| 2068 | are always available. Note that they are little endian, despite |
| 2069 | convention that device fields are guest endian:struct virtio_balloon_config { |
| 2070 | |
| 2071 | u32 num_pages; |
| 2072 | |
| 2073 | u32 actual; |
| 2074 | |
| 2075 | }; |
| 2076 | |
| 2077 | Device Initialization |
| 2078 | |
| 2079 | The inflate and deflate virtqueues are identified. |
| 2080 | |
| 2081 | If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated: |
| 2082 | |
| 2083 | Identify the stats virtqueue. |
| 2084 | |
| 2085 | Add one empty buffer to the stats virtqueue and notify the |
| 2086 | host. |
| 2087 | |
| 2088 | Device operation begins immediately. |
| 2089 | |
| 2090 | Device Operation |
| 2091 | |
| 2092 | Memory Ballooning The device is driven by the receipt of a |
| 2093 | configuration change interrupt. |
| 2094 | |
| 2095 | The “num_pages” configuration field is examined. If this is |
| 2096 | greater than the “actual” number of pages, memory must be given |
| 2097 | to the balloon. If it is less than the “actual” number of |
| 2098 | pages, memory may be taken back from the balloon for general |
| 2099 | use. |
| 2100 | |
| 2101 | To supply memory to the balloon (aka. inflate): |
| 2102 | |
| 2103 | The driver constructs an array of addresses of unused memory |
| 2104 | pages. These addresses are divided by 4096[footnote: |
| 2105 | This is historical, and independent of the guest page size |
| 2106 | ] and the descriptor describing the resulting 32-bit array is |
| 2107 | added to the inflateq. |
| 2108 | |
| 2109 | To remove memory from the balloon (aka. deflate): |
| 2110 | |
| 2111 | The driver constructs an array of addresses of memory pages it |
| 2112 | has previously given to the balloon, as described above. This |
| 2113 | descriptor is added to the deflateq. |
| 2114 | |
| 2115 | If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is set, the |
| 2116 | guest may not use these requested pages until that descriptor |
| 2117 | in the deflateq has been used by the device. |
| 2118 | |
| 2119 | Otherwise, the guest may begin to re-use pages previously given |
| 2120 | to the balloon before the device has acknowledged their |
| 2121 | withdrawl. [footnote: |
| 2122 | In this case, deflation advice is merely a courtesy |
| 2123 | ] |
| 2124 | |
| 2125 | In either case, once the device has completed the inflation or |
| 2126 | deflation, the “actual” field of the configuration should be |
| 2127 | updated to reflect the new number of pages in the balloon.[footnote: |
| 2128 | As updates to configuration space are not atomic, this field |
| 2129 | isn't particularly reliable, but can be used to diagnose buggy |
| 2130 | guests. |
| 2131 | ] |
| 2132 | |
| 2133 | Memory Statistics |
| 2134 | |
| 2135 | The stats virtqueue is atypical because communication is driven |
| 2136 | by the device (not the driver). The channel becomes active at |
| 2137 | driver initialization time when the driver adds an empty buffer |
| 2138 | and notifies the device. A request for memory statistics proceeds |
| 2139 | as follows: |
| 2140 | |
| 2141 | The device pushes the buffer onto the used ring and sends an |
| 2142 | interrupt. |
| 2143 | |
| 2144 | The driver pops the used buffer and discards it. |
| 2145 | |
| 2146 | The driver collects memory statistics and writes them into a |
| 2147 | new buffer. |
| 2148 | |
| 2149 | The driver adds the buffer to the virtqueue and notifies the |
| 2150 | device. |
| 2151 | |
| 2152 | The device pops the buffer (retaining it to initiate a |
| 2153 | subsequent request) and consumes the statistics. |
| 2154 | |
| 2155 | Memory Statistics Format Each statistic consists of a 16 bit |
| 2156 | tag and a 64 bit value. Both quantities are represented in the |
| 2157 | native endian of the guest. All statistics are optional and the |
| 2158 | driver may choose which ones to supply. To guarantee backwards |
| 2159 | compatibility, unsupported statistics should be omitted. |
| 2160 | |
| 2161 | struct virtio_balloon_stat { |
| 2162 | |
| 2163 | #define VIRTIO_BALLOON_S_SWAP_IN 0 |
| 2164 | |
| 2165 | #define VIRTIO_BALLOON_S_SWAP_OUT 1 |
| 2166 | |
| 2167 | #define VIRTIO_BALLOON_S_MAJFLT 2 |
| 2168 | |
| 2169 | #define VIRTIO_BALLOON_S_MINFLT 3 |
| 2170 | |
| 2171 | #define VIRTIO_BALLOON_S_MEMFREE 4 |
| 2172 | |
| 2173 | #define VIRTIO_BALLOON_S_MEMTOT 5 |
| 2174 | |
| 2175 | u16 tag; |
| 2176 | |
| 2177 | u64 val; |
| 2178 | |
| 2179 | } __attribute__((packed)); |
| 2180 | |
| 2181 | Tags |
| 2182 | |
| 2183 | VIRTIO_BALLOON_S_SWAP_IN The amount of memory that has been |
| 2184 | swapped in (in bytes). |
| 2185 | |
| 2186 | VIRTIO_BALLOON_S_SWAP_OUT The amount of memory that has been |
| 2187 | swapped out to disk (in bytes). |
| 2188 | |
| 2189 | VIRTIO_BALLOON_S_MAJFLT The number of major page faults that |
| 2190 | have occurred. |
| 2191 | |
| 2192 | VIRTIO_BALLOON_S_MINFLT The number of minor page faults that |
| 2193 | have occurred. |
| 2194 | |
| 2195 | VIRTIO_BALLOON_S_MEMFREE The amount of memory not being used |
| 2196 | for any purpose (in bytes). |
| 2197 | |
| 2198 | VIRTIO_BALLOON_S_MEMTOT The total amount of memory available |
| 2199 | (in bytes). |
| 2200 | |