From nobody Sun Sep 28 16:38:13 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=1757854816; cv=none; d=zohomail.com; s=zohoarc; b=TCCin1PTyiWSLtNOOTKc6JVQWCTiWndoqkHWzMMLiBSZtpbo7RwSooubTyAZEAkTbmX6EbI4mhJ6wqIVGhzLZXN5EeigfMF1Fkq06A6NLAz1Sm1/c7R0l5a6YIawGC8//SImIpJtdXY5dFMZ6azz45a46i+HSJUwtnqRcCO+cE8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1757854816; 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=n8i+jjUuq9cfattAVJFgrNhUxynT3tjgjOkOD34uDkY=; b=nPcqnMDrvygyvt8lvty70KjBk+RKdOxjICJFE+En09puJEQlV+ejGNJDEEOhFcdiojklvTQk5vOGYmY5XshL7oUZea30Nhm7NpOGm8Y9+95tGZGW8w19LmypcFKVcq6kygV5Y8CgpLo/2S6HccU5s8nPUJ3uLi0RniLHPNpMYgw= 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 1757854816718330.18291041142504; Sun, 14 Sep 2025 06:00:16 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uxmIR-0004ZO-9s; Sun, 14 Sep 2025 08:57:36 -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 1uxmID-0004WY-I3 for qemu-devel@nongnu.org; Sun, 14 Sep 2025 08:57:23 -0400 Received: from mta-65-227.siemens.flowmailer.net ([185.136.65.227]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uxmI1-0002Np-0r for qemu-devel@nongnu.org; Sun, 14 Sep 2025 08:57:21 -0400 Received: by mta-65-227.siemens.flowmailer.net with ESMTPSA id 20250914124650bc210655fb000207c7 for ; Sun, 14 Sep 2025 14:46:50 +0200 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; s=fm1; 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=n8i+jjUuq9cfattAVJFgrNhUxynT3tjgjOkOD34uDkY=; b=osKkD7BvZe/E3+4t21PhajP+vgI8vqnhmbLgmXVjPiREFDL7ltqjRxajTiU1BJg/1hD6P1 wJd/287gPp6oH9Tvf8fE7C8fO0RQCKqpYvXOiEl8dnBW7A45Cl7yz3uMDXmqt6RGxlE/kc2v 59svawZfGoOZ4GMEjj78IUuoG/Ov55uDPTuaG3W9+L0Glem6Ps0ViHrUXLN5WB8i512UI8La DE71svJ60QwGPhEA53r4CWVA+03vlKNaTpPCQG04TIuHLJuT7jM9VuRKqebulD+Yf6Wc5V3O TW+yNjjADrs5F266zMDJHQHCOLi3FV4bt65uWjC/Id57VfmoG+dHWmbA==; 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 v4 6/6] docs: Add eMMC device model description Date: Sun, 14 Sep 2025 14:46:46 +0200 Message-ID: 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.227; envelope-from=fm-294854-20250914124650bc210655fb000207c7-yjyGvZ@rts-flowmailer.siemens.com; helo=mta-65-227.siemens.flowmailer.net X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_MED=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_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: 1757854819008116600 From: Jan Kiszka Signed-off-by: Jan Kiszka Reviewed-by: Alex Benn=C3=A9e --- docs/system/device-emulation.rst | 1 + docs/system/devices/emmc.rst | 52 ++++++++++++++++++++++++++++++++ 2 files changed, 53 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..dbea6d6c7e --- /dev/null +++ b/docs/system/devices/emmc.rst @@ -0,0 +1,52 @@ +=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 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