1189c099fSAlex Bennée.. _device-emulation: 2189c099fSAlex Bennée 3189c099fSAlex BennéeDevice Emulation 4189c099fSAlex Bennée---------------- 5189c099fSAlex Bennée 6189c099fSAlex BennéeQEMU supports the emulation of a large number of devices from 7189c099fSAlex Bennéeperipherals such network cards and USB devices to integrated systems 8189c099fSAlex Bennéeon a chip (SoCs). Configuration of these is often a source of 9189c099fSAlex Bennéeconfusion so it helps to have an understanding of some of the terms 10189c099fSAlex Bennéeused to describes devices within QEMU. 11189c099fSAlex Bennée 12189c099fSAlex BennéeCommon Terms 13189c099fSAlex Bennée~~~~~~~~~~~~ 14189c099fSAlex Bennée 15189c099fSAlex BennéeDevice Front End 16189c099fSAlex Bennée================ 17189c099fSAlex Bennée 18189c099fSAlex BennéeA device front end is how a device is presented to the guest. The type 19189c099fSAlex Bennéeof device presented should match the hardware that the guest operating 20189c099fSAlex Bennéesystem is expecting to see. All devices can be specified with the 21189c099fSAlex Bennée``--device`` command line option. Running QEMU with the command line 22189c099fSAlex Bennéeoptions ``--device help`` will list all devices it is aware of. Using 23189c099fSAlex Bennéethe command line ``--device foo,help`` will list the additional 24189c099fSAlex Bennéeconfiguration options available for that device. 25189c099fSAlex Bennée 26189c099fSAlex BennéeA front end is often paired with a back end, which describes how the 27189c099fSAlex Bennéehost's resources are used in the emulation. 28189c099fSAlex Bennée 29189c099fSAlex BennéeDevice Buses 30189c099fSAlex Bennée============ 31189c099fSAlex Bennée 32189c099fSAlex BennéeMost devices will exist on a BUS of some sort. Depending on the 33189c099fSAlex Bennéemachine model you choose (``-M foo``) a number of buses will have been 34189c099fSAlex Bennéeautomatically created. In most cases the BUS a device is attached to 35189c099fSAlex Bennéecan be inferred, for example PCI devices are generally automatically 36189c099fSAlex Bennéeallocated to the next free address of first PCI bus found. However in 37189c099fSAlex Bennéecomplicated configurations you can explicitly specify what bus 38189c099fSAlex Bennée(``bus=ID``) a device is attached to along with its address 39189c099fSAlex Bennée(``addr=N``). 40189c099fSAlex Bennée 41189c099fSAlex BennéeSome devices, for example a PCI SCSI host controller, will add an 42189c099fSAlex Bennéeadditional buses to the system that other devices can be attached to. 43189c099fSAlex BennéeA hypothetical chain of devices might look like: 44189c099fSAlex Bennée 45189c099fSAlex Bennée --device foo,bus=pci.0,addr=0,id=foo 46189c099fSAlex Bennée --device bar,bus=foo.0,addr=1,id=baz 47189c099fSAlex Bennée 48189c099fSAlex Bennéewhich would be a bar device (with the ID of baz) which is attached to 49189c099fSAlex Bennéethe first foo bus (foo.0) at address 1. The foo device which provides 50189c099fSAlex Bennéethat bus is itself is attached to the first PCI bus (pci.0). 51189c099fSAlex Bennée 52189c099fSAlex Bennée 53189c099fSAlex BennéeDevice Back End 54189c099fSAlex Bennée=============== 55189c099fSAlex Bennée 56189c099fSAlex BennéeThe back end describes how the data from the emulated device will be 57189c099fSAlex Bennéeprocessed by QEMU. The configuration of the back end is usually 58189c099fSAlex Bennéespecific to the class of device being emulated. For example serial 59189c099fSAlex Bennéedevices will be backed by a ``--chardev`` which can redirect the data 60189c099fSAlex Bennéeto a file or socket or some other system. Storage devices are handled 61189c099fSAlex Bennéeby ``--blockdev`` which will specify how blocks are handled, for 62189c099fSAlex Bennéeexample being stored in a qcow2 file or accessing a raw host disk 63189c099fSAlex Bennéepartition. Back ends can sometimes be stacked to implement features 64189c099fSAlex Bennéelike snapshots. 65189c099fSAlex Bennée 66189c099fSAlex BennéeWhile the choice of back end is generally transparent to the guest, 67189c099fSAlex Bennéethere are cases where features will not be reported to the guest if 68189c099fSAlex Bennéethe back end is unable to support it. 69189c099fSAlex Bennée 70189c099fSAlex BennéeDevice Pass Through 71189c099fSAlex Bennée=================== 72189c099fSAlex Bennée 73189c099fSAlex BennéeDevice pass through is where the device is actually given access to 74189c099fSAlex Bennéethe underlying hardware. This can be as simple as exposing a single 75189c099fSAlex BennéeUSB device on the host system to the guest or dedicating a video card 76189c099fSAlex Bennéein a PCI slot to the exclusive use of the guest. 77189c099fSAlex Bennée 78189c099fSAlex Bennée 79189c099fSAlex BennéeEmulated Devices 80189c099fSAlex Bennée~~~~~~~~~~~~~~~~ 81189c099fSAlex Bennée 82189c099fSAlex Bennée.. toctree:: 83189c099fSAlex Bennée :maxdepth: 1 84189c099fSAlex Bennée 8587f14eaaSLucas Ramage devices/can.rst 8646676192SLucas Ramage devices/ccid.rst 87aa69abe6SJonathan Cameron devices/cxl.rst 88189c099fSAlex Bennée devices/ivshmem.rst 89189c099fSAlex Bennée devices/net.rst 90189c099fSAlex Bennée devices/nvme.rst 91189c099fSAlex Bennée devices/usb.rst 9215d9c3ceSAlex Bennée devices/vhost-user.rst 93189c099fSAlex Bennée devices/virtio-pmem.rst 94c47d4fa0SMathieu Poirier devices/vhost-user-rng.rst 95994e735cSHongren (Zenithal) Zheng devices/canokey.rst 96*136e9dbaSAkihiko Odaki devices/igb.rst 97