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/ivshmem.rst
88   devices/net.rst
89   devices/nvme.rst
90   devices/usb.rst
91   devices/vhost-user.rst
92   devices/virtio-pmem.rst
93   devices/vhost-user-rng.rst
94