Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

- vhost-scsi: add bootindex property
- RCU: fix MemoryRegion lifetime issues in PCI; document the rules;
convert of AddressSpaceDispatch and RAMList
- KVM: add kvm_exit reasons for aarch64

# gpg: Signature made Mon Feb 16 16:32:32 2015 GMT using RSA key ID 78C7AE83
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>"
# gpg:                 aka "Paolo Bonzini <pbonzini@redhat.com>"
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4  E2F7 7E15 100C CD36 69B1
#      Subkey fingerprint: F133 3857 4B66 2389 866C  7682 BFFB D25F 78C7 AE83

* remotes/bonzini/tags/for-upstream: (21 commits)
  Convert ram_list to RCU
  exec: convert ram_list to QLIST
  cosmetic changes preparing for the following patches
  exec: protect mru_block with RCU
  rcu: add g_free_rcu
  rcu: introduce RCU-enabled QLIST
  exec: RCUify AddressSpaceDispatch
  exec: make iotlb RCU-friendly
  exec: introduce cpu_reload_memory_map
  docs: clarify memory region lifecycle
  pci: split shpc_cleanup and shpc_free
  pcie: remove mmconfig memory leak and wrap mmconfig update with transaction
  memory: keep the owner of the AddressSpace alive until do_address_space_destroy
  rcu: run RCU callbacks under the BQL
  rcu: do not let RCU callbacks pile up indefinitely
  vhost-scsi: set the bootable value of channel/target/lun
  vhost-scsi: add a property for booting
  vhost-scsi: expose the TYPE_FW_PATH_PROVIDER interface
  vhost-scsi: add bootindex property
  qdev: support to get a device firmware path directly
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

2 files changed, 65 insertions, 20 deletions

diff --git a/docs/memory.txt b/docs/memory.txt
index b12f1f0..2ceb348 100644
--- a/docs/memory.txt
+++ b/docs/memory.txt
@@ -73,17 +73,66 @@ stability.
 Region lifecycle
 ----------------
 
-A region is created by one of the constructor functions (memory_region_init*())
-and attached to an object.  It is then destroyed by object_unparent() or simply
-when the parent object dies.
+A region is created by one of the memory_region_init*() functions and
+attached to an object, which acts as its owner or parent.  QEMU ensures
+that the owner object remains alive as long as the region is visible to
+the guest, or as long as the region is in use by a virtual CPU or another
+device.  For example, the owner object will not die between an
+address_space_map operation and the corresponding address_space_unmap.
 
-In between, a region can be added to an address space
-by using memory_region_add_subregion() and removed using
-memory_region_del_subregion().  Destroying the region implicitly
-removes the region from the address space.
+After creation, a region can be added to an address space or a
+container with memory_region_add_subregion(), and removed using
+memory_region_del_subregion().
+
+Various region attributes (read-only, dirty logging, coalesced mmio,
+ioeventfd) can be changed during the region lifecycle.  They take effect
+as soon as the region is made visible.  This can be immediately, later,
+or never.
+
+Destruction of a memory region happens automatically when the owner
+object dies.
+
+If however the memory region is part of a dynamically allocated data
+structure, you should call object_unparent() to destroy the memory region
+before the data structure is freed.  For an example see VFIOMSIXInfo
+and VFIOQuirk in hw/vfio/pci.c.
+
+You must not destroy a memory region as long as it may be in use by a
+device or CPU.  In order to do this, as a general rule do not create or
+destroy memory regions dynamically during a device's lifetime, and only
+call object_unparent() in the memory region owner's instance_finalize
+callback.  The dynamically allocated data structure that contains the
+memory region then should obviously be freed in the instance_finalize
+callback as well.
+
+If you break this rule, the following situation can happen:
+
+- the memory region's owner had a reference taken via memory_region_ref
+  (for example by address_space_map)
+
+- the region is unparented, and has no owner anymore
+
+- when address_space_unmap is called, the reference to the memory region's
+  owner is leaked.
+
+
+There is an exception to the above rule: it is okay to call
+object_unparent at any time for an alias or a container region.  It is
+therefore also okay to create or destroy alias and container regions
+dynamically during a device's lifetime.
+
+This exceptional usage is valid because aliases and containers only help
+QEMU building the guest's memory map; they are never accessed directly.
+memory_region_ref and memory_region_unref are never called on aliases
+or containers, and the above situation then cannot happen.  Exploiting
+this exception is rarely necessary, and therefore it is discouraged,
+but nevertheless it is used in a few places.
+
+For regions that "have no owner" (NULL is passed at creation time), the
+machine object is actually used as the owner.  Since instance_finalize is
+never called for the machine object, you must never call object_unparent
+on regions that have no owner, unless they are aliases or containers.
 
-Region attributes may be changed at any point; they take effect once
-the region becomes exposed to the guest.
 
 Overlapping regions and priority
 --------------------------------
@@ -215,13 +264,6 @@ BAR containing MMIO registers is mapped after it.
 Note that if the guest maps a BAR outside the PCI hole, it would not be
 visible as the pci-hole alias clips it to a 0.5GB range.
 
-Attributes
-----------
-
-Various region attributes (read-only, dirty logging, coalesced mmio, ioeventfd)
-can be changed during the region lifecycle.  They take effect once the region
-is made visible (which can be immediately, later, or never).
-
 MMIO Operations
 ---------------
 
diff --git a/docs/rcu.txt b/docs/rcu.txt
index 61752b9..21ecb81 100644
--- a/docs/rcu.txt
+++ b/docs/rcu.txt
@@ -120,12 +120,15 @@ The core RCU API is small:
      void call_rcu(T *p,
                    void (*func)(T *p),
                    field-name);
+     void g_free_rcu(T *p,
+                     field-name);
 
-        call_rcu1 is typically used through this macro, in the common case
-        where the "struct rcu_head" is the first field in the struct.  In
-        the above case, one could have written simply:
+        call_rcu1 is typically used through these macro, in the common case
+        where the "struct rcu_head" is the first field in the struct.  If
+        the callback function is g_free, in particular, g_free_rcu can be
+        used.  In the above case, one could have written simply:
 
-            call_rcu(foo_reclaim, g_free, rcu);
+            g_free_rcu(foo_reclaim, rcu);
 
      typeof(*p) atomic_rcu_read(p);