From: Raz Ben Yehuda <[email protected]> Documention of the ufs tool.
Signed-off-by: Raz Ben Yehuda <[email protected]> --- 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. + +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. -- 2.43.0
