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

[Quentin Schulz]

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://docs.u-boot-project.org/en/latest/usage/cmdline.html#general-rules) 
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