Windows Standard Packaging Configuration (WSPC) requirements for retail images
For mobile retail images, OEM firmware packages (sometimes referred to as BSP submissions) must comply with the Windows Standard Package Configuration (WSPC).
WSPC is designed to achieve a better customer experience:
- Smaller download sizes.
- Reduced imaging and update errors.
- Faster updates: Reduced system overhead needed to deliver and install updates.
- Fewer updates: Device updates can make a "single hop" update from any image baseline.
Note
Microsoft requires that all OEM retail firmware packages (BSP submissions) conform to the WSPC. While there are no exceptions to this policy, Microsoft has included tools and processes to ease the your transition to WSPC compliance.
WSPC overview
The purpose of WSPC is to define a firmware package set and update rules for that package set where it is easy to determine differences between any two arbitrary versions of the package set. The ability to easily and definitively determine the changes between any two package set versions allows Microsoft to use more efficient methods to update the device. The end result is a better customer experience as the user will experience only a single update session and associated reboot as opposed to several.
Previous WSPC implementation
Microsoft’s previous implementation of WSPC mandated a static firmware package set using static package names. The static package set and names applied globally to all of an OEM’s POPs. These packages were tightly coupled to the processor’s (SOC’s) the file system partition layout. While this implementation fulfilled the goal described in the summary above, it had two serious drawbacks. First, it put a high burden on you to achieve compliance due to its complex implementation. Second, the implementation’s tight coupling to the SOC’s file system partition layout does not accommodate new SOC’s with different partition configurations.
New WSPC implementation
The new WSPC implementation based on a simpler generalization of our previous implementation. As long as we don’t remove or rename packages between firmware versions, determining the differences between any two arbitrary firmware versions is straight forward. We simply compare the source and target firmware package sets, and update any packages that have changed between the two. This includes the addition of packages from one firmware version to another.
Complying with the new model is simple and requires less overhead. Instead of Microsoft prescribing the exact contents of the firmware package set, the you will do this by declaring one of your firmware package sets as a baseline. This baseline will apply to a specific set of POPs defined by the OEM. In addition, since this model is a generalized form of the previous WSPC implementation, Windows Phone 8.1 WSPC compliance firmware submissions are automatically compliant with the new WSPC implementation.
This implications of this model are:
You can define multiple baselines on a per POP basis.
Once a package is added to a firmware package set, it cannot be removed.
If necessary, you must include an empty package.
You cannot rename a package in a firmware package set.
This is effectively the removal of an existing and the addition of a new package.
You must be mindful to ensure the firmware package set does not grow beyond reasonable size.
Feature merge should be used to manage firmware package set growth.
WSPC requirements
Windows Phone Ingestion Client
You must upgrade to the version x.x.x.x of the Windows Phone Ingestion Client (WPIC). There are breaking changes in this version that necessitate the upgrade, including:
A Baseline parameter has been added to the Initialize-FirmwareSubmission cmdlet. This will be used to identify a firmware submission as a baseline for WSPC compliance validation.
The nonWSPCCompliant parameter of the Initialize-FirmwareSubmission cmdlet has been deprecated.
All requests for all cmdlets from previous versions of the WPIC will be rejected with the following error:
The Windows Phone Ingestion Client version you are using (Version {0}) is no longer supported. Please make sure you are using the current version of the Windows Phone Ingestion Client, Version {1}.
Feature merge
Feature Merge continues to play a critical role in the new WSPC implementation. Packages must be feature merged to greatest extent possible to smallest resultant set possible. Feature Merging firmware packages will help manage package set growth as well avoid situations where you must work around deprecated packages for WSPC compliance.
More information on using feature merge can be found at the links below:
Firmware submissions
Firmware updates are determined by comparing the baseline firmware submission with any subsequent submissions.
Baseline firmware submission
To prepare a firmware submission for updating to retail devices by using a Request For Update (RFU), it must first be declared as a baseline. By declaring a firmware submission as a baseline, the package set comprising firmware submission will be used as the basis for WSPC compliance checks.
Prior to declaring a firmware submission as a baseline, you should have performed sufficient testing on the firmware so that they are confident that the package set will experience minimal and/or manageable variance in subsequent versions. Also, as discussed above, the package set should be feature merged to the greatest extent possible.
To declare the firmware submission as a baseline, you will run the Initialize-FirmwareSubmission cmdlet with the baseline parameter as shown below.
Initialize-FirmwareSubmission -TypeOfSubmission Image –UpdateHistoryPath [path] –OemInputPath [path] –OutputFilePath [path] -Baseline
Subsequent firmware submissions
After a baseline firmware submission has been declared, subsequent firmware submissions targeting the same POPs will be compared with the previous baseline firmware version for WSPC compliance.
Important Special care must be taken when targeting firmware submissions for multiple POPs with different baselines. Achieving WSPC compliance across all baselines can be difficult.
The WSPC compliance check will ensure that the package set of the new firmware version contains the same packages as the previous baseline or is a superset of the previous baseline. Consider the following package sets as an example:
Baseline firmware submission
Package1.spkg version 1
Package2.spkg version 1
Package3.spkg version 1
Package4.spkg version 1
Firmware submission v2
Package1.spkg version 2
Package2.spkg version 2
Package3.spkg version 2
Package4.spkg version 2
Firmware submission v3
Package1.spkg version 2
Package2.spkg version 2
Package3.spkg version 2
Package4.spkg version 2
Package5.spkg version 1
Firmware submission v4
Package1.spkg version 2
Package2.spkg version 2
Package3.spkg version 2
Package5.spkg version 1
Firmware submission v2 is WSPC-compliant with the baseline because the package set is the same between versions (even though the package versions are different).
Firmware submission v4 is not WSPC-compliant with the baseline because Package4.spkg does not exist (has been removed) in version 4.
Microsoft will process all firmware submissions regardless of their WSPC compliance status as long as you have not submitted it as a baseline.
Initialize-FirmwareSubmission -TypeOfSubmission Image –UpdateHistoryPath [path] –OemInputPath [path] –OutputFilePath [path]
If the new firmware submission is not WSPC-compliant, the following warning will be returned:
The firmware submission is not WSPC compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. Since this is not a new baseline, the firmware submission is allowed. However, since this submission not WSPC compliant and is not a baseline, it will not be available for a retail servicing update. Retail servicing updates are only allowed for the following scenarios: between an RTM source submission and an RTM target submission, or between a legacy non-WSPC compliant source submission and an RTM target submission. To make this submission WSPC compliant, please ensure the missing packages are included in the submission.
Microsoft will reject baseline firmware submissions that are not WSPC-compliant. The following error will be shown:
<path>:\ Initialize-FirmwareSubmission -TypeOfSubmission Image –UpdateHistoryPath [path] –OemInputPath [path] –OutputFilePath [path] -Baseline
The firmware submission is not WSPC compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. To make this submission WSPC compliant, please ensure the missing packages are included in the submission.
*.SPKG and *.CAB firmware package names
Starting with Windows 10 Mobile, you’ll be able to build firmware using Microsoft’s Component Based Servicing Model (CBS). CBS packages use the *.CAB extension where legacy Windows Phone packages use the *.SPKG extension. Once pushed to the device, SPKG packages are converted to CAB packages on device so package names are not unique by extension.
As a result, when conducting WSPC compliance checks between firmware submissions, packages names differing only by SPKG or CAB extension will be treated as the same package.
For example, package1.spkg will be treated as the same package as package1.cab.
Using empty packages for WSPC compliance
In some cases, it may be necessary for a you to discontinue the use of a particular package that was part of a previous baseline submission. However, to maintain WSPC compliance for subsequent baseline submissions, the deprecated package must continue to exist.
To support this scenario, you can submit an empty package of the same package name in the new baseline submission.
Removal packages
Because the purpose of the new WSPC implementation is to remove the use of and need for removal packages, they are no longer supported for firmware submissions.
Out of order firmware submissions
Over the course of a typical development lifecycle for firmware, we expect that the version number of new firmware will always be larger than the previous version number. However, we understand that there may be exceptions. As a result, Microsoft will also support cases where you submit firmware with versions that are less than the max firmware version submitted.
For example, assume the following baseline versions of firmware have been submitted :
Baseline firmware submission v1
Baseline firmware submission v3
Baseline firmware submission v5
Baseline firmware submission v7
Now, you submit new firmware with version 4. WSPC compliance will need to run against:
- Baseline firmware submission v3 to ensure that the v4 package set is a superset of the v3 package set (no removals between v3 and v5)
- Baseline firmware submission v5 to ensure that the v5 package set is a superset of the v4 package set (no removals between v4 and v5)
If either of the checks fail and the firmware submission v4 was submitted without the baseline flag, the firmware will be accepted, but the following warning will be returned:
<path>:\ Initialize-FirmwareSubmission -TypeOfSubmission Image –UpdateHistoryPath [path] –OemInputPath [path] –OutputFilePath [path]
The firmware submission is not WSPC compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. Since this is not a new baseline, the firmware submission is allowed. However, since this submission not WSPC compliant and is not a baseline, it will not be available for a retail servicing update. Retail servicing updates are only allowed for the following scenarios: between an RTM source submission and an RTM target submission, or between a legacy non-WSPC compliant source submission and an RTM target submission. To make this submission WSPC compliant, please ensure the missing packages are included in the submission.
If either of the checks fail and the firmware submission v4 was submitted with the baseline parameter, the firmware will be rejected with the following error:
<path>:\ Initialize-FirmwareSubmission -TypeOfSubmission Image –UpdateHistoryPath [path] –OemInputPath [path] –OutputFilePath [path] -baseline
The firmware submission is not WSPC compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. To make this submission WSPC compliant, please ensure the missing packages are included in the submission.
Partial submissions
Partial firmware submissions with the Initialize-FirmwareSubmission cmdlet using the PartialImage parameter will still be allowed, but the submission must not be a baseline submission.
NonWSPCCompliant parameter
The NonWspcCompliant parameter is not supported.
For more info, see Initialize-FirmwareSubmission cmdlet.
Request for update (RFU)
As we mentioned previously, retail servicing must be between baseline firmware submissions. By retail servicing, we mean using the New-RequestForUpdate cmdlet with the retail servicing type. An example is shown below:
$result = New-RequestForUpdate
-FirmwareSubmissionTicketId <Target Firmware Submission>
–RequestForUpdateType RetailServicing
-SourceFirmwareSubmissionTicketId <Source Firmware Submission>
-OemDeviceName xxx
-MOId 000-yy
RFUs used for retail servicing must be:
- Between two successful baseline firmware submissions
- The version of the target firmware submission must be greater than the source firmware submission
If the target firmware submissions is not a baseline, the request will be rejected and the following error will be shown:
The target firmware submission is not a Baseline submission, which is required for a retail servicing update. A retail servicing update is only allowed for the following scenarios: between a Baseline source submission and a Baseline target submission, or between a legacy non-WSPC compliant source submission and a Baseline target submission. Please also make sure you are using the current version of the Windows Phone Ingestion Client, Version {0}. Submission status in this request for update: [Target submission: {1}, {2}], [Source submission: {3}, {4}].
If neither the source nor target firmware submissions are baseline but the source firmware submission is WSPC compliant, the request will be rejected and the following error will be shown:
The source firmware submission is WSPC compliant, however it is not a Baseline submission, which is required for a retail servicing update. A retail servicing update is only allowed for the following scenarios: between a Baseline source submission and a Baseline target submission, or between a legacy non-WSPC compliant source submission and a Baseline target submission. Please also make sure you are using the current version of the Windows Phone Ingestion Client, Version {0}.
If the target firmware submissions is not a baseline, but the request is not for retail servicing, the request will be accepted and processed with a warning similar to the follow:
$result = New-RequestForUpdate
-FirmwareSubmissionTicketId <Target Firmware Submission>
–RequestForUpdateType Trial
-SourceFirmwareSubmissionTicketId <Source Firmware Submission>
-OemDeviceName xxx
-MOId 000-yy
The target firmware submission is not a Baseline submission, which is required for a retail servicing update. A retail servicing update is only allowed for the following scenarios: between a Baseline source submission and a Baseline target submission, or between a legacy non-WSPC compliant source submission and a Baseline target submission. Since this is a non-retail RFU, it is being allowed, however the RFU should be made WSPC compliant before submitting the retail RFU. RFU status in this request for update: [Target submission: {0}, {1}], [Source submission: {2}, {3}].
If neither the source nor target firmware submissions are baseline but the source firmware submission is WSPC compliant, but the request is not for retail servicing, the request will be accepted and processed with a warning similar to the follow:
The source firmware submission is WSPC compliant, however it is not a Baseline submission, which is required for a retail servicing update. A retail servicing update is only allowed for the following scenarios: between a Baseline source submission and a Baseline target submission, or between a legacy non-WSPC compliant source submission and a Baseline target submission. Since this is a non-retail RFU, it is being allowed, however the RFU should be made WSPC compliant before submitting the retail RFU.
Support for legacy WSPC compliance
Because the new WSPC compliance is a more general implementation of the previous WSPC model, legacy WSPC compliant submissions will automatically be compliant with the new model.
All existing WSPC submissions will automatically be marked as baseline as part of the rollout of this change.
Migrating from a legacy non-compliant submission
Because our customers already have devices already with non-WSPC compliant firmware, Microsoft will provide an upgrade path for these devices to WSPC-compliant versions.
To accommodate this, Microsoft will allow retail servicing from non baseline (non-WSPC compliant) firmware submissions to baseline firmware submissions provided the following conditions are met:
- The source firmware submission version is less than the minimum version of the baseline firmware version.
- The baseline target firmware submission is WSPC-compliant with the source firmware submission.
The implication of these conditions is that the package set of the existing source non-compliant submissions will effectively become the baseline package set for WSPC compliance going forward.
For more info, see New-RequestForUpdate cmdlet.
Tools
The Microsoft Windows Phone Ingestion Client (WPIC) and Phone Image Inspector (ImgVal) have both been updated to determine if firmware submissions are WSPC-compliant or not. However, because WSPC compliance is now determined by comparison to previously submitted baseline firmware, both tools must have access to Microsoft’s UTS systems. As a result, ImgVal will not be capable of running in a standalone mode. During installation, ImgVal will prompt you for your Microsoft Connect credentials as it does currently for WPIC. For more info about WPIC, see Ingestion Client for Windows Phone.
Standard validation
In addition to WSPC validation, WPIC and ImgVal will also run a new set of standard validations against firmware submissions. These standard validation rules are designed to catch common errors in firmware submissions that may cause issues during retail servicing.
Previously, this validation was bypassed for NonWspcCompliant submissions. Going forward they will be applied to all submissions. Standard validation errors are blocking and must be fixed for successful firmware submissions.
The standard validation rules are listed below:
| Validation | Rule | |
|---|---|---|
| 1 | Removal packages | Removal packages are not allowed. This includes SPKRs or CBS-Rs. |
| 2 | Package version | Packages cannot have a 0.0.0.0 package version. |
| 3 | Binary packages in MainOS | Packages in MainOS partition cannot be flagged as binary partition package. |
| 4 | Binary packages in EFIESP | Packages in EFIESP partition cannot be flagged as binary partition package. |
| 5 | Binary packages in UpdateOS | Packages in UpdateOS partition cannot be flagged as binary partition package. |
| 6 | PhoneFirmwareRevision | Firmware version must be in x.x.x.x format where x is between 0 and 65535 (inclusive). |
| 7 | PhoneManufacturer | Phone manufacturer name must be alphanumerical and less than or equal to 32 characters. |
| 8 | PhoneManufacturerModelName | OEM device name must be alphanumerical with -._ and less than or equal to 32 characters. |
| 9 | PhoneMobileOperatorName | Mobile operator name must conform to XXX-XX format. |
Note Firmware created through the Qualcomm Windows Phone Customization Tool (QWPCT) will automatically conform to the standard compliance rules above.
Building merged packages
To conform to WSPC, OEMs should use FeatureMerger.exe to reduce the total number of packages in a firmware submissions to the greatest extent possible. For more info about the package merging process and how the merged package names are derived, see Merging packages before imaging.
Creating empty packages
Achieving WSPC compliance for a new firmware submission requires that it contain a superset of the packages contained in the previous baseline submission. An impact of this WSPC compliance rule is that packages may not be removed from new firmware submissions as compared to the previous baseline.
In some cases, it may be necessary to reconfigure your firmware in such a way that a package in the previous baseline is no longer used. In order to achieve WSPC compliance in this case, you will need to create and include an empty package in the firmware.
The following steps summarize the process of creating an empty feature merged package called Contoso.BASE.MainOS.spkg:
Build one empty package for the partition targeted by the package using PkgGen.exe. Ensure the <Components> element is empty. For example, the following package XML generates an empty project for the MainOS partition.
<Package xmlns="urn:Microsoft.WindowsPhone/PackageSchema.v8.00" Owner="Contoso" OwnerType="OEM" Component="EmptyPackage" SubComponent=”ForMainOS” ReleaseType="Production" Platform="<PLAT>" Partition="MainOS"> <Components> </Components> </Package>Reference the empty packages in the feature manifest. For example, the following feature manifest generates merged base packages and includes a combination of empty packages for the MainOS partition.
<FeatureManifest xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns="https://schemas.microsoft.com/embedded/2004/10/ImageUpdate"> <BasePackages> <PackageFile Path="C:\Packages" Name="Contoso.BASE.MainOS.spkg" Partition="MainOS" /> <PackageFile Path="C:\EmptyPackage" Name="Contoso.EmptyPackage.ForMainOS.spkg"/> <PackageFile Path="C:\EmptyPackage" Name="Contoso.EmptyPackage.ForMainOS2.spkg"/> <PackageFile Path="C:\EmptyPackage" Name="Contoso.EmptyPackage.ForMainOS3.spkg"/> </BasePackages> </FeatureManifest>Generate merged packages by running FeatureMerger.exe with the feature manifests that reference the empty packages. The generated merged packages will contain both the empty packages and, where applicable, packages with content from the OEM.
Alternately, you can generate an empty package for the partition targeted by the package using PkgGen.exe without using feature merge. Ensure the <component> element is empty. For example, the following package XML generates an empty project for the MainOS partition called Contoso.BASE.MainOS.spkg.
<Package xmlns="urn:Microsoft.WindowsPhone/PackageSchema.v8.00"
Owner="Contoso" OwnerType="OEM" Component="BASE" SubComponent=”MainOS” ReleaseType="Production" Platform="<Plat>" Partition="MainOS">
<Components>
</Components>
</Package>
Troubleshooting
| Activity | Message | Resolution | |
|---|---|---|---|
| 1 | Any WPIC command | The Windows Phone Ingestion Client version you are using (Version {0}) is no longer supported. Please make sure you are using the current version of the Windows Phone Ingestion Client, Version {1}. | Download and install the latest Windows Phone Ingestion Client from Microsoft Connect. |
| 2 | Request for update | WSPC compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. Since this is not a new baseline, the firmware submission is allowed. However, since this submission not WSPC compliant and is not a baseline, it will not be available for a retail servicing update. Retail servicing updates are only allowed for the following scenarios: between an RTM source submission and an RTM target submission, or between a legacy non-WSPC compliant source submission and an RTM target submission. To make this submission WSPC-compliant, please ensure the missing packages are included in the submission. | No action is necessary if this firmware version is not going to be used for a retail update. However, Microsoft recommends that all new firmware submission be WSPC-compliant with the previous baseline. To fix the WSPC compliance issue, ensure the missing package (or empty package as appropriate) is included in the submission. |
| 3 | Request for update | The firmware submission is not WSPC-compliant with the baseline submission {1}. This is because the packages {0} are missing from the new submission. To make this submission WSPC-compliant, please ensure the missing packages are included in the submission. | Since this submission is a baseline, it must be WSPC-compliant with the previous baseline. Ensure the missing package (or empty package as appropriate) is included in the submission. |
| 4 | Firmware submission | To be WSPC-compliant, you cannot remove a package. The following packages were removed '{0}'. | Ensure the missing package (or empty package as appropriate) is included in the submission to be WSP-compliant. |
| 5 | Firmware submission | Using a cached package list for validation because a connection to the server cannot be established. '{0}' | Ensure the Image Validation tool or Windows Phone Ingestion Client have access to Microsoft’s code signing and publishing systems. |
| 6 | Firmware submission | Could not retrieve the baseline package list while running on the client. A WSPC compliance check cannot be performed. | A check will be performed on the server. If error persists, contact Microsoft. |
| 7 | Firmware submission | Could not retrieve the baseline package list while running on a Windows server. A WSPC compliance check cannot be performed. | Contact Microsoft. |
| 8 | Firmware submission | An exception was thrown while loading a package. {0} : {1} | Contact Microsoft. |
| 9 | Firmware submission | Could not retrieve the firmware version of the submission. | Contact Microsoft. |
| 10 | Firmware submission | There was an incorrect number of baseline submissions returned. Count: {0} | Contact Microsoft. |
| 11 | Firmware submission | No submission results were returned so a cached copy is being used. | Ensure the Image Validation tool or Windows Phone Ingestion Client have access to Microsoft’s code signing and publishing systems. |
| 12 | Firmware submission | The following variant is not WSPC compliant. OEM: {0}, Mobile operator: {1}, OEM device name: {2}. | Ensure the firmware submission is targeting the correct variants. Also check the previous baseline for the offending variant and ensure all packages are present in the new submission. |
| 13 | Firmware submission | Could not get baseline package lists online for validation because connection to server cannot be established. Error: '{0}' | Ensure the Image Validation tool or Windows Phone Ingestion Client have access to Microsoft’s code signing and publishing systems. |
| 14 | Firmware submission | No baseline submission result returned, this must be the first and new baseline submission for this POP. | No baseline submission result returned, this must be the first and new baseline submission for this POP. If first baseline submission, this is the correct behavior. Otherwise ensure the firmware submission is targeting the correct variants. |
| 15 | Firmware submission | Could not retrieve the latest baseline package list through partner service. Client local cache is used instead. | Ensure the Image Validation tool or Windows Phone Ingestion Client have access to Microsoft’s code signing and publishing systems. |