Customize a device layout

  • Article

A device layout is the blueprint for a Factory OS device's disk configuration. It describes how Microsoft, OEM, and SV content works together to create a disk layout for a Factory OS image. Device layouts are created by using an XML file to describe the physical hardware, and then using Windows System Kit to generate a device layout package.

To flash an FFU with DISM, the FFU must be configured with a device layout that includes your target hardware's DevicePath and sector size.

Device layout types

Factory OS has two types of device layouts:

  • Monolithic device layout

    You can create a Factory OS image using the device layouts that are included in the Windows System Kit. These layouts are created and owned by Microsoft, and can't be modified.

  • Split device layout

    In Factory OS, device layout ownership can be cleanly split between Microsoft and OEMs. In this scenario:

    • Microsoft specifies required device layout elements like virtual disks and partitions. These are the layout components described in Partition Layout
    • OEMs create an OEM device layout (DeviceLayoutOEM.xml) file that describes the physical characteristics of their disks (such as sector size), and can also add additional partitions or virtual disks.

Compared to monolithic device layouts, split layouts reduce co-engineering time by enabling OEMs and SVs to quickly create layouts for their devices so they can test device bring-up and OS development.

How split device layout works

A split layout has two parts:

  • A device layout that's owned and maintained by Microsoft

    This layout is included in the Windows System Kit and configures the virtual disks and partitions that are required for Factory OS.

  • An OEM-authored DeviceLayoutOEM.xml

    This file describes the characteristics of a device's drive, and can also add additional partitions if required. This file is supplemental to the Microsoft-owned device layout. The two layouts work together to create a device layout that's tailored to your device.

    As a starting point, the DeviceLayoutOEM.xml included in your workspace's %WSKWorkspaceRoot%\OEMCustomization\DeviceLayout folder is pre-populated with the default Store ID and a 512 sector size. You can use this file for your disk layout by:

    • Adding a DevicePath.
    • Ensuring that the sector size matches your disk's sector size.

These two layout files are combined during image creation to create a device layout that's applicable to your device.

See Use a custom device layout on your device to learn how to add a device layout file to your image.

OEM device layout files

The following XML shows the elements that make up an DeviceLayoutOEM.xml file. Each element describes an aspect of the device layout that's configurable by an 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 reference

OEMDeviceLayout child elements

The <OEMDeviceLayout> element is the top-level element for OEM device layouts. The only required element in an OEM layout is 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>
Element Required Type Description
Stores Optional Stores Defines a group of physical disks. OEMDeviceLayout can only include a single <Stores> element.
SectorSize Required integer The disk's sector size. If sector size doesn't match the sector size on the disk, flashing will fail.
MergeVersionTag Optional Integer
UpdateByOSTag Optional, default is false Boolean

Stores child elements

The <Stores> element describes a group of physical disks. OEM device layouts can only have a single <Stores> element.

<Stores>
    <Store>
    ...
    </Store>
</Stores>
Element Description
Store <Store>'s child elements defines a physical disk.

Store child elements

Child elements of <Store> define a physical disk's attributes.

<Store>
    <Id></Id>
    <StoreType></StoreType>
    <DevicePath></DevicePath>
    <SizeInBytes></SizeInBytes>
    <Partitions></Partitions>
</Store>
Element Required Type Description
ID Required String (GUID) Use {5a585bae-900b-41b5-b736-a4cecffc34b4} for configuring a disk that has the Microsoft-required partitions.
StoreType Optional String Provides a human readable description of the store. Does not impact imaging.
DevicePath Required for physical disks String UEFI Device Path of the EFI_BLOCK_IO_PROTOCOL handle that maps to the storage device. Wildcards (?) are acceptable for individual character replacement in the string. Example: <DevicePath>PciRoot(0x0)/Pci(0x1D,0x0)/Pci(0x0,0x0)/NVMe(0x1,??-??-??-??-??-??-??-??)</DevicePath>.
SizeInBytes Required Integer -Size of the physical disk in bytes.
-The Size must be a multiple of 131072 (FFU Block Size)
Partitions Optional Partitions One and only one <Partitions> element allowed per <Store>. Partitions are defined by child elements of <Partitions>

Partitions child elements

Child elements of <Partitions> describe OEM-defined partitions for a device. Partitions configured in DeviceLayoutOEM.xml are in addition to the required partitions that are defined by the Microsoft-owned device layout.

<Partitions>
    <Partition>
    ...
    </Partition>
</Partitions>
Element Required Type Description
Partition Optional Partition Describes a partition on a physical disk

Partition child elements

Child elements to <Partition> describe the properties of partitions on a device.

<Partition>
    <Name></Name>
    <Type></Type>
    <FileSystem></FileSystem>
    <Id></Id>
    <TotalBytes></TotalBytes>    
    <ByteAlignment></ByteAlignment>
</Partition>
Element Required Type Description
Name Required String Max characters: 36 for NTFS filesystem, 11 for FAT or FAT32 filesystem. Partition name must be unique across all parts of your device layout.
Type Required String GUID for GPT partition type
Specify the basic type {ebd0a0a2-b9e5-4433-87c0-68b6b72699c7} for OEM partitions, so they can be accessed via the \\?\Volume{<partition id>}\ path while the device is running Factory OS
FileSystem Optional String -Allowed values are {NTFS, FAT, FAT32}.
-If not specified, the volume will be an unformatted RAW partition
Id Optional String GUID for GPT partition type. Partition Id must be unqiue across all parts of your device layout. If not specified, a random GUID will be assigned.
TotalBytes Optional Integer -Partition size in bytes.
-Partitions should be sized such that it can fit into the "SizeInBytes" specified in its parent "Store", after OS and OEM customization content have been added to the image.
-The value must be divisible by 131072 (FFU Block Size).
-Maximum value is determined by the specified FileSystem type.
ByteAlignment Optional Integer -DO NOT use this field unless recommended by silicon vendor.
-Overrides the byte boundary where the beginning of this partition should align to.

Sample OEM layout

The following is a sample OEM device layout for a physical disk with two partitions and a 512 sector size:

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

Use a custom device layout on your device

After you've created an DeviceLayoutOEM.xml file, you can use it to configure your Factory OS device's disk layout. OEM device layouts are enabled through the Factory OS settings framework.

  1. Author a DeviceLayoutOEM.xml file that reflects your disk configuration. You can use the DeviceLayoutOEM.xml file in your workspace, or use the empty sample above as starting points.

  2. Save the file in your workspace as DeviceLayoutOEM.xml.

  3. Follow the process in Customize settings to generate and use a settings customization file:

    • In your customization file, you'll see a setting called splitlayoutfile. Set the value of this setting to the path of your file.
    <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>

  4. Update the <DeviceLayoutType> in your OEMInput.xml file:

    <DeviceLayoutType>GPT_SPACES_SPLIT</DeviceLayoutType>

  5. When you generate your image, it will use the layout that you've configured.