From 2a28720d773df2193c9fb633c02092cca107a9e5 Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@redhat.com>
Date: Mon, 12 Aug 2019 07:23:41 +0200
Subject: [PATCH] typedefs: Separate incomplete types and function types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

While there, rewrite the obsolete file comment.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20190812052359.30071-12-armbru@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
[File comment rewritten, commit message adjusted]
---
 include/qemu/typedefs.h | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/include/qemu/typedefs.h b/include/qemu/typedefs.h
index fcdaae58c44..7fb165423a1 100644
--- a/include/qemu/typedefs.h
+++ b/include/qemu/typedefs.h
@@ -1,10 +1,26 @@
 #ifndef QEMU_TYPEDEFS_H
 #define QEMU_TYPEDEFS_H
 
-/* A load of opaque types so that device init declarations don't have to
-   pull in all the real definitions.  */
+/*
+ * This header is for selectively avoiding #include just to get a
+ * typedef name.
+ *
+ * Declaring a typedef name in its "obvious" place can result in
+ * inclusion cycles, in particular for complete struct and union
+ * types that need more types for their members.  It can also result
+ * in headers pulling in many more headers, slowing down builds.
+ *
+ * You can break such cycles and unwanted dependencies by declaring
+ * the typedef name here.
+ *
+ * For struct types used in only a few headers, judicious use of the
+ * struct tag instead of the typedef name is commonly preferable.
+ */
 
-/* Please keep this list in case-insensitive alphabetical order */
+/*
+ * Incomplete struct types
+ * Please keep this list in case-insensitive alphabetical order.
+ */
 typedef struct AdapterInfo AdapterInfo;
 typedef struct AddressSpace AddressSpace;
 typedef struct AioContext AioContext;
@@ -101,6 +117,10 @@ typedef struct SHPCDevice SHPCDevice;
 typedef struct SSIBus SSIBus;
 typedef struct VirtIODevice VirtIODevice;
 typedef struct Visitor Visitor;
+
+/*
+ * Function types
+ */
 typedef void SaveStateHandler(QEMUFile *f, void *opaque);
 typedef int LoadStateHandler(QEMUFile *f, void *opaque, int version_id);
 
-- 
GitLab