[PATCH v3 4/5] ufs: document the UFS command

[Raz Ben Yehuda via B4 Relay]

From: Raz Ben Yehuda <raz.benyehuda at mobileye.com>

    Add documentation for the UFS command-line interface.

    The document describes the available UFS subcommands and their usage,
    and provides a complete command-line reference for configuring and
    managing UFS devices.

Signed-off-by: Raz Ben Yehuda <raz.benyehuda at mobileye.com>
---
 doc/usage/cmd/ufs.rst | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)

diff --git a/doc/usage/cmd/ufs.rst b/doc/usage/cmd/ufs.rst
new file mode 100644
index 00000000000..7bc2296ec17
--- /dev/null
+++ b/doc/usage/cmd/ufs.rst
@@ -0,0 +1,202 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+ufs command line
+================
+
+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
+
+Only UnitDescriptor requires a valid LUN id. Other descriptors
+disregard the LUN id.
+
+Example:
+
+
+
+
+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 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 of size of 100xAllocUnitSize
+
+      ufs query 1 1
+
+      ufs set_lun 4 num_allocunits 100
+
+      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.
+
+Set HBA ID
+~~~~~~~~~~~~~~~
+
+    ufs sethba <hbaid>
+
+Use an hba id differs from 0.
+
+
+Init
+~~~~~
+
+    ufs init
+
+Initialize the HBA. This command is not necessary and used for debugging.
+All other commands will initialize automatically if required.
+
+
+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