{"id":23047244,"url":"https://github.com/woa-project/img2ffu","last_synced_at":"2025-06-11T09:10:01.208Z","repository":{"id":80256607,"uuid":"171906266","full_name":"WOA-Project/img2ffu","owner":"WOA-Project","description":"Converts raw image (img) files into full flash update (FFU) files","archived":false,"fork":false,"pushed_at":"2024-11-01T15:13:38.000Z","size":10175,"stargazers_count":43,"open_issues_count":0,"forks_count":14,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-01T16:19:32.159Z","etag":null,"topics":["dd","ffu","imaging","img","iot","phone","servicing","windows"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WOA-Project.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-21T16:27:04.000Z","updated_at":"2024-11-01T15:13:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"41a0c2e9-699f-4012-99ff-801da5b7f33a","html_url":"https://github.com/WOA-Project/img2ffu","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WOA-Project%2Fimg2ffu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WOA-Project%2Fimg2ffu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WOA-Project%2Fimg2ffu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WOA-Project%2Fimg2ffu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WOA-Project","download_url":"https://codeload.github.com/WOA-Project/img2ffu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229885889,"owners_count":18139380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dd","ffu","imaging","img","iot","phone","servicing","windows"],"created_at":"2024-12-15T22:32:11.545Z","updated_at":"2024-12-15T22:32:14.647Z","avatar_url":"https://github.com/WOA-Project.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# img2ffu\n\nConverts raw image (img) files into full flash update (FFU) files.\n\n## Description\n\nThis tool converts a raw image dump of a Windows Phone device or any GPT image dump to a Full Flash Update (FFU) file, compatible with the v1 format and ready to be flashed on unlocked devices. FFU being built using this tool are optimized to save both space and flashing time.\n\nDuring the making of the FFU image, some partitions will get ignored. Those partitions are typically not flashed during a FFU flash and should never be flashed. You should not attempt to disable this safety measure.\nTo be safe, it is recommended you check manually if the ignored partitions aren't present in the final FFU image, to make sure you're not going to brick your device, or cause irrecoverable damage to your device.\n\nThe tool is able to work directly on a img file, or directly on a device eMMC. Please refer to the tool help for more information.\n\nThis tool also adds support for making v2 format FFU files, as well as parsing v1, v2 and v1 with compression ffu files.\n\nYou can see a few projects listed below making use of img2ffu library to parse FFU files:\n\n- [ffu2vhdx](https://github.com/gus33000/ffu2vhdx)\n- [MobilePackageGen](https://github.com/gus33000/MobilePackageGen)\n- [UnifiedFlashingPlatform](https://github.com/WOA-Project/UnifiedFlashingPlatform)\n\n## Flashing guide\n\nPlease always make a full device backup before attempting to flash any FFU. I recommend to use Win32DiskImager, to select one of the drive letters of your device, and back it up.\n\n\u003e [!IMPORTANT]\n\u003e Win32DiskImager has no concept of partitions, it will backup and write the entire eMMC. You cannot restore just one partition using this tool, and it is recommended you do not attempt to flash in mass storage mode on devices!\n\nFor factory unlocked devices, you can always flash the FFU file without any problem.\nFor retail devices, you must unlock your device UEFI using WPinternals.\n\nYou can then flash the FFU file you made with any tool you're familiar with.\n\n## Samples\n\n### Generating a FFU file for a Surface Duo (1st Gen) 128GB device containing only LUN0\n\n```batch\nimg2ffu.exe ^\n  --ffu-file \".\\OEMEP_128GB_HalfSplit.ffu\" ^\n  --block-size 16384 ^\n  --sector-size 4096 ^\n  --plat-id \"Microsoft Corporation.Surface.Surface Duo.1930\" ^\n  --plat-id \"OEMB1.*.OEMB1 Product.*\" ^\n  --plat-id \"OEMEP.*.OEMEP Product.*\" ^\n  --os-version 10.0.22621.1 ^\n  --full-flash-update-version V2 ^\n  --img-file \".\\LUN0.vhdx\" ^\n  --device-path VenHw(860845C1-BE09-4355-8BC1-30D64FF8E63A) ^\n  --is-fixed-disk-length false ^\n  --blanksectorbuffer-size 4000 ^\n  --excluded-file .\\provisioning-partitions.txt\n```\n\n### Generating a FFU file for a Lumia 950 XL\n\n```batch\nimg2ffu.exe ^\n  --ffu-file \".\\RM-1085_Flash.ffu\" ^\n  --block-size 131072 ^\n  --sector-size 512 ^\n  --plat-id \"Microsoft.MSM8994.P6211\" ^\n  --os-version 10.0.10586.512 ^\n  --full-flash-update-version V1 ^\n  --img-file \".\\eMMC-User.vhdx\" ^\n  --device-path VenHw(B615F1F5-5088-43CD-809C-A16E52487D00) ^\n  --is-fixed-disk-length false ^\n  --blanksectorbuffer-size 100 ^\n  --excluded-file .\\provisioning-partitions.txt\n```\n\n## Command Line Help\n\n```\nImg2Ffu 1.0.0+f19d28e6878697712b4a2195ab447abfda5935e8\nCopyright (C) 2024 Img2Ffu\n\nERROR(S):\n  Required option 'f, ffu-file' is missing.\n  Required option 'p, plat-id' is missing.\n\n  -f, --ffu-file                     Required. A path to the FFU file to output\n\n  -p, --plat-id                      Required. Platform ID to use\n\n  -a, --anti-theft-version           (Default: 1.1) Anti theft version.\n\n  -o, --os-version                   (Default: 10.0.11111.0) Operating system version.\n\n  -c, --block-size                   (Default: 131072) Block size to use for the FFU file\n\n  -s, --sector-size                  (Default: 512) Sector size to use for the FFU file\n\n  -v, --full-flash-update-version    (Default: V1) Version of the FFU file format to use, can be either V1 or V2\n\n  -i, --img-file                     (Group: StoreInputOptions) A path to the img file to convert *OR* a PhysicalDisk\n                                     path. i.e. \\\\.\\PhysicalDrive1\n\n  -d, --device-path                  (Group: StoreInputOptions) (Default: VenHw(B615F1F5-5088-43CD-809C-A16E52487D00))\n                                     The UEFI device path to write the store onto when flashing.\n\n  -l, --is-fixed-disk-length         (Group: StoreInputOptions) (Default: True) Specifies the disk in question is fixed\n                                     and cannot have a different size on the end user target device. Means every data\n                                     part of this disk is required for correct device firmware operation and must not be\n                                     half flashed before a valid GPT is available on disk.\n\n  -b, --blanksectorbuffer-size       (Group: StoreInputOptions) (Default: 100) Buffer size for the upper maximum allowed\n                                     limit of blank sectors\n\n  -e, --excluded-file                (Group: StoreInputOptions) (Default: .\\provisioning-partitions.txt) A path to the\n                                     file with all partitions to exclude\n\n  --help                             Display this help screen.\n\n  --version                          Display version information.\n\nTIP(S):\n\n  When specifying multiple stores, you must specify an instance of:\n\n  img2ffu\n    --img-file XXX\n    --device-path XXX\n    --is-fixed-disk-length XXX\n    --blanksectorbuffer-size XXX\n    --excluded-file XXX\n\n  per store you want to use, in a row, and in order.\n\n  For example, to generate a FFU file that contains two stores,\n  one writing to an UFS LUN0,\n  and the other to an UFS LUN1,\n  the following should be specified:\n\n  img2ffu\n    --img-file D:\\MyCopyOfUFSLun0.vhdx\n    --device-path VenHw(860845C1-BE09-4355-8BC1-30D64FF8E63A)\n    --is-fixed-disk-length false\n    --blanksectorbuffer-size 100\n    --excluded-file .\\provisioning-partitions.txt\n\n    --img-file D:\\MyCopyOfUFSLun1.vhdx\n    --device-path VenHw(8D90D477-39A3-4A38-AB9E-586FF69ED051)\n    --is-fixed-disk-length true\n    --blanksectorbuffer-size 100\n    --excluded-file .\\provisioning-partitions.txt\n\n  In this second example, we generate a FFU file with a single store writing to the User LUN of an eMMC:\n\n  img2ffu\n    --img-file D:\\MyCopyOfeMMCUser.img\n    --device-path VenHw(B615F1F5-5088-43CD-809C-A16E52487D00)\n    --is-fixed-disk-length true\n    --blanksectorbuffer-size 100\n    --excluded-file .\\provisioning-partitions.txt\n\n  A non exhaustive list of common Phone Device Paths is given below for convenience purposes.\n  Please note that you can also specify other paths such as PCI paths,\n  they must bind to a real path in the UEFI environment.\n\n    VenHw(B615F1F5-5088-43CD-809C-A16E52487D00): eMMC (User)\n    VenHw(12C55B20-25D3-41C9-8E06-282D94C676AD): eMMC (Boot 1)\n    VenHw(6B76A6DB-0257-48A9-AA99-F6B1655F7B00): eMMC (Boot 2)\n    VenHw(C49551EA-D6BC-4966-9499-871E393133CD): eMMC (RPMB)\n    VenHw(B9251EA5-3462-4807-86C6-8948B1B36163): eMMC (GPP 1)\n    VenHw(24F906CD-EE11-43E1-8427-DC7A36F4C059): eMMC (GPP 2)\n    VenHw(5A5709A9-AC40-4F72-8862-5B0104166E76): eMMC (GPP 3)\n    VenHw(A44E27C9-258E-406E-BF33-77F5F244C487): eMMC (GPP 4)\n    VenHw(D1531D41-3F80-4091-8D0A-541F59236D66): SD Card (Removable)\n    VenHw(860845C1-BE09-4355-8BC1-30D64FF8E63A): UFS (LUN 0)\n    VenHw(8D90D477-39A3-4A38-AB9E-586FF69ED051): UFS (LUN 1)\n    VenHw(EDF85868-87EC-4F77-9CDA-5F10DF2FE601): UFS (LUN 2)\n    VenHw(1AE69024-8AEB-4DF8-BC98-0032DBDF5024): UFS (LUN 3)\n    VenHw(D33F1985-F107-4A85-BE38-68DC7AD32CEA): UFS (LUN 4)\n    VenHw(4BA1D05F-088E-483F-A97E-B19B9CCF59B0): UFS (LUN 5)\n    VenHw(4ACF98F6-26FA-44D2-8132-282F2D19A4C5): UFS (LUN 6)\n    VenHw(8598155F-34DE-415C-8B55-843E3322D36F): UFS (LUN 7)\n    VenHw(5397474E-F75D-44B3-8E57-D9324FCF6FE1): UFS (RPMB)\n\nEXAMPLE(S):\n\n  img2ffu ^\n    --img-file D:\\MyCopyOfUFSLun0.vhdx ^\n    --device-path VenHw(860845C1-BE09-4355-8BC1-30D64FF8E63A) ^\n    --is-fixed-disk-length false ^\n    --blanksectorbuffer-size 100 ^\n    --excluded-file .\\provisioning-partitions.txt ^\n    --img-file D:\\MyCopyOfUFSLun1.vhdx ^\n    --device-path VenHw(8D90D477-39A3-4A38-AB9E-586FF69ED051) ^\n    --is-fixed-disk-length true ^\n    --blanksectorbuffer-size 100 ^\n    --excluded-file .\\provisioning-partitions.txt ^\n    --full-flash-update-version V2 ^\n    --ffu-file D:\\FlashTestingCli.ffu ^\n    --plat-id My.Super.Plat.ID ^\n    --anti-theft-version 1.1 ^\n    --block-size 131072 ^\n    --sector-size 4096 ^\n    --os-version 10.0.22621.0\n\n  This command will create a FFU file named D:\\FlashTestingCli.ffu.\n  This FFU file will target a device with Platform ID My.Super.Plat.ID.\n  This FFU file will contain a disk image with a sector size of 4096 bytes.\n  This FFU file will claim to contain an operating system version of 10.0.22621.0.\n  This FFU file will report Anti Theft Version 1.1 is supported by the contained OS\n  and can be flashed on devices featuring anti theft version 1.1.\n  This FFU file will use FFU version 2.\n\n  This FFU file will contain two stores:\n\n    One store is sourced from a local file named D:\\MyCopyOfUFSLun0.vhdx\n    This store is meant to be written to the UEFI Device VenHw(860845C1-BE09-4355-8BC1-30D64FF8E63A),\n    UFS LUN 0 on a Qualcomm Snapdragon UEFI Platform\n    This store targets a disk which can have a different total size than the input.\n    This store will contain blank blocks up to 100 in a row as part of the data being written to the phone.\n    This store will not include data contained within partitions named in the provisioning-partitions.txt file.\n\n    The second store is sourced from a local file named D:\\MyCopyOfUFSLun1.vhdx\n    This store is meant to be written to the UEFI Device VenHw(8D90D477-39A3-4A38-AB9E-586FF69ED051),\n    UFS LUN 1 on a Qualcomm Snapdragon UEFI Platform\n    This store targets a disk which cannot have a different total size than the input.\n    This store will contain blank blocks up to 100 in a row as part of the data being written to the phone.\n    This store will not include data contained within partitions named in the provisioning-partitions.txt file.\n```\n\n## FFU File Structure\n\nAn outdated documentation detailing some of the V1 and some of the V2 FFU file format is included on page 1145 of [Windows Manufacturing Documentation, 2019](docs/Windows%20Manufacturing%20Documentation%202019.pdf). It however is incomplete and misses on both one version of the format and many details. A lot of the format was reverse engineered from existing FFU files and tooling present in the wild in this tool. Some notes of this work are attached below:\n\n### Revisions\n\n3 major revisions:\n\n- V1 (Used by Windows Phone 8.X, Windows 10 Mobile, IoT Core, early Windows Holographic, Windows Image App tooling (original versions), does not support multiple stores, does not support specifying a target device path to flash onto)\n- V1_COMPRESSION (Same as V1 with added compression support, mainly used by DISM /Capture-FFU)\n- V2 (Support for multiple stores, specific device path targets was added in this format revision)\n\n### Layout\n\n- Validation Descriptor is always of size 0\n- While it is possible in the struct to specify more than one Block for a BlockDataEntry it shall only be equal to 0\n- The hash table contains every hash of every block in the FFU file starting from the Image Header to the end\n- When using V1_COMPRESSION FFU file format, BlockDataEntry contains an extra entry of size 4 bytes\n- Multiple locations for a block data entry only copies the block to multiple places\n\n#### Legend\n\n*: Device Targeting Information is optional\n\n**: Only available on V1_COMPRESSION FFU file formats\n\n***: Only available on V2 FFU file formats\n\n#### Schema\n\n```\n+------------------------------+\n|                              |\n|       Security Header        |\n|                              |\n+------------------------------+\n|                              |\n|      Security Catalog        |\n|                              |\n+------------------------------+\n|                              |\n|         Hash Table           |\n|                              |\n+------------------------------+\n|                              |\n|     (Block Size) Padding     |\n|                              |\n+------------------------------+\n|                              |\n|         Image Header         |\n|                              |\n+------------------------------+\n|              *               |\n|    Image Header Extended     |\n|   DeviceTargetingInfoCount   |\n|                              |\n+------------------------------+\n|                              |\n|        Image Manifest        |\n|                              |\n+------------------------------+\n|              *               |\n|  DeviceTargetInfoLengths[0]  |\n|                              |\n+------------------------------+\n|              *               |\n|  DeviceTargetInfoStrings[0]  |\n|                              |\n+------------------------------+\n|              *               |\n|            . . .             |\n|                              |\n+------------------------------+\n|              *               |\n|  DeviceTargetInfoLengths[n]  |\n|                              |\n+------------------------------+\n|              *               |\n|  DeviceTargetInfoStrings[n]  |\n|                              |\n+------------------------------+\n|                              |\n|     (Block Size) Padding     |\n|                              |\n+------------------------------+\n|                              |\n|        Store Header[0]       |\n|                              |\n+------------------------------+\n|             * *              |\n|      CompressionAlgo[0]      |\n|                              |\n+------------------------------+\n|            * * *             |\n|      Store Header Ex[0]      |\n|                              |\n+------------------------------+\n|                              |\n|   Validation Descriptor[0]   |\n|                              |\n+------------------------------+\n|                              |\n|     Write Descriptors[0]     |\n|(BlockDataEntry+DiskLocations)|\n+------------------------------+\n|                              |\n|   (Block Size) Padding[0]    |\n|                              |\n+------------------------------+\n|            * * *             |\n|            . . .             |\n|                              |\n+------------------------------+\n|            * * *             |\n|        Store Header[n]       |\n|                              |\n+------------------------------+\n|            * * *             |\n|      Store Header Ex[n]      |\n|                              |\n+------------------------------+\n|            * * *             |\n|   Validation Descriptor[n]   |\n|                              |\n+------------------------------+\n|            * * *             |\n|     Write Descriptors[n]     |\n|(BlockDataEntry+DiskLocations)|\n+------------------------------+\n|            * * *             |\n|   (Block Size) Padding[n]    |\n|                              |\n+------------------------------+\n|                              |\n|         Data Blocks          |\n|                              |\n+------------------------------+\n```\n\n## Copyright\n\nCopyright (c) 2019-2024, Gustave Monce - gus33000.me - @gus33000\n\n*Portions from:*\nCopyright (c) 2018, Rene Lergner - wpinternals.net - @Heathcliff74xda\n\nThis software is released under the MIT license, for more information please see [LICENSE.md](./license.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoa-project%2Fimg2ffu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwoa-project%2Fimg2ffu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwoa-project%2Fimg2ffu/lists"}