Instructions for debugging recent macos kernel versions?

Is there any recent and a bit authoritative documentation which explains how to debug recent versions of macos kernel?

No, nothing for arm* that's directly published by Apple. However, I'm told by an engineer on the kernel team that the arm install instructions here "work":

https://kernelshaman.blogspot.com/2021/02/building-xnu-for-macos-112-intel-apple.html

*The process for Intel hasn't really changed.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

However, I'm told by an engineer on the kernel team that the arm install instructions here "work":

https://kernelshaman.blogspot.com/2021/02/building-xnu-for-macos-112-intel-apple.html

Thank you Kevin, I'll give that a try in the coming days. As for x64 vs arm, I am interested in arm since that's what I have access to.

Short update - the linked article did help me successfully build a kext collection for the kernel on my local M2 system. I had to do minor adjustments to the instructions in that article to get it working.

I have been trying to boot my M2 using this kext collection (after "kmutil configure-boot ..." successfully completed), but so far that step hasn't worked. Every time the system tries to boot with this custom built kext collection (in Permissive mode), the Apple icon shows up for a few seconds and then system shutdown and then again the Apple icon shows up and this keeps continuing. I switched back to "Restrictive mode" to allow me to boot the regular kernel, but I'll experiment some more and see how I can debug/investigate what's preventing a successful boot - it's going to be challenging because I can't seem to locate any logs for this part of the boot process.

I have been trying to boot my M2 using this kext collection (after "kmutil configure-boot ..." successfully completed), but so far that step hasn't worked. Every time the system tries to boot with this custom built kext collection (in Permissive mode), the Apple icon shows up for a few seconds and then system shutdown and then again the Apple icon shows up and this keeps continuing.

One quick point here- make sure you're using EXACTLY the correct KDK version and development kernel version. Running "unname -a" on your working system will get you the right T* kernel variant.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Hello Kevin,

"uname -v" on my local system shows:

Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:30 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6020

so I've been using T6020 as the "platform" when building the kernel.

The corresponding xnu source is this tag https://github.com/apple-oss-distributions/xnu/tree/xnu-11417.140.69 and the KDK is KDK_15.6_24G84.kdk. sw_vers shows me:

sw_vers
ProductName:		macOS
ProductVersion:		15.6
BuildVersion:		24G84

So I think that's the right KDK version for this system.

I'm guessing the XCode version doesn't matter for these experiments (as long as the build succeeds), but for the record, I'm on XCode 16.4:

xcodebuild -version
Xcode 16.4
Build version 16F6

Apart from the other build instructions, the primary one I use to generate a "DEVELOPMENT" variant of the kernel is:

export KDK=/Library/Developer/KDKs/KDK_15.6_24G84.kdk
make SDKROOT=macosx KDKROOT=$KDK BUILD_WERROR=0 BUILD_JSON_COMPILATION_DATABASE=1 TARGET_CONFIGS="DEVELOPMENT ARM64 T6020"

and then to generate a (bootable) kext collection for this kernel, I use (this command is similar to what's noted in the linked article):

kmutil create \
        --arch arm64e \
        --no-authorization \
        --variant-suffix development \
        --new boot \
        --boot-path /Users/me/xnu-11417.140.69/dist/macos-15.6-development.kc \
        --kernel /Users/me/xnu-11417.140.69/dist/kernel.development.T6020 \
        --repository $KDK/System/Library/Extensions \
        --repository /System/Library/Extensions \
        --repository /System/Library/DriverExtensions \
        --explicit-only $(kmutil inspect -V release --no-header | grep -v "SEPHiber" | awk '{print " -b "$1; }')

This generates the kext collection at /Users/me/xnu-11417.140.69/dist/macos-15.6-development.kc.development and the following command against that kext collection file seems to suggest all looks OK:

file  /Users/me/xnu-11417.140.69/dist/macos-15.6-development.kc.development

/Users/me/xnu-11417.140.69/dist/macos-15.6-development.kc.development: Mach-O 64-bit arm64e

All this goes fine, so does running the following command in recovery mode:

kmutil configure-boot --volume "/Volumes/Macintosh HD" --custom-boot-object "/Volumes/Macintosh HD/Users/me/xnu-11417.140.69/dist/macos-15.6-development.kc.development"

(along with "nvram boot-args='-v wlan.skywalk.enable=0 dk=0'")

Yet, when I restart with that configured custom boot object, the Apple icon keep repeating and the system keeps restarting. I haven't done any changes to the kernel code itself, so I can rule out any custom code contributing to this.

My next plan is to build the RELEASE variant of this kernel and see if that boots fine instead of the DEVELOPMENT variant. If not, I'll read up a bit to understand how to track down the boot issue. Thank you very much for the helpful hints so far.

so I've been using T6020 as the "platform" when building the kernel.

OK, so this is the part I haven't explained as well as I should. You don't actually need to build the kernel, as you already have a development build of the kernel in the KDK. That's what "kernel.development.t6020" and "kernel.kasan.t6020" installed by the KDK in /System/Library/Kernels "are".

You should be able to "jump" straight to here:

and then to generate a (bootable) kext collection for this kernel, I use (this command is similar to what's noted in the linked article):

...and continue from that point.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

OK, so this is the part I haven't explained as well as I should. You don't actually need to build the kernel, as you already have a development build of the kernel in the KDK. That's what "kernel.development.t6020" and "kernel.kasan.t6020" installed by the KDK in /System/Library/Kernels "are"

That was it - I built a kext collection using this pre-shipped kernels in the KDK and I was then able to boot this "custom" kext collection without any issues. I used the kernel.development variant for my test. Upon boot I even verified that it was indeed using the development variant of the kernel:

$> sysctl kern.osbuildconfig
kern.osbuildconfig: development

Thank you very much Kevin for this very valuable help.

I have several other things to read and try out (including hopefully building a trivially modified kernel version from xnu sources and booting it), but this initial step had blocked me for several months to even think of these additional experiments.

For now, I will just write up these steps and share here. Thank you again.

That was it - I built a kext collection using these pre-shipped kernels in the KDK and I was then able to boot this "custom" kext collection without any issues. I used the kernel.development variant for my test. Upon boot, I even verified that it was indeed using the development variant of the kernel:

Fabulous!

(including hopefully building a trivially modified kernel version from xnu sources and booting it)

It's been a very long time since I've done this, but the main thing I remember is that you need to be very careful to ensure that you've exactly matched up versions so that "everything" is the same exact version (kernel source, KDK, developer tools, etc.). The problem isn't so much that it MUST be the same, it's that there are so many details and "every" failure basically looks the same ("it doesn't boot!"). That makes it really easy to waste a ton of time trying to hunt down small "problems" that are basically just noise.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

For now, I will just write up these steps and share here.

For future reference, I've now written it up here https://jaitechwriteups.blogspot.com/2025/10/boot-custom-macos-kernel-on-macos-apple.html

It's been a very long time since I've done this, but the main thing I remember is that you need to be very careful to ensure that you've exactly matched up versions so that "everything" is the same exact version (kernel source, KDK, developer tools, etc.).

Thank you Kevin for that hint. I suspected it wouldn't be straightforward. It's still on my TODO list to experiment with that and hopefully get it to work in the coming weeks. If it does, then it will help in a big way in debugging (and reporting) some of the issues we have been running into recently.