From patchwork Thu Jul 25 16:42:02 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 18584 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-qe0-f69.google.com (mail-qe0-f69.google.com [209.85.128.69]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 5F1BD25DF6 for ; Thu, 25 Jul 2013 16:42:10 +0000 (UTC) Received: by mail-qe0-f69.google.com with SMTP id a11sf840399qen.4 for ; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=mime-version:x-beenthere:x-forwarded-to:x-forwarded-for :delivered-to:from:to:cc:subject:date:message-id:x-mailer :in-reply-to:references:x-gm-message-state:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :x-google-group-id:list-post:list-help:list-archive:list-unsubscribe; bh=l0F7dQnyaA/QkfGpGbkwGfGPOtM4J5mCZPtDn8wHFPM=; b=DWOPbJXmLbAowX/QQ0IJNPpjmpkLhFtHKqYcSg4/FLdy+NahEj9rCQ4rtK5WtUHEuW tL0CvNdx1Y3dWPJ15Kw0VF3tzP5Br8svYn4mA4VYGYGrPVWQhOdN9RBBxIMy0dJzgzmg 2OYo5KvJfwKX52y6C/6kvd7Cz+OVuGuQ+pYwJ6Z8U7Mp9n0FRqAa2bDCSj/QKlEjiYvB tK3lyPZ2wXfpt0iH4m+FNtkzh1pwZ0eNNxJYhP7U3h+CFD5ZXte2F+HBSxuLM4nHdDN2 vVjc9lkpp4y+q8MA+XZ3lw//AUVTdKUfyUPl5rZX6NQS8TtrmPObfIlC6vuqe7iTbLxv 8QAw== X-Received: by 10.236.199.102 with SMTP id w66mr24145692yhn.41.1374770529563; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.82.74 with SMTP id g10ls808511qey.60.gmail; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) X-Received: by 10.52.170.103 with SMTP id al7mr15482582vdc.27.1374770529421; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) Received: from mail-ve0-f181.google.com (mail-ve0-f181.google.com [209.85.128.181]) by mx.google.com with ESMTPS id t6si4286702vdo.9.2013.07.25.09.42.09 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 25 Jul 2013 09:42:09 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.128.181 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.128.181; Received: by mail-ve0-f181.google.com with SMTP id jz10so610867veb.12 for ; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) X-Received: by 10.58.45.70 with SMTP id k6mr18615464vem.9.1374770529300; Thu, 25 Jul 2013 09:42:09 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.58.165.8 with SMTP id yu8csp86315veb; Thu, 25 Jul 2013 09:42:08 -0700 (PDT) X-Received: by 10.194.110.39 with SMTP id hx7mr31271348wjb.4.1374770527925; Thu, 25 Jul 2013 09:42:07 -0700 (PDT) Received: from mnementh.archaic.org.uk (1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.1.0.0.b.8.0.1.0.0.2.ip6.arpa. [2001:8b0:1d0::1]) by mx.google.com with ESMTPS id mb4si19021176wjb.92.2013.07.25.09.42.07 for (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 25 Jul 2013 09:42:07 -0700 (PDT) Received-SPF: neutral (google.com: 2001:8b0:1d0::1 is neither permitted nor denied by best guess record for domain of pm215@archaic.org.uk) client-ip=2001:8b0:1d0::1; Received: from pm215 by mnementh.archaic.org.uk with local (Exim 4.80) (envelope-from ) id 1V2Oc8-0001iV-2Z; Thu, 25 Jul 2013 17:42:04 +0100 From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Anthony Liguori , =?UTF-8?q?Andreas=20F=C3=A4rber?= , Alexander Graf Subject: [RFC 1/2] Provide infrastructure for marking private QOM struct fields Date: Thu, 25 Jul 2013 17:42:02 +0100 Message-Id: <1374770523-6570-2-git-send-email-peter.maydell@linaro.org> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1374770523-6570-1-git-send-email-peter.maydell@linaro.org> References: <1374770523-6570-1-git-send-email-peter.maydell@linaro.org> X-Gm-Message-State: ALoCoQnYR4suW6AlFHKF+l0kLwIVeKvrK5uEjvuGHzN9W0SHtXngnH4dw+o1cOt/JDHUdCAxT3aN X-Original-Sender: peter.maydell@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.128.181 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , 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 23fc048..7f02f80 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 __private + * #else + * # define __private QEMU_PRIVATE_ATTR + * #endif + * + * typedef struct MyDevice + * { + * __private DeviceState parent; + * + * __private int reg0, reg1, reg2; + * } MyDevice; + * + * typedef struct MyDeviceClass + * { + * __private DeviceClass parent; + * + * void (*frobnicate) (MyDevice *obj); + * } MyDeviceClass; + * + * #undef __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. */