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
+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.51.0Jan Kiszka <jan.kiszka@siemens.com> writes: > From: Jan Kiszka <jan.kiszka@siemens.com> > > Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com> With typo fix: Reviewed-by: Alex Bennée <alex.bennee@linaro.org> -- Alex Bennée Virtualisation Tech Lead @ Linaro
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 |
On 09.09.25 15:28, Jan Lübbe wrote: > 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, both fixed. Jan -- Siemens AG, Foundational Technologies Linux Expert Center
© 2016 - 2025 Red Hat, Inc.