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

# 预配 UFS 设备

预配（Provisioning）是指在新的 UFS 设备上创建并定义 LUN 的过程。一个 UFS 设备具有一个或多个逻辑单元。逻辑单元是设备内部的独立处理实体。每个逻辑单元在 UFS 设备内都有一个地址，称为逻辑单元号（LUN）。

用于预配的配置文件位于 `<build root/common/config/ufs/provision`。

各 UFS 设备版本的预配 XML 文件如下：

* `provision_ufs22.xml` - 用于 UFS 设备 2.2 器件
* `provision_ufs31.xml` - 用于 UFS 设备 3.1 器件

在 UFS 设备预配 XML 文件中，UFS 设备描述符（Device Descriptor）是包含有关所预配 UFS 设备的关键信息的部分。设备描述符包含 LUN 数量、初始电源模式、write boost 参数等详细信息。以下是设备描述符条目示例：

```xml theme={null}
<ufs bNumberLU="6" bBootEnable="1" bDescrAccessEn="0" bInitPowerMode="1" bHighPriorityLUN="0x5" bSecureRemovalType="0"
bInitActiveICCLevel="0" wPeriodicRTCUpdate="0" bConfigDescrLock="0" bWriteBoosterBufferPreserveUserSpaceEn="1" bWriteBoosterBufferType="1"
shared_wb_buffer_size_in_kb="4194304" />
```

预配 XML 文件还使用单元描述符（Unit Descriptor）参数（例如逻辑单元使能、Boot LUN ID）来描述每个 LUN。以下是 LUN 描述符条目示例：

```xml theme={null}
<ufs LUNum="0" bLUEnable="1" bBootLunID="0" size_in_kb="4096" bDataReliability="0" bLUWriteProtect="0" bMemoryType="0"
bLogicalBlockSize="0x0c" bProvisioningType="2" wContextCapabilities="0" wb_buffer_size_in_kb="0"
desc="LU 0 - User LUN - Rest of the device" />
```

下表描述了 *provision XML* 文件中使用的一些重要参数。

| 参数                   | 说明                                                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `bNumberLU`          | 逻辑单元数量。`bNumberLU` 不包含 well-known 逻辑单元。                                                                                 |
| `bBootEnable`        | 指示设备是否启用引导：`00h` = 禁用引导功能，`01h` = 启用可引导功能                                                                               |
| `bDescrAccessEn`     | 指示在引导序列的部分初始化阶段之后是否可以读取设备描述符：`00h` = 禁用设备描述符访问，`01h` = 启用设备描述符访问                                                        |
| `BInitPowerMode`     | 定义设备初始化或硬件复位后的电源模式：`00h` = UFS-Sleep 模式，`01h` = Active 模式                                                               |
| `bHighPriorityLUN`   | 定义高优先级逻辑单元                                                                                                              |
| `bSecureRemovalType` | `00h` = 通过擦除物理内存来清除信息；`01h` = 通过使用单个字符覆盖寻址位置并随后执行擦除来清除信息；`02h` = 通过依次使用某个字符、其补码、再随机字符覆盖寻址位置来清除信息；`03h` = 使用供应商定义的机制清除信息 |
| `bConfigDescrLock`   | `0h` = 配置描述符未锁定；`1h` = 配置描述符已锁定                                                                                         |

<Note>
  * 要重新预配 UFS 设备，请设置 `bConfigDescrLock="0"`。该参数是预配 XML 文件的一部分。
  * 要防止重新预配，请在 UFS 设备配置和预配完成后设置 `bConfigDescrLock="1"`。
</Note>

| 参数                  | 说明                                                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `LUNum`             | 逻辑单元号                                                                                                                         |
| `bLUEnable`         | 启用/禁用逻辑单元：`00h` = 禁用逻辑单元，`01h` = 启用逻辑单元                                                                                       |
| `bBootLunID`        | Boot LUN ID：`00h` = 不可引导，`01h` = Boot LU A，`02h` = Boot LU B                                                                  |
| `size_in_kb`        | 以 KB 为单位指定 LUN 大小                                                                                                             |
| `bLUWriteProtect`   | 逻辑单元写保护：`00h` = LU 未写保护，`01h` = 当 `fPowerOnWPEn = 1` 时 LU 写保护                                                                 |
| `bMemoryType`       | 定义逻辑单元内存类型：`00h` = 普通内存，`01h` = 系统代码内存类型，`02h` = 非持久性内存类型，`03h` = 增强内存类型 1，`04h` = 增强内存类型 2，`05h` = 增强内存类型 3，`06h` = 增强内存类型 4 |
| `bProvisioningType` | 预配类型：`00h` = 禁用精简预配（Thin Provisioning），`02h` = 启用精简预配且 `TPRZ = 0`                                                             |

## UFS 设备分区布局

默认的 UFS 设备预配会创建八个 LUN（LUN0 到 LUN7）。

* Linux 数据和所有 Linux 文件系统镜像存储在 LUN0 中。
* Boot well-known LUN（WLUN）0xB0 在 LUN1 和 LUN2 之间交替，为 XBL 提供故障安全备份。
* 引导链的其余部分存储在 LUN4 中。
* LUN6 和 LUN7 默认未使用。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/images/default-ufs-provisioning-layout.svg" alt="默认 UFS 设备布局" />