# Configure
Use the following storage configurations and device tree parameters for UFS and SD card functionalities.
## Kernel configuration
Qualcomm Linux supports the UFS kernel and SD card kernel configurations in the kernel build.
### UFS kernel configuration
The following table lists the default values of the kernel configuration that enables UFS functionality.
UFS kernel configuration
| Configuration | Enabled (yes/no) | Description |
| --- | --- | --- |
| `CONFIG_UFS_FAULT_INJECTION` | No | Injects the failure command for debugging. |
| `CONFIG_SCSI_UFSHCD` | Yes | Enables the UFS host control driver in the kernel. |
| `CONFIG_SCSI_UFSHCD_PLATFORM` | Yes | Supports the UFS controller from the platform bus. |
| `CONFIG_SCSI_UFS_QCOM` | Yes | Enables a Qualcomm-specific addition to access the PHY configuration and vendor-specific registers. |
| `CONFIG_PHY_QCOM_QMP` | Yes | Supports UFS QMP PHY driver. |
| `CONFIG_SCSI_UFS_BSG` | Yes | Enables UFS BSG device node. |
| `CONFIG_SCSI_UFS_CRYPTO` | Yes | Supports UFS crypto engine. |
### SD card kernel configuration
The following table lists the default values of kernel configuration that enables SD card functionality.
SDHC kernel configuration
| Configuration | Enabled (yes/no) | Description |
| --- | --- | --- |
| `CONFIG_MMC` | Yes | Enables MMC driver. |
| `CONFIG_MMC_DEBUG` | No | Enables driver debug messages. |
| `CONFIG_MMC_SDHCI` | Yes | Detects SDHCI driver. |
| `CONFIG_MMC_CQHCI` | Yes | Enables command queue host control interface. |
| `CONFIG_MMC_SDHCI_MSM` | Yes | Enables MSM SDHCI driver. |
| `CONFIG_MMC_BLOCK` | Yes | Enables MMC block driver. |
## Power management states
UFS and SD cards offer multiple power states to optimize power consumption.
### UFS power management states
You can modify these states as needed. However, altering the states can cause changes in power consumption.
Note
For more information on how to run SSH, see the [Use SSH](https://docs.qualcomm.com/bundle/publicresource/topics/80-70017-254/how_to.html) section.
UFS power management states
| State | Description |
| --- | --- |
| Auto-hibern8 (AH8) | >
>
>
> AH8 automatically transitions the PHY link to the Hibernate state after 150 ms of idle time. This value is adjustable.
> To determine the AH8 idle duration value (in microseconds), run the following SSH command on the host computer.
>
>
>
> cat /sys/devices/platform/soc@0/1d84000.ufs/auto_hibern8
> Copy to clipboard
|
| Clock gating | >
>
>
> When UFS clocks are scaled up to maximum frequency due to the use case, clocks are gated after 50 ms of idle duration.
> If clocks are scaled down to optimal frequency, clocks are gated after 10 ms of idle duration. To check clock gating enabled/disabled status, run the following SSH command on the host computer.
>
>
>
> cat /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable
> Copy to clipboard
Clock gating is enabled by default.
To debug UFS issues related to clock gate or ungate and to disable the clock gating, run the following SSH command on the host computer.
echo 0 > /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable
Copy to clipboard |
| Clock scaling | >
>
>
> After the UFS load exceeds the upthreshold value, the clock frequency is set to the maximum frequency with clock scale up.
> Clock scale-down occurs when the load is lower than the threshold. The UFS operations determines the UFS load. To check the clock scaling status, run the following SSH command on the host computer.
>
>
>
> cat /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable
> Copy to clipboard
Clock scaling is enabled by default.
Disabling clock scaling can result in increased power consumption. To debug any issue related to clock scaling, run the following SSH command on the host computer.
echo 0 > /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable
Copy to clipboard |
| Runtime suspend or resume | |
| System suspend or resume |
UFS enters the system suspend with the suspend event.
UFS resume state occurs with the system resume event.
This state is enabled by default and is not configurable.
|
### SD card power management states
SD card power management states
| State | Description |
| --- | --- |
| Runtime suspend or resume | |
| System suspend or resume |
The SD card enters system suspend state with the suspend event.
SD card system resume state occurs with the system resume event.
This state is enabled by default and is not configurable.
|
## Boot loader and UEFI device tree
The device tree specifies the UFS host configuration parameters such as number of gears and lanes, rate value, and timeout values.
### UFS
The device tree is at `\boot_images\boot\Settings\Soc\Kodiak\Core\Storage\UFS\ufs.dtsi`.
For QCS9075, see `\boot_images\boot\Setting\soc\LeMans\Core\Storage\UFS\ufs.dtsi`.
The following is an example of the UFS device tree node in UEFI.
| Device tree node/key | Subnode | Device tree value | Description |
| --- | --- | --- | --- |
| `init_speed_params` | `EnableHighSpeed` | 1 | Enables high speed mode |
| `init_speed_params` | `NumGears` | 4 | Specifies the maximum gear to be used. |
| `init_speed_params` | `NumLanes` | 2 | Number of lanes used in UFS |
| `init_speed_params` | `Rate` | 2 | Values are:
|
| `perf_speed_params` | `EnableHighSpeed` | 1 | Enables high speed mode while in perf mode |
| `perf_speed_params` | `NumGears` | 4 | Specifies the maximum gear to be used in perf mode |
| `perf_speed_params` | `NumLanes` | 2 | Number of lanes used in UFS in perf mode |
| `perf_speed_params` | `Rate` | 2 | Series in perf mode
- 1 = Rate A
- 2 = Rate B |
| `timeout_values` | `fDeviceInitTimeoutUs` | 2500000 | Denotes timeout (µs) during device init |
| `timeout_values` | `UTRDPollTimeoutUs` | 30000000 | Denotes timeout (µs) for UTRD |
| `BatteryThresholdMv` | – | 3600 | Battery threshold (in milli volts) to move to Gear1 |
| `LinkStartupRetryCount` | – | 5 | Retry count for Link startup |
| `FUA_Value` | – | 1 | Forced unit access |
| `EnableLogging` | – | 0 | Enables DT serial debug logging in loader
- 1 - Enable
- 0 - Disable |
| `RefClock` | – | 19200000 | UFS controller reference clock 19.2 MHz |
| `MphyInitTable` | – | – | Denotes MphyInit table |
| `MphyInitEndTable` | – | – | Denotes MphyInitEnd table |
| `MphyLaneInitTable` | – | – | Denotes Mphy 2 Lane Init table |
| | | | |
| | | | |
| | | | |
Any change in the `.dtsi` must be compiled into `xbl_config.elf` and the image reflashed on to the device.
`MphyInitTable`, `MphyInitEndTable`, and `MphyLaneInitTable` are used for UFS PHY initialization and these values are tuned by Qualcomm. For debugging and tuning any PHY-level issue, these values should be changed with guidance from Qualcomm.
The default values are for UFS 3.1-compliant part. For UFS 2.x-compliant part, `NumGears` value should be 3. Other parameters need not be changed for UFS 2.x part.
### SD card
The device tree specifies the SD card parameters such as drive strength, maximum speed mode, and HSR settings. The device tree is at `\boot_images\boot\Settings\Soc\Kodiak\Core\Storage\SDCC\sdcc.dtsi`.
The following is an example of the SD card device tree node in UEFI.
| Device tree node/key | Device tree value | Description |
| --- | --- | --- |
| `DriveStrength` | 0x1FE4 | `DriveStrength` as recommended, sets SDC CLK, CMD, and data drive strengths to 7, 4, 4, respectively. |
| `MaxSpeedMode` | `SDCC_SDR104_MODE` | Defines maximum speed mode. For SD card, the value is `SDCC_SDR104_MODE`. |
## Linux kernel device tree
The Linux kernel device tree nodes define properties used for storage.
### UFS
The SoC DTSI node specifies register address space, clocks, interrupts, and reset information. The platform DTSI node specifies power supply, voltage, and current levels.
The `Ufs_mem_hc` node that describes the on-chip UFS host controller is at `/sources/kernel/kernel_platform/kernel/arch/arm64/boot/dts/qcom/sc7280.dtsi`.
For `Ufs_mem_hc` node in QCS9075, see `/sources/kernel/kernel_platform/kernel/arch/arm64/boot/dts/qcom/sa8775p.dtsi`.
Note
These parameters are only for information purposes. Do not modify them.
| Property | Description |
| --- | --- |
| `Compatible` | For Qualcomm SoCs, must contain strings such as `qcom`, `ufshc`. |
| `Interrupts` | Interrupt mapping for UFS host controller IRQ. |
| `Reg` | UFS host registers address mapping. |
| `Phys` | `phandle` to UFS PHY node. |
| `lanes-per-direction` | Specify the number of lanes available per direction. Either 1 or 2. |
| `clock-names` | List of clock input name strings. |
| `Clocks` | List of `phandle` and clock specifier pairs. |
| `freq-table-hz` | Array of <minimum maximum> operating frequencies stored in the same order as the clocks property. |
| `reset-gpios` | A `phandle` and GPIO specifier denoting the GPIO that is connected. |
| `Resets` | Reset node register. |
The `Ufs_mem_phy` node describes on-chip UFS PHY hardware and this node is in `/sources/kernel/kernel_platform/kernel/arch/arm64/boot/dts/qcom/sc7280.dtsi` file.
| Property | Description |
| --- | --- |
| `Compatible` | Specify compatible string such as `qcom`, `qmp-ufs-phy`. |
| `#phy-cells` | Set the property to 0. |
| `Reg` | Should contain PHY register address space. |
| `reg-names` | |
| `lanes-per-direction` | Number of lanes available per direction; either 1 or 2. |
| `clock-names` | List of clock input name strings. |
| `clocks` | List of phandle and clock specifier pairs. |
| `vdda-phy-supply` | `phandle` to main PHY supply for analog domain. |
| `vdda-pll-supply` | `phandle` to PHY PLL and Power-Gen block power supply. |
| `Resets` | Specifies the PHY reset in the UFS controller. |
For more information on DTS parameters, see `/kernel_platform/msm-kernel/Documentation/devicetree/bindings/ufs/qcom,ufs.yaml`.
### SD card
The SoC DTSI node specifies register address space, clocks, interrupts, and reset information. The platform DTSI node specifies power supply, voltage, and current levels.
`sdhc_2: mmc@8804000` node describes the on-chip SD host controller and this node is in the `/sources/kernel/kernel_platform/kernel/arch/arm64/boot/dts/qcom/sc7280.dtsi` file.
Note
These parameters are only for information purposes. Do not modify them.
| Property | Description |
| --- | --- |
| `Compatible` | Specify compatible strings such as `qcom,sc7280-sdhci`, `qcom,sdhci-msm-v5`. |
| `Pinctrl-names` | Defines name of the pin control states. |
| `Pinctrl-0 &1` | Points to pin control settings, this is an array defines pin control settings for multiple states. |
| `Interrupts` | Interrupt mapping for SDHC IRQ. |
| `Interrupt-names` | Lists the names corresponding to each interrupt defined in the `interrupts` property. |
| `reg` | SDHC host registers address mapping. |
| `iommus` | `Iommus` specifies the IOMMU node and stream ID. |
| `clock-names` | List of clock input name strings. |
| `clocks` | List of phandle and clock specifier pairs. |
| `interconnects` | Define the interconnect paths for the device. |
| `interrupt-names` | Lists the names to each interconnect path defined in `interconnects` property. |
| `power-domains` | Specifies the power domain used by the SDHC. |
| `bus-width` | Specifies the number of data lines used for communication. |
| `dma-coherent` | Specifies that the SDHCI and CPU maintain cache coherency. |
| `qcom,dll-config` | Platform specific settings for `DLL_CONFIG` reg. |
| `resets` | Reset node register. |
| `sdhc2_opp_table` | This table defines various operating points supported by the SDHCI. |
## UFS provisioning
Creating and defining LUNs on a new UFS card is called Provisioning. A UFS device contains one or more Logical Units. A logical unit is an independent processing entity within the device. Each logical unit has an address within the UFS device called a Logical Unit Number (LUN).
The configuration file for provisioning is at `
`bNumberLU` does not include well-known logical units |
| `bBootEnable` | Indicates whether the device is enabled for boot:
|
| `bDescrAccessEn` | Indicates whether the Device Descriptor can be read after the partial initialization phase of the boot sequence:
|
| `BInitPowerMode` | Defines the Power Mode after device initialization or hardware reset:
00h: UFS-Sleep Mode
01h: Active Mode
|
| `bHighPriorityLUN` | Defines the high-priority logical unit |
| `bSecureRemovalType` |
00h: Information removed by an erase of the physical memory
01h: Information removed by overwriting the addressed locations with a single character followed by an erase
02h: Information removed by overwriting the addressed locations with a character, its complement, then a random character
03h: Information removed using a vendor-defined mechanism
|
| `bConfigDescrLock` | |
UFS reprovision is possible only if this device parameter, which is part of the provision xml file, is set: `bConfigDescrLock="0"`.
To prevent reprovisioning, set `bConfigDescrLock="1"` after the UFS configuration and provisioning is finalized.
UFS LUN parameters description
| Parameter | Description |
| --- | --- |
| `LUNum` | Logical Unit Number |
| `bLUEnable` | Enables/disables the logical unit:
|
| `bBootLunID` | Boot LUN ID:
00h: Not bootable
01h: Boot LU A
02h: Boot LU B
|
| `size_in_kb` | Specifies LUN size in KBs |
| `bLUWriteProtect` | Logical Unit Write Protect:
|
| `bMemoryType` | Defines logical unit memory type:
00h: Normal memory
01h: System code memory type
02h: Non-Persistent memory type
03h: Enhanced memory type 1
04h: Enhanced memory type 2
05h: Enhanced memory type 3
06h: Enhanced memory type 4
|
| `bProvisioningType` | Provisioning type
|
## UFS partition layout
The default UFS provisioning creates eight LUNs (LUN0 to LUN7).
- The Linux data and all Linux file system images are stored in LUN0.
- Boot well-known LUN (WLUN) 0xB0 alternates between LUN1 and LUN2 to provide a fail-safe backup for the XBL.
- The rest of the boot chain is stored in LUN4.
- The LUN6 and LUN7 are unused by default.

**Default UFS layout**
Last Published: Dec 30, 2024
[Previous Topic
Features](https://docs.qualcomm.com/bundle/publicresource/80-70017-6/topics/features.md) [Next Topic
Customize](https://docs.qualcomm.com/bundle/publicresource/80-70017-6/topics/customize.md)
Source: [https://docs.qualcomm.com/doc/80-70017-6/topic/configuration.html](https://docs.qualcomm.com/doc/80-70017-6/topic/configuration.html)