Crash detection and OS reinstall tool.

1 files changed, 265 insertions, 0 deletions

diff --git a/.github/crashdetect/CrashDetectSetupGuide.md b/.github/crashdetect/CrashDetectSetupGuide.md
new file mode 100644
index 00000000..dd04d0fa
--- /dev/null
+++ b/.github/crashdetect/CrashDetectSetupGuide.md
@@ -0,0 +1,265 @@
+# Crash Detect USB Setup Guide: 
+# Automating Crash Detection and OS Reinstall of Target Test Systems
+
+---
+
+## A) Overview
+
+This guide walks through setting up a new bootable WinPE USB drive using:
+
+- A **Host Controller** (to build the USB)
+- A **bootable WinPE USB** (automatic crash detection and OS reinstall)
+- A **target test system**
+
+### High-level flow
+
+1. Download Windows image (ISO)
+2. Install Windows ADK + WinPE add-on
+3. Create bootable WinPE USB
+4. Copy image + scripts to USB
+5. Boot up target system
+6. OPTIONAL: Install OS on new Target System
+
+---
+
+## B) Requirements
+
+### Host Controller
+- Windows 11 25H2
+- Administrator privileges
+- USB drive (>= 64GB recommended)
+- Internet connection
+
+### Target System
+- Windows 11 25H2
+- BIOS boot priority set to **USB boot** and **Secure Boot disabled**
+- Windows System failure recovery set to **"Automatically restart"**
+- Willing to wipe disk (automatic OS reinstall from crash)
+
+---
+
+## C) Download Required Software and Scripts onto the Host Controller
+
+### Windows OS Image (ISO)
+
+- [Download Windows 11 (official)](https://www.microsoft.com/en-us/software-download/windows11)
+- Go to section "Download Windows 11 Disk Image (ISO) for x64 devices".
+- Select the option "Windows 11 (multi-edition ISO for x64 devices)".
+- Click "Confirm" button.
+- Section "Select the product language" should appear.
+- Select your language option. (Ex: "English (United States)")
+- Click "Confirm" button.
+- Section "Download - Windows 11 English" should appear.
+- Click "64-bit Download" button.
+- In File Explorer, go to the location you downloaded the ISO file "Win11_25H2_English_x64_v2.iso" to.
+- Right-click on the ISO file and select "Mount".
+  - If the "Open File - Security Warning" prompt pops up after a minute then click "Open".
+  - (The prompt may be hidden behind other Windows.)
+- Create new folder and subfolder "C:\WinPE_USB\Images".
+- Go to the "%MountDriveLetter%:\sources" folder and copy the **"install.wim"** file to **"C:\WinPE_USB\Images"**.
+  - This is the Windows 11 OS image file that the DISM tool will need to deploy the OS.
+  - This file will be copied over to the USB later after bootable WinPE USB creation.
+- Right-click on the %MountDriveLetter% and select "Eject" to unmount the ISO image.
+
+---
+
+### Windows Assessment and Deployment Kit (Deployment Tools) & Windows PE Add-on
+
+- [Download Windows ADK & WinPE Add-on](https://learn.microsoft.com/en-us/windows-hardware/get-started/adk-install)
+- Go to section "Download the ADK 10.1.26100.2454 (December 2024)".
+- Click on the link "Download the Windows ADK 10.1.26100.2454 (December 2024)" to download the "adksetup.exe" installer.
+- Click on the link "Download the Windows PE add-on for the Windows ADK 10.1.26100.2454 (December 2024)" to download the "adkwinpesetup.exe" installer.
+Install ADK:
+- Double-click on the "adksetup.exe" from the location you downloaded the file to launch the installer.
+- "Specify Location" page, click "Next", to install at default location.
+- "Windows Kits Privacy" page, select your privacy option, click "Next".
+- "License Agreement" page, click "Accept".
+- "Select the features you want to install" page, confirm "Deployment Tools" is checked, then click "Install".
+- If "User Account Control" prompt appears, click "Yes" to begin installation process.
+- "Installing features..." page, wait for installation process to complete.
+- "Welcome to the Windows Assessment and Deployment Kit!" page, click "Close".
+Install WinPE Add-on: **Important:** Install **ADK first**, then WinPE add-on
+- Double-click on the "adkwinpesetup.exe" from the location you downloaded the file to launch the installer.
+- "Specify Location" page, click "Next", to install at default location.
+- "Windows Kits Privacy" page, select your privacy option, click "Next".
+- "License Agreement" page, click "Accept".
+- "Select the features you want to install" page, confirm "Windows Preinstallation Environment (Windows PE)" is checked, then click "Install".
+- If "User Account Control" prompt appears, click "Yes" to begin installation process.
+- "Installing features..." page, wait for installation process to complete.
+- "Welcome to the Windows Assessment and Deployment Kit Windows Preinstallation Environment Add-ons!" page, click "Close".
+
+---
+
+### Unattend and Script Files from GitHub
+- [Windows-driver-samples/tree/main/.github/crashdetect](https://github.com/microsoft/Windows-driver-samples/tree/main/.github/crashdetect)
+- Create directory **"C:\WinPE_USB\Scripts\"** and copy the downloaded files here.
+  - CrashDetectCreateUsb.cmd
+  - CrashDetectOsReinstall.cmd
+  - Unattend.xml
+
+---
+
+## D) Create Bootable WinPE USB
+
+- [Create bootable Windows PE media](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-create-usb-bootable-drive)
+- **TIP:** It's a good idea to make a backup copy of the original **"winpe.wim"** image file before editing it in the following steps.
+- Plug a USB into the Host Controller.
+
+- Confirm the folder **"C:\WinPE_USB"** and its subfolders **"Scripts"** and **"Images"** exist.
+- Confirm the "Scripts" subfolder contains the following files that were downloaded from previous steps.
+```
+      CrashDetectOsReinstall.cmd
+      Unattend.xml
+```
+- Confirm the "Images" subfolder contains the Win11 OS image file.
+```
+      install.wim
+```
+
+### OPTION 1: Use the "CrashDetectCreateUsb.cmd" script to create the USB automatically.
+
+- Start a "Command Prompt" running as administrator.
+- Run the script by typing the following line into the Command Prompt.
+```
+      "C:\WinPE_USB\Scripts\CrashDetectCreateUsb.cmd"
+```
+- The script will display a list of detected disk drives, usually Disk 0 is the OS disk, do not select that disk.
+- Prompt 1: will ask you to enter the Disk number of your USB drive.
+- Prompt 2: will confirm one last time before wiping out the USB drive.
+- The last step will copy over the "install.wim" OS image to the USB, which could take a while.
+
+### OPTION 2: Follow the steps below to create the USB manually.
+
+#### 1. Make sure your PC has the ADK and ADK Windows PE add-on installed.
+  - Start the "Deployment and Imaging Tools Environment" running as administrator.
+
+#### 2. Update the "startnet.cmd" autorun script in the WinPE boot image.
+  - Mount the WinPE boot image (winpe.wim) using DISM.
+```text
+      cd "..\Windows Preinstallation Environment\amd64"
+      md C:\WinPE_amd64\mount
+      Dism /Mount-Image /ImageFile:"en-us\winpe.wim" /index:1 /MountDir:"C:\WinPE_amd64\mount"
+```
+  - Adds the "CrashDetectOsReinstall.cmd" script to the "startnet.cmd" script.
+```text
+      (
+      echo wpeinit
+      echo.
+      echo @echo off
+      echo REM Find USB drive.
+      echo for %%D in (D E F G H I J K L M N O P Q R S T U V W Y Z^) do ^(
+      echo     if exist %%D:Scripts\CrashDetectOsReinstall.cmd ^(
+      echo         call %%D:Scripts\CrashDetectOsReinstall.cmd
+      echo         goto EOF
+      echo     ^)
+      echo ^)
+      ) > "C:\WinPE_amd64\mount\Windows\System32\startnet.cmd"
+```
+  - Unmount the WinPE image using DISM.
+```text
+      Dism /Unmount-Image /MountDir:"C:\WinPE_amd64\mount" /commit
+```
+  - Delete folder "C:\WinPE_amd64", else the next step below will fail to copy PE files.
+```text
+      rmdir /s /q "C:\WinPE_amd64"
+```
+
+#### 3. Create and format a multiple partition USB drive. 
+  - [Create a multiple partition USB drive](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe--use-a-single-usb-key-for-winpe-and-a-wim-file---wim#option-1-create-a-multiple-partition-usb-drive)
+  - Attach a USB large enough for 2GB WinPE partition + WinUSB partition (Win11 WIM 8GB + Memory dump files 16GB-64GB + Scripts).
+  - Follow instructions for Option 1 on the following website to partition and format your USB drive.
+```txt
+      diskpart
+      list disk
+      select disk X    (where X is your USB drive)
+      clean
+      create partition primary size=2048
+      active
+      format fs=FAT32 quick label="WinPE"
+      assign letter=P
+      create partition primary
+      format fs=NTFS quick label="WinUSB"
+      assign letter=U
+      exit
+```
+
+#### 4. Create a bootable Windows PE USB drive.
+  - Copying WinPE boot files to a working directory.
+```txt
+      copype amd64 C:\WinPE_amd64
+```
+  - Copy the WinPE files to the WinPE partition on USB.
+```txt
+      MakeWinPEMedia /UFD C:\WinPE_amd64 P: /bootex
+```
+
+---
+
+#### 5. Copy scripts and OS install image over to WinUSB partition on USB. 
+
+  - Copy Script files over to USB.
+```txt
+      xcopy "C:\WinPE_USB\Scripts\" "U:\Scripts\" /e /i
+```
+  - Copy Windows 11 OS WIM file over to USB, this could take a while...
+```txt
+      xcopy "C:\WinPE_USB\Images\install.wim" "U:\Images\" /i
+```
+
+---
+
+## E) Boot Up Target System
+
+- Insert USB into target PC  
+- Power on  
+- Enter boot menu (F12 / ESC / DEL depending on vendor)  
+- Confirm BIOS/UEFI setting has USB Drive as the first boot priority. (Varies among vendors)
+- Confirm Secure Boot setting is Disabled  
+- Save BIOS settings to reboot target system.
+- WinPE will automatically launch the "startnet.cmd" script we edited earlier in the "winpe.wim" image.
+- The script will call "wpeinit", then our "CrashDetectOsReinstall.cmd" script to begin automatic OS crash detection and reimage for WDK driver testing.
+
+---
+
+## F). OPTIONAL: Install OS on new Target System
+### - On the bootable USB's second partition "WinPE_USB"
+- Create the folder **"Logs"**.
+- Create an empty file **"InstallOs.flg"** in that folder.
+  - (In File Explorer, ensure file name extensions are visible, else the filename may be accidentally set to "InstallOs.flg.txt")
+- Plug USB into target system and reboot into USB.
+- The USB will detect the flag and begin reinstalling the OS immediately.
+  - **WARNING**: There will be **NO** prompt to reconfirm OS install, be sure to plug into the correct target system.
+  - Do **NOT** leave this USB plugged into the Host Controller when this flag is set, to avoid accidental OS reinstall.
+
+---
+
+## Troubleshooting
+
+### USB won't boot
+- Check BIOS boot order  
+- Disable Secure Boot if needed  
+
+### Disk not visible in WinPE
+- Missing storage drivers  
+
+### Windows doesn't boot
+- Re-run `bcdboot`  
+- Verify partition layout  
+
+---
+
+## Reference Documentation
+
+- [WinPE: Create bootable media](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-create-usb-bootable-drive)
+- [WinPE overview](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-intro)
+- [Capture and apply Windows (WIM)](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/capture-and-apply-windows-using-a-single-wim)
+
+---
+
+## Summary
+
+This setup uses:
+
+- **ADK + WinPE** -> build bootable environment  
+- **ISO** -> get Windows image  
+- **DISM + BCDBoot** -> deploy OS