mmc-utils(1)

📦
version 1.0 · 8 versions
, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

mmc — a tool for configuring MMC storage devices. This is the mmc-utils(1) page from the General Commands Manual, and it's all about the mmc tool, bestie. 💖

✨ SYNOPSIS ✨

mmc [options] [ mmc-block-device]...

💖 DESCRIPTION 💖

Okay so mmc-utils is a single-threaded tool that will perform a specified type of mmc action as specified by the user. It does one thing at a time, no multitasking chaos. 💅

The typical use of mmc-utils is to access the mmc device either for configuring or reading its configuration registers. That's the whole vibe: configure it, read it, understand it. 🎀

👑 OPTIONS 👑

Here's the full menu, no skips, no "oops I forgot one" energy. Every flag and argument is staying right here. 🫶

  • extcsd read device — Reads and prints the extended CSD register.
  • extcsd write offset value device — Writes value at offset to the device's extcsd.
  • writeprotect boot get device — Prints the boot partitions write protect status.
  • writeprotect boot set device [number] — Sets the boot partition write protect status for the device. If number is passed (0 or 1), only protect that specified eMMC boot partition; otherwise protect both. It will be write-protected until the next boot.
  • writeprotect user set type start-block blocks device — Sets the write protect configuration for the specified region of the user area for the device. start-block specifies the first block of the protected area. blocks specifies the size of the protected area in blocks. NOTE! The area must start and end on Write Protect Group boundaries. Use the writeprotect user get command to get the Write Protect Group size. type is one of the following:
    • none — Clear temporary write protection.
    • temp — Set temporary write protection.
    • pwron — Set write protection until the next power on.
  • writeprotect user get device — Prints the user areas write protect configuration for <device>.
  • writeprotect user get device — Prints the user area's write protect configuration for the device. Yes, it's listed twice — I'm not dropping a single detail. 💅
  • disable 512B emulation device — Sets the eMMC data sector size to 4KB by disabling emulation on the device.
  • gp create dry-run length-KiB partition enh-attr ext-attr device — Creates a general purpose partition for the device. NOTE! This is a one-time programmable (irreversible) change. To set enhanced attribute to the general partition being created, set enh-attr to 1; else set it to 0. To set extended attribute to the general partition, set enh-attr to 1,2; else set it to 0. dry-run is one of the following:
    • -y — PARTITION_SETTING_COMPLETED in the extcsd will get set and the partitioning operation will take effect and be finalized.
    • -c — more partitioning settings are still to come — the partitioning operation will not take effect.
    • otherwise — These changes will not take effect neither now nor after a power cycle.
  • enh_area set dry-run start-KiB length-KiB device — Enables the enhanced user area for the device. NOTE! This is a one-time programmable (irreversible) change. dry-run is as above.
  • write_reliability set dry-run partition device — Enables write reliability per partition for the device. NOTE! This is a one-time programmable (irreversible) change. dry-run is as above.
  • status get device — Prints the response to STATUS_SEND (CMD13).
  • bootpart enable boot-partition send-ackn device — Enables the boot partition for the device. Disables the boot partition for the device if boot-partition is set to 0. To receive acknowledgment of boot from the card, set send-ackn to 1; else set it to 0.
  • bootbus set boot-mode reset-boot-bus-conditions boot-bus-width device — Sets Boot Bus Conditions. boot-mode is one of the following: single_backward, single_hs, or dual. reset-boot-bus-conditions is one of the following: x1 or retain. boot-bus-width is one of the following: x1, x4, or x8.
  • bkops_en mode device — Enables the eMMC BKOPS feature on the device. The auto (AUTO_EN) setting is only supported on eMMC 5.0 or newer. NOTE! Setting manual (MANUAL_EN) is a one-time programmable (irreversible) change. mode is one of the following:
    • auto — Auto bkops is set.
    • manual — Manual bkops is set.
  • hwreset enable device — Permanently enables the eMMC H/W Reset feature on the device. NOTE! This is a one-time programmable (irreversible) change.
  • hwreset disable device — Permanently disables the eMMC H/W Reset feature on the device. NOTE! This is a one-time programmable (irreversible) change.
  • sanitize device [timeout_ms] — Sends the Sanitize command to the device. This will delete the unmapped memory region of the device.
  • rpmb write-key rpmb-device key-file — Programs the authentication key, which is 32 bytes length and stored in the specified file. Also you can specify '-' instead of the key file path to read the key from stdin. NOTE! This is a one-time programmable (irreversible) change.
  • rpmb read-counter rpmb-device — The counter value for the rpmb-device will be read to stdout.
  • rpmb read-block rpmb-device address blocks — Blocks of 256 bytes will be read from rpmb-device to output file or stdout if '-' is specified. If key is specified — read data will be verified.
  • rpmb write-block rpmb-device address 256-byte-data-file key-file — A block of 256 bytes will be written from the data file to rpmb-device. Also you can specify '-' instead of the key file path or data file to read the data from stdin.
  • rpmb secure-wp-mode-on rpmb-device key-file — Enables Secure Write Protection mode. The access to the write protection related EXT_CSD and CSD fields depends on the value of the SECURE_WP_MASK bit in the SECURE_WP_MODE_CONFIG field. You can specify '-' instead of key.
  • rpmb secure-wp-mode-off rpmb-device key-file — Disables Secure Write Protection mode = legacy mode. TMP_WRITE_PROTECT[12] and PERM_WRITE_PROTECT[13] are updated by CMD27. USER_WP[171], BOOT_WP[173], and BOOT_WP_STATUS[174] are updated by CMD6. You can specify '-' instead of key.
  • rpmb secure-wp-disable rpmb-device key-file — Enabling updating WP related EXT_CSD and CSD fields. Applicable only if secure wp mode is enabled. You can specify '-' instead of key.
  • rpmb secure-wp-enable rpmb-device key-file — Disabling updating WP related EXT_CSD and CSD fields. Applicable only if secure wp mode is enabled. You can specify '-' instead of key.
  • rpmb secure-wp-en-read rpmb-device [key-file] — Reads the status of the SECURE_WP_EN & SECURE_WP_MASK fields. Applicable only if secure wp mode is enabled. You can specify '-' instead of key.
  • cache enable device — Enables the eMMC cache feature on the device. NOTE! The cache is an optional feature on devices >= eMMC4.5.
  • cache disable device — Disables the eMMC cache feature on the device. NOTE! The cache is an optional feature on devices >= eMMC4.5.
  • csd read [-h][-v] [-b bus_type] [-r register] <device-path> — Prints CSD data from device-path. The device path should specify the csd sysfs file directory. If bus_type is passed (mmc or sd), the register content must be passed as well, and no need for device path. It is useful for cases where we are getting the register value without having the actual platform.
  • cid read [-h][-v] [-b bus_type] [-r register] <device-path> — Prints CID data from device-path. The device path should specify the cid sysfs file directory. If bus_type is passed (mmc or sd), the register content must be passed as well, and no need for device path. It is useful for cases where we are getting the register value without having the actual platform.
  • scr read [-h][-v] [-b bus_type] [-r register] <device-path> — Prints SCR data from device-path. The device path should specify the scr sysfs file directory. If bus_type is passed (mmc or sd), the register content must be passed as well, and no need for device path. It is useful for cases where we are getting the register value without having the actual platform.
  • ffu image-file-name device [chunk-bytes] — Runs Field Firmware Update with image-file-name on the device. [chunk-bytes] is optional and defaults to its max - 512k. Should be in decimal bytes and sector aligned. If [chunk-bytes] is omitted, mmc-utils will try to run ffu using the largest possible chunks: max(image-file, 512k).
  • opt_ffu1 image-file-name device [chunk-bytes] — Optional FFU mode 1, it's the same as ffu, but uses CMD23+CMD25 for repeated downloads and remains in FFU mode until completion.
  • opt_ffu2 image-file-name device [chunk-bytes] — Optional FFU mode 2, uses CMD25+CMD12 Open-ended Multiple-block write to download and remains in FFU mode until completion.
  • opt_ffu3 image-file-name device [chunk-bytes] — Optional FFU mode 3, uses CMD24 Single-block write for downloading, exiting FFU mode after each block is written.
  • opt_ffu4 image-file-name device [chunk-bytes] — Optional FFU mode 4, uses CMD24 Single-block write for repeated downloads, remaining in FFU mode until completion.
  • erase type start-address end-address device — Sends Erase CMD38 with a specific argument to the device. NOTE! This will delete all user data in the specified region of the device. type is one of the following: legacy, discard, secure-erase, secure-trim1, secure-trim2, or trim.
  • gen_cmd read device [arg] — Sends GEN_CMD (CMD56) to read vendor-specific format/meaning data from the device. NOTE! [arg] is optional and defaults to 0x1. If [arg] is specified, then [arg] must be a 32-bit hexadecimal number, prefixed with 0x/0X. And bit0 in [arg] must be 1. Normally this command is aimed to extract a device-health info from the device.
  • softreset device — Issues a CMD0 softreset, e.g. for testing if hardware reset for UHS works.
  • boot_operation boot-data-file device — Does the alternative boot operation and writes the specified starting blocks of boot data into the requested file. Note some limitations:
    1. The boot operation must be configured first, e.g. via bootbus and/or bootpart commands.
  1. The MMC has to already be running in the bus mode that's configured for the boot operation — like, HS200 and HS400 are not supported at all, bestie, not even a little 🫶
  2. Only up to 512K bytes of boot data gets transferred, that's the ceiling, no cap 💅 (well, cap actually)
  3. The MMC will perform a soft reset — so if your system can't handle that, please do not use the boot operation from mmc-utils, I'm begging 🙈
  • --help | help | -h — shows the help, the classic ✨
  • cmd --help — shows detailed help for that specific cmd, or for a whole subset of commands. iykyk 🎀

🌸 RPMB COMMANDS 🌸

Okay so the RPMB partition on eMMC devices? It's this special little area for storing cryptographically safe information that's signed by a special secret key 🔐 iconic behaviour honestly.

To write and read records from this special area, authentication is needed — you can't just waltz in, she has standards 💅

The RPMB area is only and exclusively accessed using ioctl()s from user-space. Periodt.

RPMB commands get sent using the mmc multi-ioctl, which is the whole reason it ensures the atomic nature of the rpmb access operation — no half-finished writes, we don't do that here ⭐

Also super important: the rpmb device you pass as a parameter to the rpmb commands is not a block device but a char device 🦋 This was done to help the mmc driver account for some of the rpmb peculiarities.

✨ EXAMPLES ✨

💖 RPMB examples 💖

Program the rpmb key using the stdin option:

$ echo -n AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH | mmc rpmb write-key /dev/mmcblk0rpmb -

Read 2 blocks starting at address 2 and output the received content to stdout. Verify the received frames using the key — totally not mandatory, just a flex:

$ echo -n AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH | mmc rpmb read-block /dev/mmcblk0rpmb 0x02 2 -

Read 2 blocks without verification starting at address 2 and output the received content to /tmp/block:

$mmc rpmb read-block /dev/mmcblk0rpmb 0x02 2 /tmp/block

Write a string of 'a's to address 2 — both the input and the key use the stdin interface, multitasking queen 👑:

$ (awk 'BEGIN {while (c++<256) printf "a"}' | echo -n AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH) | mmc rpmb write-block /dev/mmcblk0rpmb 0x02 - -

🧚 Field Firmware Update (ffu) examples 🧚

Do ffu using the max-possible chunk size: if the fluf size is < 512k, it will be flushed in a single write sequence — efficient, we love her:

$ mmc ffu IO4e0aC2056001801M1100042AE1.fluf /dev/mmcblk0

Same as above, but this time use 4k chunks (baby steps, still slay):

$ mmc ffu IO4e0aC2056001801M1100042AE1.fluf /dev/mmcblk0 4096

🫶 AUTHORS 🫶

mmc-utils was written by Chris Ball <cjb@laptop.org> and <chris@printf.net>. The way that these two cooked 🔥

It is currently maintained by Ulf Hansson <ulf.hansson@linaro.org> — thank you for your service, king 👑

😭 REPORTING BUGS 😭

Found something cursed? Report bugs to the mmc mailing list <linux-mmc@vger.kernel.org> 📬

🌈 SEE ALSO 🌈

okay that's literally the whole page, you ate that 💜 This is the User Manual, dated April 2024, for mmc-utils(1) — go forth and mmc, bestie, no cap 🎀✨🦋

📦 where this page comes from