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

[Raz Ben Yehuda]

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
@@ -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