[PATCH PATCHSET 6/6] ufs: doc/usage/cmd/ufs.rst

[Neil Armstrong]

On 6/4/26 13:25, Raz Ben Yehuda via B4 Relay wrote:
> From: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
> 
> Documention of the ufs tool.

Change the subject to something like "ufs: document the ufs command"

> 
> Signed-off-by: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
> ---
>   doc/usage/cmd/ufs.rst | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 217 insertions(+)
> 
> diff --git a/doc/usage/cmd/ufs.rst b/doc/usage/cmd/ufs.rst
> new file mode 100644
> index 00000000000..a6faf4b1347
> --- /dev/null
> +++ b/doc/usage/cmd/ufs.rst
> @@ -0,0 +1,217 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +ufs Tool
> +========
> +
> +The ``ufs`` tool provides utilities for querying, displaying, and modifying
> +UFS device configuration and descriptor information.

Please document the other UFS subcommands aswell.

Thanks,
Neil

> +
> +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]
> +
> +Descriptor IDs
> +~~~~~~~~~~~~~~
> +
> +::
> +
> +    0x00  Device Descriptor
> +    0x01  Configuration Descriptor
> +    0x02  Unit Descriptor
> +    0x07  Geometry Descriptor
> +    0x08  Power Descriptor
> +
> +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
> +
> +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
> +
> +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
> +
> +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
> +
> +Examples
> +--------
> +
> +Create LUN 4::
> +
> +    ufs query 1 1
> +    ufs set_lun 4 num_allocunits <size_in_alloc_units>
> +    ufs commit
> +    scsi scan
> +
> +Update WriteBooster configuration::
> +
> +    ufs query 1 1
> +    ufs set_cfg_desc num_shared_write_booster_buffer_allocunits 100000
> +    ufs set_cfg_desc write_booster_buffer_type 1
> +    ufs commit
> +
> +Clear all LUN configurations::
> +
> +    ufs clearall
> +
> +This command clears all configured LUNs and commits the change.
> +
> +Provisioning
> +------------
> +
> +To simplify UFS provisioning, the tool displays the memory address and
> +size of the Configuration Descriptor (IDN 0x01). This allows the
> +descriptor to be exported from one system and imported on another.
> +
> +Provisioning workflow
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Source system
> +^^^^^^^^^^^^^
> +
> +1. Display the Configuration Descriptor::
> +
> +       ufs query 1 1
> +
> +   The output includes the Configuration Descriptor address and size.
> +
> +2. Save the Configuration Descriptor to a file::
> +
> +       tftpput <cfg_desc_addr> <size> <filename>
> +
> +   Example::
> +
> +       tftpput 0x8ffffc610 0xe6 luns.bin
> +
> +   This exports the current UFS configuration, including LUN settings.
> +
> +Target system
> +^^^^^^^^^^^^^
> +
> +1. Display the current Configuration Descriptor::
> +
> +       ufs query 1 1
> +
> +2. Load the configuration file into the Configuration Descriptor buffer
> +   using XMODEM or TFTP::
> +
> +       loadx 0x8ffffce00
> +
> +   or::
> +
> +       tftpget 0x8ffffce00 luns.bin
> +
> +3. Commit the configuration to the UFS device::
> +
> +       ufs commit
> +
> +   The imported Configuration Descriptor is written to the device and
> +   becomes active after the commit operation completes.
>