From patchwork Sat Feb 4 08:02:32 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 139531 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [140.186.70.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 45D29104799 for ; Sat, 4 Feb 2012 19:03:23 +1100 (EST) Received: from localhost ([::1]:37047 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rtaad-0001JD-Sw for incoming@patchwork.ozlabs.org; Sat, 04 Feb 2012 03:03:19 -0500 Received: from eggs.gnu.org ([140.186.70.92]:34456) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RtaaQ-0001IH-RQ for qemu-devel@nongnu.org; Sat, 04 Feb 2012 03:03:08 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RtaaP-00058b-BH for qemu-devel@nongnu.org; Sat, 04 Feb 2012 03:03:06 -0500 Received: from mail-we0-f173.google.com ([74.125.82.173]:55443) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RtaaP-00057N-2G for qemu-devel@nongnu.org; Sat, 04 Feb 2012 03:03:05 -0500 Received: by mail-we0-f173.google.com with SMTP id h12so3839005wer.4 for ; Sat, 04 Feb 2012 00:03:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=sender:from:to:subject:date:message-id:x-mailer:in-reply-to :references; bh=r/Yt5Uta+IBbG7lJpUa1TJeh504iaubdyEXiFNMdlG4=; b=m1pW/1WrY1iVHDPAMYmAYkr5gwFkfRqWRduSk3Kex1jmK+6RAKiTijW4injWN4Pf58 iCw6vqJRPoShw+rHRd1Zpgqou3vruVb1pE9LyKgGKqIH8mk8reB3Z667iOydTLf+QbRo XHbonS0H61FyKI5rQl3aVPditeEtRiEg2gE1s= Received: by 10.216.138.8 with SMTP id z8mr4086263wei.20.1328342584479; Sat, 04 Feb 2012 00:03:04 -0800 (PST) Received: from yakj.usersys.redhat.com.ACCOR.COM (218.104-246-81.adsl-static.isp.belgacom.be. [81.246.104.218]) by mx.google.com with ESMTPS id m8sm24963019wia.11.2012.02.04.00.03.03 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 04 Feb 2012 00:03:04 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Sat, 4 Feb 2012 09:02:32 +0100 Message-Id: <1328342577-25732-3-git-send-email-pbonzini@redhat.com> X-Mailer: git-send-email 1.7.7.6 In-Reply-To: <1328342577-25732-1-git-send-email-pbonzini@redhat.com> References: <1328342577-25732-1-git-send-email-pbonzini@redhat.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 74.125.82.173 Subject: [Qemu-devel] [PATCH v2 02/27] qom: more documentation on subclassing X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Signed-off-by: Paolo Bonzini Reviewed-by: Anthony Liguori --- include/qemu/object.h | 76 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 files changed, 73 insertions(+), 3 deletions(-) diff --git a/include/qemu/object.h b/include/qemu/object.h index ab1c48c..ad7d32d 100644 --- a/include/qemu/object.h +++ b/include/qemu/object.h @@ -55,6 +55,9 @@ typedef struct InterfaceInfo InterfaceInfo; * * #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; @@ -88,8 +91,21 @@ typedef struct InterfaceInfo InterfaceInfo; * * 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 a macro wrapper around - * object_dynamic_cast_assert() to make it easier to convert to a specific type. + * 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: + * + * + * 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 # * @@ -108,7 +124,61 @@ typedef struct InterfaceInfo InterfaceInfo; * * Once all of the parent classes have been initialized, #TypeInfo::class_init * is called to let the class being instantiated provide default initialize for - * it's virtual functions. + * it's virtual functions. Here is how the above example might be modified + * to introduce an overridden virtual function: + * + * + * 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 TypeInfo my_device_info = { + * .name = TYPE_MY_DEVICE, + * .parent = TYPE_DEVICE, + * .instance_size = sizeof(MyDevice), + * .class_init = my_device_class_init, + * }; + * + * + * + * Introducing new virtual functions requires a class to define its own + * struct and to add a .class_size member to the TypeInfo. Each function + * will also have a wrapper to call it easily: + * + * + * Defining an abstract class + * + * #include "qdev.h" + * + * typedef struct MyDeviceClass + * { + * DeviceClass parent; + * + * void (*frobnicate) (MyDevice *obj); + * } MyDeviceClass; + * + * static 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 # *