[PATCH v2 4/5] ufs: document the UFS command

[Quentin Schulz]

Please ignore this mail, I see there is a v5 of this series (without a 
cover-letter, hence why I missed it when looking for new versions) and 
at cursory glance at least a few if not all of the comments have been 
tackled already.

Sorry for the noise

On 6/26/26 11:37 AM, Quentin Schulz wrote:
> Hi Raz Ben Yehuda,
> 
> On 6/7/26 5:45 PM, Raz Ben Yehuda via B4 Relay wrote:
>> From: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
>>
>> Add documentation for the UFS command-line interface.
>>
>> The document describes the available UFS subcommands and their usage,
>> and provides a complete command-line reference for configuring and
>> managing UFS devices.
>>
>> Signed-off-by: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
>> ---
>>   doc/usage/cmd/ufs.rst | 226 ++++++++++++++++++++++++++++++++++++++++ 
>> ++++++++++
>>   1 file changed, 226 insertions(+)
>>
>> diff --git a/doc/usage/cmd/ufs.rst b/doc/usage/cmd/ufs.rst
>> new file mode 100644
>> index 00000000000..1553bc28935
>> --- /dev/null
>> +++ b/doc/usage/cmd/ufs.rst
>> @@ -0,0 +1,226 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +
>> +ufs Tool
>> +========
>> +
>> +The ``ufs`` tool provides utilities for querying, displaying, and 
>> modifying
>> +UFS device configuration and descriptor information.
>> +
> 
> It's not a tool, it's a command.
> 
> Please follow the same template as other command documentation.
> 
> For example, doc/usage/cmd/sm3sum.rst was recently added.
> 
> So:
> 
> .. index::
>     single: ufs (command)
> 
> ufs command
> ===========
> 
> Synopsis
> --------
> 
> ::
> 
> <output of `help ufs` from U-Boot and/or all supported ufs commands, 
> similarly to SYNOPSIS section in manpage>
> 
> Description
> -----------
> 
> <description of each command and their options, see the mmc.rst example 
> for something that is likely closer to the ufs command>
> <you *must* specify if parameters, functions, features, etc... are only 
> available if a specific Kconfig symbol is enabled>
> 
> Examples
> --------
> 
> <typical example usage of the ufs tool with the console output kept>
> 
> Configuration
> -------------
> 
> <specify which Kconfig symbol is necessary to be able to use the ufs 
> command at all>
> <specify which Kconfig symbols are necessary for subcommands or features>
> 
> If the ufs command doesn't follow the general rules applicable to 
> commands (see https://eur02.safelinks.protection.outlook.com/? 
> url=https%3A%2F%2Fdocs.u-boot- 
> project.org%2Fen%2Flatest%2Fusage%2Fcmdline.html%23general- 
> rules&data=05%7C02%7Cquentin.schulz%40cherry.de%7C3871837b97374bfac7e808ded36694bb%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C639180634709249262%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=oqfGHsgWJ8kuajTSmBcstmmRyGVu7b29n%2Bd9zWKOiFg%3D&reserved=0) then you must make this clear as well. Specifically, are numbers parsed as hex values by default or not. Does it return something else than 0 on success?
> 
> This document is also missing
> 
> ufs init
> ufs luns
> ufs clearall
> 
> It documents `ufs sethba` which isn't implemented (at least not provided 
> in the help text of the command).
> 
>> +Features
>> +--------
>> +
>> +* Query and display Device, Geometry, Unit, Configuration, and Power
>> +  Descriptors.
>> +* Display LUN configuration and calculated capacities.
>> +* Modify LUN, Configuration, and Device Descriptor fields.
>> +* Configure WriteBooster-related parameters.
>> +* Query common UFS runtime flags.
>> +* Commit configuration changes or clear all LUN configurations.
>> +* Decode and format descriptor contents for easier debugging.
>> +* Provision UFS devices using exported Configuration Descriptors.
>> +
>> +The UFS tool header definitions are based on the JEDEC JESD220E
>> +*Universal Flash Storage (UFS) Version 3.1* specification.
>> +
>> +Usage
>> +-----
>> +
>> +Query descriptors::
>> +
>> +    ufs query [lun] [idn]
>> +
> 
> This is wrong, lun and idn aren't optional.
> 
>> +Descriptor IDs
>> +~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +    0x00  Device Descriptor
>> +    0x01  Configuration Descriptor
>> +    0x02  Unit Descriptor
>> +    0x07  Geometry Descriptor
>> +    0x08  Power Descriptor
>> +
> 
> What do they do.
> 
>> +Configure a Logical Unit (LUN)
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +    ufs set_lun <lun> <parameter> <value>
>> +
>> +Supported parameters::
>> +
>> +    lu_enable
>> +    boot_lun_id
>> +    lu_write_protect
>> +    memory_type
>> +    data_reliability
>> +    num_allocunits
>> +    logical_block_size
>> +    provisioning_type
>> +    context_capabilities
>> +    lu_num_write_booster_buffer_allocunits
>> +
> 
> What do they do, what are the allowed values.
> 
>> +Modify Device Descriptor fields
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +    ufs set_dev_desc <parameter> <value>
>> +
>> +Supported parameters::
>> +
>> +    descriptor_idn
>> +    device
>> +    device_class
>> +    device_sub_class
>> +    number_lu
>> +    boot_enable
>> +    descr_access_en
>> +    init_power_mode
>> +    high_priority_lun
>> +    secure_removal_type
>> +    initactive_icc_level
>> +    queue_depth
>> +    write_booster_buffer_preserve_user_space_en
>> +    write_booster_buffer_type
>> +    spec_version
>> +    manufacturer_id
>> +    periodic_rtc_update
>> +    device_version
>> +    psa_max_data_size
>> +    extended_ufs_features_support
>> +    num_shared_write_booster_buffer_allocunits
>> +
> 
> What do they do, what are the allowed values.
> 
>> +Modify Configuration Descriptor fields
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +    ufs set_cfg_desc <parameter> <value>
>> +
>> +Supported parameters::
>> +
>> +    length
>> +    descriptor_idn
>> +    conf_desc_continue
>> +    boot_enable
>> +    descr_access_en
>> +    initpower_mode
>> +    high_priority_lun
>> +    secure_removal_type
>> +    init_active_icc_level
>> +    periodic_rtc_update
>> +    reserved_HPB
>> +    rpmb_region_enable
>> +    rpmb_region1_size
>> +    rpmb_region2_size
>> +    rpmb_region3_size
>> +    write_booster_buffer_preserve_user_space_en
>> +    write_booster_buffer_type
>> +    num_shared_write_booster_buffer_allocunits
>> +
> 
> What do they do, what are the allowed values.
> 
>> +Query UFS flags
>> +~~~~~~~~~~~~~~~
>> +
>> +::
>> +
>> +    ufs getflag <flag_name>
>> +
>> +Supported flags::
>> +
>> +    deviceinit
>> +    permanent_wpe
>> +    pwr_on_wpe
>> +    bkops_en
>> +    life_span_mode
>> +    purge_enable
>> +    fphy_resource_removal
>> +    busy_rtc
>> +    permanently_disable_fw_update
>> +    write_booster_en
>> +    wb_buf_flush_en
>> +    wb_buf_flush_h8
>> +
> 
> What do they do, what are the allowed values.
> 
> Cheers,
> Quentin