> On 27/03/2024 18:45, Avri Altman wrote:
> > I have put together a draft man page for mmc-utils. The contents are
> > from mmc-utils help documents and edited for brevity. The point is
> > not to replace the existing docmentation, but to serve as a quick reference.
> >
> > Signed-off-by: Avri Altman <avri.altman@xxxxxxx>
> > ---
> >
> > Changelog:
> > v1->v2: Fix some spelling mistakes
> > ---
> > Makefile | 9 +-
> > mmc.1 | 308
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > 2 files changed, 312 insertions(+), 5 deletions(-) create mode
> > 100644 mmc.1
> >
> > diff --git a/Makefile b/Makefile
> > index 10b78ab..a890833 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -21,6 +21,7 @@ prefix ?= /usr/local bindir = $(prefix)/bin LIBS=
> > RESTORE_LIBS=
> > +mandir = /usr/share/man
> >
> > progs = mmc
> >
> > @@ -29,7 +30,7 @@ ifdef C
> > check = sparse $(CHECKFLAGS)
> > endif
> >
> > -all: $(progs) manpages
> > +all: $(progs)
> >
> > .c.o:
> > ifdef C
> > @@ -43,16 +44,14 @@ mmc: $(objects)
> > manpages:
> > $(MAKE) -C man
> >
> > -install-man:
> > - $(MAKE) -C man install
> > -
> > clean:
> > rm -f $(progs) $(objects)
> > $(MAKE) -C man clean
> >
> > -install: $(progs) install-man
> > +install: $(progs)
> > $(INSTALL) -m755 -d $(DESTDIR)$(bindir)
> > $(INSTALL) $(progs) $(DESTDIR)$(bindir)
> > + $(INSTALL) -m 644 mmc.1 $(DESTDIR)$(mandir)/man1
> >
> > -include $(foreach obj,$(objects), $(dir $(obj))/.$(notdir $(obj)).d)
> >
> > diff --git a/mmc.1 b/mmc.1
> > new file mode 100644
> > index 0000000..888b8b6
> > --- /dev/null
> > +++ b/mmc.1
> > @@ -0,0 +1,308 @@
> > +.TH mmc\-utils 1 "April 2024" "User Manual"
> > +.SH NAME
> > +mmc \- a tool for configuring MMC storage devices .SH SYNOPSIS .B
> > +mmc [\fIoptions\fR] [\ mmc\-block\-device\fR]...
> > +.SH DESCRIPTION
> > +.B mmc-utils
> > +is a single-threaded tool that will perform a particular type of mmc action as
> specified by the user.
> > +.br
> > +The typical use of mmc-utils is to access the mmc device either for
> configuring or reading its configuration registers.
> > +.SH OPTIONS
> > +.TP
> > +.BI extcsd " " read " " \fIdevice\fR
> > +Read and prints the extended csd register .TP .BI extcsd " " write "
> > +" \fIoffset\fR " " \fIvalue\fR " " \fIdevice\fR Write \fIvalue\fR at
> > +\fIoffset\fR to the device's extcsd .TP .BI writeprotect " " boot " "
> > +get " " \fIdevice\fR Print the boot partitions write protect status
> > +.TP .BI writeprotect " " boot " " set " " \fIdevice\fR " "
> > +[\fInumber\fR] Set the boot partition write protect status for the
> > +device.
> > +.br
> > +If \fInumber\fR is passed (0 or 1), only protect that particular eMMC boot
> partition, otherwise protect both.
> s/particular/specified/?
Done.
> > +.br
> > +It will be write-protected until the next boot.
> > +.TP
> > +.BI writeprotect " " user " " set " " \fItype\fR " "
> > +\fIstart\-block\fR " " \fIblocks\fR " " \fIdevice\fR Set the write protect
> configuration for the specified region of the user area for the device.
> > +.br
> > +\fIstart\-block\fR specifies the first block of the protected area.
> > +.br
> > +\fIblocks\fR specifies the size of the protected area in blocks.
> > +.br
> > +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.
> > + \fItype\fR is one of the following:
> > +.RS
> > +.RS
> > +.TP
> > +.B none
> > +Clear temporary write protection.
> > +.TP
> > +.B temp
> > +Set temporary write protection.
> > +.TP
> > +.B pwron
> > +Set write protection until the next power on.
> > +.RE
> > +.RE
> > +.TP
> > +.BI writeprotect " " user " " get " " \fIdevice\fR Print the user
> > +areas write protect configuration for the device.
> s/areas/area's
Done.
> > +.TP
> > +.BI disable " " 512B " " emulation " " \fIdevice\fR Set the eMMC data
> > +sector size to 4KB by disabling emulation on the device.
> > +.TP
> > +.BI gp " " create " " \fIdry\-run\fR " " \fIlength\-KiB\fR " "
> > +\fIpartition\fR " " \fIenh\-attr\fR " " \fIext\-attr\fR " " \fIdevice\fR Create
> general purpose partition for the the device.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> > +.br
> > +To set enhanced attribute to general partition being created set \fIenh\-
> attr\fR to 1 else set it to 0.
> > +.br
> > +To set extended attribute to general partition set \fIenh\-attr\fR to 1,2 else
> set it to 0.
> > +.br
> > +\fIdry\-run\fR is one of the following:
> > +.RS
> > +.RS
> > +.TP
> > +.B \-y
> > +PARTITION_SETTING_COMPLETED in the extcsd will get set and the
> partisioning operation will take effect and finalized.
> s/partisioning/partitioning
> s/and finalized/and be finalized/?
Done.
> > +.TP
> > +.B \-c
> > +more partitioning settings are still to come - partitioning operation will not
> take effect.
> > +.TP
> > +.B otherwise
> > +These changes will not take effect neither now nor after a power cycle.
> > +.RE
> > +.RE
> > +.TP
> > +.BI enh_area " " set " " \fIdry\-run\fR " " \fIstart\-KiB\fR " "
> > +\fIlength\-KiB\fR " " \fIdevice\fR Enable the enhanced user area for the
> device.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> s/unreversible/irreversible
> > +\fIdry\-run\fR is as above.
> > +.TP
> > +.BI write_reliability " " set " " " \fIdry\-run\fR " "
> > +\fIpartition\fR " " \fIdevice\fR Enable write reliability per partition for the
> device.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> s/unreversible/irreversible
Done.
> > +\fIdry\-run\fR is as above.
> > +.TP
> > +.BI status " " get " " \fIdevice\fR
> > +Print the response to STATUS_SEND (CMD13).
> > +.TP
> > +.BI bootpart " " enable " " \fIboot\-partition\fR " "
> > +\fIsend\-ackn\fR " " \fIdevice\fR Enable the boot partition for the device.
> > +Disable the boot partition for the device if is \fIboot\-partition\fR set to 0.
> > +.br
> > +To receive acknowledgment of boot from the card set \fIsend\-ackn\fR to 1,
> else set it to 0.
> > +.TP
> > +.BI bootbus " " set " " \fIboot\-mode\fR " "
> > +\fIreset\-boot\-bus\-conditions\fR " " \fIboot\-bus\-width\fR " " \fIdevice\fR
> Set Boot Bus Conditions.
> > +.br
> > +\fIboot\-mode\fR is one of the following: single_backward, single_hs, or
> dual.
> > +.br
> > +\fIreset\-boot\-bus\-conditions\fR is one of the following: x1 or retain.
> > +.br
> > +\fIboot\-bus\-width\fR is one of the following: x1, x4, or x8.
> > +.TP
> > +.BI bkops_en " " \fImode\fR " " \fIdevice\fR Enable the eMMC BKOPS
> > +feature on the device.
> > +The auto (AUTO_EN) setting is only supported on eMMC 5.0 or newer.
> > +.br
> > +NOTE! Setting manual (MANUAL_EN) is one-time programmable
> (unreversible) change.
> s/unreversible/irreversible
Done.
> > +.br
> > +\fImode\fR is one of the following:
> > +.RS
> > +.RS
> > +.TP
> > +.B auto
> > +Auto backops is set
> > +.TP
> > +.B manual
> > +Manual bkops is set
> > +.RE
> > +.RE
> > +.TP
> > +.BI hwreset " " enable " " \fIdevice\fR Permanently enable the eMMC
> > +H/W Reset feature on the device.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> s/unreversible/irreversible
Done.
> > +.TP
> > +.BI hwreset " " disable " " \fIdevice\fR Permanently disable the eMMC
> > +H/W Reset feature on the device.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> s/unreversible/irreversible
Done.
> > +.TP
> > +.BI sanitize " " \fIdevice\fR " " \fI[timeout_ms]\fR Send Sanitize
> > +command to the device.
> > +This will delete the unmapped memory region of the device.
> > +.TP
> > +.BI rpmb " " write\-key " " \fIrpmb\-device\fR " " \fIkey\-file\fR
> > +Program authentication key which is 32 bytes length and stored in the
> specified file.
> > +.br
> > +Also you can specify '-' instead of key file path to read the key from stdin.
> > +.br
> > +NOTE! This is a one-time programmable (unreversible) change.
> s/unreversible/irreversible
Done.
Thanks a lot,
Avri
> > +.TP
> > +.BI rpmb " " read\-counter " " \fIrpmb\-device\fR Counter value for
> > +the \fIrpmb\-device\fR will be read to stdout.
> > +.TP
> > +.BI rpmb " " read\-block " " \fIrpmb\-device\fR " " \fIaddress\fR " "
> > +\fIblocks-\count\fR " " \fIoutput-\file\fR " " [\fIkey\-file\fR]
> > +Blocks of 256 bytes will be read from \fIrpmb\-device\fR to output
> > +file or stdout if '-' is specified. If key is specified - read data will be verified.
> > +.TP
> > +.BI rpmb " " write\-block " " \fIrpmb\-device\fR " " \fIaddress\fR "
> > +" \fI256\-byte\-data\-file\fR " " \fIkey\-file\fR Block of 256 bytes
> > +will be written from data file to \fIrpmb\-device\fR.
> > +.br
> > +Also you can specify '-' instead of key file path or data file to read the data
> from stdin.
> > +.TP
> > +.BI cache " " enable " " \fIdevice\fR Enable the eMMC cache feature
> > +on the device.
> > +.br
> > +NOTE! The cache is an optional feature on devices >= eMMC4.5.
> > +.TP
> > +.BI cache disable " " \fIdevice\fR
> > +Disable the eMMC cache feature on the device.
> > +.br
> > +NOTE! The cache is an optional feature on devices >= eMMC4.5.
> > +.TP
> > +.BI csd " " read " " \fidevice\-path\fR Print CSD data from
> > +\fIdevice\-path\fR.
> > +The device path should specify the csd sysfs file directory.
> > +.TP
> > +.BI cid " " read " " \fIdevice\-path\fR Print CID data from
> > +\fIdevice\-path\fR.
> > +The device path should specify the cid sysfs file directory.
> > +.TP
> > +.BI scr " " read " " \fIdevice\-path\fR Print SCR data from
> > +\fIdevice\-path\fR.
> > +The device path should specify the scr sysfs file directory.
> > +.TP
> > +.BI ffu " " \fIimage\-file\-name\fR " " \fIdevice\fR " "
> > +[\fIchunk\-bytes\fR] Run Field Firmware Update with \fIimage\-file\-name\fR
> on the device.
> > +.br
> > +[\fIchunk\-bytes\fR] is optional and defaults to its max - 512k. should be in
> decimal bytes and sector aligned.
> > +.br
> > +if [\fIchunk\-bytes\fR] is omitted, mmc-utils will try to run ffu using the
> largest possible chunks: max(image-file, 512k).
> > +.TP
> > +.BI erase " " \fItype\fR " " \fIstart-address\fR " "
> > +\fIend\-address\fR " " \fIdevice\fR Send Erase CMD38 with specific argument
> to the device.
> > +.br
> > +NOTE!: This will delete all user data in the specified region of the device.
> > +.br
> > +\fItype\fR is one of the following: legacy, discard, secure-erase, secure-trim1,
> secure-trim2, or trim.
> > +.TP
> > +.BI gen_cmd " " read " \fidevice\fR [\fIarg\fR] Send GEN_CMD (CMD56)
> > +to read vendor-specific format/meaning data from the device.
> > +.br
> > +NOTE!: [\fIarg\fR] is optional and defaults to 0x1. If [\fIarg\fR] is
> > +specified, then [\fIarg\fR] must be a 32-bit hexadecimal number, prefixed
> with 0x/0X. And bit0 in [\fIarg\fR] must be 1.
> > +Normally this command is aimed to extract a device-health info from the
> device.
> > +.TP
> > +.BI softreset " " \fIdevice\fR
> > +Issues a CMD0 softreset, e.g. for testing if hardware reset for UHS
> > +works .TP .BI boot_operation " " \fIboot\-data\-file\fR " "
> > +\fIdevice\fR Does the alternative boot operation and writes the
> > +specified starting blocks of boot data into the requested file.
> > +Note some limitations:
> > +.RS
> > +.RS
> > +.TP
> > +.B 1)
> > +The boot operation must be configured first, e.g. via bootbus and/or
> > +bootpart commands .TP .B 2) The MMC must currently be running at the
> > +bus mode that is configured for the boot operation (HS200 and HS400 not
> supported at all).
> > +.TP
> > +.B 3)
> > +Only up to 512K bytes of boot data will be transferred.
> > +.TP
> > +.B 4)
> > +The MMC will perform a soft reset, if your system cannot handle that do not
> use the boot operation from mmc-utils.
> > +.RE
> > +.RE
> > +.TP
> > +.BI \-\-help " " | " " help " " | " " \-h Show the help .TP .BI
> > +\fIcmd\fR " " \-\-help Show detailed help for that specific \fIcmd\fR
> > +or subset of commands.
> > +.SH "RPMB COMMANDS"
> > +The RPMB partition on the eMMC devices is a special area used for
> > +storing cryptographically safe information signed by a special secret key.
> > +.br
> > +To write and read records from this special area, authentication is needed.
> > +.br
> > +The RPMB area is *only* and *exclusively* accessed using ioctl()s from
> user-space.
> > +.br
> > +RPMB commands are send using the mmc multi-ioctl, thus ensures that the
> atomic nature of the rpmb access operation.
> > +.br
> > +The rpmb device given as a parameter to the rpmb commands is not a block
> device but a char device.
> > +.br
> > +This was done to help the mmc driver to account for some of the rpmb
> peculiarities.
> > +.SH "EXAMPLES"
> > +.RE
> > +.P
> > +.B RPMB examples
> > +.RS
> > +Program rpmb key using the stdin option:
> > +.RS
> > +.P
> > +$ echo -n AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH | mmc rpmb write-
> key
> > +/dev/mmcblk0rpmb - .RE .P Read 2 blocks starting address 2 and output
> > +the received content to stdout. Verify the received frames using the key (not
> mandatory):
> > +.RS
> > +.P
> > +$ echo -n AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH | mmc rpmb read-
> block
> > +/dev/mmcblk0rpmb 0x02 2 - .RE .P Read 2 blocks without verification
> > +starting address 2 and output the received content to /tmp/block:
> > +.RS
> > +.P
> > +$mmc rpmb read-block /dev/mmcblk0rpmb 0x02 2 /tmp/block .RE .P Write
> > +a string of 'a's to address 2. both the input and key uses stdin interface:
> > +.RS
> > +.P
> > +$ (awk 'BEGIN {while (c++<256) printf "a"}' | echo -n
> > +AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH) | mmc rpmb write-block
> > +/dev/mmcblk0rpmb 0x02 - - .RE .P .RE .P .B Field Firmware Update
> > +(ffu) examples .RS Do ffu using max-possible chunk size: If the fluf
> > +size < 512k, it will be flushed in a single write sequence.
> > +.RS
> > +.P
> > +$ mmc ffu IO4e0aC2056001801M1100042AE1.fluf /dev/mmcblk0 .RE .P
> Same
> > +as above, this time use a 4k chunks:
> > +.RS
> > +.P
> > +$ mmc ffu IO4e0aC2056001801M1100042AE1.fluf /dev/mmcblk0 4096 .RE
> .P
> > +.RE .SH AUTHORS .B mmc-utils was written by Chris Ball
> > +<cjb@xxxxxxxxxx> and <chris@xxxxxxxxxx>.
> > +.br
> > +It is currently maintained by Ulf Hansson <ulf.hansson@xxxxxxxxxx>.
> > +.SH "REPORTING BUGS"
> > +Report bugs to the \fBmmc\fR mailing list <linux-mmc@xxxxxxxxxxxxxxx>.
> > +.SH "SEE ALSO"
> > +For further documentation see \fBREADME\fR.
> > +.br
> > +A short intro - https://docs.kernel.org/driver-api/mmc/mmc-tools.html
> > +.br
> > +official git tree -
> > +https://git.kernel.org/pub/scm/utils/mmc/mmc-utils.git
>
