From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:46579) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VmKcD-00078i-Qy for qemu-devel@nongnu.org; Fri, 29 Nov 2013 04:44:07 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VmKc5-0000lY-Kn for qemu-devel@nongnu.org; Fri, 29 Nov 2013 04:44:01 -0500 Received: from mx1.redhat.com ([209.132.183.28]:43882) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VmKc5-0000lM-Ac for qemu-devel@nongnu.org; Fri, 29 Nov 2013 04:43:53 -0500 From: armbru@redhat.com Date: Fri, 29 Nov 2013 10:43:45 +0100 Message-Id: <1385718225-26379-3-git-send-email-armbru@redhat.com> In-Reply-To: <1385718225-26379-1-git-send-email-armbru@redhat.com> References: <1385718225-26379-1-git-send-email-armbru@redhat.com> Subject: [Qemu-devel] [PATCH 2/2] qdev: Document that pointer properties kill device_add List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, marcel.a@redhat.com, chouteau@adacore.com, blauwirbel@gmail.com, kraxel@redhat.com, aliguori@amazon.com, edgar.iglesias@gmail.com, afaerber@suse.de From: Markus Armbruster Ask users of DEFINE_PROP_PTR() to set cannot_instantiate_with_device_add_yet, or explain why it's not needed. Signed-off-by: Markus Armbruster --- include/hw/qdev-properties.h | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/include/hw/qdev-properties.h b/include/hw/qdev-properties.h index 692f82e..77c6f7c 100644 --- a/include/hw/qdev-properties.h +++ b/include/hw/qdev-properties.h @@ -122,8 +122,25 @@ extern PropertyInfo qdev_prop_arraylen; #define DEFINE_PROP_PCI_DEVFN(_n, _s, _f, _d) \ DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_pci_devfn, int32_t) +/* + * Please avoid pointer properties. If you must use them, you must + * cover them in their device's class init function as follows: + * + * - If the property must be set, the device cannot be used with + * device_add, so add code like this: + * |* Reason: pointer property "NAME-OF-YOUR-PROP" *| + * DeviceClass *dc = DEVICE_CLASS(class); + * dc->cannot_instantiate_with_device_add_yet = true; + * + * - If the property may safely remain null, document it like this: + * |* + * * Note: pointer property "interrupt_vector" may remain null, thus + * * no need for dc->cannot_instantiate_with_device_add_yet = true; + * *| + */ #define DEFINE_PROP_PTR(_n, _s, _f) \ DEFINE_PROP(_n, _s, _f, qdev_prop_ptr, void*) + #define DEFINE_PROP_CHR(_n, _s, _f) \ DEFINE_PROP(_n, _s, _f, qdev_prop_chr, CharDriverState*) #define DEFINE_PROP_STRING(_n, _s, _f) \ -- 1.8.1.4