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

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,

C.

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.

Jan

-- 
Siemens AG, Foundational Technologies
Linux Expert Center

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".

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


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/

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