From 45423e247076c0680bd1936c681efdb81641088d Mon Sep 17 00:00:00 2001 From: Jan Kiszka Date: Tue, 9 Sep 2025 08:13:22 +0200 Subject: [PATCH] docs: Add eMMC device model description MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jan Kiszka Reviewed-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Message-ID: Signed-off-by: Philippe Mathieu-Daudé --- docs/system/device-emulation.rst | 1 + docs/system/devices/emmc.rst | 55 ++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 docs/system/devices/emmc.rst diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index db714ad47a..971325527a 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -88,6 +88,7 @@ Emulated Devices devices/canokey.rst devices/ccid.rst devices/cxl.rst + devices/emmc.rst devices/igb.rst devices/ivshmem-flat.rst devices/ivshmem.rst diff --git a/docs/system/devices/emmc.rst b/docs/system/devices/emmc.rst new file mode 100644 index 0000000000..e62adfd68e --- /dev/null +++ b/docs/system/devices/emmc.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============== +eMMC Emulation +============== + +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 +================== + +A recent eMMC consists of 4 partitions: 2 boot partitions, 1 Replay protected +Memory Block (RPMB), and the user data area. QEMU expects backing images for +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. The +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 helper +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 firmware +image and an OS image with an empty 2 MByte RPMB, use the following command: + +.. code-block:: console + + scripts/mkemmc.sh -b firmware.img -r /dev/zero:2M os.img emmc.img + +This will take care of rounding up the partition sizes to the next valid value +and will leave the RPMB and the second boot partition empty (zeroed). + +Adding eMMC Devices +=================== + +An eMMC is either automatically created by a machine model (e.g. Aspeed boards) +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 other +SDHCI controllers while assuming that the firmware needs a boot partitions of +1 MB, use the following options: + +.. code-block:: console + + -drive file=emmc.img,if=none,format=raw,id=emmc-img + -device sdhci-pci + -device emmc,drive=emmc-img,boot-partition-size=1048576,rpmb-partition-size=2097152 -- 2.47.3