From patchwork Fri May 13 14:30:09 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anthony Liguori X-Patchwork-Id: 95492 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 18313B6EEE for ; Sat, 14 May 2011 00:30:31 +1000 (EST) Received: from localhost ([::1]:53625 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKtNs-0007D4-BT for incoming@patchwork.ozlabs.org; Fri, 13 May 2011 10:30:28 -0400 Received: from eggs.gnu.org ([140.186.70.92]:51789) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKtNd-0007CN-9P for qemu-devel@nongnu.org; Fri, 13 May 2011 10:30:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKtNb-0008I3-Ce for qemu-devel@nongnu.org; Fri, 13 May 2011 10:30:13 -0400 Received: from mail-gy0-f173.google.com ([209.85.160.173]:46044) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKtNb-0008Ht-8w for qemu-devel@nongnu.org; Fri, 13 May 2011 10:30:11 -0400 Received: by gyg4 with SMTP id 4so1057165gyg.4 for ; Fri, 13 May 2011 07:30:10 -0700 (PDT) Received: by 10.236.187.72 with SMTP id x48mr1493250yhm.136.1305297010732; Fri, 13 May 2011 07:30:10 -0700 (PDT) Received: from [192.168.0.107] (cpe-70-123-132-139.austin.res.rr.com [70.123.132.139]) by mx.google.com with ESMTPS id r62sm1117814yhm.95.2011.05.13.07.30.09 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 13 May 2011 07:30:10 -0700 (PDT) Message-ID: <4DCD4071.4040403@codemonkey.ws> Date: Fri, 13 May 2011 09:30:09 -0500 From: Anthony Liguori User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.17) Gecko/20110424 Lightning/1.0b2 Thunderbird/3.1.10 MIME-Version: 1.0 To: Markus Armbruster References: <1305023443-8722-1-git-send-email-kraxel@redhat.com> <201105101624.08253.bradh@frogmouth.net> <4DCBA79B.5040608@redhat.com> <4DCBFBFF.7000203@redhat.com> <4DCBFE2F.7040202@codemonkey.ws> <4DCC0981.4070801@codemonkey.ws> <4DCC21D2.7000409@codemonkey.ws> In-Reply-To: X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 209.85.160.173 Cc: amit.shah@redhat.com, Gerd Hoffmann , Brad Hards , qemu-devel@nongnu.org Subject: Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.) 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 On 05/13/2011 02:35 AM, Markus Armbruster wrote: > Anthony Liguori writes: > >> That's fine. But what better way to ensure a consistent and stable UI >> than having it centralized in one place. > > Consistent, stable, and bit-rotten. Unless you come up with a way to > catch bit-rot immediately. That means on "make", not on "make docs". > > Extra points if the error message points right to the offending source > line. Er, hit send too fast. Here's the next patch. From f5c30c922ce1cf755ef78887f4015c131d8d6841 Mon Sep 17 00:00:00 2001 From: Anthony Liguori Date: Thu, 12 May 2011 10:56:29 -0500 Subject: [PATCH 1/1] qdev: add centralized documentation for qdev (v2) This adds a -qdev-verify option that will confirm that the documentation matches the code. It returns a non-zero exit status if any errors are detected. Signed-off-by: Anthony Liguori --- Makefile | 2 + Makefile.doc | 5 ++ Makefile.objs | 2 +- qdev-doc.h | 23 +++++++++++ qdev-doc.json | 16 ++++++++ qemu-options.hx | 10 +++++ scripts/qdev-doc-to-c.py | 30 ++++++++++++++ scripts/qdev-doc-to-html.py | 40 +++++++++++++++++++ vl.c | 89 +++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 216 insertions(+), 1 deletions(-) create mode 100644 Makefile.doc create mode 100644 qdev-doc.h create mode 100644 qdev-doc.json create mode 100644 scripts/qdev-doc-to-c.py create mode 100644 scripts/qdev-doc-to-html.py diff --git a/Makefile b/Makefile index 2b0438c..fddb261 100644 --- a/Makefile +++ b/Makefile @@ -341,5 +341,7 @@ tarbin: $(mandir)/man1/qemu-img.1 \ $(mandir)/man8/qemu-nbd.8 +include $(SRC_PATH)/Makefile.doc + # Include automatically generated dependency files -include $(wildcard *.d audio/*.d slirp/*.d block/*.d net/*.d ui/*.d) diff --git a/Makefile.doc b/Makefile.doc new file mode 100644 index 0000000..c1cf74a --- /dev/null +++ b/Makefile.doc @@ -0,0 +1,5 @@ +qdev-doc.html: $(SRC_PATH)/qdev-doc.json $(SRC_PATH)/scripts/qdev-doc-to-html.py + python $(SRC_PATH)/scripts/qdev-doc-to-html.py < $< > $@ + +qdev-doc.c: $(SRC_PATH)/qdev-doc.json $(SRC_PATH)/scripts/qdev-doc-to-c.py + python $(SRC_PATH)/scripts/qdev-doc-to-c.py < $< > $@ diff --git a/Makefile.objs b/Makefile.objs index 4478c61..9547ab1 100644 --- a/Makefile.objs +++ b/Makefile.objs @@ -97,7 +97,7 @@ common-obj-y += bt-hci-csr.o common-obj-y += buffered_file.o migration.o migration-tcp.o common-obj-y += qemu-char.o savevm.o #aio.o common-obj-y += msmouse.o ps2.o -common-obj-y += qdev.o qdev-properties.o +common-obj-y += qdev.o qdev-properties.o qdev-doc.o common-obj-y += block-migration.o iohandler.o common-obj-y += pflib.o common-obj-y += bitmap.o bitops.o diff --git a/qdev-doc.h b/qdev-doc.h new file mode 100644 index 0000000..401e03e --- /dev/null +++ b/qdev-doc.h @@ -0,0 +1,23 @@ +#ifndef QDEV_DOC_H +#define QDEV_DOC_H + +#include "qemu-common.h" + +typedef struct PropertyDocumentation +{ + const char *name; + const char *type; + const char *docs; +} PropertyDocumentation; + +typedef struct DeviceStateDocumentation +{ + const char *name; + PropertyDocumentation *properties; +} DeviceStateDocumentation; + +extern DeviceStateDocumentation device_docs[]; + +bool qdev_verify_docs(void); + +#endif diff --git a/qdev-doc.json b/qdev-doc.json new file mode 100644 index 0000000..a798bff --- /dev/null +++ b/qdev-doc.json @@ -0,0 +1,16 @@ +# -*- Mode: Python -*- + +[ { "device": "isa-serial", + "parent": "ISADevice", + "properties": { + "index": { "type": "uint32", + "doc": "A value from 0-3 that describes which IO regions to expose the device on. This sets appropriate values for iobase and irq." }, + "iobase": { "type": "hex32", + "doc": "The base IO address to expose the device on." }, + "irq": { "type": "uint32", + "doc": "The IRQ to use for the device." }, + "chardev": { "type": "chr", + "doc": "The name of a character device to specify." } + } + } + ] diff --git a/qemu-options.hx b/qemu-options.hx index 9f121ad..a6abab4 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -2378,6 +2378,16 @@ Specify a trace file to log output traces to. ETEXI #endif +DEF("qdev-verify", 0, QEMU_OPTION_qdev_verify, + "-qdev-verify\n" + " Verify qdev properties match documentation\n", + QEMU_ARCH_ALL) +STEXI +@item -qdev-verify +@findex -qdev-verify +Verify qdev properties match documentation. +ETEXI + HXCOMM This is the last statement. Insert new options before this line! STEXI @end table diff --git a/scripts/qdev-doc-to-c.py b/scripts/qdev-doc-to-c.py new file mode 100644 index 0000000..eb7ee59 --- /dev/null +++ b/scripts/qdev-doc-to-c.py @@ -0,0 +1,30 @@ +#!/usr/bin/python + +import sys + +data = sys.stdin.read() + +docs = eval(data) + +sys.stdout.write(''' +#include "qdev-doc.h" + +DeviceStateDocumentation device_docs[] = {''') + +for item in docs: + sys.stdout.write(''' + { + .name = "%(device)s", + .properties = (PropertyDocumentation[]){''' % item) + for prop in item["properties"]: + sys.stdout.write(''' + { "%s", "%s", "%s" },''' % (prop, item["properties"][prop]['type'], item["properties"][prop]['doc'])) + + sys.stdout.write(''' + { } }, + },''') + +sys.stdout.write(''' + { } +}; +''') diff --git a/scripts/qdev-doc-to-html.py b/scripts/qdev-doc-to-html.py new file mode 100644 index 0000000..a25fe35 --- /dev/null +++ b/scripts/qdev-doc-to-html.py @@ -0,0 +1,40 @@ +#!/usr/bin/python + +import sys + +data = sys.stdin.read() + +docs = eval(data) + +sys.stdout.write(''' + + +QEMU device documentation + + +''') + +for item in docs: + sys.stdout.write(''' +

%(device)s :: %(parent)s

+ + + + + +''' % item) + for prop in item["properties"]: + sys.stdout.write(''' + + + +''' % (prop, item["properties"][prop]['type'], item["properties"][prop]['doc'])) + + sys.stdout.write(''' +
NameTypeComments
%s%s%s
+''') + +sys.stdout.write(''' + + +''') diff --git a/vl.c b/vl.c index bffba69..b9f6e63 100644 --- a/vl.c +++ b/vl.c @@ -163,6 +163,8 @@ int main(int argc, char **argv) #include "ui/qemu-spice.h" +#include "qdev-doc.h" + //#define DEBUG_NET //#define DEBUG_SLIRP @@ -1298,6 +1300,82 @@ void qemu_system_vmstop_request(int reason) qemu_notify_event(); } +bool qdev_verify_docs(void) +{ + DeviceStateDocumentation *doc; + DeviceInfo *dev; + int errors = 0; + int warnings = 0; + + for (dev = device_info_list; dev; dev = dev->next) { + PropertyDocumentation *prop_doc; + Property *prop; + + for (doc = device_docs; doc->name; doc++) { + if (strcmp(doc->name, dev->name) == 0) { + break; + } + } + + if (doc->name == NULL) { + fprintf(stderr, "Warning: device `%s' is undocumented\n", + dev->name); + warnings++; + continue; + } + + for (prop = dev->props; prop->name; prop++) { + for (prop_doc = doc->properties; prop_doc->name; prop_doc++) { + if (strcmp(prop->name, prop_doc->name) == 0) { + break; + } + } + + if (prop_doc->name == NULL) { + fprintf(stderr, "Warning: device `%s' has undocumented property `%s'\n", + dev->name, prop->name); + warnings++; + } + } + + for (prop_doc = doc->properties; prop_doc->name; prop_doc++) { + for (prop = dev->props; prop->name; prop++) { + if (strcmp(prop->name, prop_doc->name) == 0) { + break; + } + } + + if (prop->name == NULL) { + fprintf(stderr, "Error: device `%s' has documented property `%s' with no definition\n", + dev->name, prop_doc->name); + errors++; + } + } + } + + for (doc = device_docs; doc->name; doc++) { + for (dev = device_info_list; dev; dev = dev->next) { + if (strcmp(doc->name, dev->name) == 0) { + break; + } + } + + if (dev == NULL) { + fprintf(stderr, "Error: documented device `%s' has no definition\n", + doc->name); + errors++; + } + } + + fprintf(stderr, "%d warnings, %d errors.\n", warnings, errors); + + if (errors > 0) { + return true; + } + + return false; +} + void main_loop_wait(int nonblocking) { fd_set rfds, wfds, xfds; @@ -2057,6 +2135,7 @@ int main(int argc, char **argv, char **envp) #endif int defconfig = 1; const char *trace_file = NULL; + bool do_qdev_verify = false; atexit(qemu_run_exit_notifiers); error_set_progname(argv[0]); @@ -2890,6 +2969,9 @@ int main(int argc, char **argv, char **envp) fclose(fp); break; } + case QEMU_OPTION_qdev_verify: + do_qdev_verify = true; + break; default: os_parse_cmd_args(popt->index, optarg); } @@ -3136,6 +3218,13 @@ int main(int argc, char **argv, char **envp) module_call_init(MODULE_INIT_DEVICE); + if (do_qdev_verify) { + if (qdev_verify_docs()) { + exit(1); + } + exit(0); + } + if (qemu_opts_foreach(qemu_find_opts("device"), device_help_func, NULL, 0) != 0) exit(0); -- 1.7.4.1