From nobody Fri Nov 29 19:23:38 2024 Delivered-To: importer@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+importer=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 1632332234965753.0145883765474; Wed, 22 Sep 2021 10:37:14 -0700 (PDT) Received: from localhost ([::1]:39824 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mT6BF-0002G0-Oz for importer@patchew.org; Wed, 22 Sep 2021 13:37:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:44808) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mT4v4-0003M6-8P; Wed, 22 Sep 2021 12:16:27 -0400 Received: from beetle.greensocs.com ([5.135.226.135]:39278) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mT4v1-0005S5-AB; Wed, 22 Sep 2021 12:16:26 -0400 Received: from crumble.bar.greensocs.com (unknown [172.17.10.6]) by beetle.greensocs.com (Postfix) with ESMTPS id 879E321ED3; Wed, 22 Sep 2021 16:16:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=greensocs.com; s=mail; t=1632327361; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Lg6JGGOuMKgOK9bkuvAzYukD8OqEWtmOgbk2hQPItz8=; b=ND0iqKFzTzDcZ27ooxhDOEEEV8AccARG7AJHhC9a02u1e9KnwGeBRww88INrFwYdnUiGLU iWgot6Scekg2EdCjx5zulK0cCIpl/uZhww0kpehf4I9kg6qVmrIhlxI6IZCWAofixBVreB IFn8x3hm1X67NsswL2KN8XfRLNp4fgc= From: Damien Hedde To: qemu-devel@nongnu.org Subject: [RFC PATCH v2 14/16] docs/system: add doc about the initialized machine phase and an example Date: Wed, 22 Sep 2021 18:14:03 +0200 Message-Id: <20210922161405.140018-15-damien.hedde@greensocs.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20210922161405.140018-1-damien.hedde@greensocs.com> References: <20210922161405.140018-1-damien.hedde@greensocs.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Spam: Yes 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+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=5.135.226.135; envelope-from=damien.hedde@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: Peter Maydell , "Michael S. Tsirkin" , David Hildenbrand , Peter Xu , mirela.grujic@greensocs.com, Alistair Francis , Gerd Hoffmann , Ani Sinha , Eric Blake , Stefano Stabellini , xen-devel@lists.xenproject.org, Paul Durrant , Markus Armbruster , Anthony Perard , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Eduardo Habkost , "Dr. David Alan Gilbert" , Eric Auger , Paolo Bonzini , qemu-riscv@nongnu.org, Damien Hedde , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , mark.burton@greensocs.com, edgari@xilinx.com, Igor Mammedov Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1632332235917100001 Content-Type: text/plain; charset="utf-8" Signed-off-by: Damien Hedde --- docs/system/managed-startup.rst | 77 +++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.= rst index 9bcf98ea79..af12a10d27 100644 --- a/docs/system/managed-startup.rst +++ b/docs/system/managed-startup.rst @@ -32,4 +32,81 @@ machine, including but not limited to: - ``query-qmp-schema`` - ``query-commands`` - ``query-status`` +- ``x-machine-init`` - ``x-exit-preconfig`` + +In particular these commands allow to advance and stop qemu at different +phases of the VM creation and finally to leave the "preconfig" state. The +accessible phases are: + +- ``accel-created`` +- ``initialized`` +- ``ready`` + +The order of the phases is enforced. It is not possible to go backwards. +Note that other early phases exist, but they are not attainable with +``--preconfig``. Depending on the phase, QMP commands can be issued to mod= ify +some part of the VM creation. + +accel-created phase +------------------- + +Initial phase entered with ``--preconfig``. + +initialized phase +----------------- + +``x-machine-init`` advances to ``initialized`` phase. During this phase, t= he +machine is initialized and populated with buses and devices. The following= QMP +commands are available to manually populate or modify the machine: + +- ``device_add`` +- ``x-sysbus-mmio-map`` +- ``qom-set`` + +ready phase +----------- + +``x-exit-preconfig`` advances to the final phase. When entering this phase, +the VM creation finishes. "preconfig" state is then done and QEMU goes to +normal execution. + +Machine creation example +------------------------ + +The following is an example that shows how to add some devices with qmp +commands, memory map them, and add interrupts:: + + x-machine-init + + device_add driver=3Dsysbus-memory id=3Drom size=3D0x4000 readonly= =3Dtrue + x-sysbus-mmio-map device=3Drom addr=3D32768 + + device_add driver=3Dsysbus-memory id=3Dflash size=3D0x80000 reado= nly=3Dtrue + x-sysbus-mmio-map device=3Dflash addr=3D536870912 + + device_add driver=3Dsysbus-memory id=3Dram size=3D0x10000 + x-sysbus-mmio-map device=3Dram addr=3D268435456 + + device_add driver=3Dibex-plic id=3Dplic + x-sysbus-mmio-map device=3Dplic addr=3D1090584576 + + device_add driver=3Dibex-uart id=3Duart chardev=3Dserial0 + x-sysbus-mmio-map device=3Duart addr=3D1073741824 + qom-set path=3Duart property=3Dsysbus-irq[0] value=3Dplic/unnamed-gpio-i= n[1] + qom-set path=3Duart property=3Dsysbus-irq[1] value=3Dplic/unnamed-gpio-i= n[2] + qom-set path=3Duart property=3Dsysbus-irq[2] value=3Dplic/unnamed-gpio-i= n[3] + qom-set path=3Duart property=3Dsysbus-irq[3] value=3Dplic/unnamed-gpio-i= n[4] + + x-exit-preconfig + +These commands reproduce a subset of the riscv32 opentitan (hw/riscv/opent= itan) +machine. We can start qemu using:: + + qemu-sytem-riscv32 -preconfig -qmp unix:./qmp-sock,server \ + -machine none -cpu lowriscv-ibex -serial mon:stdio ... + +Then we just have to issue the commands, for example using `qmp-shell`. If= the +previous commands were in a file named `machine.qmp`, we could do:: + + qmp-shell ./qmp-sock < machine.qmp --=20 2.33.0