From nobody Wed May 1 08:46:38 2024 Delivered-To: importer2@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer2=patchew.org@nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1622542443; cv=none; d=zohomail.com; s=zohoarc; b=bF/kde5P85xfOpZD59FL5T/yLWWKdE736BvSScFariambqoapMPKJao/Sla4MoMQVFF9v/4aBGtJTx3bLhuFjcdPWjZzqTXqmM9rmq72rOi47ez1yYdJbGbxmUZmE9vbMC37q/yHD0i5kplXlyE9VRzAdqq6TChKrTiy56Lb/pc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1622542443; h=Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:Sender:Subject:To; bh=5vEyFIn0hat4Soz4d6PIKXr8fmc5BKSw+hHGDueaV/0=; b=l8+/5od2qeIoV11BqV+jwEW0SVaNXI+eWB4x4hjOBNH+D+i+pz7Um88HeX9YNm9iDycJx7wRXn/2rYop9fLduANd7/5pIC7QDwt6hmFrT+4fsvMvhgksAZjmmcrjhNLPfurB3m50Fz/jdqdm7fygKTRRhDLF1aLuzv3pRxu1I/o= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer2=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 162254244326954.10539075929455; Tue, 1 Jun 2021 03:14:03 -0700 (PDT) Received: from localhost ([::1]:43820 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lo1PN-00043z-Np for importer2@patchew.org; Tue, 01 Jun 2021 06:14:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:56348) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lo1JR-0001Uq-Na for qemu-devel@nongnu.org; Tue, 01 Jun 2021 06:07:53 -0400 Received: from beetle.greensocs.com ([5.135.226.135]:47234) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lo1JO-0001N3-RR for qemu-devel@nongnu.org; Tue, 01 Jun 2021 06:07:53 -0400 Received: from localhost.localdomain (cable-24-135-22-90.dynamic.sbb.rs [24.135.22.90]) by beetle.greensocs.com (Postfix) with ESMTPSA id E8B9920775; Tue, 1 Jun 2021 10:07:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=greensocs.com; s=mail; t=1622542066; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc; bh=5vEyFIn0hat4Soz4d6PIKXr8fmc5BKSw+hHGDueaV/0=; b=fATrEj2UwJGli+YZJI/ZnovFLvpohnz5wgj21UytACrn4o0R9dYOD2cYI9PZpy6Zxy33Xb PPdisEmeUqlbKchm36nrGJDAx8lIk3fy2wutduvPrDWKvceSSM+Ef5pLu7iniuGjdR2D/4 q26xWFHTS9dRFH33yIy54JCtu+CbDuI= From: Mirela Grujic To: qemu-devel@nongnu.org Subject: [RFC PATCH] docs/specs: QMP configuration design specification Date: Tue, 1 Jun 2021 12:07:29 +0200 Message-Id: <20210601100729.23006-1-mirela.grujic@greensocs.com> X-Mailer: git-send-email 2.17.1 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer2=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=5.135.226.135; envelope-from=mirela.grujic@greensocs.com; helo=beetle.greensocs.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: edgar.iglesias@xilinx.com, damien.hedde@greensocs.com, mark.burton@greensocs.com, armbru@redhat.com, Mirela Grujic , pbonzini@redhat.com, jsnow@redhat.com Errors-To: qemu-devel-bounces+importer2=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" This document describes the design specification for the configuration of machines using QMP. The QMP configuration will be built on top of the existing: 1) machine initialization phases 2) -preconfig command line option 3) x-exit-preconfig QMP command We plan to implement query-machine-phase and x-machine-init QMP commands, and to enable the device_add QMP command in machine initialized phase. The configuration flow would look like this: 1) Run qemu instance: $ qemu-system-aarch64 \ -qmp unix:./qmp-sock,server \ -preconfig \ ... 2) Run QMP client, e.g. qmp-shell: qemu/scripts/qmp/qmp-shell ./qmp-sock Welcome to the QMP low-level shell! Connected to QEMU 6.0.0 (QEMU) query-machine-phase {"return": {"phase": "accel-created"}} (QEMU) x-machine-init {"return": {}} (QEMU) device_add driver=3D... ... (QEMU) x-exit-preconfig {"return": {}} Signed-off-by: Mirela Grujic --- docs/specs/qmp-configuration.txt | 112 +++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/specs/qmp-configuration.txt diff --git a/docs/specs/qmp-configuration.txt b/docs/specs/qmp-configuratio= n.txt new file mode 100644 index 0000000000..69ff49cae6 --- /dev/null +++ b/docs/specs/qmp-configuration.txt @@ -0,0 +1,112 @@ + +Overview +-------- + +The QMP configuration in the context of this design stands for customizing= an +existing machine using the QEMU Monitor Protocol (QMP). The requirement fo= r such +a configuration comes from the use cases where a complete system-on-chip c= an be +customized: from the number of cores, available peripherals, memories, IRQ +mapping, etc. Our goal is to enable the emulation of customized platforms +without requiring modifications in QEMU, and thus the QEMU recompilation. + +We will perform the QMP configuration from a QMP client that will communic= ate +with QEMU via a socket. As an example of a QMP client, we will include a s= cript, +namely the QMP configurator, that will read QMP commands from a configurat= ion +file and send them to QEMU, one by one. The configuration file will be a t= ext +file that includes only a list of QMP commands to be executed. + +We will start QEMU with the -preconfig command-line option, thus QEMU will= wait +for the QMP configuration at an early initialization phase, before the mac= hine +initialization. The following configuration flow will rely on the machine +initialization phases. In each initialization phase, a set of QMP commands= will +be available for configuring the machine and advancing it to the next +initialization phase. Upon reaching the final initialization phase, the ma= chine +shall be ready to run. We specify detailed configuration flow in +"QMP configuration flow in QEMU." + + +QMP configurator +---------------- + +We decided to include the QMP configurator, a QMP client script that will +communicate with QEMU, to automate the configuration. The QMP configurator= will +read the QMP commands from the configuration file, send each QMP command to +QEMU, and quit at the end or exit earlier in the case of an error. We have= not +envisioned the QMP configurator to be interactive. For debugging purposes,= one +could use the QMP shell instead (scripts/qmp/qmp-shell). + + +QMP configuration file +---------------------- + +The QMP configuration file will be a text file that includes only a list of +QMP commands which configure the machine. QMP commands in the configuratio= n file +shall be in the same format and order as if they were issued using the QMP +shell. The QMP configurator will convert each command into JSON format bef= ore +sending it to QEMU, similarly as the QMP shell does. + +There are several ways to create a configuration file. One approach is to +manually create a list of QMP commands which specify how to configure the +machine. Another convenient method is to generate QMP commands from existi= ng +descriptions, such as the device tree or a proprietary format. Either way,= the +creation of the configuration file is out of the scope of this work. + +However, along with the QMP configurator, we will include an example of the +machine and its configuration file to demonstrate the QMP configuration +approach. + + +QMP configuration flow in QEMU +------------------------------ + +We will build the QMP configuration flow on top of the machine initializat= ion +phases, that are: +1) no-machine: machine does not exist yet (current_machine =3D=3D NULL) +2) machine-created: machine exists, but its accelerator does not + (current_machine->accelerator =3D=3D NULL) +3) accel-created: machine's accelerator is configured + (current_machine->accelerator !=3D NULL), but machine class's init() ha= s not + been called (no properties validated, machine_init_done notifiers not + registered, no sysbus, etc.) +4) initialized: machine class's init() has been called, thus machine prope= rties + are validated, machine_init_done notifiers registered, sysbus realized,= etc. + Devices added at this phase are considered to be cold-plugged. +5) ready: machine_init_done notifiers are called, then QEMU is ready to st= art + CPUs. Devices added at this phase are considered to be hot-plugged. + +We can stop QEMU today using the -preconfig command-line option at phase 3 +('accel-created'). This option was introduced to enable the QMP configurat= ion of +parameters that affect the machine initialization. We cannot add devices at +this point because the machine class's init() has not been called, thus sy= sbus +does not exist yet (a device cannot be added because there is no bus to at= tach +it to). + +QEMU can be also stopped using the -S command-line option at the machine '= ready' +phase. However, it is too late to add devices at this phase because the ma= chine +is already configured, and any devices added at this point are considered = to be +hot-plugged. + +Since the existing -preconfig command-line option stops QEMU too early, an= d the +-S option stops too late, we need a way to stop QEMU in between (after the +machine is initialized and before it becomes ready). + +We will reuse the existing -preconfig command-line option to stop QEMU at = the +'accel-created' phase. Then, we will add a QMP command, namely 'x-machine-= init', +to advance and stop the machine in the next initialization phase +('initialized' phase). We will configure the machine during this phase usi= ng the +existing 'device_add' QMP command. Note that the use of 'device_add' QMP c= ommand +is currently not allowed before the machine is ready. We will enable the u= se of +'device_add' during the 'initialized' phase. + +Once we complete the configuration, we will advance the machine to the 're= ady' +phase using the existing 'x-exit-preconfig' command. Upon the execution of +'x-exit-preconfig' command, the machine will immediately start running the= guest +unless the -S option is provided as the command-line argument. + +We will also implement a QMP command to query the current machine initiali= zation +phase, namely the 'query-machine-phase' command. + +--------------------------------------------------------------------------= ------ + +This work is supported by Xilinx, SiFive, and Greensocs. + --=20 2.17.1