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

# 内存与存储

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

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

<Warning>
  请将设备配置为仅从一个存储源启动。如果两个存储源都包含可启动文件,可能导致系统崩溃或不可预测的行为。
</Warning>

## UFS 存储

### 特性

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

### 电源管理状态

**Auto-Hibern8 (AH8)** — 空闲 150 毫秒后将 PHY 链路切换到 Hibernate 状态(可调整)。

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

**时钟门控(Clock Gating)** — 默认启用。

```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)** — 默认启用;禁用会增加功耗。

```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-staging/TEuuywLWbysJVmUv/Linux/images/peripheral-interfaces/ufs_storage_archi.png?fit=max&auto=format&n=TEuuywLWbysJVmUv&q=85&s=db163a8e21a9a85d80f05afa93c7ea29" width="1128" height="874" data-path="Linux/images/peripheral-interfaces/ufs_storage_archi.png" />

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

<img src="https://mintcdn.com/qualcomm-staging/TEuuywLWbysJVmUv/Linux/images/peripheral-interfaces/ufs_PM_TM.png?fit=max&auto=format&n=TEuuywLWbysJVmUv&q=85&s=30f5484edcc83463a206fdc10e925fd3" 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 存储

| 特性            | 说明                       |
| ------------- | ------------------------ |
| **通道(Lanes)** | 通过 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-staging/TEuuywLWbysJVmUv/Linux/images/peripheral-interfaces/debugging_flow_diagram.png?fit=max&auto=format&n=TEuuywLWbysJVmUv&q=85&s=f201e2f00fe33b93224176a2e2b04927" 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)