Skip to content
Proton Kernel for the Windows Subsystem for Linux 2 (WSL 2). Highly experimental and always at the mercy of Windows Update.
C C++ Assembly Objective-C Makefile Shell Other
Branch: v4.19-proton
Clone or download
kdrag0n Merge tag 'v4.19.64' into v4.19-proton
This is the 4.19.64 stable release
Latest commit 54a3e83 Aug 4, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.drone drone: Add Drone CI pipeline Jul 4, 2019
Documentation dt-bindings: allow up to four clocks for orion-mdio Jul 26, 2019
LICENSES
arch Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
block block, scsi: Change the preempt-only flag into a counter Aug 4, 2019
certs export.h: remove VMLINUX_SYMBOL() and VMLINUX_SYMBOL_STR() Aug 22, 2018
crypto crypto: chacha20poly1305 - fix atomic sleep when using async algorithm Jul 26, 2019
drivers Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
firmware kbuild: remove all dummy assignments to obj- Nov 18, 2017
fs Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
include Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
init Revert "ZEN: Add a CONFIG option that sets -O3" Jul 23, 2019
ipc ipc: prevent lockup on alloc_msg and free_msg Jun 15, 2019
kernel Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
lib Merge remote-tracking branch 'msft/master' into v4.19-proton Jul 27, 2019
mm Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
net Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
samples samples, bpf: suppress compiler warning Jul 14, 2019
scripts Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
security selinux: fix empty write to keycreate file Jul 26, 2019
sound ALSA: hda - Add a conexant codec entry to let mute led work Jul 31, 2019
tools Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
usr initramfs: move gen_initramfs_list.sh from scripts/ to usr/ Aug 22, 2018
virt KVM: arm/arm64: vgic: Fix kvm_device leak in vgic_its_destroy Jul 14, 2019
.clang-format clang-format: Set IndentWrappedFunctionNames false Aug 1, 2018
.cocciconfig scripts: add Linux .cocciconfig for coccinelle Jul 22, 2016
.get_maintainer.ignore Add hch to .get_maintainer.ignore Aug 21, 2015
.gitattributes .gitattributes: set git diff driver for C source code files Oct 8, 2016
.gitignore Import kernel build and helper scripts Jul 1, 2019
.mailmap Merge tag 'libnvdimm-for-4.19_misc' of gitolite.kernel.org:pub/scm/li… Aug 26, 2018
COPYING COPYING: use the new text with points to the license files Mar 23, 2018
CREDITS 9p: remove Ron Minnich from MAINTAINERS Aug 17, 2018
Kbuild Merge tag 'kbuild-v4.15' of git://git.kernel.org/pub/scm/linux/kernel… Nov 18, 2017
Kconfig
MAINTAINERS arm64: hyperv: Add support for Hyper-V as a hypervisor Jul 21, 2019
Makefile Merge tag 'v4.19.64' into v4.19-proton Aug 4, 2019
README.md README: Replace with comprehensive WSL 2 + Proton Kernel guide Jul 1, 2019
helpers.sh Import kernel build and helper scripts Jul 1, 2019
setup.sh Import kernel build and helper scripts Jul 1, 2019
setup_clang.sh setup_clang: Fix script and switch to Proton Clang 10 toolchain Jul 27, 2019

README.md

Proton Kernel for WSL 2

Proton Kernel is a custom modified Linux kernel for the Windows Subsystem for Linux 2, using a clean import of Microsoft's kernel changes as a base. The goal is to improve performance, memory utilization, and power efficiency while reducing boot times and making other improvements to the overall user experience.

Motivation

Microsoft did a relatively good job on their minimal set of changes to the Linux kernel in WSL 2, but there is always room for improvement. For example, one can compile the kernel with a newer version of GCC (Microsoft used a custom build of GCC 7.3.0) or even Clang. This can offer small performance improvements and help debug certain parts of both the kernel and the compiler.

Proton Kernel aims to improve upon Microsoft's kernel in every aspect and thus improve the overall WSL 2 user experience.

Compilation

  1. Install a recent Linux distribution

    • Any install will work — WSL 1, WSL 2, VirtualBox, bare-metal, etc.
  2. Install GCC or Clang, essential development packages, flex, bison, OpenSSL + headers, libelf + headers

    • Example command for Ubuntu: apt install build-essential flex bison libssl-dev libelf-dev
  3. Load the Proton Kernel helpers (optional)

    • Note that this requires a Bourne-compatible shell, such as bash or zsh
    • Command: source setup.sh for GCC or source setup_clang.sh for Clang
    • These helpers are solely to simplify the building and testing process and are not mandatory by any means
    • Parallel Kbuild job count can be adjusted in the setup scripts
      • The optimal value for build times is usually the number of logical CPU cores present on your system
      • Sometimes increasing or decreasing this number helps reduce build time further
  4. Select the WSL 2 kernel configuration

    • Using the Proton helpers: mc
    • Using plain Kbuild: make wsl2_defconfig
  5. Start the kernel build

    • Using the Proton helpers: kmake
    • Using plain Kbuild: make
      • If you have multiple CPU cores, you can pass a -jX argument (where X is the number of logical CPU cores present on your system) to speed up the build by parallelizing the process
      • Sometimes increasing or decreasing this number helps reduce build time further

Assuming there were no errors and everything worked as intended, you will find the new kernel at the following location:

  • Using Proton helpers: out/arch/x86/boot/compressed/vmlinux.bin
  • Using plain Kbuild: arch/x86/boot/compressed/vmlinux.bin

If not, double-check each command to make sure you did everything correctly. You can open an issue if you need help resolving a build error.

Installation

BE SURE TO MAKE A BACKUP OF THE OFFICIAL KERNEL PRIOR TO REPLACEMENT! Otherwise, you will be unable to revert if your custom kernel fails to boot or malfunctions.

Warning: Having any unofficial kernel installed currently breaks distribution installation and conversion for unknown reasons and causes the process to lock up. A temporary workaround is to use the official kernel for the aforementioned tasks, then revert back to your custom kernel afterwards.

The kernel is located at C:\Windows\System32\lxss\tools\kernel in Windows.

Preparation

When you first replace the WSL 2 kernel on your system, you will need to grant yourself the permissions necessary to replace the file. This requires administrator access.

  1. Assign ownership of the kernel file to the Administrators group

    • This is easy to do in Windows Explorer:
      • Right-click the file and click Properties
      • Switch to the Security tab
      • Click the Advanced button
      • Click the blue Change button next to Owner
      • Enter Administrators for the object name
      • Click OK to close the advanced security window and reload permissions
  2. Grant Full Control of the file to Administrators and yourself

    • Again, this is trivial in Windows Explorer:
      • Return to the advanced security management window
      • Click the Change permissions button
      • Double-click Administrators in the list of permission entries and check the Full Control box
      • Dismiss the entry control dialog
      • Click the Add button to add a new permission entry
      • Click the blue Select principal button at the top and enter your username at the object name prompt
      • Check the Full Control box
      • Dismiss the entry control dialog

After taking ownership and acquiring critical permissions, you may proceed to the kernel replacement steps listed below. These preparatory steps may need to be repeated after each Windows update.

Kernel replacement

Automatic (for users of the Proton Kernel helpers)

  • Run the desired command(s) from the list below:
    • Copy the product to kernel.bin: cpimg
    • Build and copy: incbuild
    • Build, copy, and test: inc
    • Test: ktest

Note that ktest looks for kernel.bin for ease of management, not the build product (out/arch/x86/boot/compressed/vmlinux.bin). This means that you will need to either use incbuild to build or run cpimg after each build to copy the new kernel to kernel.bin.

Manual

  1. Shut down the WSL 2 distros and utility VM from Windows

    • Command: wsl --shutdown
  2. Rename the new kernel (vmlinux.bin) to kernel

  3. Copy the new kernel to C:\Windows\System32\lxss\tools and choose to overwrite the existing file named kernel

Be sure to copy and overwrite the kernel. Doing otherwise (moving, deleting and recreating, etc.) will invalidate the hard link in WinSxS, which may cause issues when updating or repairing the system in the future. You have been warned.

Helpers

The Proton Kernel helper scripts provide a handy set of helpers that enhance the overall kernel development and deployment experience. You can use them in a Bourne-compatible shell by sourceing one of the compiler-specific setup scripts — source setup.sh for GCC and source setup_clang.sh for Clang. If you don't want to use one of those scripts, you can also directly run source helpers.sh. However, this setup is not supported nor encouraged and may break at any time.

Keep in mind that you must source the scripts instead of executing them. Nothing will happen if you execute them because they simply define variables and functions for interactive use. They are not build scripts. The execute bit is missing on them for this very reason.

Functions

  • croot: cd to the root of the kernel tree, where the helper scripts are
  • cpimg: Copy the product to the specified path, defaulting to kernel.bin
    • dimg: Copy the product to builds with a file name tailored for development/test releases
      • timg: Run dimg, then upload the resulting file to transfer.sh
  • kmake: A wrapper for make that passes the defined kernel-oriented arguments
    • cleanbuild: Perform a clean build and run cpimg
    • incbuild: Perform an incremental build and run cpimg
    • dbuild: Perform an incremental build and run dimg
      • tbuild: Perform an incremental build and run timg
  • rel: Build and copy the product to builds with a file name and version tailored for stable releases
    • crel: Clean the built object files and run rel
  • ktest: Install kernel.bin using an auto-selected method (wktest for WSL 1 and WSL 2, vktest for other environments)
    • wktest: Install kernel.bin locally from either WSL 1 or WSL 2
    • vktest: Install kernel.bin into WSL 2 in the Windows VM running on a bare-metal Linux host (using the winvm SSH host)
  • inc: Perform an incremental build and install the product using an auto-selected method (wktest for WSL 1 and WSL 2, vktest for other environments)
    • winc: Perform an incremental build and install the product locally from either WSL 1 or WSL 2
    • vinc: Perform an incremental build and install the product into WSL 2 in the Windows VM running on a bare-metal Linux host (using the winvm SSH host)
  • dc: diff the current config with wsl2_defconfig
  • cpc: Update wsl2_defconfig with the current config
  • mc: Reset the current config to wsl2_defconfig
  • cf: Start an interactive config editor with a TUI (nconfig)
  • ec: Open the raw current config in a text editor
  • buildnum: Get the current build number
  • zerover: Reset the build number to 0
  • zver: Get the version string from an uncompressed kernel image
  • osize: Get a sorted list of the sizes of various objects compiled and linked into the final kernel image
  • glink: Get a link to the provided commit hash in this repository on GitHub

All building helpers will propagate the arguments passed to them to make.

You can’t perform that action at this time.