Hi Raz Ben Yehuda,
On 6/7/26 5:45 PM, Raz Ben Yehuda via B4 Relay wrote:
From: Raz Ben Yehuda <[email protected]>
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 <[email protected]>
---
doc/usage/cmd/ufs.rst | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 226 insertions(+)
diff --git a/doc/usage/cmd/ufs.rst b/doc/usage/cmd/ufs.rst
new file mode 100644
index 00000000000..1553bc28935
--- /dev/null
+++ b/doc/usage/cmd/ufs.rst
@@ -0,0 +1,226 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+ufs Tool
+========
+
+The ``ufs`` tool provides utilities for querying, displaying, and modifying
+UFS device configuration and descriptor information.
+
It's not a tool, it's a command.
Please follow the same template as other command documentation.
For example, doc/usage/cmd/sm3sum.rst was recently added.
So:
.. index::
single: ufs (command)
ufs command
===========
Synopsis
--------
::
<output of `help ufs` from U-Boot and/or all supported ufs commands,
similarly to SYNOPSIS section in manpage>
Description
-----------
<description of each command and their options, see the mmc.rst example
for something that is likely closer to the ufs command>
<you *must* specify if parameters, functions, features, etc... are only
available if a specific Kconfig symbol is enabled>
Examples
--------
<typical example usage of the ufs tool with the console output kept>
Configuration
-------------
<specify which Kconfig symbol is necessary to be able to use the ufs
command at all>
<specify which Kconfig symbols are necessary for subcommands or features>
If the ufs command doesn't follow the general rules applicable to
commands (see
https://docs.u-boot-project.org/en/latest/usage/cmdline.html#general-rules)
then you must make this clear as well. Specifically, are numbers parsed
as hex values by default or not. Does it return something else than 0 on
success?
This document is also missing
ufs init
ufs luns
ufs clearall
It documents `ufs sethba` which isn't implemented (at least not provided
in the help text of the command).
+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]
+
This is wrong, lun and idn aren't optional.
+Descriptor IDs
+~~~~~~~~~~~~~~
+
+::
+
+ 0x00 Device Descriptor
+ 0x01 Configuration Descriptor
+ 0x02 Unit Descriptor
+ 0x07 Geometry Descriptor
+ 0x08 Power Descriptor
+
What do they do.
+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
+
What do they do, what are the allowed values.
+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
+
What do they do, what are the allowed values.
+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
+
What do they do, what are the allowed values.
+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
+
What do they do, what are the allowed values.
Cheers,
Quentin
