Alex Bennée | 189c099 | 2021-07-21 00:26:36 +0100 | [diff] [blame] | 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 | |
Lucas Ramage | 87f14ea | 2022-01-05 20:56:28 +0000 | [diff] [blame] | 85 | devices/can.rst |
Lucas Ramage | 4667619 | 2022-04-05 14:29:06 +0000 | [diff] [blame] | 86 | devices/ccid.rst |
Jonathan Cameron | aa69abe | 2022-04-29 15:41:07 +0100 | [diff] [blame] | 87 | devices/cxl.rst |
Alex Bennée | 189c099 | 2021-07-21 00:26:36 +0100 | [diff] [blame] | 88 | devices/ivshmem.rst |
| 89 | devices/net.rst |
| 90 | devices/nvme.rst |
| 91 | devices/usb.rst |
Alex Bennée | 15d9c3c | 2021-07-21 00:26:37 +0100 | [diff] [blame] | 92 | devices/vhost-user.rst |
Alex Bennée | 189c099 | 2021-07-21 00:26:36 +0100 | [diff] [blame] | 93 | devices/virtio-pmem.rst |
Mathieu Poirier | c47d4fa | 2021-10-12 14:59:04 -0600 | [diff] [blame] | 94 | devices/vhost-user-rng.rst |
Hongren (Zenithal) Zheng | 994e735 | 2022-05-19 20:39:38 +0800 | [diff] [blame] | 95 | devices/canokey.rst |
Akihiko Odaki | 136e9db | 2023-02-23 19:50:57 +0900 | [diff] [blame] | 96 | devices/igb.rst |