| 1 | .. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | |
| 3 | ============== |
| 4 | eMMC Emulation |
| 5 | ============== |
| 6 | |
| 7 | Besides SD card emulation, QEMU also offers an eMMC model as found on many |
| 8 | embedded boards. An eMMC, just like an SD card, is connected to the machine |
| 9 | via an SDHCI controller. |
| 10 | |
| 11 | Create eMMC Images |
| 12 | ================== |
| 13 | |
| 14 | A recent eMMC consists of 4 partitions: 2 boot partitions, 1 Replay protected |
| 15 | Memory Block (RPMB), and the user data area. QEMU expects backing images for |
| 16 | the eMMC to contain those partitions concatenated in exactly that order. |
| 17 | However, the boot partitions as well as the RPMB might be absent if their sizes |
| 18 | are configured to zero. |
| 19 | |
| 20 | The eMMC specification defines alignment constraints for the partitions. The |
| 21 | two boot partitions must be of the same size. Furthermore, boot and RPMB |
| 22 | partitions must be multiples of 128 KB with a maximum of 32640 KB for each |
| 23 | boot partition and 16384K for the RPMB partition. |
| 24 | |
| 25 | The alignment constrain of the user data area depends on its size. Up to 2 |
| 26 | GByte, the size must be a power of 2. From 2 GByte onward, the size has to be |
| 27 | multiples of 512 byte. |
| 28 | |
| 29 | QEMU is enforcing those alignment rules before instantiating the device. |
| 30 | Therefore, the provided image has to strictly follow them as well. The helper |
| 31 | script ``scripts/mkemmc.sh`` can be used to create compliant images, with or |
| 32 | without pre-filled partitions. E.g., to create an eMMC image from a firmware |
| 33 | image and an OS image with an empty 2 MByte RPMB, use the following command: |
| 34 | |
| 35 | .. code-block:: console |
| 36 | |
| 37 | scripts/mkemmc.sh -b firmware.img -r /dev/zero:2M os.img emmc.img |
| 38 | |
| 39 | This will take care of rounding up the partition sizes to the next valid value |
| 40 | and will leave the RPMB and the second boot partition empty (zeroed). |
| 41 | |
| 42 | Adding eMMC Devices |
| 43 | =================== |
| 44 | |
| 45 | An eMMC is either automatically created by a machine model (e.g. Aspeed boards) |
| 46 | or can be user-created when using a PCI-attached SDHCI controller. To |
| 47 | instantiate the eMMC image from the example above in a machine without other |
| 48 | SDHCI controllers while assuming that the firmware needs a boot partitions of |
| 49 | 1 MB, use the following options: |
| 50 | |
| 51 | .. code-block:: console |
| 52 | |
| 53 | -drive file=emmc.img,if=none,format=raw,id=emmc-img |
| 54 | -device sdhci-pci |
| 55 | -device emmc,drive=emmc-img,boot-partition-size=1048576,rpmb-partition-size=2097152 |
| 56 | |
| 57 | RPMB Authentication Key |
| 58 | ======================= |
| 59 | |
| 60 | A private shared key is used for authenticating requests of the host to the |
| 61 | RPMB. A real eMMC stores this persistently and permits no reprogramming once it |
| 62 | is set. QEMU emulates key programming but does not persist the key state |
| 63 | across restarts. To emulate the state "key is set", the eMMC can be created |
| 64 | with a user-provided key via the ``auth-key`` property: |
| 65 | |
| 66 | .. code-block:: console |
| 67 | |
| 68 | -device emmc,[...],auth-key=D3EB3EC36E334C9F988CE2C0B85954610D2BCF8664844DF2AB56E6C61BB701E4 |
| 69 | |
| 70 | This sets the well-known test key of OP-TEE on emmc device creation. In case an |
| 71 | eMMC is instantiated by the machine model already: |
| 72 | |
| 73 | .. code-block:: console |
| 74 | |
| 75 | -global emmc.auth-key=D3EB3EC36E334C9F988CE2C0B85954610D2BCF8664844DF2AB56E6C61BB701E4 |
| 76 | |
| 77 | A key always consists of 32 bytes that have to be encoded as hex numbers, |
| 78 | left-padding with zeros as needed. |