> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.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-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/ufs_storage_archi.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=1bdf851292b3bba7d316553dca4b50e7" width="1128" height="874" data-path="Linux/images/peripheral-interfaces/ufs_storage_archi.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/storage_subsystem_overview.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=25809c750bd00f17d425ad6b7ab5813c" width="1104" height="502" data-path="Linux/images/peripheral-interfaces/storage_subsystem_overview.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/ufs_device_partition_layout.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=f091aac646ff16f8a2199240aca2b924" width="419" height="959" data-path="Linux/images/peripheral-interfaces/ufs_device_partition_layout.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/ufs_PM_TM.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=d6b083db978617e43973d8760664ba3d" width="1571" height="444" data-path="Linux/images/peripheral-interfaces/ufs_PM_TM.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/storage_IO_flowsequence.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=85b88bc09eb56e7b0794f73b9d03d1e2" width="1058" height="1001" data-path="Linux/images/peripheral-interfaces/storage_IO_flowsequence.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/ufs_provision_flow.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=58eb62b0b8fae200eb52a38285fbc210" width="746" height="935" data-path="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-prod/Bh7DlgudKfjY_3Wf/Linux/images/peripheral-interfaces/debugging_flow_diagram.png?fit=max&auto=format&n=Bh7DlgudKfjY_3Wf&q=85&s=32fa5c3f2b0343001bef1cb89ad198a3" width="1156" height="1011" data-path="Linux/images/peripheral-interfaces/debugging_flow_diagram.png" />

<img src="https://mintcdn.com/qualcomm-prod/jy6NQT2Y7J_sAxdX/Linux/images/peripheral-interfaces/troubleshotting_decision_tree.png?fit=max&auto=format&n=jy6NQT2Y7J_sAxdX&q=85&s=78803768bf84d32e7741ad01c79d0e5c" width="1601" height="789" data-path="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)