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

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

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