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

# 内存与存储

Qualcomm Linux 平台支持四种主要存储类型。

| 存储类型                 | 版本             |
| -------------------- | -------------- |
| **通用闪存存储（UFS）**      | v2.1、v2.2、v3.1 |
| **嵌入式多媒体卡（eMMC）**    | v5.1           |
| **非易失性内存高速接口（NVMe）** | v1.3           |
| **安全数字（SD）卡**        | v3.0           |

<Warning>
  请将设备配置为仅从一个存储源启动。同时使用两个存储源存放可启动文件可能导致系统崩溃或不可预测的行为。
</Warning>

## UFS 存储

### 特性

| 特性        | 说明                |
| --------- | ----------------- |
| **通道**    | 支持 2 通道           |
| **Gear**  | HS Gear 1、2、3 和 4 |
| **低功耗模式** | 链路休眠和设备睡眠         |
| **热插拔**   | 不支持（仅嵌入式）         |

### 电源管理状态

**Auto-Hibern8（AH8）** — 空闲 150 ms 后将 PHY 链路转换为休眠状态（可调整）。

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

**时钟门控** — 默认启用。

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

**时钟调节** — 默认启用；禁用会增加功耗。

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

### UFS 分区配置（Provisioning）

<Warning>
  开发期间设置 `bConfigDescrLock="0"`。定型后设置为 `"1"` 以防止重新配置。
</Warning>

**默认分区布局：**

* **LUN0** — Linux 数据和文件系统镜像
* **LUN1 和 LUN2** — Boot WLUN（0xB0）交替使用，用于故障安全的 XBL 备份
* **LUN4** — 启动链的其余部分
* **LUN6 和 LUN7** — 默认未使用

### 架构图

<img src="https://mintcdn.com/qualcomm-prod/P0rmO3AZfXx7cgqQ/Ubuntu/images/peripheral-interfaces/ufs_storage_archi.png?fit=max&auto=format&n=P0rmO3AZfXx7cgqQ&q=85&s=bc7b3c176978c5517ba21e8a29f384d9" width="1128" height="874" data-path="Ubuntu/images/peripheral-interfaces/ufs_storage_archi.png" />

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

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

## eMMC 存储

### 特性

| 特性       | 说明                               |
| -------- | -------------------------------- |
| **速率**   | DDR50、HS200、HS400、HS400 Enhanced |
| **睡眠模式** | 时钟门控和自动挂起                        |
| **命令队列** | 多命令并发                            |

### 设备树配置

```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 卡存储

| 特性       | 说明                 |
| -------- | ------------------ |
| **总线宽度** | 4 位模式              |
| **速率**   | SDR50、SDR104、DDR50 |
| **热插拔**  | 支持                 |

## NVMe 存储

| 特性     | 说明                      |
| ------ | ----------------------- |
| **通道** | 通过 PCIe 端口（PCIe1）的 4 通道 |
| **接口** | 高速串行                    |

## 配置指南

### 挂载文件系统

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

  <Tab title="SD 卡">
    ```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>

### 电源管理控制

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

## 故障排查

<img src="https://mintcdn.com/qualcomm-prod/P0rmO3AZfXx7cgqQ/Ubuntu/images/peripheral-interfaces/debugging_flow_diagram.png?fit=max&auto=format&n=P0rmO3AZfXx7cgqQ&q=85&s=37b801b926e7a30efac548413840e1d8" width="1156" height="1011" data-path="Ubuntu/images/peripheral-interfaces/debugging_flow_diagram.png" />

<AccordionGroup>
  <Accordion title="设备中有待处理命令">
    **症状：** `ufshcd_abort: cmd pending in the device`

    联系 UFS 器件供应商；检查器件兼容性和供电稳定性。
  </Accordion>

  <Accordion title="设备无响应">
    **症状：** `ufshcd_abort: no response from device, err -110`

    检查物理连接、验证电源轨、检查 PHY 初始化。
  </Accordion>

  <Accordion title="物理适配层 / 数据链路错误">
    ```bash theme={null}
    mount -t debugfs none /sys/kernel/debug
    cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats
    ```

    表明信号质量差。检查 PCB 布局和 PHY 设置。
  </Accordion>

  <Accordion title="未处理的 SMMU 故障">
    在 SoC DTSI 文件的 `ufshc_mem` 节点中，将：

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

    改为：

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

## 命令参考

### UFS 命令

| 用途            | 命令                                                                         |
| ------------- | -------------------------------------------------------------------------- |
| 查看 PA/DL 错误计数 | `cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats`                           |
| 读取当前时钟频率      | `cat /sys/devices/platform/soc@0/1d84000.ufs/devfreq/1d84000.ufs/cur_freq` |
| 读取设备状态        | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/dev_pm`            |
| 读取链路状态        | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/link_state`        |
| 读取运行时状态       | `cat /sys/devices/platform/soc@0/1d84000.ufs/power/runtime_status`         |

### eMMC 命令

| 用途    | 命令                                                             |
| ----- | -------------------------------------------------------------- |
| 错误统计  | `cat /sys/kernel/debug/mmc0/err_stats`                         |
| 当前时钟  | `cat /sys/kernel/debug/mmc0/clock`                             |
| 运行时状态 | `cat /sys/devices/platform/soc@0/87c4000/power/runtime_status` |

<Note>
  对于 IQ-8275，eMMC 地址为 `87c4000`。
</Note>

## 参考资料

* [EXT4 文件系统介绍](https://opensource.com/article/17/5/introduction-ext4-filesystem)