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

[Jan Kiszka <jan.kiszka@siemens.com>]

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