> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory and Storage

The Qualcomm Linux platform supports four primary storage types.

| Storage Type | Versions |
| - | - |
| **Universal Flash Storage (UFS)** | v2.1, v2.2, v3.1 |
| **Embedded Multi-Media Card (eMMC)** | v5.1 |
| **Non-Volatile Memory Express (NVMe)** | v1.3 |
| **Secure Digital (SD) Card** | v3.0 |

<Warning>
  Configure the device to boot from only one storage source. Using both sources for bootable files may cause system crashes or unpredictable behavior.
</Warning>

## UFS Storage

### Features

| Feature | Description |
| - | - |
| **Lanes** | 2 lanes supported |
| **Gear** | HS Gear 1, 2, 3, and 4 |
| **Low-Power Mode** | Link hibernate and device sleep |
| **Hot-Plug** | Not supported (embedded only) |

### Kernel Configuration

| Configuration | Default | Description |
| - | - | - |
| `CONFIG_UFS_FAULT_INJECTION` | No | Injects failure commands for debugging |
| `CONFIG_SCSI_UFSHCD` | Yes | UFS host control driver |
| `CONFIG_SCSI_UFSHCD_PLATFORM` | Yes | UFS controller from platform bus |
| `CONFIG_SCSI_UFS_QCOM` | Yes | Qualcomm-specific PHY and vendor registers |
| `CONFIG_PHY_QCOM_QMP` | Yes | UFS QMP PHY driver |
| `CONFIG_SCSI_UFS_BSG` | Yes | UFS BSG device node |
| `CONFIG_SCSI_UFS_CRYPTO` | Yes | UFS crypto engine |

### Power Management States

**Auto-Hibern8 (AH8)** — Transitions PHY link to Hibernate after 150 ms of idle time (adjustable).

```bash theme={null}
cat /sys/devices/platform/soc@0/1d84000.ufs/auto_hibern8
```

**Clock Gating** — Gated after 50 ms (max freq) or 10 ms (scaled freq) of idle time. Enabled by default.

```bash theme={null}
cat /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable
# Disable for debugging:
echo 0 > /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable
```

**Clock Scaling** — Scales up/down based on load threshold. Enabled by default; disabling increases power consumption.

```bash theme={null}
cat /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable
```

**Runtime Suspend/Resume** — Enters suspend after 3 seconds of inactivity. Always enabled, not configurable.

**System Suspend/Resume** — Follows system suspend/resume events. Always enabled, not configurable.

### Device Parameters

| Parameter | Subnode | Value | Description |
| - | - | - | - |
| `init_speed_params` | EnableHighSpeed | 1 | Enables high speed mode |
| | NumGears | 4 | Maximum gear (3 for UFS 2.x, 4 for UFS 3.1) |
| | NumLanes | 2 | Number of lanes |
| | Rate | 2 | 1=Rate A, 2=Rate B |
| `perf_speed_params` | EnableHighSpeed | 1 | High speed in perf mode |
| | NumGears | 4 | Maximum gear in perf mode |
| | NumLanes | 2 | Lanes in perf mode |
| | Rate | 2 | Series in perf mode |
| `timeout_values` | fDeviceInitTimeout | 2500000 μs | Device init timeout |
| | UTRDPollTimeout | 30000000 μs | UTRD timeout |
| `BatteryThresholdMv` | — | 3600 | Battery threshold (mV) to move to Gear 1 |
| `LinkStartupRetryCount` | — | 5 | Link startup retry count |
| `RefClock` | — | 19200000 | Reference clock (19.2 MHz) |

### UFS Provisioning

UFS provisioning creates Logical Unit Numbers (LUNs) on a new UFS device.

**Device Descriptor Parameters:**

| Parameter | Description |
| - | - |
| `bNumberLU` | Number of Logical Units |
| `bBootEnable` | `00h`: Boot disabled, `01h`: Boot enabled |
| `bConfigDescrLock` | `0h`: Unlocked, `1h`: Locked (prevents reprovisioning) |

<Warning>
  Set `bConfigDescrLock="0"` during development. Set to `"1"` after finalization to prevent reprovisioning.
</Warning>

**LUN Parameters:**

| Parameter | Description |
| - | - |
| `LUNum` | Logical Unit Number |
| `bLUEnable` | `00h`: Disabled, `01h`: Enabled |
| `bBootLunID` | `00h`: Not bootable, `01h`: Boot LU A, `02h`: Boot LU B |
| `size_in_kb` | LUN size in KB |
| `bMemoryType` | `00h`: Normal, `01h`: System code, `02h`: Non-Persistent |
| `bProvisioningType` | `00h`: Thin provisioning disabled, `02h`: Enabled (TPRZ=0) |

**Default Partition Layout:**

* **LUN0** — Linux data and filesystem images
* **LUN1 & LUN2** — Boot WLUN (0xB0) alternates for fail-safe XBL backup
* **LUN4** — Rest of boot chain
* **LUN6 & LUN7** — Unused by default

### Architecture Diagrams

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/ufs_storage_archi.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=cf79fecb53639466e65731730626abfe" width="1128" height="874" data-path="archives/2.1/Linux/images/peripheral-interfaces/ufs_storage_archi.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/storage_subsystem_overview.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=030bf24fbc2e7c933e57ed3c20d75112" width="1104" height="502" data-path="archives/2.1/Linux/images/peripheral-interfaces/storage_subsystem_overview.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/ufs_device_partition_layout.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=22482ad054485c1f24b1eeeec7501390" width="419" height="959" data-path="archives/2.1/Linux/images/peripheral-interfaces/ufs_device_partition_layout.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/ufs_PM_TM.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=6dbe9002e20df358bb1adbfe86ba5f7c" width="1571" height="444" data-path="archives/2.1/Linux/images/peripheral-interfaces/ufs_PM_TM.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/storage_IO_flowsequence.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=0a06e6afae6ae79a5c4243f4769f7b16" width="1058" height="1001" data-path="archives/2.1/Linux/images/peripheral-interfaces/storage_IO_flowsequence.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/ufs_provision_flow.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=8fb070755a791755cf82836f33c6d55b" width="746" height="935" data-path="archives/2.1/Linux/images/peripheral-interfaces/ufs_provision_flow.png" />

## eMMC Storage

### Features

| Feature | Description |
| - | - |
| **Speed** | DDR50, HS200, HS400, HS400 Enhanced |
| **Sleep Mode** | Clock gating and auto suspend |
| **Command Queuing** | Multiple simultaneous commands |

### Device Tree Configuration

Add the following to the `&sdhc_1` node in the SoC-specific DTSI file:

```dts theme={null}
&sdhc_1 {
    status = "okay";
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&sdc1_on>;
    pinctrl-1 = <&sdc1_off>;
    vmmc-supply = <&vreg_l19a_2p9>;
    vqmmc-supply = <&vreg_l12a_1p8>;
};
```

### Power Management

* **Runtime Suspend** — After 50 ms of inactivity; always enabled
* **System Suspend** — Follows system suspend/resume events; always enabled

## SD Card Storage

### Features

| Feature | Description |
| - | - |
| **Bus Width** | 4-bit mode |
| **Speed** | SDR50, SDR104, DDR50 |
| **Hot-Plug** | Supported |

### Kernel Configuration

| Configuration | Default | Description |
| - | - | - |
| `CONFIG_MMC` | Yes | MMC driver |
| `CONFIG_MMC_SDHCI` | Yes | SDHCI driver |
| `CONFIG_MMC_CQHCI` | Yes | Command Queue Host Control Interface |
| `CONFIG_MMC_SDHCI_MSM` | Yes | MSM SDHCI driver |
| `CONFIG_MMC_BLOCK` | Yes | MMC block driver |
| `CONFIG_MMC_CRYPTO` | Yes | MMC Crypto Engine |

### Power Management

* **Runtime Suspend** — After 50 ms of inactivity; always enabled
* **System Suspend** — Follows system suspend/resume events; always enabled

## NVMe Storage

| Feature | Description |
| - | - |
| **Lanes** | 4 lanes over PCIe port (PCIe1) |
| **Interface** | High-speed serial |
| **Protocol** | Optimized for NAND flash and next-gen SSDs |

## Configuration Guide

### Mount File Systems

<Tabs>
  <Tab title="UFS / eMMC">
    ```bash theme={null}
    mkdir /tmp/data
    mount -t ext4 /dev/sda3 /tmp/data
    df -a
    ```
  </Tab>

  <Tab title="SD Card">
    ```bash theme={null}
    mkdir sdcard
    mkfs.vfat /dev/mmcblk1p1   # Format if needed
    mount -t vfat /dev/mmcblk1p1 /sdcard
    df -a
    ```
  </Tab>

  <Tab title="NVMe">
    ```bash theme={null}
    # Create partition table
    fdisk /dev/nvme0n1
    # Follow prompts: n (new), p (primary), accept defaults, w (write)

    reboot

    mkfs.ext4 /dev/nvme0n1p1
    mount /dev/nvme0n1p1 /media
    df -a
    ```
  </Tab>
</Tabs>

### Power Management Control

```bash theme={null}
# Mount debugfs (required for debug nodes)
mount -t debugfs none /sys/kernel/debug

# UFS Auto-Hibern8
cat /sys/devices/platform/soc@0/1d84000.ufs/auto_hibern8
echo <value_in_us> > /sys/devices/platform/soc@0/1d84000.ufs/auto_hibern8

# UFS Clock Gating
echo 0 > /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable  # Disable
echo 1 > /sys/devices/platform/soc@0/1d84000.ufs/clkgate_enable  # Enable

# UFS Clock Scaling
echo 0 > /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable  # Disable
echo 1 > /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable  # Enable
```

## Troubleshooting

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/debugging_flow_diagram.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=27f1f95f2f479306d36cf99401937920" width="1156" height="1011" data-path="archives/2.1/Linux/images/peripheral-interfaces/debugging_flow_diagram.png" />

<img src="https://mintcdn.com/qualcomm-staging/blZpKs_b9On5nj-y/archives/2.1/Linux/images/peripheral-interfaces/troubleshotting_decision_tree.png?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=9e12849ed5b6eced7a133b453108c891" width="1601" height="789" data-path="archives/2.1/Linux/images/peripheral-interfaces/troubleshotting_decision_tree.png" />

<AccordionGroup>
  <Accordion title="Command Pending in Device">
    **Symptoms:**

    ```
    ufshcd-qcom 1d84000.ufshc: ufshcd_abort: cmd pending in the device. tag = 1
    ```

    **Resolution:** Contact UFS device vendor; check device compatibility and power supply stability.
  </Accordion>

  <Accordion title="No Response from Device">
    **Symptoms:**

    ```
    ufshcd-qcom 1d84000.ufshc: ufshcd_abort: no response from device. tag = 2, err -110
    ```

    **Resolution:** Check physical connections, verify power rails, check PHY initialization.
  </Accordion>

  <Accordion title="Physical Adapter / Data Link Error">
    **Symptoms:**

    ```
    ufshcd-qcom 1d84000.ufshc: pa_err_cnt_total=5086, pa_lane_0_err_cnt=3250
    ufshcd-qcom 1d84000.ufshc: dl_err_cnt_total=4488, dl_nac_received_err_cnt=289
    ```

    **Diagnosis:**

    ```bash theme={null}
    mount -t debugfs none /sys/kernel/debug
    cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats
    ```

    **Resolution:** Indicates poor signal quality. Check PCB layout, signal integrity, and PHY settings. Contact Qualcomm support for PHY tuning.
  </Accordion>

  <Accordion title="High Power Consumption in Active State">
    **Diagnosis:**

    ```bash theme={null}
    cat /sys/devices/platform/soc@0/1d84000.ufs/devfreq/1d84000.ufs/cur_freq
    cat /sys/devices/platform/soc@0/1d84000.ufs/clkscale_enable
    ```

    **Resolution:** Enable clock scaling if disabled; disable WriteBooster if not needed.
  </Accordion>

  <Accordion title="High Power Consumption in Sleep State">
    **Diagnosis:**

    ```bash theme={null}
    cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/link_state
    cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/dev_pm
    cat /sys/devices/platform/soc@0/1d84000.ufs/power/runtime_status
    ```

    **Resolution:** Adjust PM level; disable HPB/WriteBooster if causing issues; verify VCC/VCCQ/VCCQ2 timing.
  </Accordion>

  <Accordion title="Unhandled SMMU Fault">
    **Symptoms:**

    ```
    arm-smmu 15000000.apps-smmu: Unhandled arm-smmu context fault from 1d84000.ufshc!
    ```

    **Resolution:** In the `ufshc_mem` node in the SoC DTSI file, change:

    ```dts theme={null}
    qcom,iommu-dma = "fastmap";
    ```

    to:

    ```dts theme={null}
    qcom,iommu-dma = "bypass";
    ```
  </Accordion>
</AccordionGroup>

## Command Reference

### UFS Commands

| Purpose | Command |
| - | - |
| Check PA/DL error count | `cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats` |
| Read current clock frequency | `cat /sys/devices/platform/soc@0/1d84000.ufs/devfreq/1d84000.ufs/cur_freq` |
| Read device state (active/sleep) | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/dev_pm` |
| Read gear information | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/gear` |
| Read link state (ACTIVE/HIBERN8) | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/link_state` |
| Read runtime status | `cat /sys/devices/platform/soc@0/1d84000.ufs/power/runtime_status` |
| Read RPM/SPM level | `cat /sys/devices/platform/soc@0/1d84000.ufs/rpm_lvl` |

### SD Card Commands

| Purpose | Command |
| - | - |
| Read error stats | `cat /sys/kernel/debug/mmc1/err_stats` |
| Check current clock | `cat /sys/kernel/debug/mmc1/clock` |
| Read runtime status | `cat /sys/devices/platform/soc@0/8804000.mmc/power/runtime_status` |

### NVMe Commands

| Purpose | Command |
| - | - |
| View device model | `cat /sys/class/nvme/nvme0/model` |
| View firmware version | `cat /sys/class/nvme/nvme0/firmware_rev` |
| View namespace size | `cat /sys/class/nvme/nvme0/nvme0n1/size` |

### eMMC Commands

| Purpose | Command |
| - | - |
| Error stats | `cat /sys/kernel/debug/mmc0/err_stats` |
| Current clock | `cat /sys/kernel/debug/mmc0/clock` |
| Runtime status | `cat /sys/devices/platform/soc@0/7c4000/power/runtime_status` |

<Note>
  For eMMC commands, replace the address with the SoC-specific value: IQ-615 and IQ-9075 use `7c4000`; IQ-8275 uses `87c4000`.
</Note>

## References

* [EXT4 Filesystem Introduction](https://opensource.com/article/17/5/introduction-ext4-filesystem)