1.. _device-emulation: 2 3Device Emulation 4---------------- 5 6QEMU supports the emulation of a large number of devices from 7peripherals such network cards and USB devices to integrated systems 8on a chip (SoCs). Configuration of these is often a source of 9confusion so it helps to have an understanding of some of the terms 10used to describes devices within QEMU. 11 12Common Terms 13~~~~~~~~~~~~ 14 15Device Front End 16================ 17 18A device front end is how a device is presented to the guest. The type 19of device presented should match the hardware that the guest operating 20system is expecting to see. All devices can be specified with the 21``--device`` command line option. Running QEMU with the command line 22options ``--device help`` will list all devices it is aware of. Using 23the command line ``--device foo,help`` will list the additional 24configuration options available for that device. 25 26A front end is often paired with a back end, which describes how the 27host's resources are used in the emulation. 28 29Device Buses 30============ 31 32Most devices will exist on a BUS of some sort. Depending on the 33machine model you choose (``-M foo``) a number of buses will have been 34automatically created. In most cases the BUS a device is attached to 35can be inferred, for example PCI devices are generally automatically 36allocated to the next free address of first PCI bus found. However in 37complicated configurations you can explicitly specify what bus 38(``bus=ID``) a device is attached to along with its address 39(``addr=N``). 40 41Some devices, for example a PCI SCSI host controller, will add an 42additional buses to the system that other devices can be attached to. 43A hypothetical chain of devices might look like: 44 45 --device foo,bus=pci.0,addr=0,id=foo 46 --device bar,bus=foo.0,addr=1,id=baz 47 48which would be a bar device (with the ID of baz) which is attached to 49the first foo bus (foo.0) at address 1. The foo device which provides 50that bus is itself is attached to the first PCI bus (pci.0). 51 52 53Device Back End 54=============== 55 56The back end describes how the data from the emulated device will be 57processed by QEMU. The configuration of the back end is usually 58specific to the class of device being emulated. For example serial 59devices will be backed by a ``--chardev`` which can redirect the data 60to a file or socket or some other system. Storage devices are handled 61by ``--blockdev`` which will specify how blocks are handled, for 62example being stored in a qcow2 file or accessing a raw host disk 63partition. Back ends can sometimes be stacked to implement features 64like snapshots. 65 66While the choice of back end is generally transparent to the guest, 67there are cases where features will not be reported to the guest if 68the back end is unable to support it. 69 70Device Pass Through 71=================== 72 73Device pass through is where the device is actually given access to 74the underlying hardware. This can be as simple as exposing a single 75USB device on the host system to the guest or dedicating a video card 76in a PCI slot to the exclusive use of the guest. 77 78 79Emulated Devices 80~~~~~~~~~~~~~~~~ 81 82.. toctree:: 83 :maxdepth: 1 84 85 devices/can.rst 86 devices/ccid.rst 87 devices/cxl.rst 88 devices/ivshmem.rst 89 devices/keyboard.rst 90 devices/net.rst 91 devices/nvme.rst 92 devices/usb.rst 93 devices/vhost-user.rst 94 devices/virtio-gpu.rst 95 devices/virtio-pmem.rst 96 devices/virtio-snd.rst 97 devices/vhost-user-rng.rst 98 devices/canokey.rst 99 devices/usb-u2f.rst 100 devices/igb.rst 101