From: Raz Ben Yehuda Date: Thu, 11 Jun 2026 10:49:38 +0300 Subject: [PATCH v4 4/4] ufs: document the UFS command MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260611-ufs_tool2-v4-4-a4de78bc2409@mobileye.com> References: <20260611-ufs_tool2-v4-0-a4de78bc2409@mobileye.com> In-Reply-To: <20260611-ufs_tool2-v4-0-a4de78bc2409@mobileye.com> To: u-boot@lists.denx.de Cc: Neil Armstrong , Bhupesh Sharma , Neha Malcom Francis , Tawfik Bayouk , Vladimir Kondratiev , Raz Ben Yehuda X-Mailer: b4 0.15.2 X-Developer-Signature: v=1; a=openpgp-sha256; l=13018; i=raz.benyehuda@mobileye.com; h=from:subject:message-id; bh=Dyog3ZSXrLfqd5w/GXKNpmz22XE2OAOHVdAyM4HiReE=; b=owEBbQKS/ZANAwAKAZ+a6ZSW6I45AcsmYgBqKmicZoaOWdt9OCeqeFQrmU7JbielcAGQ3AHOW FhXVBUuEcOJAjMEAAEKAB0WIQSC7lz5E3UmOrJvRDqfmumUluiOOQUCaiponAAKCRCfmumUluiO Oa/FD/4sg+G2DwtYnBXhvdHa4K1HnONtbIsqpdAhnqUBmb8eXEKInQbFd84PtdFDIKVudQH2ki1 +dWav2uKUDatHaxKp9DgZzSf+M/lqZhvFbpeSnz0Qd0lLwrlPMuMAaTRgytjaIc84Z+eRr6nydO S9nm14Xi72MFEH8nVrW41zvxl5Ym2xbJaVFwCzbxDEiT111uZhEhLppIxDFAuWV5cZr2VC6sI2q bODgVq6FI3EcpGRzXmD11qRfJPFdzW3dCuLGE1p7aQCQeqg6QL/gbXPVJgJHZvgbjtUOMSMzXtQ BshwML+f23yltRrG3puajQHguNwUumuDIRAdb2w1809xQnVHpndgz8I5z0HZshz64LtUGC6Rvat dZcmsI4j2FQbvMtsYyZ3T2C7qAnruagBxfOJUjikzaOfQy/0WUWMp7ONX3Xr8VjwP6wCliK2Wt9 Sl4Fya2rT2QfDmpvEJGGUf2IFF8J5Dm38I0u2QMXIuEOgZHkYDPwrtFpyMcfgd4L2mPSQGBR4i4 qxnAEVdTQIbMjguMktqCa6LNO0bm43EXmxcvP0pJrVM3gBBwjhrskv5g0LBLobD/bwXcMGseU1I oxmf+2NxXGmVunN+YFZOgXMajet3zK2wMEuoyBkL9mGcbWYwRGq/p5mBlsEtY9LhSYMzwO6QIig 3pQYi+a7WjbMV6A== X-Developer-Key: i=raz.benyehuda@mobileye.com; a=openpgp; fpr=82EE5CF91375263AB26F443A9F9AE99496E88E39 X-Endpoint-Received: by B4 Relay for raz.benyehuda@mobileye.com/default with auth_id=808 List-Id: B4 Relay Submissions 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 --- doc/usage/cmd/ufs.rst | 462 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 462 insertions(+) diff --git a/doc/usage/cmd/ufs.rst b/doc/usage/cmd/ufs.rst new file mode 100644 index 00000000000..c9631331e73 --- /dev/null +++ b/doc/usage/cmd/ufs.rst @@ -0,0 +1,462 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: ufs (command) + +ufs command +=========== + +Synopsis +-------- + +:: + + ufs query [lun] + ufs set_cfg_desc + ufs getflag + ufs set_hba + ufs init + ufs commit + ufs clearall + ufs luns + + +Query Description +------------------ + +The ``ufs`` command is used to query, display and modify Universal Flash +Storage (UFS) device configuration and descriptor information. + +The ``ufs query`` command displays UFS descriptors. + +:: + + ufs query [lun] + + idn + Descriptor identifier. + + ===== ================================= + Value Descriptor + ===== ================================= + 0x00 Device Descriptor + 0x01 Configuration Descriptor + 0x02 Unit Descriptor + 0x07 Geometry Descriptor + 0x08 Power Descriptor + ===== ================================= + + + LUN Required only for Unit Descriptor (IDN 0x02). + + +Descriptor Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Queries for descriptors always require direct access to the controller. + + +Device Descriptor (IDN 0x00) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Device Descriptor contains general information about the UFS device, +including: + +* Device identification +* Manufacturer information +* Product name and revision +* Number of logical units +* Queue depth +* Boot configuration +* WriteBooster capabilities +* Supported UFS features + ... + +Example: + +:: + + => ufs query 0 + + Name | Value | Description + --------------------------- + Length | 0x59 + DescriptorIdn | 0x0 + Device | 0x0 + DeviceClass | 0x0 + DeviceSubClass | 0x0 + protocol | 0x0 + NumberLu | 0 + NumberWLu | 4 + BootEnable | 0x1 + DescrAccessEn | 0x1 + + ... + + +Geometry Descriptor (IDN 0x07) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Geometry Descriptor provides information about the physical layout +and capabilities of the device, including: + +* Total raw device capacity +* Maximum number of logical units +* Allocation unit size +* Segment size +* Supported memory types +* RPMB capabilities +* Secure removal support +* WriteBooster limits + +Example: + +:: + + => ufs query 7 + + Name | Value | Description + --------------------------------------------- + Length | 0x57 | Size of descriptor + DescriptorIdn | 0x7 | geometry Descriptor ID + MediaTechnology | 0x0 | Reserved (00h) + TotalRawDeviceCapacity | 119 GB + MaxNumberLu | 1 | Max LUs (00h: 8, 01h: 32) + SegmentSize | 8192 | Segment size (512B units) + AllocationunitSize | 1 | Alloc unit size (in segments) + ... + + +Unit Descriptor (IDN 0x02) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Unit Descriptor contains information about a specific Logical Unit +(LUN), including: + +* LUN enable state +* Boot LUN assignment +* Write protection configuration +* Memory type +* Logical block size +* Provisioning type +* Data reliability settings +* WriteBooster allocation + +Example: + +:: + + => ufs query 2 3 + + --- UFS unit Descriptor (IDN: 02h) --- + Name | Value | Description + --------------------------------------------- + Length | 45 | Size of descriptor + DescriptorIdn | 0x2 | unit Descriptor ID + BunitIndex | 0x3 | Logical unit Index + luEnable | 0x0 | LU Enabled (01h) or Disabled (00h) + BootLunId | 0x0| Boot LU ID (01h: A, 02h: B + luWriteProtect | 0x0 | WP (01h: power-on, 02h: Perm) + luQueueDepth | 0x0 | Queue depth (0 if shared) + ... + + +Power Descriptor (IDN 0x08) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Queries command of Power IDN. + +:: + + => ufs query 8 + --- UFS power Parameters Descriptor (IDN: 08h) --- + + Descriptor Length: 0x62 (98 bytes) + Descriptor IDN: 0x8 + + Level | VCC Current | VCCQ Current | VCCQ2 Current + -------------------------------------------------- + 0 | 0 n_a | 0 n_a | 0 n_a + 1 | 0 n_a | 0 n_a | 0 n_a + 2 | 0 n_a | 0 n_a | 0 n_a + 3 | 0 n_a | 0 n_a | 0 n_a + 4 | 0 n_a | 0 n_a | 0 n_a + + + +Configuration Descriptor (IDN 0x01) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Configuration Descriptor defines the layout and configuration +of all Logical Units on the device. This query reads the descriptor +from the controller and caches it. The cached descriptor is used +exclusively by configuration commands, including get_lun, set_lun, and commit. +The ufs command does not use ufs staging. + +It contains: + +* Boot configuration +* RPMB configuration +* WriteBooster settings +* Logical Unit definitions +* Allocation unit assignments + +etc.. + +Example: + +:: + + => ufs query 1 + Config Descriptor: (0x00000008ffff6628) + Length : 0x0e6 + DescriptorIdn : 0x01 + ConfDescContinue : 0x00 + BootEnable : 0x01 + DescrAccess_en : 0x01 + InitPowerMode : 0x01 + HighPriorityLun : 0x07f + SecureRemovalType : 0x02 + InitActiveIccLevel : 0x01 + PeriodicRtcUpdate : 0x00 + Reserved_HPB : 0x00 + RpmbRegionEnable : 0x00 + RpmbRegion1Size : 0x00 + RpmbRegion2Size : 0x00 + RpmbRegion3Size : 0x00 + WriteBoosterBufferPreserveUserSpaceEN : 0x01 + WriteBoosterBufferType : 0x00 + NumSharedWriteBoosterBufferAllocUnits : 0x00 + ------------------------------------------------- + LUN 0 Capacity 16 MB + Name | Value | Description + ------------------------------------------------- + LuEnable | 0x1 | Enabled, 00h: Disabled + BootLunId | 0x1 | Boot LU A, 02h: Boot LU B + LuWriteProtect | 0x0 | power-on, 02h: Permanent + MemoryType| 0x3 | Normal, 01h: System Code + NumAllocunits | 12 | Number of Allocation units for LU + DataReliability | 0x1 | power failure protection + LogicalBlockSize | 0xc | Block size exponent (Min: 0Ch) + ProvisioningType | 0x0 | Full, 02h/03h: Thin + ... + + +Examining a LUN +---------------------- + +The command get_lun reports a lun from the Cached Configuration descriptor. + +Example: + +:: + + + => ufs get_lun 1 + + LuEnable | 0x1 | Enabled, 00h: Disabled + BootLunId | 0x2 | Boot LU A, 02h: Boot LU B + LuWriteProtect | 0x0 | power-on, 02h: Permanent + MemoryType| 0x3 | Normal, 01h: System Code + NumAllocunits | 12 | Number of Allocation units for LU + DataReliability | 0x1 | power failure protection + LogicalBlockSize | 0xc | Block size exponent (Min: 0Ch) + ProvisioningType | 0x0 | Full, 02h/03h: Thin + ContextCapabilities | 0x0 | LU Context support/multipliers + LuNumWriteBoosterBufferAllocunits| 16777220 | WB Buffer size (LUs 0-7 only) + + +Creating a LUN +---------------------- + +The command set_lun updates a LUN configuration in the cached configuration descriptor. +The updated LUN can be viewed using the get_lun command. + + ufs set_lun + +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 + +Example: + +:: + + => ufs set_lun 0 num_allocunits 4 + + LuEnable | 0x0 | Enabled, 00h: Disabled + BootLunId | 0x1 | Boot LU A, 02h: Boot LU B + LuWriteProtect | 0x0 | power-on, 02h: Permanent + MemoryType| 0x3 | Normal, 01h: System Code + NumAllocunits | 4 | Number of Allocation units for LU + DataReliability | 0x1 | power failure protection + LogicalBlockSize | 0xc | Block size exponent (Min: 0Ch) + ProvisioningType | 0x0 | Full, 02h/03h: Thin + ContextCapabilities | 0x0 | LU Context support/multipliers + LuNumWriteBoosterBufferAllocunits| 16908291 | WB Buffer size (LUs 0-7 only) + + +Getting A flag +------------------ +The command get_flag retrieves a flag value.. + ufs get_flag + +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 + +Example: + +:: + + => ufs getflag bkops_en + bkops_en = 1 + + +Configuration Descriptor +----------------------------------------- + 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 + +Example: + +:: + + => ufs set_cfg_desc num_shared_write_booster_buffer_allocunits 100 + + +Luns Info +----------------------------- + +The command ufs luns prints the current enabled LUNs stored in the controller. + +Example: + +:: + + => ufs luns + + + | LUN 0 | LUN 1 | LUN 2 | LUN 3 | LUN 4 | + | 3 MB | 10 MB | 1 MB | 2312 MB | 114364 MB | + + +Clear all LUNs +----------------------------- + + +The command ufs clearall, clears all LUNs, and auto-commit the zeroed LUNs to the controller. + + +Set HBA ID +---------------------- + + + ufs set_hba [hbaid] + +Use an hba id differs from 0. + + +Init +---------------------- + + ufs init + +Initialize the HBA controller. This command is not necessary and used for debugging. +All other commands initializes the HBA controller automatically if required. + +Commit +---------------------- + + ufs commit + +The command ufs commit writes the current configuration descriptor to the controller. In case the configuration +is incorrect, the commit will fail. Ufs commit is usually done after creating a lun. + +Provisioning workflow +---------------------- + +Source system +~~~~~~~~~~~~~~~ + +1. Display the Configuration Descriptor:: + + ufs query 1 + +:: + => ufs query 1 + Config Descriptor: (0x00000008ffff6628) + ... + + The output includes the Configuration Descriptor address and size. + +2. Save the Configuration Descriptor to a file:: + + tftpput + + Example:: + + tftpput 0x00000008ffff6628 0xe6 luns.bin + + This exports the current UFS configuration, including LUN settings. + +Target system +^^^^^^^^^^^^^ + +1. Display the current Configuration Descriptor: + + ufs query 1 + + Copy the address near the Config Descriptor output. + + +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