Merge tag 'pull-testing-docs-270423-1' of https://gitlab.com/stsquad/qemu into staging

Testing and documentation updates:

  - bump avocado to 101.0
  - use snapshots for tuxrun baseline tests
  - add sbda-ref test to avocado
  - avoid spurious re-configure in gitlab
  - better description of blockdev options
  - drop FreeBSD 12 from Cirrus CI
  - fix up the ast2[56]00 tests to be more stable
  - improve coverage of ppc64 tests in tuxrun baselines
  - limit plugin tests to just the generic multiarch binaries

# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmRKgI0ACgkQ+9DbCVqe
# KkQG9Qf/fvSaiNvkttmb0OFDf3+Qz1uQ33YzLZxETCwI1cSqpGZbssQUrTJZWgpu
# c7FHzdOnTem3Q3PsBY9UN5oqm5IraXEu+nZRO+QyCwHEZzdL9DBfJs46La4BkWG6
# 9vXbNtXLUPd6qJy9ntcZzRShrYy0x0KeszDq7371LS/fng+zMtaIhm4ck0fVWKnj
# htrZEN6nn+CqEnvOc06ICmxiysUVLGRScWKgAHCS9ORGyOtZsj3vWafBoIC6hwzi
# oM3kebhFsVOdbGdL0ZiBdHZqUGAEq3gr+3CpX/48bQ0pYnuYMX8iHk1FhqEK7Adk
# H9ZLnpYUXVyt70rJUjImPyIHpdyq0A==
# =fCif
# -----END PGP SIGNATURE-----
# gpg: Signature made Thu 27 Apr 2023 03:02:53 PM BST
# gpg:                using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [undefined]
# 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: 6685 AE99 E751 67BC AFC8  DF35 FBD0 DB09 5A9E 2A44

* tag 'pull-testing-docs-270423-1' of https://gitlab.com/stsquad/qemu:
  docs/style: call out the use of GUARD macros
  docs/devel: mention the spacing requirement for QOM
  docs/devel: make a statement about includes
  docs/system: remove excessive punctuation from guest-loader docs
  qemu-options.hx: Update descriptions of memory options for NUMA node
  tests/tcg: limit the scope of the plugin tests
  tests/avocado/tuxrun_baselines.py: improve code coverage for ppc64
  avocado_qemu/__init__.py: factor out the qemu-img finding
  MAINTAINERS: Cover tests/avocado/machine_aspeed.py
  tests/avocado/machine_aspeed: Fix the broken ast2[56]00_evb_sdk tests
  tests/avocado: Make ssh_command_output_contains() globally available
  .gitlab-ci.d/cirrus: Drop the CI job for compiling with FreeBSD 12
  qemu-options: finesse the recommendations around -blockdev
  scripts/device-crash-test: Add a parameter to run with TCG only
  gitlab-ci: Avoid to re-run "configure" in the device-crash-test jobs
  tests/avocado: Add set of boot tests on SBSA-ref
  tests/avocado: use the new snapshots for testing
  tests/requirements.txt: bump up avocado-framework version to 101.0

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

2 files changed, 107 insertions, 0 deletions

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 3e34b07..c923795 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -1,3 +1,5 @@
+.. _qom:
+
 ===========================
 The QEMU Object Model (QOM)
 ===========================
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 68aa776..aa5e083 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -300,6 +300,20 @@ putting those into qemu/typedefs.h instead of including the header.
 
 Cyclic inclusion is forbidden.
 
+Generative Includes
+-------------------
+
+QEMU makes fairly extensive use of the macro pre-processor to
+instantiate multiple similar functions. While such abuse of the macro
+processor isn't discouraged it can make debugging and code navigation
+harder. You should consider carefully if the same effect can be
+achieved by making it easy for the compiler to constant fold or using
+python scripting to generate grep friendly code.
+
+If you do use template header files they should be named with the
+``.c.inc`` or ``.h.inc`` suffix to make it clear they are being
+included for expansion.
+
 C types
 =======
 
@@ -614,6 +628,97 @@ are still some caveats to beware of
 QEMU Specific Idioms
 ********************
 
+QEMU Object Model Declarations
+==============================
+
+The QEMU Object Model (QOM) provides a framework for handling objects
+in the base C language. The first declaration of a storage or class
+structure should always be the parent and leave a visual space between
+that declaration and the new code. It is also useful to separate
+backing for properties (options driven by the user) and internal state
+to make navigation easier.
+
+For a storage structure the first declaration should always be called
+"parent_obj" and for a class structure the first member should always
+be called "parent_class" as below:
+
+.. code-block:: c
+
+    struct MyDeviceState {
+        DeviceState parent_obj;
+
+        /* Properties */
+        int prop_a;
+        char *prop_b;
+        /* Other stuff */
+        int internal_state;
+    };
+
+    struct MyDeviceClass {
+        DeviceClass parent_class;
+
+        void (*new_fn1)(void);
+        bool (*new_fn2)(CPUState *);
+    };
+
+Note that there is no need to provide typedefs for QOM structures
+since these are generated automatically by the QOM declaration macros.
+See :ref:`qom` for more details.
+
+QEMU GUARD macros
+=================
+
+QEMU provides a number of ``_GUARD`` macros intended to make the
+handling of multiple exit paths easier. For example using
+``QEMU_LOCK_GUARD`` to take a lock will ensure the lock is released on
+exit from the function.
+
+.. code-block:: c
+
+    static int my_critical_function(SomeState *s, void *data)
+    {
+        QEMU_LOCK_GUARD(&s->lock);
+        do_thing1(data);
+        if (check_state2(data)) {
+            return -1;
+        }
+        do_thing3(data);
+        return 0;
+    }
+
+will ensure s->lock is released however the function is exited. The
+equivalent code without _GUARD macro makes us to carefully put
+qemu_mutex_unlock() on all exit points:
+
+.. code-block:: c
+
+    static int my_critical_function(SomeState *s, void *data)
+    {
+        qemu_mutex_lock(&s->lock);
+        do_thing1(data);
+        if (check_state2(data)) {
+            qemu_mutex_unlock(&s->lock);
+            return -1;
+        }
+        do_thing3(data);
+        qemu_mutex_unlock(&s->lock);
+        return 0;
+    }
+
+There are often ``WITH_`` forms of macros which more easily wrap
+around a block inside a function.
+
+.. code-block:: c
+
+    WITH_RCU_READ_LOCK_GUARD() {
+        QTAILQ_FOREACH_RCU(kid, &bus->children, sibling) {
+            err = do_the_thing(kid->child);
+            if (err < 0) {
+                return err;
+            }
+        }
+    }
+
 Error handling and reporting
 ============================