All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: fam@euphon.net, berrange@redhat.com,
	"Eduardo Habkost" <ehabkost@redhat.com>,
	f4bug@amsat.org, "Markus Armbruster" <armbru@redhat.com>,
	stefanha@redhat.com, crosa@redhat.com, pbonzini@redhat.com,
	"Alex Bennée" <alex.bennee@linaro.org>,
	aurelien@aurel32.net
Subject: [PATCH v1 02/29] docs: collect the disparate device emulation docs into one section
Date: Wed, 21 Jul 2021 00:26:36 +0100	[thread overview]
Message-ID: <20210720232703.10650-3-alex.bennee@linaro.org> (raw)
In-Reply-To: <20210720232703.10650-1-alex.bennee@linaro.org>

While we are at it add a brief preamble that explains some of the
common concepts in QEMU's device emulation which will hopefully lead
to less confusing about our dizzying command line options.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210714182056.25888-3-alex.bennee@linaro.org>
Cc: Markus Armbruster <armbru@redhat.com>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Daniel P. Berrangé <berrange@redhat.com>
Cc: Eduardo Habkost <ehabkost@redhat.com>

---
v2
  - be a bit more precise about necessity of a buses
  - add an example showing id/bus relations
---
 docs/system/device-emulation.rst          | 89 +++++++++++++++++++++++
 docs/system/{ => devices}/ivshmem.rst     |  0
 docs/system/{ => devices}/net.rst         |  0
 docs/system/{ => devices}/nvme.rst        |  0
 docs/system/{ => devices}/usb.rst         |  0
 docs/system/{ => devices}/virtio-pmem.rst |  0
 docs/system/index.rst                     |  6 +-
 7 files changed, 90 insertions(+), 5 deletions(-)
 create mode 100644 docs/system/device-emulation.rst
 rename docs/system/{ => devices}/ivshmem.rst (100%)
 rename docs/system/{ => devices}/net.rst (100%)
 rename docs/system/{ => devices}/nvme.rst (100%)
 rename docs/system/{ => devices}/usb.rst (100%)
 rename docs/system/{ => devices}/virtio-pmem.rst (100%)

diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
new file mode 100644
index 0000000000..7af5dbefab
--- /dev/null
+++ b/docs/system/device-emulation.rst
@@ -0,0 +1,89 @@
+.. _device-emulation:
+
+Device Emulation
+----------------
+
+QEMU supports the emulation of a large number of devices from
+peripherals such network cards and USB devices to integrated systems
+on a chip (SoCs). Configuration of these is often a source of
+confusion so it helps to have an understanding of some of the terms
+used to describes devices within QEMU.
+
+Common Terms
+~~~~~~~~~~~~
+
+Device Front End
+================
+
+A device front end is how a device is presented to the guest. The type
+of device presented should match the hardware that the guest operating
+system is expecting to see. All devices can be specified with the
+``--device`` command line option. Running QEMU with the command line
+options ``--device help`` will list all devices it is aware of. Using
+the command line ``--device foo,help`` will list the additional
+configuration options available for that device.
+
+A front end is often paired with a back end, which describes how the
+host's resources are used in the emulation.
+
+Device Buses
+============
+
+Most devices will exist on a BUS of some sort. Depending on the
+machine model you choose (``-M foo``) a number of buses will have been
+automatically created. In most cases the BUS a device is attached to
+can be inferred, for example PCI devices are generally automatically
+allocated to the next free address of first PCI bus found. However in
+complicated configurations you can explicitly specify what bus
+(``bus=ID``) a device is attached to along with its address
+(``addr=N``).
+
+Some devices, for example a PCI SCSI host controller, will add an
+additional buses to the system that other devices can be attached to.
+A hypothetical chain of devices might look like:
+
+  --device foo,bus=pci.0,addr=0,id=foo
+  --device bar,bus=foo.0,addr=1,id=baz
+
+which would be a bar device (with the ID of baz) which is attached to
+the first foo bus (foo.0) at address 1. The foo device which provides
+that bus is itself is attached to the first PCI bus (pci.0).
+
+
+Device Back End
+===============
+
+The back end describes how the data from the emulated device will be
+processed by QEMU. The configuration of the back end is usually
+specific to the class of device being emulated. For example serial
+devices will be backed by a ``--chardev`` which can redirect the data
+to a file or socket or some other system. Storage devices are handled
+by ``--blockdev`` which will specify how blocks are handled, for
+example being stored in a qcow2 file or accessing a raw host disk
+partition. Back ends can sometimes be stacked to implement features
+like snapshots.
+
+While the choice of back end is generally transparent to the guest
+there are cases where features will not be reported to the guest if
+the back end is unable to support it.
+
+Device Pass Through
+===================
+
+Device pass through is where the device is actually given access to
+the underlying hardware. This can be as simple as exposing a single
+USB device on the host system to the guest or dedicating a video card
+in a PCI slot to the exclusive use of the guest.
+
+
+Emulated Devices
+~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   devices/ivshmem.rst
+   devices/net.rst
+   devices/nvme.rst
+   devices/usb.rst
+   devices/virtio-pmem.rst
diff --git a/docs/system/ivshmem.rst b/docs/system/devices/ivshmem.rst
similarity index 100%
rename from docs/system/ivshmem.rst
rename to docs/system/devices/ivshmem.rst
diff --git a/docs/system/net.rst b/docs/system/devices/net.rst
similarity index 100%
rename from docs/system/net.rst
rename to docs/system/devices/net.rst
diff --git a/docs/system/nvme.rst b/docs/system/devices/nvme.rst
similarity index 100%
rename from docs/system/nvme.rst
rename to docs/system/devices/nvme.rst
diff --git a/docs/system/usb.rst b/docs/system/devices/usb.rst
similarity index 100%
rename from docs/system/usb.rst
rename to docs/system/devices/usb.rst
diff --git a/docs/system/virtio-pmem.rst b/docs/system/devices/virtio-pmem.rst
similarity index 100%
rename from docs/system/virtio-pmem.rst
rename to docs/system/devices/virtio-pmem.rst
diff --git a/docs/system/index.rst b/docs/system/index.rst
index fda4b1b705..64a424ae99 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -11,15 +11,12 @@ or Hypervisor.Framework.
 
    quickstart
    invocation
+   device-emulation
    keys
    mux-chardev
    monitor
    images
-   net
    virtio-net-failover
-   usb
-   nvme
-   ivshmem
    linuxboot
    generic-loader
    guest-loader
@@ -30,7 +27,6 @@ or Hypervisor.Framework.
    gdb
    managed-startup
    cpu-hotplug
-   virtio-pmem
    pr-manager
    targets
    security
-- 
2.32.0.264.g75ae10bc75



  parent reply	other threads:[~2021-07-20 23:28 UTC|newest]

Thread overview: 36+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-20 23:26 [PATCH for 6.1-rc1 v1 00/29] various fixes pre-PR (metadata, docs, plugins, testing) Alex Bennée
2021-07-20 23:26 ` [PATCH v1 01/29] gitignore: Update with some filetypes Alex Bennée
2021-07-20 23:26 ` Alex Bennée [this message]
2021-07-21 13:25   ` [PATCH v1 02/29] docs: collect the disparate device emulation docs into one section Markus Armbruster
2021-07-20 23:26 ` [PATCH v1 03/29] docs: add a section on the generalities of vhost-user Alex Bennée
2021-07-20 23:26 ` [PATCH v1 04/29] configure: remove needless if leg Alex Bennée
2021-07-20 23:26 ` [PATCH v1 05/29] contrib/gitdm: add some new aliases to fix up commits Alex Bennée
2021-07-20 23:26 ` [PATCH v1 06/29] .mailmap: fix up some broken commit authors Alex Bennée
2021-07-20 23:26 ` [PATCH v1 07/29] contrib/gitdm: add domain-map for MontaVista Alex Bennée
2021-07-20 23:26 ` [PATCH v1 08/29] contrib/gitdm: add a group mapping for robot scanners Alex Bennée
2021-07-20 23:26 ` [PATCH v1 09/29] gitdm.config: sort the corporate GroupMap entries Alex Bennée
2021-07-21  8:06   ` Philippe Mathieu-Daudé
2021-07-20 23:26 ` [PATCH v1 10/29] contrib/gitdm: add domain-map/group-map mappings for Samsung Alex Bennée
2021-07-20 23:26 ` [PATCH v1 11/29] contrib/gitdm: add domain-map for Eldorado Alex Bennée
2021-07-20 23:26 ` [PATCH v1 12/29] contrib/gitdm: add domain-map/group-map for Wind River Alex Bennée
2021-07-20 23:26 ` [PATCH v1 13/29] contrib/gitdm: un-ironically add a mapping for LWN Alex Bennée
2021-07-20 23:26 ` [PATCH v1 14/29] contrib/gitdm: add domain-map for Crudebyte Alex Bennée
2021-07-20 23:26 ` [PATCH v1 15/29] contrib/gitdm: add domain-map for NVIDIA Alex Bennée
2021-07-20 23:26 ` [PATCH v1 16/29] contrib/gitdm: add group-map for Netflix Alex Bennée
2021-07-20 23:26 ` [PATCH v1 17/29] contrib/gitdm: add an explicit academic entry for BU Alex Bennée
2021-07-20 23:26 ` [PATCH v1 18/29] contrib/gitdm: add a new interns group-map for GSoC/Outreachy work Alex Bennée
2021-07-20 23:26 ` [PATCH v1 19/29] contrib/gitdm: add more individual contributor entries Alex Bennée
2021-07-20 23:26 ` [PATCH v1 20/29] tcg/plugins: implement a qemu_plugin_user_exit helper Alex Bennée
2021-07-20 23:26 ` [PATCH v1 21/29] plugins/cache: Fixed a bug with destroying FIFO metadata Alex Bennée
2021-07-20 23:26 ` [PATCH v1 22/29] plugins/cache: limited the scope of a mutex lock Alex Bennée
2021-07-20 23:26 ` [PATCH v1 23/29] plugins/cache: Fixed "function decl. is not a prototype" warnings Alex Bennée
2021-07-21  8:09   ` Philippe Mathieu-Daudé
2021-07-20 23:26 ` [PATCH v1 24/29] plugins: Fix physical address calculation for IO regions Alex Bennée
2021-07-20 23:26 ` [PATCH v1 25/29] hw/tricore: fix inclusion of tricore_testboard Alex Bennée
2021-08-02 16:07   ` Bastian Koppelmann
2021-07-20 23:27 ` [PATCH v1 26/29] tests/tcg/configure.sh: add handling for assembler only builds Alex Bennée
2021-07-20 23:27 ` [PATCH v1 27/29] gitlab: enable a very minimal build with the tricore container Alex Bennée
2021-07-21  7:05   ` Thomas Huth
2021-07-21 15:00   ` Willian Rampazzo
2021-07-20 23:27 ` [PATCH v1 28/29] gitlab-ci: Remove the second superfluous macos task Alex Bennée
2021-07-20 23:27 ` [PATCH v1 29/29] gitlab-ci: Extract OpenSBI job rules to reusable section Alex Bennée

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210720232703.10650-3-alex.bennee@linaro.org \
    --to=alex.bennee@linaro.org \
    --cc=armbru@redhat.com \
    --cc=aurelien@aurel32.net \
    --cc=berrange@redhat.com \
    --cc=crosa@redhat.com \
    --cc=ehabkost@redhat.com \
    --cc=f4bug@amsat.org \
    --cc=fam@euphon.net \
    --cc=pbonzini@redhat.com \
    --cc=qemu-devel@nongnu.org \
    --cc=stefanha@redhat.com \
    --subject='Re: [PATCH v1 02/29] docs: collect the disparate device emulation docs into one section' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.