> ## 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) |

### 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** — Enabled by default.

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

**Clock Scaling** — Enabled by default; disabling increases power consumption.

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

### UFS Provisioning

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

**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_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" />

## 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

```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>;
};
```

## SD Card Storage

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

## NVMe Storage

| Feature | Description |
| - | - |
| **Lanes** | 4 lanes over PCIe port (PCIe1) |
| **Interface** | High-speed serial |

## 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
    mount -t vfat /dev/mmcblk1p1 /sdcard
    df -a
    ```
  </Tab>

  <Tab title="NVMe">
    ```bash theme={null}
    fdisk /dev/nvme0n1
    reboot
    mkfs.ext4 /dev/nvme0n1p1
    mount /dev/nvme0n1p1 /media
    df -a
    ```
  </Tab>
</Tabs>

### Power Management Control

```bash theme={null}
mount -t debugfs none /sys/kernel/debug

# 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
```

## 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" />

<AccordionGroup>
  <Accordion title="Command Pending in Device">
    **Symptoms:** `ufshcd_abort: cmd pending in the device`

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

  <Accordion title="No Response from Device">
    **Symptoms:** `ufshcd_abort: no response from device, err -110`

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

  <Accordion title="Physical Adapter / Data Link Error">
    ```bash theme={null}
    mount -t debugfs none /sys/kernel/debug
    cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats
    ```

    Indicates poor signal quality. Check PCB layout and PHY settings.
  </Accordion>

  <Accordion title="Unhandled SMMU Fault">
    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 | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/dev_pm` |
| Read link state | `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` |

### 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/87c4000/power/runtime_status` |

<Note>
  For IQ-8275, the eMMC address is `87c4000`.
</Note>

## References

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