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