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

### 特性

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

### 内核配置

| 配置项                           | 默认值 | 说明                       |
| ----------------------------- | --- | ------------------------ |
| `CONFIG_UFS_FAULT_INJECTION`  | 否   | 注入故障命令用于调试               |
| `CONFIG_SCSI_UFSHCD`          | 是   | UFS 主机控制驱动               |
| `CONFIG_SCSI_UFSHCD_PLATFORM` | 是   | 来自平台总线的 UFS 控制器          |
| `CONFIG_SCSI_UFS_QCOM`        | 是   | Qualcomm 特定的 PHY 和供应商寄存器 |
| `CONFIG_PHY_QCOM_QMP`         | 是   | UFS QMP PHY 驱动           |
| `CONFIG_SCSI_UFS_BSG`         | 是   | UFS BSG 设备节点             |
| `CONFIG_SCSI_UFS_CRYPTO`      | 是   | UFS 加密引擎                 |

### 电源管理状态

**Auto-Hibern8(AH8)** — 在空闲 150 ms 后将 PHY 链路切换到休眠状态(可调整)。

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

**时钟门控** — 在空闲 50 ms(最大频率)或 10 ms(缩放频率)后进行门控。默认启用。

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

**时钟调节** — 根据负载阈值上调/下调。默认启用;禁用会增加功耗。

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

**运行时挂起/恢复** — 在 3 秒无活动后进入挂起状态。始终启用,不可配置。

**系统挂起/恢复** — 跟随系统挂起/恢复事件。始终启用,不可配置。

### 设备参数

| 参数                      | 子节点                | 值           | 说明                            |
| ----------------------- | ------------------ | ----------- | ----------------------------- |
| `init_speed_params`     | EnableHighSpeed    | 1           | 启用高速模式                        |
|                         | NumGears           | 4           | 最大档位(UFS 2.x 为 3,UFS 3.1 为 4) |
|                         | NumLanes           | 2           | 通道数                           |
|                         | Rate               | 2           | 1=Rate A,2=Rate B             |
| `perf_speed_params`     | EnableHighSpeed    | 1           | 性能模式下的高速                      |
|                         | NumGears           | 4           | 性能模式下的最大档位                    |
|                         | NumLanes           | 2           | 性能模式下的通道数                     |
|                         | Rate               | 2           | 性能模式下的系列                      |
| `timeout_values`        | fDeviceInitTimeout | 2500000 μs  | 设备初始化超时                       |
|                         | UTRDPollTimeout    | 30000000 μs | UTRD 超时                       |
| `BatteryThresholdMv`    | —                  | 3600        | 切换到 Gear 1 的电池阈值(mV)          |
| `LinkStartupRetryCount` | —                  | 5           | 链路启动重试次数                      |
| `RefClock`              | —                  | 19200000    | 参考时钟(19.2 MHz)                |

### UFS 预配

UFS 预配(provisioning)在新的 UFS 设备上创建逻辑单元号(LUN)。

**设备描述符参数:**

| 参数                 | 说明                        |
| ------------------ | ------------------------- |
| `bNumberLU`        | 逻辑单元数量                    |
| `bBootEnable`      | `00h`:禁用启动,`01h`:启用启动     |
| `bConfigDescrLock` | `0h`:未锁定,`1h`:已锁定(防止重新预配) |

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

**LUN 参数:**

| 参数                  | 说明                                         |
| ------------------- | ------------------------------------------ |
| `LUNum`             | 逻辑单元号                                      |
| `bLUEnable`         | `00h`:禁用,`01h`:启用                          |
| `bBootLunID`        | `00h`:不可启动,`01h`:Boot LU A,`02h`:Boot LU B |
| `size_in_kb`        | LUN 大小(KB)                                 |
| `bMemoryType`       | `00h`:普通,`01h`:系统代码,`02h`:非持久              |
| `bProvisioningType` | `00h`:禁用精简预配,`02h`:启用(TPRZ=0)              |

**默认分区布局:**

* **LUN0** — Linux 数据和文件系统镜像
* **LUN1 和 LUN2** — 启动 WLUN(0xB0)交替使用,用于故障保护的 XBL 备份
* **LUN4** — 启动链的其余部分
* **LUN6 和 LUN7** — 默认未使用

### 架构图

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

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

<img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/ufs_device_partition_layout.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=016f38e0894837d082af1405f13bdbde" width="419" height="959" data-path="Ubuntu/images/peripheral-interfaces/ufs_device_partition_layout.png" />

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

<img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/storage_IO_flowsequence.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=d099ba0815aa3804713099fd0ea15bec" width="1058" height="1001" data-path="Ubuntu/images/peripheral-interfaces/storage_IO_flowsequence.png" />

<img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/ufs_provision_flow.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=cde2ec6a251bc8c3670db7fe4fffd982" width="746" height="935" data-path="Ubuntu/images/peripheral-interfaces/ufs_provision_flow.png" />

## eMMC 存储

### 特性

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

### 设备树配置

在 SoC 专用 DTSI 文件的 `&sdhc_1` 节点中添加以下内容:

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

### 电源管理

* **运行时挂起** — 50 ms 无活动后触发;始终启用
* **系统挂起** — 跟随系统挂起/恢复事件;始终启用

## SD 卡存储

### 特性

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

### 内核配置

| 配置项                    | 默认值 | 说明           |
| ---------------------- | --- | ------------ |
| `CONFIG_MMC`           | 是   | MMC 驱动       |
| `CONFIG_MMC_SDHCI`     | 是   | SDHCI 驱动     |
| `CONFIG_MMC_CQHCI`     | 是   | 命令队列主机控制接口   |
| `CONFIG_MMC_SDHCI_MSM` | 是   | MSM SDHCI 驱动 |
| `CONFIG_MMC_BLOCK`     | 是   | MMC 块设备驱动    |
| `CONFIG_MMC_CRYPTO`    | 是   | MMC 加密引擎     |

### 电源管理

* **运行时挂起** — 50 ms 无活动后触发;始终启用
* **系统挂起** — 跟随系统挂起/恢复事件;始终启用

## NVMe 存储

| 特性     | 说明                      |
| ------ | ----------------------- |
| **通道** | 通过 PCIe 端口(PCIe1)的 4 通道 |
| **接口** | 高速串行                    |
| **协议** | 针对 NAND 闪存和下一代 SSD 优化   |

## 配置指南

### 挂载文件系统

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

### 电源管理控制

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

## 故障排除

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

<img src="https://mintcdn.com/qualcomm-staging/5j1H6H_NhFpsAqlq/Ubuntu/images/peripheral-interfaces/troubleshotting_decision_tree.png?fit=max&auto=format&n=5j1H6H_NhFpsAqlq&q=85&s=b827374c9ba04549d6c7af9fe0141dbb" width="1601" height="789" data-path="Ubuntu/images/peripheral-interfaces/troubleshotting_decision_tree.png" />

<AccordionGroup>
  <Accordion title="命令在设备中挂起">
    **症状:**

    ```
    ufshcd-qcom 1d84000.ufshc: ufshcd_abort: cmd pending in the device. tag = 1
    ```

    **解决方法:** 联系 UFS 设备供应商;检查设备兼容性和电源供应稳定性。
  </Accordion>

  <Accordion title="设备无响应">
    **症状:**

    ```
    ufshcd-qcom 1d84000.ufshc: ufshcd_abort: no response from device. tag = 2, err -110
    ```

    **解决方法:** 检查物理连接,验证电源轨,检查 PHY 初始化。
  </Accordion>

  <Accordion title="物理适配器/数据链路错误">
    **症状:**

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

    **诊断:**

    ```bash theme={null}
    mount -t debugfs none /sys/kernel/debug
    cat /sys/kernel/debug/ufshcd/1d84000.ufs/stats
    ```

    **解决方法:** 表明信号质量差。检查 PCB 布局、信号完整性和 PHY 设置。请联系 Qualcomm 支持进行 PHY 调优。
  </Accordion>

  <Accordion title="活动状态下功耗过高">
    **诊断:**

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

    **解决方法:** 如果时钟调节被禁用,请启用它;如不需要 WriteBooster,请将其禁用。
  </Accordion>

  <Accordion title="睡眠状态下功耗过高">
    **诊断:**

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

    **解决方法:** 调整 PM 级别;如果 HPB/WriteBooster 引发问题,请将其禁用;验证 VCC/VCCQ/VCCQ2 时序。
  </Accordion>

  <Accordion title="未处理的 SMMU 故障">
    **症状:**

    ```
    arm-smmu 15000000.apps-smmu: Unhandled arm-smmu context fault from 1d84000.ufshc!
    ```

    **解决方法:** 在 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/gear`              |
| 读取链路状态(ACTIVE/HIBERN8) | `cat /sys/devices/platform/soc@0/1d84000.ufs/power_info/link_state`        |
| 读取运行时状态                | `cat /sys/devices/platform/soc@0/1d84000.ufs/power/runtime_status`         |
| 读取 RPM/SPM 级别          | `cat /sys/devices/platform/soc@0/1d84000.ufs/rpm_lvl`                      |

### SD 卡命令

| 用途      | 命令                                                                 |
| ------- | ------------------------------------------------------------------ |
| 读取错误统计  | `cat /sys/kernel/debug/mmc1/err_stats`                             |
| 检查当前时钟  | `cat /sys/kernel/debug/mmc1/clock`                                 |
| 读取运行时状态 | `cat /sys/devices/platform/soc@0/8804000.mmc/power/runtime_status` |

### NVMe 命令

| 用途       | 命令                                       |
| -------- | ---------------------------------------- |
| 查看设备型号   | `cat /sys/class/nvme/nvme0/model`        |
| 查看固件版本   | `cat /sys/class/nvme/nvme0/firmware_rev` |
| 查看命名空间大小 | `cat /sys/class/nvme/nvme0/nvme0n1/size` |

### eMMC 命令

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

<Note>
  对于 eMMC 命令,请将地址替换为 SoC 对应的值:IQ-615 和 IQ-9075 使用 `7c4000`;IQ-8275 使用 `87c4000`。
</Note>

## 参考资料

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