Bug 1774674 - Flesh out the documentation for getting Instruments to pick up macOS kernel symbols. r=jrmuizel

Differential Revision: https://phabricator.services.mozilla.com/D149561

docs/performance/profiling_with_instruments.md

@@ -48,14 +48,58 @@ also need the fix to [Bug
 719427](https://bugzilla.mozilla.org/show_bug.cgi?id=719427 "https://bugzilla.mozilla.org/show_bug.cgi?id=719427")
 
 ## Kernel stacks
+
 Under "File" -> "Recording Options" you can enable "Record Kernel Callstacks".
 To get full symbols and not just the exported ones, you'll to install the matching
 [Kernel Debug Kit](https://developer.apple.com/download/all/?q=Kernel%20Debug%20Kit).
-Instruments uses Spotlight to find the dSYMs with the matching uuid so if the
-symbols are still not showing up it may help to move the appropriate dSYM file
-to a place where Spotlight will notice it. You can double check the uuid of the
-kernel in `/System/Library/Kernels` with `dwarfdump --uuid` and check that
-Spotlight knows about the file with `mdls`.
+Make sure you install the one whose macOS version exactly matches your version,
+including the identifier at the end (e.g. "12.3.1 (21E258)").
+
+### Allow Instruments to find kernel symbols
+
+Installing the KDK is often not enough for Instruments to find the symbols.
+Instruments uses Spotlight to find the dSYMs with the matching UUID, so you
+need to put the dSYM in a place where Spotlight will index it.
+
+First, check the UUID of your macOS installation's kernel. To do so, run the
+following:
+
+```
+% dwarfdump --uuid /System/Library/Kernels/kernel.release.t6000
+UUID: C342869F-FFB9-3CCE-A5A3-EA711C1E87F6 (arm64e) /System/Library/Kernels/kernel.release.t6000
+```
+
+Then, find the corresponding dSYM file in the KDK that you installed, and
+run `mdls` on it. For example:
+
+```
+% mdls /Library/Developer/KDKs/KDK_12.3.1_21E258.kdk/System/Library/Kernels/kernel.release.t6000.dSYM
+```
+
+(Make sure you use the `.release` variant, not the `.development` variant
+or any of the others.)
+
+If the output from `mdls` contains the string `com_apple_xcode_dsym_uuids`
+and the UUID matches, you're done.
+
+Otherwise, try copying the `kernel.release.t6000.dSYM` bundle to your home
+directory, and then run `mdls` on the copied file. For example:
+
+```
+% cp -r /Library/Developer/KDKs/KDK_12.3.1_21E258.kdk/System/Library/Kernels/kernel.release.t6000.dSYM ~/
+% mdls ~/kernel.release.t6000.dSYM
+_kMDItemDisplayNameWithExtensions      = "kernel.release.t6000.dSYM"
+com_apple_xcode_dsym_paths             = (
+    "Contents/Resources/DWARF/kernel.release.t6000"
+)
+com_apple_xcode_dsym_uuids             = (
+    "C342869F-FFB9-3CCE-A5A3-EA711C1E87F6"
+)
+kMDItemContentCreationDate             = 2022-03-21 15:25:57 +0000
+[...]
+```
+
+Now Instruments should be able to pick up the kernel symbols.
 
 ## Misc