[PATCH v2 00/21] documentation and metadata updates

[PATCH v2 00/21] documentation and metadata updates

[Alex Bennée]

Hi,

Posting v2 as the v1 posting got double posted due to git problems so
it's easier if we reset here.

As with previous release cycles I'll switch to maintaining a single
tree of patches for the current release at any given time. The usual
patch admission rules apply so you won't find any feature changes in
here. This series is mostly a collection of documentation and metadata
tweaks, the later being me getting ready for KVM Forum later this year
;-)

All the gitdm changes are mostly waiting for the Cc'd people to
confirm their mappings but I will accept acks from within the
appropriate organisations. If you use the proper Reviewed-by or
Acked-by tags it will make my life easier because the tooling will do
most of the work for me. I've manually converted positive statements
from v1 to Acked-by.

Otherwise the following need review:

- contrib/gitdm: add more individual contributor entries. (3 acks, 1 sobs)
- contrib/gitdm: add a new interns group-map for GSoC/Outreachy work
- contrib/gitdm: add an explicit academic entry for BU
- contrib/gitdm: add domain-map for NVIDIA
- contrib/gitdm: add domain-map for Syrmia
- contrib/gitdm: add domain-map for ZTE
- contrib/gitdm: un-ironically add a mapping for LWN
- contrib/gitdm: add domain-map/group-map for Wind River
- contrib/gitdm: add domain-map for Eldorado
- contrib/gitdm: add domain-map/group-map mappings for Samsung
- gitdm.config: sort the corporate GroupMap entries
- contrib/gitdm: add a group mapping for robot scanners
- contrib/gitdm: add domain-map for MontaVista
- .mailmap: fix up some broken commit authors
- contrib/gitdm: add some new aliases to fix up commits
- configure: remove needless if leg
- docs: add a section on the generalities of vhost-user
- docs: collect the disparate device emulation docs into one section


Alex Bennée (20):
  docs: collect the disparate device emulation docs into one section
  docs: add a section on the generalities of vhost-user
  configure: remove needless if leg
  contrib/gitdm: add some new aliases to fix up commits
  .mailmap: fix up some broken commit authors
  contrib/gitdm: add domain-map for MontaVista
  contrib/gitdm: add a group mapping for robot scanners
  gitdm.config: sort the corporate GroupMap entries
  contrib/gitdm: add domain-map/group-map mappings for Samsung
  contrib/gitdm: add domain-map for Eldorado
  contrib/gitdm: add domain-map/group-map for Wind River
  contrib/gitdm: un-ironically add a mapping for LWN
  contrib/gitdm: add domain-map for Crudebyte
  contrib/gitdm: add domain-map for ZTE
  contrib/gitdm: add domain-map for Syrmia
  contrib/gitdm: add domain-map for NVIDIA
  contrib/gitdm: add group-map for Netflix
  contrib/gitdm: add an explicit academic entry for BU
  contrib/gitdm: add a new interns group-map for GSoC/Outreachy work
  contrib/gitdm: add more individual contributor entries.

Viresh Kumar (1):
  gitignore: Update with some filetypes

 docs/interop/vhost-user.rst               |  2 +
 docs/system/device-emulation.rst          | 79 +++++++++++++++++++++++
 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/vhost-user.rst        | 59 +++++++++++++++++
 docs/system/{ => devices}/virtio-pmem.rst |  0
 docs/system/index.rst                     |  6 +-
 configure                                 | 10 ++-
 .gitignore                                |  2 +
 .mailmap                                  |  4 ++
 contrib/gitdm/aliases                     |  6 ++
 contrib/gitdm/domain-map                  |  9 +++
 contrib/gitdm/group-map-academics         |  3 +
 contrib/gitdm/group-map-individuals       |  5 ++
 contrib/gitdm/group-map-interns           | 13 ++++
 contrib/gitdm/group-map-netflix           |  5 ++
 contrib/gitdm/group-map-robots            |  7 ++
 contrib/gitdm/group-map-samsung           |  5 ++
 gitdm.config                              | 14 ++--
 21 files changed, 214 insertions(+), 15 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%)
 create mode 100644 docs/system/devices/vhost-user.rst
 rename docs/system/{ => devices}/virtio-pmem.rst (100%)
 create mode 100644 contrib/gitdm/group-map-interns
 create mode 100644 contrib/gitdm/group-map-netflix
 create mode 100644 contrib/gitdm/group-map-robots
 create mode 100644 contrib/gitdm/group-map-samsung

-- 
2.20.1

[PATCH v2 01/21] gitignore: Update with some filetypes

[Alex Bennée]

From: Viresh Kumar <viresh.kumar@linaro.org>

Update .gitignore to ignore .swp and .patch files.

Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <79262dbe1f7888eb02e1911501eebafa6f2f6400.1616583806.git.viresh.kumar@linaro.org>
Message-Id: <20210714093638.21077-2-alex.bennee@linaro.org>
---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 75a4be0724..eb2553026c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,5 @@ GTAGS
 *~
 *.ast_raw
 *.depend_raw
+*.swp
+*.patch
-- 
2.20.1

[PATCH v2 02/21] docs: collect the disparate device emulation docs into one section

[Alex Bennée]

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: <20210714093638.21077-3-alex.bennee@linaro.org>
---
 docs/system/device-emulation.rst          | 78 +++++++++++++++++++++++
 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, 79 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..3156eeac2d
--- /dev/null
+++ b/docs/system/device-emulation.rst
@@ -0,0 +1,78 @@
+.. _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
+============
+
+All devices exist on a BUS. 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 slot of the PCI bus. However in complicated configurations you
+can explicitly specify what bus a device is attached to and its
+address. Some devices, for example a PCI SCSI host controller, will
+add an additional bus to the system that other devices can be attached
+to.
+
+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 6092eb2d91..641d243ba4 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -16,15 +16,12 @@ Contents:
 
    quickstart
    invocation
+   device-emulation
    keys
    mux-chardev
    monitor
    images
-   net
    virtio-net-failover
-   usb
-   nvme
-   ivshmem
    linuxboot
    generic-loader
    guest-loader
@@ -35,7 +32,6 @@ Contents:
    gdb
    managed-startup
    cpu-hotplug
-   virtio-pmem
    pr-manager
    targets
    security
-- 
2.20.1

[PATCH v2 03/21] docs: add a section on the generalities of vhost-user

[Alex Bennée]

While we do mention some of this stuff in the various daemons and
manuals the subtleties of the socket and memory sharing are sometimes
missed. This document attempts to give some background on vhost-user
daemons in general terms.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20210714093638.21077-4-alex.bennee@linaro.org>
---
 docs/interop/vhost-user.rst        |  2 +
 docs/system/device-emulation.rst   |  1 +
 docs/system/devices/vhost-user.rst | 59 ++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+)
 create mode 100644 docs/system/devices/vhost-user.rst

diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst
index d6085f7045..7fc693521e 100644
--- a/docs/interop/vhost-user.rst
+++ b/docs/interop/vhost-user.rst
@@ -1,3 +1,5 @@
+.. _vhost_user_proto:
+
 ===================
 Vhost-user Protocol
 ===================
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 3156eeac2d..ea7e1fd491 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -75,4 +75,5 @@ Emulated Devices
    devices/net.rst
    devices/nvme.rst
    devices/usb.rst
+   devices/vhost-user.rst
    devices/virtio-pmem.rst
diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/vhost-user.rst
new file mode 100644
index 0000000000..86128114fa
--- /dev/null
+++ b/docs/system/devices/vhost-user.rst
@@ -0,0 +1,59 @@
+.. _vhost_user:
+
+vhost-user back ends
+--------------------
+
+vhost-user back ends are way to service the request of VirtIO devices
+outside of QEMU itself. To do this there are a number of things
+required.
+
+vhost-user device
+===================
+
+These are simple stub devices that ensure the VirtIO device is visible
+to the guest. The code is mostly boilerplate although each device has
+a ``chardev`` option which specifies the ID of the ``--chardev``
+device that connects via a socket to the vhost-user *daemon*.
+
+vhost-user daemon
+=================
+
+This is a separate process that is connected to by QEMU via a socket
+following the :ref:`vhost_user_proto`. There are a number of daemons
+that can be built when enabled by the project although any daemon that
+meets the specification for a given device can be used.
+
+Shared memory object
+====================
+
+In order for the daemon to access the VirtIO queues to process the
+requests it needs access to the guest's address space. This is
+achieved via the ``memory-backend-file`` or ``memory-backend-memfd``
+objects. A reference to a file-descriptor which can access this object
+will be passed via the socket as part of the protocol negotiation.
+
+Currently the shared memory object needs to match the size of the main
+system memory as defined by the ``-m`` argument.
+
+Example
+=======
+
+First start you daemon.
+
+.. parsed-literal::
+
+  $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
+
+The you start your QEMU instance specifying the device, chardev and
+memory objects.
+
+.. parsed-literal::
+
+  $ |qemu_system| \\
+      -m 4096 \\
+      -chardev socket,id=ba1,path=/var/run/foo.sock \\
+      -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\
+      -object memory-backend-memfd,id=mem,size=4G,share=on \\
+      -numa node,memdev=mem \\
+        ...
+
-- 
2.20.1

[PATCH v2 04/21] configure: remove needless if leg

[Alex Bennée]

It was pointed out in review of the previous patch that the if leg
isn't needed as the for loop will not enter on an empty $device_archs.

Fixes: d1d5e9eefd ("configure: allow the selection of alternate config in the build")
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210714093638.21077-5-alex.bennee@linaro.org>
---
 configure | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/configure b/configure
index 4d0a2bfdd8..013f327f4a 100755
--- a/configure
+++ b/configure
@@ -5083,12 +5083,10 @@ if test "$skip_meson" = no; then
   echo "[properties]" >> $cross
 
   # unroll any custom device configs
-  if test -n "$device_archs"; then
-      for a in $device_archs; do
-          eval "c=\$devices_${a}"
-          echo "${a}-softmmu = '$c'" >> $cross
-      done
-  fi
+  for a in $device_archs; do
+      eval "c=\$devices_${a}"
+      echo "${a}-softmmu = '$c'" >> $cross
+  done
 
   test -z "$cxx" && echo "link_language = 'c'" >> $cross
   echo "[built-in options]" >> $cross
-- 
2.20.1

[PATCH v2 05/21] contrib/gitdm: add some new aliases to fix up commits

[Alex Bennée]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Yuval Shaia <yuval.shaia.ml@gmail.com>
Message-Id: <20210714093638.21077-6-alex.bennee@linaro.org>
---
 contrib/gitdm/aliases | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/contrib/gitdm/aliases b/contrib/gitdm/aliases
index c1e744312f..c6ed215e68 100644
--- a/contrib/gitdm/aliases
+++ b/contrib/gitdm/aliases
@@ -31,6 +31,9 @@ pbrook@c046a42c-6fe2-441c-8c8c-71466251a162 paul@codesourcery.com
 ths@c046a42c-6fe2-441c-8c8c-71466251a162 ths@networkno.de
 malc@c046a42c-6fe2-441c-8c8c-71466251a162 av1474@comtv.ru
 
+# some broken tags
+yuval.shaia.ml.gmail.com yuval.shaia.ml@gmail.com
+
 # There is also a:
 #    (no author) <(no author)@c046a42c-6fe2-441c-8c8c-71466251a162>
 # for the cvs2svn initialization commit e63c3dc74bf.
-- 
2.20.1

[PATCH v2 06/21] .mailmap: fix up some broken commit authors

[Alex Bennée]

Fixes: 49a6f3bffb ("target/arm: Correct the encoding of MDCCSR_EL0 and DBGDSCRint")
Fixes: 5a07192a04 ("target/i386: Fix handling of k_gs_base register in 32-bit mode in gdbstub")
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Nick Hudson <hnick@vmware.com>
Cc: Marek Dolata <mkdolata@us.ibm.com>
Message-Id: <20210714093638.21077-7-alex.bennee@linaro.org>
---
 .mailmap | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.mailmap b/.mailmap
index a1bd659817..082ff893ab 100644
--- a/.mailmap
+++ b/.mailmap
@@ -27,6 +27,10 @@ Paul Brook <paul@codesourcery.com> pbrook <pbrook@c046a42c-6fe2-441c-8c8c-714662
 Thiemo Seufer <ths@networkno.de> ths <ths@c046a42c-6fe2-441c-8c8c-71466251a162>
 malc <av1474@comtv.ru> malc <malc@c046a42c-6fe2-441c-8c8c-71466251a162>
 
+# Corrupted Author fields
+Marek Dolata <mkdolata@us.ibm.com> mkdolata@us.ibm.com <mkdolata@us.ibm.com>
+Nick Hudson <hnick@vmware.com> hnick@vmware.com <hnick@vmware.com>
+
 # There is also a:
 #    (no author) <(no author)@c046a42c-6fe2-441c-8c8c-71466251a162>
 # for the cvs2svn initialization commit e63c3dc74bf.
-- 
2.20.1

[PATCH v2 07/21] contrib/gitdm: add domain-map for MontaVista

[Alex Bennée]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Corey Minyard <cminyard@mvista.com>
Cc: Corey Minyard <minyard@mvista.com>
Message-Id: <20210714093638.21077-8-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index 0074da618f..efbbb15643 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -18,6 +18,7 @@ igalia.com      Igalia
 intel.com       Intel
 linaro.org      Linaro
 microsoft.com   Microsoft
+mvista.com      MontaVista
 nokia.com       Nokia
 nuviainc.com    NUVIA
 oracle.com      Oracle
-- 
2.20.1

[PATCH v2 08/21] contrib/gitdm: add a group mapping for robot scanners

[Alex Bennée]

This mostly affects Reported-by: tags

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210714093638.21077-9-alex.bennee@linaro.org>
---
 contrib/gitdm/group-map-robots | 7 +++++++
 gitdm.config                   | 3 +++
 2 files changed, 10 insertions(+)
 create mode 100644 contrib/gitdm/group-map-robots

diff --git a/contrib/gitdm/group-map-robots b/contrib/gitdm/group-map-robots
new file mode 100644
index 0000000000..ffd956c2eb
--- /dev/null
+++ b/contrib/gitdm/group-map-robots
@@ -0,0 +1,7 @@
+#
+# There are various automatic robots that occasionally scan and report
+# bugs. Let's group them together here.
+#
+
+# Euler Robot
+euler.robot@huawei.com
diff --git a/gitdm.config b/gitdm.config
index c01c219078..7378238c20 100644
--- a/gitdm.config
+++ b/gitdm.config
@@ -43,6 +43,9 @@ GroupMap contrib/gitdm/group-map-janustech Janus Technologies
 GroupMap contrib/gitdm/group-map-individuals (None)
 GroupMap contrib/gitdm/group-map-academics Academics (various)
 
+# Group together robots and other auto-reporters
+GroupMap contrib/gitdm/group-map-robots Robots (various)
+
 #
 #
 # Use FileTypeMap to map a file types to file names using regular
-- 
2.20.1

[PATCH v2 09/21] gitdm.config: sort the corporate GroupMap entries

[Alex Bennée]

Lets try and keep them that way.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210714093638.21077-10-alex.bennee@linaro.org>
---
 gitdm.config | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/gitdm.config b/gitdm.config
index 7378238c20..a3542d2fc7 100644
--- a/gitdm.config
+++ b/gitdm.config
@@ -28,15 +28,15 @@ EmailMap contrib/gitdm/domain-map
 #
 # Use GroupMap to map a file full of addresses to the
 # same employer. This is used for people that don't post from easily
-# identifiable corporate emails.
+# identifiable corporate emails. Please keep this list sorted.
 #
 
-GroupMap contrib/gitdm/group-map-redhat Red Hat
-GroupMap contrib/gitdm/group-map-wavecomp Wave Computing
 GroupMap contrib/gitdm/group-map-cadence Cadence Design Systems
 GroupMap contrib/gitdm/group-map-codeweavers CodeWeavers
 GroupMap contrib/gitdm/group-map-ibm IBM
 GroupMap contrib/gitdm/group-map-janustech Janus Technologies
+GroupMap contrib/gitdm/group-map-redhat Red Hat
+GroupMap contrib/gitdm/group-map-wavecomp Wave Computing
 
 # Also group together our prolific individual contributors
 # and those working under academic auspices
-- 
2.20.1

[PATCH v2 10/21] contrib/gitdm: add domain-map/group-map mappings for Samsung

[Alex Bennée]

Minwoo's work from their personal address are treated as personal
contributions.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Klaus Jensen <k.jensen@samsung.com>
Cc: Gollu Appalanaidu <anaidu.gollu@samsung.com>
Cc: Minwoo Im <minwoo.im.dev@gmail.com>
Message-Id: <220210714093719.21429-11-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map            | 1 +
 contrib/gitdm/group-map-individuals | 1 +
 contrib/gitdm/group-map-samsung     | 5 +++++
 gitdm.config                        | 1 +
 4 files changed, 8 insertions(+)
 create mode 100644 contrib/gitdm/group-map-samsung

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index efbbb15643..beeb24341e 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -26,6 +26,7 @@ proxmox.com     Proxmox
 quicinc.com     Qualcomm Innovation Center
 redhat.com      Red Hat
 rt-rk.com       RT-RK
+samsung.com     Samsung
 siemens.com     Siemens
 sifive.com      SiFive
 suse.com        SUSE
diff --git a/contrib/gitdm/group-map-individuals b/contrib/gitdm/group-map-individuals
index 36bbb77c39..4ac2f98823 100644
--- a/contrib/gitdm/group-map-individuals
+++ b/contrib/gitdm/group-map-individuals
@@ -29,3 +29,4 @@ mrolnik@gmail.com
 huth@tuxfamily.org
 jhogan@kernel.org
 atar4qemu@gmail.com
+minwoo.im.dev@gmail.com
diff --git a/contrib/gitdm/group-map-samsung b/contrib/gitdm/group-map-samsung
new file mode 100644
index 0000000000..e38c7eeeac
--- /dev/null
+++ b/contrib/gitdm/group-map-samsung
@@ -0,0 +1,5 @@
+#
+# Some Samsung contributors submit via another domain
+#
+
+minwoo.im.dev@gmail.com
diff --git a/gitdm.config b/gitdm.config
index a3542d2fc7..e7a744146e 100644
--- a/gitdm.config
+++ b/gitdm.config
@@ -36,6 +36,7 @@ GroupMap contrib/gitdm/group-map-codeweavers CodeWeavers
 GroupMap contrib/gitdm/group-map-ibm IBM
 GroupMap contrib/gitdm/group-map-janustech Janus Technologies
 GroupMap contrib/gitdm/group-map-redhat Red Hat
+GroupMap contrib/gitdm/group-map-samsung Samsung
 GroupMap contrib/gitdm/group-map-wavecomp Wave Computing
 
 # Also group together our prolific individual contributors
-- 
2.20.1

[PATCH v2 11/21] contrib/gitdm: add domain-map for Eldorado

[Alex Bennée]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Bruno Larsen (billionai) <bruno.larsen@eldorado.org.br>
Cc: Luis Pires <luis.pires@eldorado.org.br>
Message-Id: <20210714093638.21077-12-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index beeb24341e..41875c9e75 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -9,6 +9,7 @@ baidu.com       Baidu
 bytedance.com   ByteDance
 cmss.chinamobile.com China Mobile
 citrix.com      Citrix
+eldorado.org.br Instituto de Pesquisas Eldorado
 fujitsu.com     Fujitsu
 google.com      Google
 greensocs.com   GreenSocs
-- 
2.20.1

[PATCH v2 12/21] contrib/gitdm: add domain-map/group-map for Wind River

[Alex Bennée]

As per discussion at:
  http://patchwork.ozlabs.org/project/qemu-devel/patch/20201004180443.2035359-19-f4bug@amsat.org/

I've added Bin's personal email as an individual contributor.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Bin Meng <bin.meng@windriver.com>
Cc: Ruimei Yan <ruimei.yan@windriver.com>
Cc: Xuzhou Cheng <xuzhou.cheng@windriver.com>
Message-Id: <20210714093719.21429-13-alex.bennee@linaro.org>

---
v2
  - moved Bin's personal address to group-map-individuals
---
 contrib/gitdm/domain-map            | 1 +
 contrib/gitdm/group-map-individuals | 1 +
 2 files changed, 2 insertions(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index 41875c9e75..27b8fbdf8a 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -34,6 +34,7 @@ suse.com        SUSE
 suse.de         SUSE
 virtuozzo.com   Virtuozzo
 wdc.com         Western Digital
+windriver.com   Wind River
 xilinx.com      Xilinx
 yadro.com       YADRO
 yandex-team.ru  Yandex
diff --git a/contrib/gitdm/group-map-individuals b/contrib/gitdm/group-map-individuals
index 4ac2f98823..9b6406e624 100644
--- a/contrib/gitdm/group-map-individuals
+++ b/contrib/gitdm/group-map-individuals
@@ -30,3 +30,4 @@ huth@tuxfamily.org
 jhogan@kernel.org
 atar4qemu@gmail.com
 minwoo.im.dev@gmail.com
+bmeng.cn@gmail.com
-- 
2.20.1

[PATCH v2 13/21] contrib/gitdm: un-ironically add a mapping for LWN

[Alex Bennée]

I think this mainly comes from kernel-doc stuff imported into the QEMU
tree.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Message-Id: <20210714093638.21077-14-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index 27b8fbdf8a..5ac8288716 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -18,6 +18,7 @@ ibm.com         IBM
 igalia.com      Igalia
 intel.com       Intel
 linaro.org      Linaro
+lwn.net         LWN
 microsoft.com   Microsoft
 mvista.com      MontaVista
 nokia.com       Nokia
-- 
2.20.1

[PATCH v2 14/21] contrib/gitdm: add domain-map for Crudebyte

[Alex Bennée]

Let me know if you want to be moved to individual contributor or you
want to keep with the work domain mapping.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Christian Schoenebeck <qemu_oss@crudebyte.com>
Message-Id: <20210714093638.21077-15-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index 5ac8288716..e42861cd11 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -9,6 +9,7 @@ baidu.com       Baidu
 bytedance.com   ByteDance
 cmss.chinamobile.com China Mobile
 citrix.com      Citrix
+crudebyte.com   Crudebyte
 eldorado.org.br Instituto de Pesquisas Eldorado
 fujitsu.com     Fujitsu
 google.com      Google
-- 
2.20.1

[PATCH v2 15/21] contrib/gitdm: add domain-map for ZTE

[Alex Bennée]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Yi Wang <wang.yi59@zte.com.cn>
Cc: Yun Liu <liu.yunh@zte.com.cn>
Message-Id: <20210714093638.21077-16-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index e42861cd11..bada5384dd 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -40,3 +40,4 @@ windriver.com   Wind River
 xilinx.com      Xilinx
 yadro.com       YADRO
 yandex-team.ru  Yandex
+zte.com.cn      ZTE
-- 
2.20.1

[PATCH v2 16/21] contrib/gitdm: add domain-map for Syrmia

[Alex Bennée]

We have multiple engineers contributing from this domain.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Filip Bozuta <Filip.Bozuta@syrmia.com>
Cc: Aleksandar Rikalo <Aleksandar.Rikalo@syrmia.com>
Message-Id: <20210714093638.21077-17-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index bada5384dd..0b0cd9feee 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -34,6 +34,7 @@ siemens.com     Siemens
 sifive.com      SiFive
 suse.com        SUSE
 suse.de         SUSE
+syrmia.com      Syrmia
 virtuozzo.com   Virtuozzo
 wdc.com         Western Digital
 windriver.com   Wind River
-- 
2.20.1

[PATCH v2 17/21] contrib/gitdm: add domain-map for NVIDIA

[Alex Bennée]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Kirti Wankhede <kwankhede@nvidia.com>
Cc: Yishai Hadas <yishaih@nvidia.com>
Message-Id: <20210714093638.21077-18-alex.bennee@linaro.org>
---
 contrib/gitdm/domain-map | 1 +
 1 file changed, 1 insertion(+)

diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
index 0b0cd9feee..329ff09029 100644
--- a/contrib/gitdm/domain-map
+++ b/contrib/gitdm/domain-map
@@ -24,6 +24,7 @@ microsoft.com   Microsoft
 mvista.com      MontaVista
 nokia.com       Nokia
 nuviainc.com    NUVIA
+nvidia.com      NVIDIA
 oracle.com      Oracle
 proxmox.com     Proxmox
 quicinc.com     Qualcomm Innovation Center
-- 
2.20.1

[PATCH v2 18/21] contrib/gitdm: add group-map for Netflix

[Alex Bennée]

Warner confirmed he works for Netflix on IRC.

Message-Id: <20210714093638.21077-19-alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Warner Losh <imp@bsdimp.com>
---
 contrib/gitdm/group-map-netflix | 5 +++++
 gitdm.config                    | 1 +
 2 files changed, 6 insertions(+)
 create mode 100644 contrib/gitdm/group-map-netflix

diff --git a/contrib/gitdm/group-map-netflix b/contrib/gitdm/group-map-netflix
new file mode 100644
index 0000000000..468f95dcb2
--- /dev/null
+++ b/contrib/gitdm/group-map-netflix
@@ -0,0 +1,5 @@
+#
+# Netflix contributors using their personal emails
+#
+
+imp@bsdimp.com
diff --git a/gitdm.config b/gitdm.config
index e7a744146e..17a7746892 100644
--- a/gitdm.config
+++ b/gitdm.config
@@ -35,6 +35,7 @@ GroupMap contrib/gitdm/group-map-cadence Cadence Design Systems
 GroupMap contrib/gitdm/group-map-codeweavers CodeWeavers
 GroupMap contrib/gitdm/group-map-ibm IBM
 GroupMap contrib/gitdm/group-map-janustech Janus Technologies
+GroupMap contrib/gitdm/group-map-netflix Netflix
 GroupMap contrib/gitdm/group-map-redhat Red Hat
 GroupMap contrib/gitdm/group-map-samsung Samsung
 GroupMap contrib/gitdm/group-map-wavecomp Wave Computing
-- 
2.20.1

[PATCH v2 19/21] contrib/gitdm: add an explicit academic entry for BU

[Alex Bennée]

For some reason Alexander's contributions were not getting grouped
from the plain "edu" mapping.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20210714093638.21077-20-alex.bennee@linaro.org>
---
 contrib/gitdm/group-map-academics | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/contrib/gitdm/group-map-academics b/contrib/gitdm/group-map-academics
index bf3c894821..44745ca85b 100644
--- a/contrib/gitdm/group-map-academics
+++ b/contrib/gitdm/group-map-academics
@@ -16,3 +16,6 @@ cota@braap.org
 uni-paderborn.de
 edu
 edu.cn
+
+# Boston University
+bu.edu
-- 
2.20.1

[PATCH v2 20/21] contrib/gitdm: add a new interns group-map for GSoC/Outreachy work

[Alex Bennée]

It makes sense to put our various interns in a group so we can see the
overall impact of GSoC and Outreachy on the project.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Ahmed Karaman <ahmedkhaledkaraman@gmail.com>
Cc: Mahmoud Mandour <ma.mandourr@gmail.com>
Cc: César Belley <cesar.belley@lse.epita.fr>
Message-Id: <20210714093638.21077-21-alex.bennee@linaro.org>
---
 contrib/gitdm/group-map-interns | 13 +++++++++++++
 gitdm.config                    |  3 ++-
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 contrib/gitdm/group-map-interns

diff --git a/contrib/gitdm/group-map-interns b/contrib/gitdm/group-map-interns
new file mode 100644
index 0000000000..fe33a3231e
--- /dev/null
+++ b/contrib/gitdm/group-map-interns
@@ -0,0 +1,13 @@
+#
+# Group together everyone working as an intern via one of the various
+# outreach programs.
+#
+
+# GSoC 2020 Virtual FIDO/U2F security key
+cesar.belley@lse.epita.fr
+
+# GSoC 2020 TCG performance
+ahmedkhaledkaraman@gmail.com
+
+# GSoC 2021 TCG plugins
+ma.mandourr@gmail.com
diff --git a/gitdm.config b/gitdm.config
index 17a7746892..21bb63aff1 100644
--- a/gitdm.config
+++ b/gitdm.config
@@ -41,9 +41,10 @@ GroupMap contrib/gitdm/group-map-samsung Samsung
 GroupMap contrib/gitdm/group-map-wavecomp Wave Computing
 
 # Also group together our prolific individual contributors
-# and those working under academic auspices
+# and those working under academic or intern auspices
 GroupMap contrib/gitdm/group-map-individuals (None)
 GroupMap contrib/gitdm/group-map-academics Academics (various)
+GroupMap contrib/gitdm/group-map-interns GSoC/Outreachy Interns
 
 # Group together robots and other auto-reporters
 GroupMap contrib/gitdm/group-map-robots Robots (various)
-- 
2.20.1

[PATCH v2 21/21] contrib/gitdm: add more individual contributor entries.

[Alex Bennée]

Also ensure Li's canonical gmail address is used.

Message-Id: <20210714100628.10460-1-alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Li Qiang <liq3ea@gmail.com>
Acked-by: Chetan Pant <chetan4windows@gmail.com>
Acked-by: Akihiko Odaki <akihiko.odaki@gmail.com>

---
v2
  - dropped un-acked individuals
---
 contrib/gitdm/aliases               | 3 +++
 contrib/gitdm/group-map-individuals | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/contrib/gitdm/aliases b/contrib/gitdm/aliases
index c6ed215e68..4792413ce7 100644
--- a/contrib/gitdm/aliases
+++ b/contrib/gitdm/aliases
@@ -31,6 +31,9 @@ pbrook@c046a42c-6fe2-441c-8c8c-71466251a162 paul@codesourcery.com
 ths@c046a42c-6fe2-441c-8c8c-71466251a162 ths@networkno.de
 malc@c046a42c-6fe2-441c-8c8c-71466251a162 av1474@comtv.ru
 
+# canonical emails
+liq3ea@163.com liq3ea@gmail.com
+
 # some broken tags
 yuval.shaia.ml.gmail.com yuval.shaia.ml@gmail.com
 
diff --git a/contrib/gitdm/group-map-individuals b/contrib/gitdm/group-map-individuals
index 9b6406e624..f816aa8770 100644
--- a/contrib/gitdm/group-map-individuals
+++ b/contrib/gitdm/group-map-individuals
@@ -31,3 +31,6 @@ jhogan@kernel.org
 atar4qemu@gmail.com
 minwoo.im.dev@gmail.com
 bmeng.cn@gmail.com
+liq3ea@gmail.com
+chetan4windows@gmail.com
+akihiko.odaki@gmail.com
-- 
2.20.1

Re: [PATCH v2 19/21] contrib/gitdm: add an explicit academic entry for BU

[Alexander Bulekov]

On 210714 1920, Alex Bennée wrote:
> For some reason Alexander's contributions were not getting grouped
> from the plain "edu" mapping.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Alexander Bulekov <alxndr@bu.edu>

Reviewed-by: Alexander Bulekov <alxndr@bu.edu>

Thanks!

> Message-Id: <20210714093638.21077-20-alex.bennee@linaro.org>
> ---
>  contrib/gitdm/group-map-academics | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/contrib/gitdm/group-map-academics b/contrib/gitdm/group-map-academics
> index bf3c894821..44745ca85b 100644
> --- a/contrib/gitdm/group-map-academics
> +++ b/contrib/gitdm/group-map-academics
> @@ -16,3 +16,6 @@ cota@braap.org
>  uni-paderborn.de
>  edu
>  edu.cn
> +
> +# Boston University
> +bu.edu
> -- 
> 2.20.1
> 

Re: [PATCH v2 10/21] contrib/gitdm: add domain-map/group-map mappings for Samsung

[Klaus Jensen]

[-- Attachment #1: Type: text/plain, Size: 2389 bytes --]

On Jul 14 19:20, Alex Bennée wrote:
> Minwoo's work from their personal address are treated as personal
> contributions.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Acked-by: Klaus Jensen <k.jensen@samsung.com>
> Cc: Gollu Appalanaidu <anaidu.gollu@samsung.com>
> Cc: Minwoo Im <minwoo.im.dev@gmail.com>
> Message-Id: <220210714093719.21429-11-alex.bennee@linaro.org>
> ---
>  contrib/gitdm/domain-map            | 1 +
>  contrib/gitdm/group-map-individuals | 1 +
>  contrib/gitdm/group-map-samsung     | 5 +++++
>  gitdm.config                        | 1 +
>  4 files changed, 8 insertions(+)
>  create mode 100644 contrib/gitdm/group-map-samsung
> 
> diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
> index efbbb15643..beeb24341e 100644
> --- a/contrib/gitdm/domain-map
> +++ b/contrib/gitdm/domain-map
> @@ -26,6 +26,7 @@ proxmox.com     Proxmox
>  quicinc.com     Qualcomm Innovation Center
>  redhat.com      Red Hat
>  rt-rk.com       RT-RK
> +samsung.com     Samsung
>  siemens.com     Siemens
>  sifive.com      SiFive
>  suse.com        SUSE
> diff --git a/contrib/gitdm/group-map-individuals b/contrib/gitdm/group-map-individuals
> index 36bbb77c39..4ac2f98823 100644
> --- a/contrib/gitdm/group-map-individuals
> +++ b/contrib/gitdm/group-map-individuals
> @@ -29,3 +29,4 @@ mrolnik@gmail.com
>  huth@tuxfamily.org
>  jhogan@kernel.org
>  atar4qemu@gmail.com
> +minwoo.im.dev@gmail.com
> diff --git a/contrib/gitdm/group-map-samsung b/contrib/gitdm/group-map-samsung
> new file mode 100644
> index 0000000000..e38c7eeeac
> --- /dev/null
> +++ b/contrib/gitdm/group-map-samsung
> @@ -0,0 +1,5 @@
> +#
> +# Some Samsung contributors submit via another domain
> +#
> +
> +minwoo.im.dev@gmail.com

I'm not sure how this groupmap works, but was it intentional that you
left Minwoo in the Samsung group map?

> diff --git a/gitdm.config b/gitdm.config
> index a3542d2fc7..e7a744146e 100644
> --- a/gitdm.config
> +++ b/gitdm.config
> @@ -36,6 +36,7 @@ GroupMap contrib/gitdm/group-map-codeweavers CodeWeavers
>  GroupMap contrib/gitdm/group-map-ibm IBM
>  GroupMap contrib/gitdm/group-map-janustech Janus Technologies
>  GroupMap contrib/gitdm/group-map-redhat Red Hat +GroupMap
>  contrib/gitdm/group-map-samsung Samsung GroupMap
>  contrib/gitdm/group-map-wavecomp Wave Computing
>  

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v2 02/21] docs: collect the disparate device emulation docs into one section

[Markus Armbruster]

Cc: QOM maintainers for additional eyes.

Alex Bennée <alex.bennee@linaro.org> writes:

> 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: <20210714093638.21077-3-alex.bennee@linaro.org>
> ---
>  docs/system/device-emulation.rst          | 78 +++++++++++++++++++++++
>  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, 79 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..3156eeac2d
> --- /dev/null
> +++ b/docs/system/device-emulation.rst
> @@ -0,0 +1,78 @@
> +.. _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
> +============
> +
> +All devices exist on a BUS. Depending on the machine model you choose

This isn't true anymore; there are bus-less devices.  To show the
user-pluggable ones, try

    $ qemu-system-FOO -device help | grep -v '", bus'

> +(``-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 slot of the PCI bus. However in complicated configurations you

"The PCI bus" tacitly assumes there's just one.

We actually pick the first bus (in qtree pre-order) that can take
another device.  Best not to rely on the search order; if you care which
bus to plug into, specify it with bus=ID.

"Next free slot" is about the device address on the bus.  Should we
explain the concept "device address on a bus"?

> +can explicitly specify what bus a device is attached to and its
> +address. Some devices, for example a PCI SCSI host controller, will
> +add an additional bus to the system that other devices can be attached

A device can add more than one bus.

> +to.
> +
> +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

Comma, I think.

> +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.

Thanks for writing this up!

> +
> +
> +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 6092eb2d91..641d243ba4 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -16,15 +16,12 @@ Contents:
>  
>     quickstart
>     invocation
> +   device-emulation
>     keys
>     mux-chardev
>     monitor
>     images
> -   net
>     virtio-net-failover
> -   usb
> -   nvme
> -   ivshmem
>     linuxboot
>     generic-loader
>     guest-loader
> @@ -35,7 +32,6 @@ Contents:
>     gdb
>     managed-startup
>     cpu-hotplug
> -   virtio-pmem
>     pr-manager
>     targets
>     security

Re: [PATCH v2 10/21] contrib/gitdm: add domain-map/group-map mappings for Samsung

[Alex Bennée]

Klaus Jensen <its@irrelevant.dk> writes:

> [[PGP Signed Part:Undecided]]
> On Jul 14 19:20, Alex Bennée wrote:
>> Minwoo's work from their personal address are treated as personal
>> contributions.
>> 
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> Acked-by: Klaus Jensen <k.jensen@samsung.com>
>> Cc: Gollu Appalanaidu <anaidu.gollu@samsung.com>
>> Cc: Minwoo Im <minwoo.im.dev@gmail.com>
>> Message-Id: <220210714093719.21429-11-alex.bennee@linaro.org>
>> ---
>>  contrib/gitdm/domain-map            | 1 +
>>  contrib/gitdm/group-map-individuals | 1 +
>>  contrib/gitdm/group-map-samsung     | 5 +++++
>>  gitdm.config                        | 1 +
>>  4 files changed, 8 insertions(+)
>>  create mode 100644 contrib/gitdm/group-map-samsung
>> 
>> diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
>> index efbbb15643..beeb24341e 100644
>> --- a/contrib/gitdm/domain-map
>> +++ b/contrib/gitdm/domain-map
>> @@ -26,6 +26,7 @@ proxmox.com     Proxmox
>>  quicinc.com     Qualcomm Innovation Center
>>  redhat.com      Red Hat
>>  rt-rk.com       RT-RK
>> +samsung.com     Samsung
>>  siemens.com     Siemens
>>  sifive.com      SiFive
>>  suse.com        SUSE
>> diff --git a/contrib/gitdm/group-map-individuals b/contrib/gitdm/group-map-individuals
>> index 36bbb77c39..4ac2f98823 100644
>> --- a/contrib/gitdm/group-map-individuals
>> +++ b/contrib/gitdm/group-map-individuals
>> @@ -29,3 +29,4 @@ mrolnik@gmail.com
>>  huth@tuxfamily.org
>>  jhogan@kernel.org
>>  atar4qemu@gmail.com
>> +minwoo.im.dev@gmail.com
>> diff --git a/contrib/gitdm/group-map-samsung b/contrib/gitdm/group-map-samsung
>> new file mode 100644
>> index 0000000000..e38c7eeeac
>> --- /dev/null
>> +++ b/contrib/gitdm/group-map-samsung
>> @@ -0,0 +1,5 @@
>> +#
>> +# Some Samsung contributors submit via another domain
>> +#
>> +
>> +minwoo.im.dev@gmail.com
>
> I'm not sure how this groupmap works, but was it intentional that you
> left Minwoo in the Samsung group map?

Doh - no - I evidently forgot to remove the samsung one at the same time
as adding him to individual. Will fix.

>
>> diff --git a/gitdm.config b/gitdm.config
>> index a3542d2fc7..e7a744146e 100644
>> --- a/gitdm.config
>> +++ b/gitdm.config
>> @@ -36,6 +36,7 @@ GroupMap contrib/gitdm/group-map-codeweavers CodeWeavers
>>  GroupMap contrib/gitdm/group-map-ibm IBM
>>  GroupMap contrib/gitdm/group-map-janustech Janus Technologies
>>  GroupMap contrib/gitdm/group-map-redhat Red Hat +GroupMap
>>  contrib/gitdm/group-map-samsung Samsung GroupMap
>>  contrib/gitdm/group-map-wavecomp Wave Computing
>>  
>
> [[End of PGP Signed Part]]


-- 
Alex Bennée

Re: [PATCH v2 03/21] docs: add a section on the generalities of vhost-user

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 796 bytes --]

On Wed, Jul 14, 2021 at 07:20:38PM +0100, Alex Bennée wrote:
> While we do mention some of this stuff in the various daemons and
> manuals the subtleties of the socket and memory sharing are sometimes
> missed. This document attempts to give some background on vhost-user
> daemons in general terms.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Stefan Hajnoczi <stefanha@redhat.com>
> Message-Id: <20210714093638.21077-4-alex.bennee@linaro.org>
> ---
>  docs/interop/vhost-user.rst        |  2 +
>  docs/system/device-emulation.rst   |  1 +
>  docs/system/devices/vhost-user.rst | 59 ++++++++++++++++++++++++++++++
>  3 files changed, 62 insertions(+)
>  create mode 100644 docs/system/devices/vhost-user.rst

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v2 20/21] contrib/gitdm: add a new interns group-map for GSoC/Outreachy work

[Mahmoud Mandour]

[-- Attachment #1: Type: text/plain, Size: 540 bytes --]

On Wed, Jul 14, 2021 at 8:28 PM Alex Bennée <alex.bennee@linaro.org> wrote:

> It makes sense to put our various interns in a group so we can see the
> overall impact of GSoC and Outreachy on the project.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Ahmed Karaman <ahmedkhaledkaraman@gmail.com>
> Cc: Mahmoud Mandour <ma.mandourr@gmail.com>
> Cc: César Belley <cesar.belley@lse.epita.fr>
> Message-Id: <20210714093638.21077-21-alex.bennee@linaro.org>
>

Reviewed-by: Mahmoud Mandour <ma.mandourr@gmail.com>

[-- Attachment #2: Type: text/html, Size: 1324 bytes --]

Re: [PATCH v2 17/21] contrib/gitdm: add domain-map for NVIDIA

[Kirti Wankhede]

On 7/14/2021 11:50 PM, Alex Bennée wrote:
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Cc: Kirti Wankhede <kwankhede@nvidia.com>
> Cc: Yishai Hadas <yishaih@nvidia.com>
> Message-Id: <20210714093638.21077-18-alex.bennee@linaro.org>
> ---
>   contrib/gitdm/domain-map | 1 +
>   1 file changed, 1 insertion(+)
> 
> diff --git a/contrib/gitdm/domain-map b/contrib/gitdm/domain-map
> index 0b0cd9feee..329ff09029 100644
> --- a/contrib/gitdm/domain-map
> +++ b/contrib/gitdm/domain-map
> @@ -24,6 +24,7 @@ microsoft.com   Microsoft
>   mvista.com      MontaVista
>   nokia.com       Nokia
>   nuviainc.com    NUVIA
> +nvidia.com      NVIDIA
>   oracle.com      Oracle
>   proxmox.com     Proxmox
>   quicinc.com     Qualcomm Innovation Center
> 

Reviewed-by: Kirti Wankhede <kwankhede@nvidia.com>

Re: [PATCH v2 04/21] configure: remove needless if leg

[Richard Henderson]

On 7/14/21 11:20 AM, Alex Bennée wrote:
> It was pointed out in review of the previous patch that the if leg
> isn't needed as the for loop will not enter on an empty $device_archs.
> 
> Fixes: d1d5e9eefd ("configure: allow the selection of alternate config in the build")
> Signed-off-by: Alex Bennée<alex.bennee@linaro.org>
> Message-Id:<20210714093638.21077-5-alex.bennee@linaro.org>
> ---
>   configure | 10 ++++------
>   1 file changed, 4 insertions(+), 6 deletions(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

r~

Re: [PATCH v2 05/21] contrib/gitdm: add some new aliases to fix up commits

[Richard Henderson]

On 7/14/21 11:20 AM, Alex Bennée wrote:
> Signed-off-by: Alex Bennée<alex.bennee@linaro.org>
> Cc: Yuval Shaia<yuval.shaia.ml@gmail.com>
> Message-Id:<20210714093638.21077-6-alex.bennee@linaro.org>
> ---
>   contrib/gitdm/aliases | 3 +++
>   1 file changed, 3 insertions(+)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

r~

Re: [PATCH v2 02/21] docs: collect the disparate device emulation docs into one section

[Alex Bennée]

Markus Armbruster <armbru@redhat.com> writes:

> Cc: QOM maintainers for additional eyes.
>
> Alex Bennée <alex.bennee@linaro.org> writes:
>
>> 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: <20210714093638.21077-3-alex.bennee@linaro.org>
>> ---
>>  docs/system/device-emulation.rst          | 78 +++++++++++++++++++++++
>>  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, 79 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..3156eeac2d
>> --- /dev/null
>> +++ b/docs/system/device-emulation.rst
>> @@ -0,0 +1,78 @@
>> +.. _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
>> +============
>> +
>> +All devices exist on a BUS. Depending on the machine model you choose
>
> This isn't true anymore; there are bus-less devices.  To show the
> user-pluggable ones, try
>
>     $ qemu-system-FOO -device help | grep -v '", bus'


Are they user-pluggable though? Aside from strange cases like loaders
most of them look like SoC specific adornments which I suspect would
make no sense to attach to another machine type. x86_64 seems to be a
special case has all the various CPU types show up as non-bus devices. 

>
>> +(``-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 slot of the PCI bus. However in complicated configurations you
>
> "The PCI bus" tacitly assumes there's just one.
>
> We actually pick the first bus (in qtree pre-order) that can take
> another device.  Best not to rely on the search order; if you care which
> bus to plug into, specify it with bus=ID.
>
> "Next free slot" is about the device address on the bus.  Should we
> explain the concept "device address on a bus"?
>
>> +can explicitly specify what bus a device is attached to and its
>> +address. Some devices, for example a PCI SCSI host controller, will
>> +add an additional bus to the system that other devices can be attached
>
> A device can add more than one bus.

So how about:

  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.0
    --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 foo bus foo.0 which itself is attached to the first slot of a PCI
  bus pci.0

Maybe we should add a section about device IDs?

-- 
Alex Bennée

Re: [PATCH v2 02/21] docs: collect the disparate device emulation docs into one section

[Markus Armbruster]

Alex Bennée <alex.bennee@linaro.org> writes:

> Markus Armbruster <armbru@redhat.com> writes:
>
>> Cc: QOM maintainers for additional eyes.
>>
>> Alex Bennée <alex.bennee@linaro.org> writes:
>>
>>> 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: <20210714093638.21077-3-alex.bennee@linaro.org>
>>> ---
>>>  docs/system/device-emulation.rst          | 78 +++++++++++++++++++++++
>>>  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, 79 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..3156eeac2d
>>> --- /dev/null
>>> +++ b/docs/system/device-emulation.rst
>>> @@ -0,0 +1,78 @@
>>> +.. _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
>>> +============
>>> +
>>> +All devices exist on a BUS. Depending on the machine model you choose
>>
>> This isn't true anymore; there are bus-less devices.  To show the
>> user-pluggable ones, try
>>
>>     $ qemu-system-FOO -device help | grep -v '", bus'
>
>
> Are they user-pluggable though? Aside from strange cases like loaders
> most of them look like SoC specific adornments which I suspect would
> make no sense to attach to another machine type.

qdev_device_add() has code for plugging bus-less devices.  Goes back to
2f7bd829db "qdev: Fix device_add bus assumptions", 2013-04-16.

>                                                  x86_64 seems to be a
> special case has all the various CPU types show up as non-bus devices. 

The CPU types are non-bus devices everywhere.  For some targets, they're
pluggable.  Check out ppc64 and s390x.

>>> +(``-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 slot of the PCI bus. However in complicated configurations you
>>
>> "The PCI bus" tacitly assumes there's just one.
>>
>> We actually pick the first bus (in qtree pre-order) that can take
>> another device.  Best not to rely on the search order; if you care which
>> bus to plug into, specify it with bus=ID.
>>
>> "Next free slot" is about the device address on the bus.  Should we
>> explain the concept "device address on a bus"?
>>
>>> +can explicitly specify what bus a device is attached to and its
>>> +address. Some devices, for example a PCI SCSI host controller, will
>>> +add an additional bus to the system that other devices can be attached
>>
>> A device can add more than one bus.
>
> So how about:
>
>   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``).

Maybe break the paragraph here?

>                 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.0
>     --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 foo bus foo.0 which itself is attached to the first slot of a PCI
>   bus pci.0

Uh, the naming is... more complicated %-}

    $ ../qemu/bld/qemu-system-x86_64 -device lsi,id=foo.0 -device scsi-cd,bus=foo.0
    qemu-system-x86_64: -device scsi-cd,bus=foo.0: Bus 'foo.0' not found

The bus ID is commonly derived from the ID of the device that provides
it, here 'foo.0'.  The first bus is named ID.0, here 'foo.0.0'.  A
second bus would be named ID.1, and so forth.

The example should say

      --device foo,bus=pci.0,addr=0,id=foo
      --device bar,bus=foo.0,addr=1,id=baz

> Maybe we should add a section about device IDs?

We can always improve on top.