From patchwork Fri Jul 29 09:19:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 594352 Delivered-To: patch@linaro.org Received: by 2002:a05:7000:b345:0:0:0:0 with SMTP id w5csp1183153maz; Fri, 29 Jul 2022 02:32:30 -0700 (PDT) X-Google-Smtp-Source: AGRyM1spexJsbRw8EfuLUdmhTQCiDPBPHuHzH/r+Hw43yKUQ76uWpxMaCi/jO4LMo2IoboXgU2ly X-Received: by 2002:a05:622a:1a14:b0:31e:e89f:4dda with SMTP id f20-20020a05622a1a1400b0031ee89f4ddamr2593620qtb.622.1659087150191; Fri, 29 Jul 2022 02:32:30 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1659087150; cv=none; d=google.com; s=arc-20160816; b=R4xQilDEFd0Ejx6pdQA4FgUYuKg4fMXKaWL7GkezZv2w46X0psUBJE0JBlmlDzVdsv UV8KW1lQAKANjZ82OhQIwr4PlCJxCrtENluMrgC+FG9GV/yRwkzPTANLtMcMMV9UpIE5 u+Adbjsa5oCYeuEFWjOn3DYH/uB7zbwa+b3bLM8gNfNQqP2Bfjkl9W3xajliAYLS8DA2 coem8Yw6PvS5z/D50cUnwknDwZWAWfZO+RjujglzLEfhW/D3eVnNFtrc3B9Ak17rTaaZ uOEAtqAgQ+0tUcDKtocVre1G5irT1l/BinvlE0zejniLrCur0ch7nlgqP4uJIQVZ+Kal NQLw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=hwvFbZR4/H0xiyraePhgzCmgfa2kY4WJ3yx1/sETcUM=; b=fNkw9tqSffAw97K83XX5/kasDfOcd6sexgInxr0E++HpJCeu3t+xUE7wdiJzT0Scqb fEtsZGIRzVCzzc7ZcFYW4uqZ6kNnVcJYYnZzZezL1MxkTmRwsDc2nc/hRCzmk44h/pIQ 5Kfvdq8pZvFInY+VcaR5cX7ISyOkE1szbK7sU/NIBsh3oEOSQmAqkK84c7aYkkXGnEck EWvmSHTo7eXM6r29a1B8XiDI8gLN95V1AERA3RiIIEW7sTS0JEQYakPEe17ypfZqe4tH hlqO3Klx9iCX2MnGSaAKx6lr0R2/63XEA+2xcYn7H0TXe9itjzlYmJNiAnV+Fa+WAJWS g2LQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=uAiWvsLW; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id z20-20020ac84314000000b0031f0b633bd9si1919040qtm.40.2022.07.29.02.32.30 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 29 Jul 2022 02:32:30 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=uAiWvsLW; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:39632 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oHMM9-0000V4-N6 for patch@linaro.org; Fri, 29 Jul 2022 05:32:29 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:45288) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHMFE-0005Vz-1T for qemu-devel@nongnu.org; Fri, 29 Jul 2022 05:25:20 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:40592) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oHMFB-0006hP-BZ for qemu-devel@nongnu.org; Fri, 29 Jul 2022 05:25:19 -0400 Received: by mail-wr1-x432.google.com with SMTP id l22so5278318wrz.7 for ; Fri, 29 Jul 2022 02:25:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hwvFbZR4/H0xiyraePhgzCmgfa2kY4WJ3yx1/sETcUM=; b=uAiWvsLW9GsXLYfPlzsVX3X09rgfo2JFXxbgzJcLUSZkXHyh1y9sEC1WYd/l0YGxqf 1rtmKgohtz34jEYRLHKicUcmy4FHp09GLDcEoZMxNI0hjT2aPbtoTKgkZ2bTAlh11ir2 eomJKbsEzjmUsKQ9cElZz4uWrnDFCqWM/sfrPA7PiVvaFr2cPfoHOueDLiLYSwr0keZ2 Tdbm6QFvCHQaHUmXbgDhb6PzdDFy7mcLpB1xajfYw6Z+R9Nt+lxwrw3U+A/w3iRtuMRW FGbQffMUtJZyWNj1NpydcueWM+NY51rZeLloGpBP9KTnXaaFmy0VXe1KQUHf2DnPuf6K iLYQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hwvFbZR4/H0xiyraePhgzCmgfa2kY4WJ3yx1/sETcUM=; b=wq39VAiqpLLUMVyN5px5gXVBFaoqXdY7s/06T1dDod/B1Rlzs2zIvbQ+Y7ZTP5gsVL aCOnkm5kfSkyERQi74dcDPwjjQFTabhz7aKB9sdI9fMfYs8MYwY+0vHJ4KMRNixkMOK+ MBgRZj3HMyyuZfOXnSGmLXar2tHRYQW9BiosfK1GgADbmcqns80Y5i1V7B0ko2agmLYE xVEM7bA5Wz0bLz/Qbbi7/XfhB9Wh4hKRp6VLN7ktb+JRBrR+y0tnmnA9wUbtIQis7Qu8 uWGysBTXTsJ1/j2CtNqUH97hzIThLItUrB/wTt6RjsM6BVM+AeyOEE1qdUfmtCYo+RnR cVEQ== X-Gm-Message-State: ACgBeo1vDzyYcBk+74DKAlcb5lrmm3UL0N2mQYfm51uoKIDgCYDRGbgW 2mIKPVGuUeUdLMnGhJcCbK8VQQ== X-Received: by 2002:a5d:6d46:0:b0:21f:8b7:4c1d with SMTP id k6-20020a5d6d46000000b0021f08b74c1dmr1758009wri.455.1659086715650; Fri, 29 Jul 2022 02:25:15 -0700 (PDT) Received: from zen.linaroharston ([185.81.254.11]) by smtp.gmail.com with ESMTPSA id bk9-20020a0560001d8900b0021d76a1b0e3sm3137983wrb.6.2022.07.29.02.25.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Jul 2022 02:25:14 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id ED72D1FFC5; Fri, 29 Jul 2022 10:19:44 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: peter.maydell@linaro.org, richard.henderson@linaro.org Cc: qemu-devel@nongnu.org, =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?C=C3=A9dri?= =?utf-8?q?c_Le_Goater?= Subject: [PULL 13/13] qemu-options: bring the kernel and image options together Date: Fri, 29 Jul 2022 10:19:43 +0100 Message-Id: <20220729091943.2152410-14-alex.bennee@linaro.org> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20220729091943.2152410-1-alex.bennee@linaro.org> References: <20220729091943.2152410-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=alex.bennee@linaro.org; helo=mail-wr1-x432.google.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, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" How to control the booting of QEMU is often a source of confusion for users. Bring the options that control this together in the manual pages and add some verbiage to describe when each option is appropriate. This attempts to codify some of the knowledge expressed in: https://stackoverflow.com/questions/58420670/qemu-bios-vs-kernel-vs-device-loader-file/58434837#58434837 Signed-off-by: Alex Bennée Reviewed-by: Peter Maydell Reviewed-by: Cédric Le Goater Message-Id: <20220725140520.515340-14-alex.bennee@linaro.org> diff --git a/qemu-options.hx b/qemu-options.hx index 8e17c5064a..3f23a42fa8 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -1585,13 +1585,6 @@ SRST Use file as SecureDigital card image. ERST -DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, - "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) -SRST -``-pflash file`` - Use file as a parallel flash image. -ERST - DEF("snapshot", 0, QEMU_OPTION_snapshot, "-snapshot write to temporary files instead of disk image files\n", QEMU_ARCH_ALL) @@ -3684,12 +3677,67 @@ DEFHEADING() #endif -DEFHEADING(Linux/Multiboot boot specific:) +DEFHEADING(Boot Image or Kernel specific:) +SRST +There are broadly 4 ways you can boot a system with QEMU. + + - specify a firmware and let it control finding a kernel + - specify a firmware and pass a hint to the kernel to boot + - direct kernel image boot + - manually load files into the guest's address space + +The third method is useful for quickly testing kernels but as there is +no firmware to pass configuration information to the kernel the +hardware must either be probeable, the kernel built for the exact +configuration or passed some configuration data (e.g. a DTB blob) +which tells the kernel what drivers it needs. This exact details are +often hardware specific. + +The final method is the most generic way of loading images into the +guest address space and used mostly for ``bare metal`` type +development where the reset vectors of the processor are taken into +account. + +ERST + SRST -When using these options, you can use a given Linux or Multiboot kernel -without installing it in the disk image. It can be useful for easier -testing of various kernels. +For x86 machines and some other architectures ``-bios`` will generally +do the right thing with whatever it is given. For other machines the +more strict ``-pflash`` option needs an image that is sized for the +flash device for the given machine type. + +Please see the :ref:`system-targets-ref` section of the manual for +more detailed documentation. + +ERST + +DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ + "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) +SRST +``-bios file`` + Set the filename for the BIOS. +ERST + +DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, + "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) +SRST +``-pflash file`` + Use file as a parallel flash image. +ERST + +SRST + +The kernel options were designed to work with Linux kernels although +other things (like hypervisors) can be packaged up as a kernel +executable image. The exact format of a executable image is usually +architecture specific. + +The way in which the kernel is started (what address it is loaded at, +what if any information is passed to it via CPU registers, the state +of the hardware when it is started, and so on) is also architecture +specific. Typically it follows the specification laid down by the +Linux kernel for how kernels for that architecture must be started. ERST @@ -3729,6 +3777,25 @@ SRST kernel on boot. ERST +SRST + +Finally you can also manually load images directly into the address +space of the guest. This is most useful for developers who already +know the layout of their guest and take care to ensure something sane +will happen when the reset vector executes. + +The generic loader can be invoked by using the loader device: + +``-device loader,addr=,data=,data-len=[,data-be=][,cpu-num=]`` + +there is also the guest loader which operates in a similar way but +tweaks the DTB so a hypervisor loaded via ``-kernel`` can find where +the guest image is: + +``-device guest-loader,addr=[,kernel=,[bootargs=]][,initrd=]`` + +ERST + DEFHEADING() DEFHEADING(Debug/Expert options:) @@ -4179,13 +4246,6 @@ SRST To list all the data directories, use ``-L help``. ERST -DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ - "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) -SRST -``-bios file`` - Set the filename for the BIOS. -ERST - DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ARM | QEMU_ARCH_I386 | QEMU_ARCH_MIPS | QEMU_ARCH_PPC |