[PATCH 5/5] ufs: doc/README.ufs

[Neil Armstrong]

Hi,

On 6/3/26 14:45, Raz Ben Yehuda wrote:
> Documention of the ufs tool.
> 
> Signed-off-by: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
> ---
>   doc/README.ufs | 217 +++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 217 insertions(+)
>   create mode 100644 doc/README.ufs
> 
> diff --git a/doc/README.ufs b/doc/README.ufs
> new file mode 100644
> index 00000000000..bd9f5cd2856
> --- /dev/null
> +++ b/doc/README.ufs

This should be reStructuredText and placed in the right path like doc/usage/cmd/ufs.rst

Neil

> @@ -0,0 +1,217 @@
> +			ufs_tool
> +		**********************
> + The UFS tool provides utilities for querying, displaying, and modifying
> +UFS device configuration and descriptor information.
> +
> +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
> +- Clear
> +- Provisioning
> +
> +The UFS tool header definitions are based on the JEDEC Standard JESD220E:
> +Universal Flash Storage (UFS) Version 3.1.
> +
> +--------------------------------
> +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 luns, and commits.
> +
> +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.
> +
> +   Example:
> +
> +       Config Descriptor: (0x00000008ffffc610)
> +       Length                          : 0x0e6
> +       DescriptorIdn                   : 0x01
> +       ConfDescContinue                : 0x00
> +       BootEnable                      : 0x01
> +       ...
> +
> +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. Load the currect Configuration descriptor.
> +    ufs query 1 1
> +       Config Descriptor: (0x00000008ffffce00)
> +       Length                          : 0x0e6
> +       DescriptorIdn                   : 0x01
> +       ConfDescContinue                : 0x00
> +       BootEnable                      : 0x01
> +
> +
> +2. Load the configuration file onto Configuration Descriptor using XMODEM or TFTP.
> +   Examples:
> +
> +       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.