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

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

On 16.09.25 09:10, Cédric Le Goater wrote:
> On 9/16/25 08:02, Jan Kiszka wrote:
>> On 15.09.25 19:37, Cédric Le Goater wrote:
>>> On 9/14/25 14:46, Jan Kiszka wrote:
>>>> From: Jan Kiszka <jan.kiszka@siemens.com>
>>>>
>>>> Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
>>>> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
>>>> ---
>>>>    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..dbea6d6c7e
>>>> --- /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
>>>
>>> the single backquote would interpret scripts/mkemmc.sh as a ref. I think
>>> you want ``scripts/mkemmc.sh``
>>>
>>>> +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 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=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
>>>
>>> I will see if I can adjust the existing aspeed test with your proposal.
>>>
>>
>> Thanks in advance! Yeah, the existing alignment rules were incorrect
>> once you turned on boot partitions. So there is unfortunately no way
>> around fixing images that followed them.
> 
> Ideally we should generate the rainier emmc image with your script
> from the OpenBMC artifacts [1]. The current image is not broken by
> this series, so, we have time.
> 
> 
> However, regarding this command line :
> 
>     -drive file=emmc.img,if=none,format=raw,id=emmc-img
>     -device sdhci-pci
>     -device emmc,drive=emmc-img,boot-partition-size=1048576,rpmb-
> size=2097152
> 
> a few assumptions are made.
> 
> Machines can have multiple sdhci controllers with several slots. In
> the, case above, the emmc device is "blindly" attached to slot 0 on
> a bus named "sd-bus".

If the machine has an sdhci controller already, the sdhci-pci device is
not needed. I can try to make the description clearer, and maybe you can
tell me what would be needed for the rainier boards, then we can have
both examples there.

> 
> Removing all QEMU internal references to "sd-bus" will require some work.
> 

Sure, this should rather document the current situation.

Jan

> 
> Philippe,
> 
> Should we allow automatic bus numbering  :
> 
> -    qbus_init(&s->sdbus, sizeof(s->sdbus), TYPE_SDHCI_BUS, DEVICE(s),
> "sd-bus");
> +    qbus_init(&s->sdbus, sizeof(s->sdbus), TYPE_SDHCI_BUS, DEVICE(s),
> NULL);
> 
> and replace all :
> 
> -        BusState *bus = qdev_get_child_bus(DEVICE(sdhci), "sd-bus");
> +        BusState *bus = BUS(&sdhci->sdbus);
> 
> 
> Thanks,
> 
> C.
> 
> 
> [1] https://jenkins.openbmc.org/job/ci-openbmc/
> distro=ubuntu,label=docker-builder,target=p10bmc/32112/artifact/openbmc/
> build/tmp/deploy/images/p10bmc/
> 

-- 
Siemens AG, Foundational Technologies
Linux Expert Center