(no cover subject)
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"
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]>
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
@@ -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
@@ -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
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
Signed-off-by Raz Ben Yehuda <[email protected]>--- 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
PATCH v3 2/5 ufs: Add flags according
In reply to Raz Ben YehudaSome flags are missing according to UFS 3.1
--- drivers/ufs/ufs.h | 3 +++ 1 file changed, 3 insertions(+)
drivers/ufs/ufs.h +3 -0
@@ -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
PATCH v3 3/5 ufs: extending ufs cmd line
In reply to Raz Ben YehudaThe 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
@@ -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
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@@ -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
[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
PATCH v3 4/5 ufs: document the UFS command
In reply to Raz Ben YehudaAdd 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
@@ -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
PATCH v3 5/5 MAINTAINERS: Add myself to the list of UFS maintainers
In reply to Raz Ben YehudaAdding myself to ufs.
--- MAINTAINERS | 3 +++ 1 file changed, 3 insertions(+)
MAINTAINERS +3 -0
@@ -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
Quoted 11 lines · Raz Ben Yehuda
Changes in v3:
- removeset_dev_desccommand. 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