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

* SCSI fix (Dmitry, Li Feng, Li Qiang)
* memory API fixes (Eduardo)
* removal of deprecated '-numa node', 'cpu-add', '-smp' (Igor)
* ACPI fix for VMBus (Jon)
* relocatable install (myself)
* always remove docker containers (myself)
* serial cleanups (Philippe)
* vmware cpuid leaf for tsc and apic frequency (Sunil)
* KVM_FEATURE_ASYNC_PF_INT support (Vitaly)
* i386 XSAVE bugfix (Xiaoyao)
* QOM developer documentation in docs/devel (Eduardo)
* new checkpatch tests (Dov)
* x86_64 syscall fix (Douglas)
* interrupt-based APF fix (Vitaly)
* always create kvmclock (Vitaly)
* fix bios-tables-test (Eduardo)
* KVM PV features cleanup (myself)
* CAN FD (Pavel)

meson:
* fixes (Marc-André, Max, Stefan, Alexander, myself)
* moved libmpathpersist, cocoa, malloc tests (myself)
* support for 0.56 introspected test dependencies (myself)

# gpg: Signature made Wed 30 Sep 2020 18:11:45 BST
# gpg:                using RSA key F13338574B662389866C7682BFFBD25F78C7AE83
# gpg:                issuer "pbonzini@redhat.com"
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" [full]
# gpg:                 aka "Paolo Bonzini <pbonzini@redhat.com>" [full]
# 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-gitlab/tags/for-upstream: (86 commits)
  hw/net/can: Correct Kconfig dependencies
  hw/net/can: Documentation for CTU CAN FD IP open hardware core emulation.
  hw/net/can: CTU CAN FD IP open hardware core emulation.
  hw/net/can/ctucafd: Add CTU CAN FD core register definitions.
  net/can: Add can_dlc2len and can_len2dlc for CAN FD.
  hw/net/can: sja1000 ignore CAN FD frames
  net/can: Initial host SocketCan support for CAN FD.
  target/i386: kvm: do not use kvm_check_extension to find paravirtual capabilities
  bios-tables-test: Remove kernel-irqchip=off option
  target/i386: always create kvmclock device
  target/i386: Fix VM migration when interrupt based APF is enabled
  helper_syscall x86_64: clear exception_is_int
  checkpatch: Detect '%#' or '%0#' in printf-style format strings
  typedefs: Restrict PCMachineState to 'hw/i386/pc.h'
  hw/xen: Split x86-specific declaration from generic hardware ones
  stubs: Split accelerator / hardware related stubs
  sysemu/xen: Add missing 'exec/cpu-common.h' header for ram_addr_t type
  hw/i386/xen: Rename X86/PC specific function as xen_hvm_init_pc()
  docs: Move object.h overview doc comment to qom.rst
  docs: Create docs/devel/qom.rst
  ...

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

3 files changed, 384 insertions, 0 deletions

diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 08e85c6..2ee368f 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -193,6 +193,11 @@ compilation as possible. The Meson "sourceset" functionality is used
 to list the files and their dependency on various configuration  
 symbols.
 
+All executables are built by default, except for some `contrib/`
+binaries that are known to fail to build on some platforms (for example
+32-bit or big-endian platforms).  Tests are also built by default,
+though that might change in the future.
+
 Various subsystems that are common to both tools and emulators have
 their own sourceset, for example `block_ss` for the block device subsystem,
 `chardev_ss` for the character device subsystem, etc.  These sourcesets
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 04773ce..c34b43e 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -31,3 +31,4 @@ Contents:
    reset
    s390-dasd-ipl
    clocks
+   qom
diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
new file mode 100644
index 0000000..0b943b2
--- /dev/null
+++ b/docs/devel/qom.rst
@@ -0,0 +1,378 @@
+===========================
+The QEMU Object Model (QOM)
+===========================
+
+.. highlight:: c
+
+The QEMU Object Model provides a framework for registering user creatable
+types and instantiating objects from those types.  QOM provides the following
+features:
+
+ - System for dynamically registering types
+ - Support for single-inheritance of types
+ - Multiple inheritance of stateless interfaces
+
+.. code-block:: c
+   :caption: Creating a minimal type
+
+   #include "qdev.h"
+
+   #define TYPE_MY_DEVICE "my-device"
+
+   // No new virtual functions: we can reuse the typedef for the
+   // superclass.
+   typedef DeviceClass MyDeviceClass;
+   typedef struct MyDevice
+   {
+       DeviceState parent;
+
+       int reg0, reg1, reg2;
+   } MyDevice;
+
+   static const TypeInfo my_device_info = {
+       .name = TYPE_MY_DEVICE,
+       .parent = TYPE_DEVICE,
+       .instance_size = sizeof(MyDevice),
+   };
+
+   static void my_device_register_types(void)
+   {
+       type_register_static(&my_device_info);
+   }
+
+   type_init(my_device_register_types)
+
+In the above example, we create a simple type that is described by #TypeInfo.
+#TypeInfo describes information about the type including what it inherits
+from, the instance and class size, and constructor/destructor hooks.
+
+Alternatively several static types could be registered using helper macro
+DEFINE_TYPES()
+
+.. code-block:: c
+
+   static const TypeInfo device_types_info[] = {
+       {
+           .name = TYPE_MY_DEVICE_A,
+           .parent = TYPE_DEVICE,
+           .instance_size = sizeof(MyDeviceA),
+       },
+       {
+           .name = TYPE_MY_DEVICE_B,
+           .parent = TYPE_DEVICE,
+           .instance_size = sizeof(MyDeviceB),
+       },
+   };
+
+   DEFINE_TYPES(device_types_info)
+
+Every type has an #ObjectClass associated with it.  #ObjectClass derivatives
+are instantiated dynamically but there is only ever one instance for any
+given type.  The #ObjectClass typically holds a table of function pointers
+for the virtual methods implemented by this type.
+
+Using object_new(), a new #Object derivative will be instantiated.  You can
+cast an #Object to a subclass (or base-class) type using
+object_dynamic_cast().  You typically want to define macro wrappers around
+OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a
+specific type:
+
+.. code-block:: c
+   :caption: Typecasting macros
+
+   #define MY_DEVICE_GET_CLASS(obj) \
+      OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
+   #define MY_DEVICE_CLASS(klass) \
+      OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
+   #define MY_DEVICE(obj) \
+      OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+
+Class Initialization
+====================
+
+Before an object is initialized, the class for the object must be
+initialized.  There is only one class object for all instance objects
+that is created lazily.
+
+Classes are initialized by first initializing any parent classes (if
+necessary).  After the parent class object has initialized, it will be
+copied into the current class object and any additional storage in the
+class object is zero filled.
+
+The effect of this is that classes automatically inherit any virtual
+function pointers that the parent class has already initialized.  All
+other fields will be zero filled.
+
+Once all of the parent classes have been initialized, #TypeInfo::class_init
+is called to let the class being instantiated provide default initialize for
+its virtual functions.  Here is how the above example might be modified
+to introduce an overridden virtual function:
+
+.. code-block:: c
+   :caption: Overriding a virtual function
+
+   #include "qdev.h"
+
+   void my_device_class_init(ObjectClass *klass, void *class_data)
+   {
+       DeviceClass *dc = DEVICE_CLASS(klass);
+       dc->reset = my_device_reset;
+   }
+
+   static const TypeInfo my_device_info = {
+       .name = TYPE_MY_DEVICE,
+       .parent = TYPE_DEVICE,
+       .instance_size = sizeof(MyDevice),
+       .class_init = my_device_class_init,
+   };
+
+Introducing new virtual methods requires a class to define its own
+struct and to add a .class_size member to the #TypeInfo.  Each method
+will also have a wrapper function to call it easily:
+
+.. code-block:: c
+   :caption: Defining an abstract class
+
+   #include "qdev.h"
+
+   typedef struct MyDeviceClass
+   {
+       DeviceClass parent;
+
+       void (*frobnicate) (MyDevice *obj);
+   } MyDeviceClass;
+
+   static const TypeInfo my_device_info = {
+       .name = TYPE_MY_DEVICE,
+       .parent = TYPE_DEVICE,
+       .instance_size = sizeof(MyDevice),
+       .abstract = true, // or set a default in my_device_class_init
+       .class_size = sizeof(MyDeviceClass),
+   };
+
+   void my_device_frobnicate(MyDevice *obj)
+   {
+       MyDeviceClass *klass = MY_DEVICE_GET_CLASS(obj);
+
+       klass->frobnicate(obj);
+   }
+
+Interfaces
+==========
+
+Interfaces allow a limited form of multiple inheritance.  Instances are
+similar to normal types except for the fact that are only defined by
+their classes and never carry any state.  As a consequence, a pointer to
+an interface instance should always be of incomplete type in order to be
+sure it cannot be dereferenced.  That is, you should define the
+'typedef struct SomethingIf SomethingIf' so that you can pass around
+``SomethingIf *si`` arguments, but not define a ``struct SomethingIf { ... }``.
+The only things you can validly do with a ``SomethingIf *`` are to pass it as
+an argument to a method on its corresponding SomethingIfClass, or to
+dynamically cast it to an object that implements the interface.
+
+Methods
+=======
+
+A <emphasis>method</emphasis> is a function within the namespace scope of
+a class. It usually operates on the object instance by passing it as a
+strongly-typed first argument.
+If it does not operate on an object instance, it is dubbed
+<emphasis>class method</emphasis>.
+
+Methods cannot be overloaded. That is, the #ObjectClass and method name
+uniquely identity the function to be called; the signature does not vary
+except for trailing varargs.
+
+Methods are always <emphasis>virtual</emphasis>. Overriding a method in
+#TypeInfo.class_init of a subclass leads to any user of the class obtained
+via OBJECT_GET_CLASS() accessing the overridden function.
+The original function is not automatically invoked. It is the responsibility
+of the overriding class to determine whether and when to invoke the method
+being overridden.
+
+To invoke the method being overridden, the preferred solution is to store
+the original value in the overriding class before overriding the method.
+This corresponds to ``{super,base}.method(...)`` in Java and C#
+respectively; this frees the overriding class from hardcoding its parent
+class, which someone might choose to change at some point.
+
+.. code-block:: c
+   :caption: Overriding a virtual method
+
+   typedef struct MyState MyState;
+
+   typedef void (*MyDoSomething)(MyState *obj);
+
+   typedef struct MyClass {
+       ObjectClass parent_class;
+
+       MyDoSomething do_something;
+   } MyClass;
+
+   static void my_do_something(MyState *obj)
+   {
+       // do something
+   }
+
+   static void my_class_init(ObjectClass *oc, void *data)
+   {
+       MyClass *mc = MY_CLASS(oc);
+
+       mc->do_something = my_do_something;
+   }
+
+   static const TypeInfo my_type_info = {
+       .name = TYPE_MY,
+       .parent = TYPE_OBJECT,
+       .instance_size = sizeof(MyState),
+       .class_size = sizeof(MyClass),
+       .class_init = my_class_init,
+   };
+
+   typedef struct DerivedClass {
+       MyClass parent_class;
+
+       MyDoSomething parent_do_something;
+   } DerivedClass;
+
+   static void derived_do_something(MyState *obj)
+   {
+       DerivedClass *dc = DERIVED_GET_CLASS(obj);
+
+       // do something here
+       dc->parent_do_something(obj);
+       // do something else here
+   }
+
+   static void derived_class_init(ObjectClass *oc, void *data)
+   {
+       MyClass *mc = MY_CLASS(oc);
+       DerivedClass *dc = DERIVED_CLASS(oc);
+
+       dc->parent_do_something = mc->do_something;
+       mc->do_something = derived_do_something;
+   }
+
+   static const TypeInfo derived_type_info = {
+       .name = TYPE_DERIVED,
+       .parent = TYPE_MY,
+       .class_size = sizeof(DerivedClass),
+       .class_init = derived_class_init,
+   };
+
+Alternatively, object_class_by_name() can be used to obtain the class and
+its non-overridden methods for a specific type. This would correspond to
+``MyClass::method(...)`` in C++.
+
+The first example of such a QOM method was #CPUClass.reset,
+another example is #DeviceClass.realize.
+
+Standard type declaration and definition macros
+===============================================
+
+A lot of the code outlined above follows a standard pattern and naming
+convention. To reduce the amount of boilerplate code that needs to be
+written for a new type there are two sets of macros to generate the
+common parts in a standard format.
+
+A type is declared using the OBJECT_DECLARE macro family. In types
+which do not require any virtual functions in the class, the
+OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed
+in the header file:
+
+.. code-block:: c
+   :caption: Declaring a simple type
+
+    OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+
+This is equivalent to the following:
+
+.. code-block:: c
+   :caption: Expansion from declaring a simple type
+
+    typedef struct MyDevice MyDevice;
+    typedef struct MyDeviceClass MyDeviceClass;
+
+    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
+
+    #define MY_DEVICE_GET_CLASS(void *obj) \
+            OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
+    #define MY_DEVICE_CLASS(void *klass) \
+            OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
+    #define MY_DEVICE(void *obj)
+            OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+
+    struct MyDeviceClass {
+        DeviceClass parent_class;
+    };
+
+The 'struct MyDevice' needs to be declared separately.
+If the type requires virtual functions to be declared in the class
+struct, then the alternative OBJECT_DECLARE_TYPE() macro can be
+used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without
+the 'struct MyDeviceClass' definition.
+
+To implement the type, the OBJECT_DEFINE macro family is available.
+In the simple case the OBJECT_DEFINE_TYPE macro is suitable:
+
+.. code-block:: c
+   :caption: Defining a simple type
+
+    OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+
+This is equivalent to the following:
+
+.. code-block:: c
+   :caption: Expansion from defining a simple type
+
+    static void my_device_finalize(Object *obj);
+    static void my_device_class_init(ObjectClass *oc, void *data);
+    static void my_device_init(Object *obj);
+
+    static const TypeInfo my_device_info = {
+        .parent = TYPE_DEVICE,
+        .name = TYPE_MY_DEVICE,
+        .instance_size = sizeof(MyDevice),
+        .instance_init = my_device_init,
+        .instance_finalize = my_device_finalize,
+        .class_size = sizeof(MyDeviceClass),
+        .class_init = my_device_class_init,
+    };
+
+    static void
+    my_device_register_types(void)
+    {
+        type_register_static(&my_device_info);
+    }
+    type_init(my_device_register_types);
+
+This is sufficient to get the type registered with the type
+system, and the three standard methods now need to be implemented
+along with any other logic required for the type.
+
+If the type needs to implement one or more interfaces, then the
+OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead.
+This accepts an array of interface type names.
+
+.. code-block:: c
+   :caption: Defining a simple type implementing interfaces
+
+    OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
+                                       MY_DEVICE, DEVICE,
+                                       { TYPE_USER_CREATABLE }, { NULL })
+
+If the type is not intended to be instantiated, then then
+the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
+
+.. code-block:: c
+   :caption: Defining a simple abstract type
+
+    OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+
+
+
+API Reference
+-------------
+
+.. kernel-doc:: include/qom/object.h