Re: [PATCH v3 6/6] docs: Add eMMC device model description

["Jan Lübbe" <jlu@pengutronix.de>]

On Tue, 2025-09-09 at 14:50 +0200, Jan Kiszka wrote:
> From: Jan Kiszka <jan.kiszka@siemens.com>
> 
> Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
> ---
>  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-emulation.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..3bd70c0e94
> --- /dev/null
> +++ b/docs/system/devices/emmc.rst
> @@ -0,0 +1,52 @@
> +==============
> +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:2MB 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 form the example above while assuming that the

s/form/from/

> +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

Missing ',' before rpmb-partition-size?

Thanks,
Jan
-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |