From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:46180) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Win9c-0002eX-Kj for qemu-devel@nongnu.org; Fri, 09 May 2014 11:56:09 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Win9b-0006rP-Bd for qemu-devel@nongnu.org; Fri, 09 May 2014 11:56:08 -0400 Received: from mnementh.archaic.org.uk ([2001:8b0:1d0::1]:48095) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Win9b-0006rF-3Q for qemu-devel@nongnu.org; Fri, 09 May 2014 11:56:07 -0400 From: Peter Maydell Date: Fri, 9 May 2014 16:56:01 +0100 Message-Id: <1399650964-21067-2-git-send-email-peter.maydell@linaro.org> In-Reply-To: <1399650964-21067-1-git-send-email-peter.maydell@linaro.org> References: <1399650964-21067-1-git-send-email-peter.maydell@linaro.org> Subject: [Qemu-devel] [PATCH v2 1/4] Provide infrastructure for marking private QOM struct fields List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Andreas=20F=C3=A4rber?= , Anthony Liguori , patches@linaro.org Provide infrastructure for marking private QOM struct fields, so that a compiler warning is generated when a user of the QOM object attempts to access them directly. This is implemented using GCC's 'deprecated' attribute; preprocessor macros arrange that when compiling the class implementation, no attribute is applied to the fields; when compiling a user of the class the fields are marked deprecated. This allows us to have a single simple C struct defining the object, and for users of the QOM object to be able to embed instances of it into other structs, but still to have a guard against users accidentally touching parts of the structure they should not be accessing. Signed-off-by: Peter Maydell --- include/qemu/compiler.h | 10 ++++++++++ include/qom/object.h | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/include/qemu/compiler.h b/include/qemu/compiler.h index 155b358..d7cc153 100644 --- a/include/qemu/compiler.h +++ b/include/qemu/compiler.h @@ -52,4 +52,14 @@ #define GCC_FMT_ATTR(n, m) #endif +/* An attribute usable to mark structure fields as private to the + * implementation; since this is only a diagnostic to catch programming + * errors, it's OK if it expands to nothing on non-gcc compilers. + */ +#if defined __GNUC__ +# define QEMU_PRIVATE_ATTR __attribute__((deprecated("this field is private"))) +#else +# define QEMU_PRIVATE_ATTR +#endif + #endif /* COMPILER_H */ diff --git a/include/qom/object.h b/include/qom/object.h index a641dcd..ea80008 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -284,6 +284,53 @@ typedef struct InterfaceInfo InterfaceInfo; * * The first example of such a QOM method was #CPUClass.reset, * another example is #DeviceClass.realize. + * + * = Marking fields as private to the class implementation = + * + * The expected code structure for QOM objects is that they should + * have a header file in include/ which defines the class and object + * structures and the typecasting macros. This header can then be + * included by both the source file which implements the QOM object + * and also by other source files which merely wish to use the object. + * Users of your object need the class and object structures so that + * they can embed instances of the object in their own structures; + * however they do not need to be able to access individual fields in + * these structures. To enforce this you should use the QEMU_PRIVATE_ATTR + * macro in a pattern like this: + * + * + * Marking fields as private + * + * #ifdef IMPLEMENTING_MY_DEVICE + * # define qom_private + * #else + * # define qom_private QEMU_PRIVATE_ATTR + * #endif + * + * typedef struct MyDevice + * { + * qom_private DeviceState parent; + * + * qom_private int reg0, reg1, reg2; + * } MyDevice; + * + * typedef struct MyDeviceClass + * { + * qom_private DeviceClass parent; + * + * void (*frobnicate) (MyDevice *obj); + * } MyDeviceClass; + * + * #undef qom_private + * + * + * + * The source files which provide the implementation of your + * class (or of subclasses to it) should then have + * "#define IMPLEMENTING_MY_DEVICE" before they include any + * headers. Since users of the class will not define this + * macro, they will get a compilation warning if they access + * any of the private fields by mistake. */ -- 1.9.2