自定义设备布局

项目
05/30/2023

设备布局是工厂 OS 设备的磁盘配置蓝图。它描述了 Microsoft、OEM 和 SV 内容如何协同工作，为工厂 OS 映像创建磁盘布局。设备布局的创建方式如下：使用 XML 文件描述物理硬件，然后使用 Windows 系统工具包生成设备布局包。

若要使用 DISM 刷写 FFU，必须使用包含目标硬件的 DevicePath 和扇区大小的设备布局配置 FFU。

设备布局类型

工厂 OS 有两种类型的设备布局：

整体式设备布局

可以使用 Windows 系统工具包中包含的设备布局创建工厂 OS 映像。这些布局由 Microsoft 创建和拥有，无法修改。
拆分设备布局

在工厂 OS 中，可以在 Microsoft 和 OEM 之间完全拆分设备布局所有权。在本方案中：
- Microsoft 指定所需的设备布局元素，例如虚拟磁盘和分区。这些是分区布局中描述的布局组件
- OEM 创建 OEM 设备布局 (DeviceLayoutOEM.xml) 文件来描述其磁盘的物理特征（例如扇区大小），并且还可以添加额外的分区或虚拟磁盘。

与整体式设备布局相比，拆分布局使 OEM 和 SV 能够快速为其设备创建布局来测试设备启动和 OS 开发，从而减少了协同工程时间。

拆分设备布局的工作原理

拆分布局有两个部分：

由 Microsoft 拥有和维护的设备布局

此布局包含在 Windows 系统工具包中，用于配置工厂 OS 所需的虚拟磁盘和分区。
OEM 创作的 DeviceLayoutOEM.xml

此文件描述设备驱动器的特征，如果需要，还可以添加额外的分区。此文件是对 Microsoft 拥有的设备布局的补充。这两种布局协同工作，可创建针对设备定制的设备布局。

作为起点，工作区的 %WSKWorkspaceRoot%\OEMCustomization\DeviceLayout 文件夹中包含的 DeviceLayoutOEM.xml 已预先填充默认存储 ID 和 512 扇区大小。你可以通过以下方式将此文件用于磁盘布局：
- 添加 DevicePath。
- 确保扇区大小与磁盘的扇区大小匹配。

这两个布局文件在映像创建期间组合在一起，以创建适用于你的设备的设备布局。

请参阅在设备上使用自定义设备布局，了解如何将设备布局文件添加到映像中。

OEM 设备布局文件

以下 XML 显示了构成 DeviceLayoutOEM.xml 文件的元素。每个元素都描述了可由 OEM 配置的设备布局的一个方面。

<?xml version="1.0" encoding="utf-8"?>
<OEMDeviceLayout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate/v2">
    <Stores>
        <Store>
            <Id></Id>
            <StoreType></StoreType>
            <DevicePath></DevicePath>
            <SizeInBytes></SizeInBytes>
            <Partitions>
                <Partition>
                    <Name></Name>
                    <Type></Type>
                    <FileSystem></FileSystem>
                    <Id></Id>
                    <TotalBytes></TotalBytes>    
                    <ByteAlignment></ByteAlignment>
                </Partition>
            </Partitions>
        </Store>
    </Stores>
    <SectorSize></SectorSize>
    <MergeVersionTag></MergeVersionTag>
    <UpdateByOSTag></UpdateByOSTag>
</OEMDeviceLayout>

OEMDeviceLayout 参考

OEMDeviceLayout 子元素

<OEMDeviceLayout> 元素是 OEM 设备布局的顶级元素。 OEM 布局中唯一需要的元素是 SectorSize。

<OEMDeviceLayout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate/v2">
    <Stores></Stores>
    <SectorSize></SectorSize>
    <MergeVersionTag></MergeVersionTag>
    <UpdateByOSTag></UpdateByOSTag>
</OEMDeviceLayout>

元素	必须	类型	说明
Stores	可选	Stores	定义一组物理磁盘。 OEMDeviceLayout 只能包含一个 <Stores> 元素。
SectorSize	必需	integer	磁盘的扇区大小。如果扇区大小与磁盘上的扇区大小不匹配，刷写将失败。
MergeVersionTag	可选	整数
UpdateByOSTag	可选，默认值为 false	Boolean

Stores 子元素

<Stores> 元素描述一组物理磁盘。 OEM 设备布局只能有一个 <Stores> 元素。

<Stores>
    <Store>
    ...
    </Store>
</Stores>

元素	说明
存储	<Store> 的子元素定义物理磁盘。

Store 子元素

<Store> 的子元素定义物理磁盘的属性。

<Store>
    <Id></Id>
    <StoreType></StoreType>
    <DevicePath></DevicePath>
    <SizeInBytes></SizeInBytes>
    <Partitions></Partitions>
</Store>

元素	必须	类型	描述
ID	必选	字符串 (GUID)	使用 `{5a585bae-900b-41b5-b736-a4cecffc34b4}` 配置具有 Microsoft 所需分区的磁盘。
StoreType	可选	字符串	提供用户可读的存储说明。不会影响映像。
DevicePath	对于物理磁盘是必需的	字符串	映射到存储设备的 EFI_BLOCK_IO_PROTOCOL 句柄的 UEFI 设备路径。通配符 (`?`) 可用于字符串中的单个字符替换。示例：`<DevicePath>PciRoot(0x0)/Pci(0x1D,0x0)/Pci(0x0,0x0)/NVMe(0x1,??-??-??-??-??-??-??-??)</DevicePath>`。
SizeInBytes	必需	整数	-物理磁盘的大小，以字节为单位。 -大小必须是 131072（FFU 块大小）的倍数
分区	可选	分区	每个 <Store> 允许一个且仅一个 <Partitions> 元素。分区由 <Partitions> 的子元素定义

Partitions 子元素

<Partitions> 的子元素描述 OEM 为设备定义的分区。 DeviceLayoutOEM.xml 中配置的分区是对 Microsoft 拥有的设备布局定义的所需分区的补充。

<Partitions>
    <Partition>
    ...
    </Partition>
</Partitions>

元素	必须	类型	描述
分区	可选	分区	描述物理磁盘上的分区

Partition 子元素

<Partition> 的子元素描述设备上分区的属性。

<Partition>
    <Name></Name>
    <Type></Type>
    <FileSystem></FileSystem>
    <Id></Id>
    <TotalBytes></TotalBytes>    
    <ByteAlignment></ByteAlignment>
</Partition>

元素	必须	类型	说明
客户	必须	String	最大字符数：NTFS 文件系统为 36 个，FAT 或 FAT32 文件系统为 11 个。分区名称在设备布局的所有部分中必须是唯一的。
类型	必须	String	GPT 分区类型的 GUID 为 OEM 分区指定基本类型 `{ebd0a0a2-b9e5-4433-87c0-68b6b72699c7}`，以便在设备运行工厂 OS 时通过 `\\?\Volume{<partition id>}\` 路径访问它们
FileSystem	可选	字符串	-允许的值为 {NTFS、FAT、FAT32}。 -如果未指定，卷将为未格式化的原始分区
ID	可选	String	GPT 分区类型的 GUID。分区 ID 在设备布局的所有部分中必须是唯一的。如果未指定，将分配一个随机 GUID。
TotalBytes	可选	整数	-以字节为单位的分区大小。 -在将 OS 和 OEM 自定义内容添加到映像后，应将分区的大小调整为适应其父“Store”中指定的“SizeInBytes”。 -该值必须能被 131072（FFU 块大小）整除。 -最大值由指定的文件系统类型决定。
ByteAlignment	可选	整数	-除非芯片供应商推荐，否则请勿使用此字段。 -替代此分区的开头应对齐的字节边界。

OEM 布局示例

下面是具有两个分区和 512 扇区大小的物理磁盘的 OEM 设备布局示例：

<?xml version="1.0" encoding="utf-8"?>
<OEMDeviceLayout xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.microsoft.com/embedded/2004/10/ImageUpdate/v2">
    <Stores>
        <Store>
            <Id>{5a585bae-900b-41b5-b736-a4cecffc34b4}</Id>
            <StoreType>Default</StoreType>
            <DevicePath>VenHw(8D90D477-39A3-4A38-AB9E-586FF69ED051)</DevicePath>
            <SizeInBytes>4294967296</SizeInBytes>            
            <Partitions>
                <Partition>
                    <Name>OEM1</Name>
                    <Type>{ebd0a0a2-b9e5-4433-87c0-68b6b72699c7}</Type>
                    <FileSystem>FAT32</FileSystem>
                    <TotalBytes>134217728</TotalBytes>
                </Partition>
                <Partition>
                    <Name>OEM2</Name>
                    <Type>{ebd0a0a2-b9e5-4433-87c0-68b6b72699c7}</Type>
                    <FileSystem>FAT32</FileSystem>
                    <TotalBytes>67108864</TotalBytes>
                </Partition>
            </Partitions>
        </Store>
    </Stores>
    <SectorSize>512</SectorSize>
    <MergeVersionTag>1</MergeVersionTag>
</OEMDeviceLayout>

在设备上使用自定义设备布局

创建 DeviceLayoutOEM.xml 文件后，可以使用它来配置工厂 OS 设备的磁盘布局。 OEM 设备布局通过工厂 OS 设置框架启用。

创作反映磁盘配置的 DeviceLayoutOEM.xml 文件。可以在工作区中使用 DeviceLayoutOEM.xml 文件，或者使用上面的空示例作为起点。
将工作区中的文件另存为 DeviceLayoutOEM.xml。

按照自定义设置中的过程生成和使用 settings 自定义文件：

在自定义文件中，你会看到一个名为 splitlayoutfile 的设置。将此设置的值设置为文件的路径。

<Customization Name="splitlayoutfile">
    <ReadOnlyMetadata Description="oem/sv-owned split layout file. (file must be named DeviceLayoutOEM.xml)" Type="FILE" DefaultValue="" SupportedExtensions="xml" />
    <Value>C:\Workspace\OEMCustomization\DeviceLayout\DeviceLayoutOEM.xml</Value>
</Customization>

更新 OEMInput.xml 文件中的 <DeviceLayoutType>：

<DeviceLayoutType>GPT_SPACES_SPLIT</DeviceLayoutType>

生成映像时，它将使用已配置的布局。

通过