From nobody Fri Nov 14 18:05:58 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass header.i=jan.kiszka@siemens.com; 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; dmarc=pass(p=reject dis=none) header.from=siemens.com ARC-Seal: i=1; a=rsa-sha256; t=1760703427; cv=none; d=zohomail.com; s=zohoarc; b=TOR3X0RkYoShykSr4HqIIbV18BlJ4tTd8qorcU8EW0P0OIYIapuqeF7gvWSSDYyOACFWh0yg0np3cvmpJs0u1yiLFpBcSyzM5fBvOxgtmrVx3V9uPEl5fiD2zmsQJf5WICeJL7fScfDV8MNu+Yt59jqyEVQiim+RWF7CIfPTgG8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1760703427; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=vQy/u7fiHlMEW5tuxu760IqkWFgGR5Ow2qzEfvinbS4=; b=b446tiThz2wh05P2tf1c0KtpvJhZ3VNfbakT8NFbRhNjWJrMAHzJSOFDwZhYFEmcNN9yWAd7mu/noGQW1a4kVcui3H8Vltl6ICU8SPwtuo7IR9W34xPmiAvtzIn+DAYEJE6nK/TWvWvLuwUxi2Tg79A6c5HiYBKGXtojOTjkaNY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=jan.kiszka@siemens.com; 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; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1760703427895795.8754374428748; Fri, 17 Oct 2025 05:17:07 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1v9jM7-00060X-Sl; Fri, 17 Oct 2025 08:14:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1v9jLz-0005tW-TK for qemu-devel@nongnu.org; Fri, 17 Oct 2025 08:14:41 -0400 Received: from mta-65-225.siemens.flowmailer.net ([185.136.65.225]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1v9jLi-0005Ey-Bm for qemu-devel@nongnu.org; Fri, 17 Oct 2025 08:14:37 -0400 Received: by mta-65-225.siemens.flowmailer.net with ESMTPSA id 202510171204036c9fae5418000207cd for ; Fri, 17 Oct 2025 14:04:03 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm2; d=siemens.com; i=jan.kiszka@siemens.com; h=Date:From:Subject:To:Message-ID:MIME-Version:Content-Type:Content-Transfer-Encoding:Cc:References:In-Reply-To; bh=vQy/u7fiHlMEW5tuxu760IqkWFgGR5Ow2qzEfvinbS4=; b=E8cWg4nmG3EjFY6SSaYIktcJCt0WKleDN24gD7LNjelCrf2l9xx+04wR5xqClKCsFY5Qok VTxi2WUP6FMaUEFlYm1jPImB2ospGxdheCS2BnATFOUKQRCuwMv8cJytGRNPHM90N3+4wgmM wKpEb4Y5aTKcAOcIGPQQQOVBLTFVxCUnztnlq2pI9qN2/f3Zzd9kStvZQ9aMJJICqIPrhqxT 1VUudtx34IvJ5ZOALKL2BZHOCDYQtTW7LgoqMECugjlORIBrecxM0JpeYfVVmFOKjh7/Y2yJ KBx5MuWQI3SUl03b7bCwdZTEVt5mUD5nqRuZrQgNoVVGbu3skm+j2xPw==; From: Jan Kiszka To: qemu-devel Cc: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Bin Meng , qemu-block@nongnu.org, Ilias Apalodimas , =?UTF-8?q?Alex=20Benn=C3=A9e?= , =?UTF-8?q?Jan=20L=C3=BCbbe?= , Jerome Forissier Subject: [PATCH v5 6/6] docs: Add eMMC device model description Date: Fri, 17 Oct 2025 14:03:58 +0200 Message-ID: <43c6bc1a28f449e59792526319ddc5ba23fd2fbf.1760702638.git.jan.kiszka@siemens.com> In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Flowmailer-Platform: Siemens Feedback-ID: 519:519-294854:519-21489:flowmailer 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=185.136.65.225; envelope-from=fm-294854-202510171204036c9fae5418000207cd-baGzVs@rts-flowmailer.siemens.com; helo=mta-65-225.siemens.flowmailer.net X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_MED=-0.272, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, SPF_HELO_PASS=-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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity jan.kiszka@siemens.com) X-ZM-MESSAGEID: 1760703431014154100 From: Jan Kiszka Signed-off-by: Jan Kiszka Reviewed-by: Alex Benn=C3=A9e Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- docs/system/device-emulation.rst | 1 + docs/system/devices/emmc.rst | 53 ++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/system/devices/emmc.rst diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulatio= n.rst index 911381643f..36429b1d17 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -101,3 +101,4 @@ Emulated Devices devices/canokey.rst devices/usb-u2f.rst devices/igb.rst + devices/emmc.rst diff --git a/docs/system/devices/emmc.rst b/docs/system/devices/emmc.rst new file mode 100644 index 0000000000..7e15b62270 --- /dev/null +++ b/docs/system/devices/emmc.rst @@ -0,0 +1,53 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +eMMC Emulation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Besides SD card emulation, QEMU also offers an eMMC model as found on many +embedded boards. An eMMC, just like an SD card, is connected to the machine +via an SDHCI controller. + +Create eMMC Images +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +A recent eMMC consists of 4 partitions: 2 boot partitions, 1 Replay protec= ted +Memory Block (RPMB), and the user data area. QEMU expects backing images f= or +the eMMC to contain those partitions concatenated in exactly that order. +However, the boot partitions as well as the RPMB might be absent if their = sizes +are configured to zero. + +The eMMC specification defines alignment constraints for the partitions. T= he +two boot partitions must be of the same size. Furthermore, boot and RPMB +partitions must be multiples of 128 KB with a maximum of 32640 KB for each +boot partition and 16384K for the RPMB partition. + +The alignment constrain of the user data area depends on its size. Up to 2 +GByte, the size must be a power of 2. From 2 GByte onward, the size has to= be +multiples of 512 byte. + +QEMU is enforcing those alignment rules before instantiating the device. +Therefore, the provided image has to strictly follow them as well. The hel= per +script ``scripts/mkemmc.sh`` can be used to create compliant images, with = or +without pre-filled partitions. E.g., to create an eMMC image from a firmwa= re +image and an OS image with an empty 2 MByte RPMB, use the following comman= d: + +.. code-block:: console + + scripts/mkemmc.sh -b firmware.img -r /dev/zero:2MB os.img emmc.img + +This will take care of rounding up the partition sizes to the next valid v= alue +and will leave the RPMB and the second boot partition empty (zeroed). + +Adding eMMC Devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +An eMMC is either automatically created by a machine model (e.g. Aspeed bo= ards) +or can be user-created when using a PCI-attached SDHCI controller. To +instantiate the eMMC image from the example above in a machine without oth= er +SDHCI controllers while assuming that the firmware needs a boot partitions= of +1 MB, use the following options: + +.. code-block:: console + + -drive file=3Demmc.img,if=3Dnone,format=3Draw,id=3Demmc-img + -device sdhci-pci + -device emmc,drive=3Demmc-img,boot-partition-size=3D1048576,rpmb-parti= tion-size=3D2097152 --=20 2.51.0