docs/system/device-emulation.rst

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