From patchwork Mon Mar 19 15:09:23 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anthony Liguori X-Patchwork-Id: 147549 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 79DFAB6FBE for ; Tue, 20 Mar 2012 02:11:04 +1100 (EST) Received: from localhost ([::1]:47766 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S9eEg-0005Lf-8Q for incoming@patchwork.ozlabs.org; Mon, 19 Mar 2012 11:11:02 -0400 Received: from eggs.gnu.org ([208.118.235.92]:35555) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S9eDc-0003n3-6f for qemu-devel@nongnu.org; Mon, 19 Mar 2012 11:10:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1S9eDI-0000Kr-4I for qemu-devel@nongnu.org; Mon, 19 Mar 2012 11:09:55 -0400 Received: from cpe-70-123-132-139.austin.res.rr.com ([70.123.132.139]:47558 helo=localhost6.localdomain6) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1S9eDH-0000Kd-Tz for qemu-devel@nongnu.org; Mon, 19 Mar 2012 11:09:36 -0400 Received: from localhost6.localdomain6 (localhost.localdomain [127.0.0.1]) by localhost6.localdomain6 (8.14.4/8.14.4/Debian-2ubuntu2) with ESMTP id q2JF9YT0030961; Mon, 19 Mar 2012 10:09:34 -0500 Received: (from anthony@localhost) by localhost6.localdomain6 (8.14.4/8.14.4/Submit) id q2JF9XXf030960; Mon, 19 Mar 2012 10:09:33 -0500 From: Anthony Liguori To: qemu-devel@nongnu.org Date: Mon, 19 Mar 2012 10:09:23 -0500 Message-Id: <1332169763-30665-10-git-send-email-aliguori@us.ibm.com> X-Mailer: git-send-email 1.7.5.4 In-Reply-To: <1332169763-30665-1-git-send-email-aliguori@us.ibm.com> References: <1332169763-30665-1-git-send-email-aliguori@us.ibm.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 70.123.132.139 Cc: Anthony Liguori , Eric Blake , Eduardo Habkost , Gerd Hoffman Subject: [Qemu-devel] [PATCH 9/9] Add a management tool writer's guide 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 I guess it's long overdue at this point, but let's use it to explain how to properly use -query-capabilities. Signed-off-by: Anthony Liguori --- docs/management-tools.md | 31 +++++++++++++++++++++++++++++++ 1 files changed, 31 insertions(+), 0 deletions(-) create mode 100644 docs/management-tools.md diff --git a/docs/management-tools.md b/docs/management-tools.md new file mode 100644 index 0000000..d879e48 --- /dev/null +++ b/docs/management-tools.md @@ -0,0 +1,31 @@ +Writing a QEMU Management Tool +============================== + +This is a guide on writing a QEMU management tool. This document outlines +which interfaces the QEMU project exports and will support long term. + +Specifying options +------------------ + +The preferred way for a management tool to specify options to QEMU is to create +a configuration file and use '-readconfig' on the command line. We prefer this +interface over direct use of command line options because this interface +supports introspection in a machine friendly way. + +Determining if an option is supported +------------------------------------- + +A management tool should use the '-query-capabilities' option to determine what +the capabilities of the current QEMU executable is. The 'config' section of +the resulting JSON object describes all of the config sections that are +currently supported. + +Many options currently fall into the 'system' section and some of these options +have complex syntax. Management tools should assume that these syntaxes will +never change and never be extended. Whenever there is a need to change or +extend this syntax, we will first convert the option to use a stand alone +section. + +While help text is available, the help text *should not* be parsed to attempt to +determine if the option has changed. The help text is exposed merely as a stop +gap to help libvirt transition to this new format.