Esphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget,/translations/zh_CN/driver-api/virtio/virtiomodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/zh_TW/driver-api/virtio/virtiomodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/it_IT/driver-api/virtio/virtiomodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ja_JP/driver-api/virtio/virtiomodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/ko_KR/driver-api/virtio/virtiomodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget,/translations/sp_SP/driver-api/virtio/virtiomodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhF/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio.rsthKubhtarget)}(h .. _virtio:h]h}(h]h ]h"]h$]h&]refidvirtiouh1hhKhhhhhhubhsection)}(hhh](htitle)}(hVirtio on Linuxh]hVirtio on Linux}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh paragraph)}(hX_Virtio is an open standard that defines a protocol for communication between drivers and devices of different types, see Chapter 5 ("Device Types") of the virtio spec (`[1]`_). Originally developed as a standard for paravirtualized devices implemented by a hypervisor, it can be used to interface any compliant device (real or emulated) with a driver.h](hVirtio is an open standard that defines a protocol for communication between drivers and devices of different types, see Chapter 5 (“Device Types”) of the virtio spec (}(hhhhhNhNubh reference)}(h`[1]`_h]h[1]}(hhhhhNhNubah}(h]h ]h"]h$]h&]name[1]hid2uh1hhhresolvedKubh). Originally developed as a standard for paravirtualized devices implemented by a hypervisor, it can be used to interface any compliant device (real or emulated) with a driver.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hFor illustrative purposes, this document will focus on the common case of a Linux kernel running in a virtual machine and using paravirtualized devices provided by the hypervisor, which exposes them as virtio devices via standard mechanisms such as PCI.h]hFor illustrative purposes, this document will focus on the common case of a Linux kernel running in a virtual machine and using paravirtualized devices provided by the hypervisor, which exposes them as virtio devices via standard mechanisms such as PCI.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h)Device - Driver communication: virtqueuesh]h)Device - Driver communication: virtqueues}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&hhhhhKubh)}(hXiAlthough the virtio devices are really an abstraction layer in the hypervisor, they're exposed to the guest as if they are physical devices using a specific transport method -- PCI, MMIO or CCW -- that is orthogonal to the device itself. The virtio spec defines these transport methods in detail, including device discovery, capabilities and interrupt handling.h]hXkAlthough the virtio devices are really an abstraction layer in the hypervisor, they’re exposed to the guest as if they are physical devices using a specific transport method -- PCI, MMIO or CCW -- that is orthogonal to the device itself. The virtio spec defines these transport methods in detail, including device discovery, capabilities and interrupt handling.}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj&hhubh)}(hXCThe communication between the driver in the guest OS and the device in the hypervisor is done through shared memory (that's what makes virtio devices so efficient) using specialized data structures called virtqueues, which are actually ring buffers [#f1]_ of buffer descriptors similar to the ones used in a network device:h](hThe communication between the driver in the guest OS and the device in the hypervisor is done through shared memory (that’s what makes virtio devices so efficient) using specialized data structures called virtqueues, which are actually ring buffers }(hjEhhhNhNubhfootnote_reference)}(h[#f1]_h]h1}(hjOhhhNhNubah}(h]id1ah ]h"]h$]h&]autoKhf1docnamedriver-api/virtio/virtiouh1jMhjEjKubhD of buffer descriptors similar to the ones used in a network device:}(hjEhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK"hj&hhubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](singlevring_desc (C struct) c.vring_deschNtauh1jlhj&hhhNhNubhdesc)}(hhh](hdesc_signature)}(h vring_desch]hdesc_signature_line)}(hstruct vring_desch](hdesc_sig_keyword)}(hstructh]hstruct}(hjhhhNhNubah}(h]h ]kah"]h$]h&]uh1jhjhhhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKubhdesc_sig_space)}(h h]h }(hjhhhNhNubah}(h]h ]wah"]h$]h&]uh1jhjhhhjhKubh desc_name)}(h vring_desch]h desc_sig_name)}(hjh]h vring_desc}(hjhhhNhNubah}(h]h ]nah"]h$]h&]uh1jhjubah}(h]h ](sig-namedescnameeh"]h$]h&]hhuh1jhjhhhjhKubeh}(h]h ]h"]h$]h&]hh add_permalinkuh1jsphinx_line_type declaratorhjhhhjhKubah}(h]j{ah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1jhjhKhjhhubh desc_content)}(hhh]h)}(hNVirtio ring descriptors, 16 bytes long. These can chain together via **next**.h](hEVirtio ring descriptors, 16 bytes long. These can chain together via }(hjhhhNhNubhstrong)}(h**next**h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKahjhhubah}(h]h ]h"]h$]h&]uh1jhjhhhjhKubeh}(h]h ](cstructeh"]h$]h&]domainjobjtypejdesctypejnoindex noindexentrynocontentsentryuh1j}hhhj&hNhNubh container)}(hX**Definition**:: struct vring_desc { __virtio64 addr; __virtio32 len; __virtio16 flags; __virtio16 next; }; **Members** ``addr`` buffer address (guest-physical) ``len`` buffer length ``flags`` descriptor flags ``next`` index of the next descriptor in the chain, if the VRING_DESC_F_NEXT flag is set. We chain unused descriptors via this, too.h](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj%ubh:}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKehj!ubh literal_block)}(hjstruct vring_desc { __virtio64 addr; __virtio32 len; __virtio16 flags; __virtio16 next; };h]hjstruct vring_desc { __virtio64 addr; __virtio32 len; __virtio16 flags; __virtio16 next; };}hjDsbah}(h]h ]h"]h$]h&]hhuh1jBhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKghj!ubh)}(h **Members**h]j)}(hjUh]hMembers}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubah}(h]h ]h"]h$]h&]uh1hhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKnhj!ubhdefinition_list)}(hhh](hdefinition_list_item)}(h)``addr`` buffer address (guest-physical) h](hterm)}(h``addr``h]hliteral)}(hjzh]haddr}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1j|hjxubah}(h]h ]h"]h$]h&]uh1jvhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKehjrubh definition)}(hhh]h)}(hbuffer address (guest-physical)h]hbuffer address (guest-physical)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKehjubah}(h]h ]h"]h$]h&]uh1jhjrubeh}(h]h ]h"]h$]h&]uh1jphjhKehjmubjq)}(h``len`` buffer length h](jw)}(h``len``h]j})}(hjh]hlen}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j|hjubah}(h]h ]h"]h$]h&]uh1jvhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKfhjubj)}(hhh]h)}(h buffer lengthh]h buffer length}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKfhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jphjhKfhjmubjq)}(h``flags`` descriptor flags h](jw)}(h ``flags``h]j})}(hjh]hflags}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j|hjubah}(h]h ]h"]h$]h&]uh1jvhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKghjubj)}(hhh]h)}(hdescriptor flagsh]hdescriptor flags}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhKghjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jphjhKghjmubjq)}(h``next`` index of the next descriptor in the chain, if the VRING_DESC_F_NEXT flag is set. We chain unused descriptors via this, too.h](jw)}(h``next``h]j})}(hj)h]hnext}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1j|hj'ubah}(h]h ]h"]h$]h&]uh1jvhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKihj#ubj)}(hhh]h)}(h{index of the next descriptor in the chain, if the VRING_DESC_F_NEXT flag is set. We chain unused descriptors via this, too.h]h{index of the next descriptor in the chain, if the VRING_DESC_F_NEXT flag is set. We chain unused descriptors via this, too.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhi/var/lib/git/docbuild/linux/Documentation/driver-api/virtio/virtio:40: ./include/uapi/linux/virtio_ring.hhKhhj?ubah}(h]h ]h"]h$]h&]uh1jhj#ubeh}(h]h ]h"]h$]h&]uh1jphj>hKihjmubeh}(h]h ]h"]h$]h&]uh1jkhj!ubeh}(h]h ] kernelindentah"]h$]h&]uh1jhj&hhhNhNubh)}(hAll the buffers the descriptors point to are allocated by the guest and used by the host either for reading or for writing but not for both.h]hAll the buffers the descriptors point to are allocated by the guest and used by the host either for reading or for writing but not for both.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hj&hhubh)}(hX Refer to Chapter 2.5 ("Virtqueues") of the virtio spec (`[1]`_) for the reference definitions of virtqueues and "Virtqueues and virtio ring: How the data travels" blog post (`[2]`_) for an illustrated overview of how the host device and the guest driver communicate.h](h`__ device as an example. When using PCI as a transport method, the device will present itself on the PCI bus with vendor 0x1af4 (Red Hat, Inc.) and device id 0x1003 (virtio console), as defined in the spec, so the kernel will detect it as it would do with any other PCI device.h](hoHow a virtio device is found and configured by the kernel depends on how the hypervisor defines it. Taking the }(hjg hhhNhNubh)}(he`QEMU virtio-console `__h]hQEMU virtio-console}(hjo hhhNhNubah}(h]h ]h"]h$]h&]nameQEMU virtio-consolerefuriKhttps://gitlab.com/qemu-project/qemu/-/blob/master/hw/char/virtio-console.cuh1hhjg ubhX device as an example. When using PCI as a transport method, the device will present itself on the PCI bus with vendor 0x1af4 (Red Hat, Inc.) and device id 0x1003 (virtio console), as defined in the spec, so the kernel will detect it as it would do with any other PCI device.}(hjg hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKMhj" hhubh)}(hDuring the PCI enumeration process, if a device is found to match the virtio-pci driver (according to the virtio-pci device table, any PCI device with vendor id = 0x1af4)::h]hDuring the PCI enumeration process, if a device is found to match the virtio-pci driver (according to the virtio-pci device table, any PCI device with vendor id = 0x1af4):}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhj" hhubjC)}(h/* Qumranet donated their vendor ID for devices 0x1000 thru 0x10FF. */ static const struct pci_device_id virtio_pci_id_table[] = { { PCI_DEVICE(PCI_VENDOR_ID_REDHAT_QUMRANET, PCI_ANY_ID) }, { 0 } };h]h/* Qumranet donated their vendor ID for devices 0x1000 thru 0x10FF. */ static const struct pci_device_id virtio_pci_id_table[] = { { PCI_DEVICE(PCI_VENDOR_ID_REDHAT_QUMRANET, PCI_ANY_ID) }, { 0 } };}hj sbah}(h]h ]h"]h$]h&]hhuh1jBhhhKYhj" hhubh)}(hpthen the virtio-pci driver is probed and, if the probing goes well, the device is registered to the virtio bus::h]hothen the virtio-pci driver is probed and, if the probing goes well, the device is registered to the virtio bus:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hj" hhubjC)}(hXstatic int virtio_pci_probe(struct pci_dev *pci_dev, const struct pci_device_id *id) { ... if (force_legacy) { rc = virtio_pci_legacy_probe(vp_dev); /* Also try modern mode if we can't map BAR0 (no IO space). */ if (rc == -ENODEV || rc == -ENOMEM) rc = virtio_pci_modern_probe(vp_dev); if (rc) goto err_probe; } else { rc = virtio_pci_modern_probe(vp_dev); if (rc == -ENODEV) rc = virtio_pci_legacy_probe(vp_dev); if (rc) goto err_probe; } ... rc = register_virtio_device(&vp_dev->vdev);h]hXstatic int virtio_pci_probe(struct pci_dev *pci_dev, const struct pci_device_id *id) { ... if (force_legacy) { rc = virtio_pci_legacy_probe(vp_dev); /* Also try modern mode if we can't map BAR0 (no IO space). */ if (rc == -ENODEV || rc == -ENOMEM) rc = virtio_pci_modern_probe(vp_dev); if (rc) goto err_probe; } else { rc = virtio_pci_modern_probe(vp_dev); if (rc == -ENODEV) rc = virtio_pci_legacy_probe(vp_dev); if (rc) goto err_probe; } ... rc = register_virtio_device(&vp_dev->vdev);}hj sbah}(h]h ]h"]h$]h&]hhuh1jBhhhKbhj" hhubh)}(hWhen the device is registered to the virtio bus the kernel will look for a driver in the bus that can handle the device and call that driver's ``probe`` method.h](hWhen the device is registered to the virtio bus the kernel will look for a driver in the bus that can handle the device and call that driver’s }(hj hhhNhNubj})}(h ``probe``h]hprobe}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j|hj ubh method.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKzhj" hhubh)}(hAt this point, the virtqueues will be allocated and configured by calling the appropriate ``virtio_find`` helper function, such as virtio_find_single_vq() or virtio_find_vqs(), which will end up calling a transport-specific ``find_vqs`` method.h](hZAt this point, the virtqueues will be allocated and configured by calling the appropriate }(hj hhhNhNubj})}(h``virtio_find``h]h virtio_find}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j|hj ubhw helper function, such as virtio_find_single_vq() or virtio_find_vqs(), which will end up calling a transport-specific }(hj hhhNhNubj})}(h ``find_vqs``h]hfind_vqs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j|hj ubh method.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK~hj" hhubeh}(h]device-discovery-and-probingah ]h"]device discovery and probingah$]h&]uh1hhhhhhhhKFubh)}(hhh](h)}(h Referencesh]h References}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hX_`[1]` Virtio Spec v1.2: https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.htmlh](h)}(h_`[1]`h]h[1]}(hj2 hhhNhNubah}(h]jah ]h"][1]ah$]h&]uh1hhj. referencedKubh Virtio Spec v1.2: }(hj. hhhNhNubh)}(h?https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.htmlh]h?https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html}(hjF hhhNhNubah}(h]h ]h"]h$]h&]refurijH uh1hhj. ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(h-Check for later versions of the spec as well.h]h-Check for later versions of the spec as well.}hj[ sbah}(h]h ]h"]h$]h&]hhuh1hhj hhhhhKubh)}(h_`[2]` Virtqueues and virtio ring: How the data travels https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travelsh](h)}(h_`[2]`h]h[2]}(hjm hhhNhNubah}(h]jah ]h"][2]ah$]h&]uh1hhji jA Kubh2 Virtqueues and virtio ring: How the data travels }(hji hhhNhNubh)}(hJhttps://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travelsh]hJhttps://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij uh1hhji ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubhrubric)}(h Footnotesh]h Footnotes}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj hhhhhKubhfootnote)}(h5that's why they may be also referred to as virtrings.h](hlabel)}(hhh]h1}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj hhhNhNubh)}(hj h]h7that’s why they may be also referred to as virtrings.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubeh}(h]j_ah ]h"]f1ah$]h&]jYaj^Kj`jauh1j hhhKhj hhubeh}(h] referencesah ]h"] referencesah$]h&]uh1hhhhhhhhKubeh}(h](virtio-on-linuxheh ]h"](virtio on linuxvirtioeh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}j hsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}([1]](hjef1]jOa[2]]jaurefids}(h]haj_]jOaunameids}(j hj j j#j j j j j j j j> jjy jj j_u nametypes}(j j j#j j j j> jy j uh}(hhj hj hj j&jYjOj{jjjj2j7j j" j j jj2 jjm j_j u footnote_refs}jH ]jOas citation_refs} autofootnotes]j aautofootnote_refs]jOasymbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j KsRparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h,Hyperlink target "virtio" is not referenced.}hjx sbah}(h]h ]h"]h$]h&]uh1hhju ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehlineKuh1js uba transformerN include_log] decorationNhhub.