Skip to contentSkip to conversation

(no cover subject)

PATCH Superseded Raz Ben Yehuda 2 participants 9 messages Jun 8 SCSI

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v3 cover (no cover subject)

Changes in v3:
- remove set_dev_desc command. DeviceDescriptor is not writable
- Beautify the rst document
- Link to v2: https://patch.msgid.link/[email protected]

ufs: Exted cmd line

The UFS command provides utilities for querying, displaying, and modifying UFS device configuration and descriptor information. It is commonly used to configure UFS logical units (LUNs) in U-Boot, allowing storage devices to be provisioned and reconfigured as needed.

Features:

* Display Device, Geometry, Unit, Configuration, and Power Descriptors
* Display LUN configuration and calculated capacities
* Modify fields in Device, Configuration, and Unit Descriptors
* Query common UFS runtime flags
* Commit configuration changes or clear all LUN configurations
* Decode and format descriptor contents for easier debugging
* Provision and configure UFS logical units

Changes in v2:

* Add HBA ID support
* Move ufs_tool.c to cmd/ufs.c
* Add myself as reviewer
* Rename patch subject to "ufs: document the UFS command"

To: [email protected]

Cc:      Neil Armstrong <[email protected]>
Cc:      Bhupesh Sharma <[email protected]>
Cc:      Neha Malcom Francis <[email protected]>
Cc:      Tawfik Bayouk  <[email protected]>
Cc:      Vladimir Kondratiev  <[email protected]>

---
Raz Ben Yehuda (5):
ufs: Expose selected UFS functions
ufs: Add flags according
ufs: extending ufs cmd line
ufs: document the UFS command
MAINTAINERS: Add myself to the list of UFS maintainers

 MAINTAINERS              |    3 +
 cmd/Makefile             |    1 +
 cmd/ufs.c                | 1271 +++++++++++++++++++++++++++++++++++++++++++++-
 doc/usage/cmd/ufs.rst    |  202 ++++++++
 drivers/ufs/ufs-uclass.c |   18 +-
 drivers/ufs/ufs.h        |   16 +
 include/ufs.h            |  374 +++++++++++++-
 7 files changed, 1867 insertions(+), 18 deletions(-)

---
base-commit: 0c035ff60c1e8caee7fccd2673ce75380dee825b
change-id: 20260607-ufs_tool2-11c3493690c4

Best regards,

Signature · 1 line
Raz Ben Yehuda <[email protected]>
#1 lore raw

PATCH v3 1/5 ufs: Expose selected UFS functions

Remove static qualifier from selected functios to allow future use

---
 drivers/ufs/ufs-uclass.c | 18 +++++++++---------
 drivers/ufs/ufs.h        | 13 +++++++++++++
 2 files changed, 22 insertions(+), 9 deletions(-)
drivers/ufs/ufs-uclass.c +9 -9
index 6a51f337e47..78f6064ddea 100644
@@ -757,7 +757,7 @@ static inline u8 ufshcd_get_upmcrs(struct ufs_hba *hba)
  *
  * Flush cache in aligned address..address+size range.
  */
-static void ufshcd_cache_flush(void *addr, unsigned long size)
+void ufshcd_cache_flush(void *addr, unsigned long size)
 {
 	uintptr_t start_addr = (uintptr_t)addr & ~(ARCH_DMA_MINALIGN - 1);
 	uintptr_t end_addr = ALIGN((uintptr_t)addr + size, ARCH_DMA_MINALIGN);
@@ -1089,8 +1089,8 @@ static inline void ufshcd_init_query(struct ufs_hba *hba,
 /**
  * ufshcd_query_flag() - API function for sending flag query requests
  */
-static int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
-			     enum flag_idn idn, bool *flag_res)
+int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
+		      enum flag_idn idn, bool *flag_res)
 {
 	struct ufs_query_req *request = NULL;
 	struct ufs_query_res *response = NULL;
@@ -1320,9 +1320,9 @@ out:
 /**
  * ufshcd_query_descriptor_retry - API function for sending descriptor requests
  */
-static int ufshcd_query_descriptor_retry(struct ufs_hba *hba, enum query_opcode opcode,
-					 enum desc_idn idn, u8 index, u8 selector,
-					 u8 *desc_buf, int *buf_len)
+int  ufshcd_query_descriptor_retry(struct ufs_hba *hba, enum query_opcode opcode,
+				   enum desc_idn idn, u8 index, u8 selector,
+				   u8 *desc_buf, int *buf_len)
 {
 	int err;
 	int retries;
@@ -1457,9 +1457,9 @@ static int ufshcd_map_desc_id_to_length(struct ufs_hba *hba, enum desc_idn desc_
  * ufshcd_read_desc_param - read the specified descriptor parameter
  *
  */
-static int ufshcd_read_desc_param(struct ufs_hba *hba, enum desc_idn desc_id,
-				  int desc_index, u8 param_offset,
-				  u8 *param_read_buf, u8 param_size)
+int ufshcd_read_desc_param(struct ufs_hba *hba, enum desc_idn desc_id,
+			   int desc_index, u8 param_offset,
+			   u8 *param_read_buf, u8 param_size)
 {
 	int ret;
 	u8 *desc_buf;
drivers/ufs/ufs.h +13 -0
index 0f6c93fbce7..213b489e5e4 100644
@@ -809,4 +809,17 @@ static inline void ufshcd_rmwl(struct ufs_hba *hba, u32 mask, u32 val, u32 reg)
 
 int ufshcd_probe(struct udevice *dev, struct ufs_hba_ops *hba_ops);
 
+int ufshcd_read_desc_param(struct ufs_hba *hba, enum desc_idn desc_id,
+			   int desc_index, u8 param_offset, u8 *param_read_buf,
+			   u8 param_size);
+
+void ufshcd_cache_flush(void *addr, unsigned long size);
+
+int ufshcd_query_flag(struct ufs_hba *hba, enum query_opcode opcode,
+		      enum flag_idn idn, bool *flag_res);
+
+int ufshcd_query_descriptor_retry(struct ufs_hba *hba, enum query_opcode opcode,
+				  enum desc_idn idn, u8 index, u8 selector,
+				  u8 *desc_buf, int *buf_len);
+
 #endif
Signature · 1 line
2.43.0
#2 lore raw

Re: [PATCH v3 1/5] ufs: Expose selected UFS functions

Quoted 8 lines · Raz Ben Yehuda

Remove static qualifier from selected functios to allow future use

---
 drivers/ufs/ufs-uclass.c | 18 +++++++++---------
 drivers/ufs/ufs.h        | 13 +++++++++++++
 2 files changed, 22 insertions(+), 9 deletions(-)

Making these functions public means that the kernel-doc portions need to moved too, and put in include/ufs.h. This fixes the problem of having to get drivers/ufs/ufs.h included by cmd/ufs.c in a later patch.

Signature · 1 line
Tom
#3 lore raw

PATCH v3 2/5 ufs: Add flags according

In reply to Raz Ben Yehuda

Some flags are missing according to UFS 3.1

---
 drivers/ufs/ufs.h | 3 +++
 1 file changed, 3 insertions(+)
drivers/ufs/ufs.h +3 -0
index 213b489e5e4..75b7ff83155 100644
@@ -218,6 +218,9 @@ enum flag_idn {
 	QUERY_FLAG_IDN_BUSY_RTC				= 0x09,
 	QUERY_FLAG_IDN_RESERVED3			= 0x0A,
 	QUERY_FLAG_IDN_PERMANENTLY_DISABLE_FW_UPDATE	= 0x0B,
+	QUERY_FLAG_IDN_F_WRITE_BOOSTER_EN               = 0x0E,
+	QUERY_FLAG_IDN_F_WB_BUF_FLUSH_EN                = 0x0F,
+	QUERY_FLAG_IDN_F_WB_BUF_FLUSH_HIBERN8           = 0x10
 };
 
 /* Attribute idn for Query requests */
Signature · 1 line
2.43.0
#4 lore raw

PATCH v3 3/5 ufs: extending ufs cmd line

In reply to Raz Ben Yehuda

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
- Query common UFS runtime flags
- Commit configuration changes or clear all LUN configurations
- Decode and format descriptor contents
- Provisioning

---
 cmd/Makefile  |    1 +
 cmd/ufs.c     | 1271 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 include/ufs.h |  374 ++++++++++++++++-
 3 files changed, 1637 insertions(+), 9 deletions(-)
cmd/Makefile +1 -0
index bbbdfcc4ded..fef7c054881 100644
@@ -300,3 +300,4 @@ $(obj)/license_data_size.h: $(srctree)/Licenses/gpl-2.0.txt FORCE
 	$(call filechk,data_size)
 
 CFLAGS_ethsw.o := -Wno-enum-conversion
+CFLAGS_ufs.o :=  -include drivers/ufs/ufs.h
cmd/ufs.c +1264 -7

1,291 lines not on this page · raw message

include/ufs.h +372 -2

382 lines not on this page · raw message

Signature · 1 line
2.43.0
#5 lore raw

Re: [PATCH v3 3/5] ufs: extending ufs cmd line

Quoted 2 lines · Raz Ben Yehuda

The UFS tool provides utilities for querying, displaying, and modifying UFS device configuration and descriptor information.

This still reads like you're adding a new command, which you aren't anymore. Please reword all of this to make sense again given that it's now part of the existing ufs command.

[snip]

Quoted 24 lines
cmd/ufs.c +14 -1
index 790dab50f18..203a58d6026 100644
@@ -3,12 +3,1191 @@
  * ufs.c - UFS specific U-Boot commands
  *
  * Copyright (C) 2019 Texas Instruments Incorporated - https://www.ti.com
- *
+ * Copyright (C) 2026 Mobileye Incorporated - https://www.mobileye.com
  */
+#include <asm/io.h>
+#include <dm/devres.h>
+#include <errno.h>
+#include <limits.h>
+#include <linux/bitops.h>
+#include <linux/byteorder/little_endian.h>
+#include <linux/compiler.h>
+#include <linux/delay.h>
+#include <linux/dma-mapping.h>
+#include <linux/kernel.h>
+#include <linux/types.h>
+#include <malloc.h>
+#include <stdio.h>

cmd/ufs.c line 11

Quoted 10 lines
cmd/ufs.c +6 -2
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <dm/uclass.h>
+#include <dm/device.h>
 #include <command.h>
+
 #include <ufs.h>
-#include <vsprintf.h>
-#include <linux/string.h>

Please audit this new big list of includes to make sure you're only adding what's required.

[snip]

cmd/ufs.c line 585

Quoted 5 lines
cmd/ufs.c +5 -0
+int ufshcd_query_desc_idn_power(struct ufs_hba *hba, int lun,
+				struct ufs_power_parameters_descriptor
+				*out_desc)
+{
+	unsigned char Space[QUERY_DESC_POWER_DEF_SIZE];

That's not a good variable name, and do we need to allocate this on the stack like that?

Quoted 57 lines
cmd/ufs.c +57 -0
+#define CMD_HELP \
+		"query:\n" \
+		"\tDevice desc (0h)\n" \
+		"\tGeometry desc(7h)\n" \
+		"\tPower desc (8h)\n" \
+		"\tUnit desc(2h)\n" \
+		"\tConfig desc(1h)\n" \
+		"****************************\n" \
+		"\n\tset_lun [LUN] (parm)\n" \
+		"\t\tlu_enable\n" \
+		"\t\tboot_lun_id\n" \
+		"\t\tlu_write_protect\n" \
+		"\t\tmemory_type\n" \
+		"\t\tdata_reliability\n" \
+		"\t\tnum_allocunits\n" \
+		"\t\tlogical_block_size\n" \
+		"\t\tprovisioning_type\n" \
+		"\t\tcontext_capabilities\n" \
+		"\t\tlu_num_write_booster_buffer_allocunits\n\n" \
+		"****************************\n" \
+		"\n\tset_cfg_desc [parm] [value]\n" \
+		"\t\tlength\n" \
+		"\t\tdescriptor_idn\n" \
+		"\t\tconf_desc_continue\n" \
+		"\t\tboot_enable\n" \
+		"\t\tdescr_access_en\n" \
+		"\t\tinitpower_mode\n" \
+		"\t\thigh_priority_lun\n" \
+		"\t\tsecure_removal_type\n" \
+		"\t\tinit_active_icc_level\n" \
+		"\t\tperiodic_rtc_update\n" \
+		"\t\treserved_HPB\n" \
+		"\t\trpmb_region_enable\n" \
+		"\t\trpmb_region1_size\n" \
+		"\t\trpmb_region2_size\n" \
+		"\t\trpmb_region3_size\n" \
+		"\t\twrite_booster_buffer_preserve_user_space_en\n" \
+		"\t\twrite_booster_buffer_type\n" \
+		"\t\tnum_shared_write_booster_buffer_allocunits\n" \
+		"****************************\n" \
+		"\n\tgetflag [flag name]\n" \
+		"\t\tdeviceinit\n" \
+		"\t\tpermanent_wpe\n" \
+		"\t\tpwr_on_wpe\n" \
+		"\t\tbkops_en\n" \
+		"\t\tlife_span_mode\n" \
+		"\t\tpurge_enable\n" \
+		"\t\tfphy_resource_removal\n" \
+		"\t\tbusy_rtc\n" \
+		"\t\tpermanently_disable_fw_update\n" \
+		"\t\twrite_booster_en\n" \
+		"\t\twb_buf_flush_en\n" \
+		"\t\twb_buf_flush_h8\n" \
+		"****************************\n" \
+		"\texamples :\n" \
+		"\n\nto write lun please\n" \
+		"\tufs query 0 1\n" \

cmd/ufs.c line 892

Quoted 10 lines
cmd/ufs.c +10 -0
+		"\tfix the luns, disable lu_enable\n" \
+		"\tuse ufs set_lun [LUN] num_allocunits=xxx to set size\n" \
+		"\tufs set_cfg_desc num_shared_write_booster_buffer_allocunits 100000\n" \
+		"\tufs set_cfg_desc write_booster_buffer_type 1\n" \
+		"\tufs commit\n"
+
+void ufs_tool_help(void)
+{
+	puts(CMD_HELP);
+}

Please integrate this, properly, to the existing command. It seems like you just copy/pasted the previous ufs_tool.c file in to cmd/ufs.c instead.

[snip]

Quoted 4 lines
include/ufs.h +0 -0
index f6e27d90e43..89fde263fcf 100644

[snip]

include/ufs.h int ufs_probe(void); · line 391

Quoted 13 lines
include/ufs.h +13 -0
+int ufshcd_query_desc_idn_geometry(struct ufs_hba *hba,
+				   struct ufs_geometry_descriptor *decs);
+int ufshcd_query_desc_idn_config(struct ufs_hba *hba, struct ufs_config_descriptor *cfg);
+int ufshcd_query_desc_idn_device(struct ufs_hba *hba, struct ufs_device_descriptor *desc);
+int ufshcd_query_desc_idn_unit(struct ufs_hba *hba, int lun,
+			       struct unit_descriptor *desc);
+void ufshcd_print_idn_geometry_desc(struct ufs_geometry_descriptor *desc);
+void ufshcd_print_device_descriptor(struct ufs_device_descriptor *desc);
+void ufshcd_print_unit_descriptor(struct unit_descriptor *desc);
+int ufshcd_query_desc_idn_power(struct ufs_hba *hba, int lun,
+				struct ufs_power_parameters_descriptor *desc);
+void print_ufs_power_parameters(struct ufs_power_parameters_descriptor *desc);
+int ufshcd_query_user_flag(struct ufs_hba *hba, const char *flag_name);

These all need appropriate kernel-doc comments.

Signature · 1 line
Tom
#6 lore raw

PATCH v3 4/5 ufs: document the UFS command

In reply to Raz Ben Yehuda

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.

---
 doc/usage/cmd/ufs.rst | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 202 insertions(+)
doc/usage/cmd/ufs.rst new file +202 -0
new file mode 100644
index 00000000000..7bc2296ec17
@@ -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.
Signature · 1 line
2.43.0
#7 lore raw

PATCH v3 5/5 MAINTAINERS: Add myself to the list of UFS maintainers

In reply to Raz Ben Yehuda

Adding myself to ufs.

---
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)
MAINTAINERS +3 -0
index 571af196465..d2257a8327c 100644
@@ -1920,8 +1920,11 @@ UFS
 M:	Neil Armstrong <[email protected]>
 M:	Bhupesh Sharma <[email protected]>
 M:	Neha Malcom Francis <[email protected]>
+R:	Raz Ben Yehuda <[email protected]>
 S:	Maintained
+F:	cmd/ufs.c
 F:	common/spl/spl_ufs.c
+F:	doc/usage/cmd/ufs.rst
 F:	drivers/ufs/
 
 UPL
Signature · 1 line
2.43.0
#8 lore raw
In reply to Raz Ben Yehuda
Quoted 11 lines · Raz Ben Yehuda

Changes in v3:
- remove set_dev_desc command. DeviceDescriptor is not writable
- Beautify the rst document
- Link to v2: https://patch.msgid.link/[email protected]

ufs: Exted cmd line

The UFS command provides utilities for querying, displaying, and modifying UFS device configuration and descriptor information. It is commonly used to configure UFS logical units (LUNs) in U-Boot, allowing storage devices to be provisioned and reconfigured as needed.

In addition to the feedback I gave you just now, please see
https://docs.u-boot-project.org/en/latest/develop/ci_testing.html and put this through CI before v4. I can see the rST will fail, and you should also make sure it has meaningful examples and renders similar to
https://docs.u-boot-project.org/en/latest/usage/cmd/mmc.html for example, thanks.

Signature · 1 line
Tom