docs/internals/Darwin-debug.txt

   1 Some general notes on debugging on macOS
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3 Written early 2023, based on macOS 13.1 / Darwin 22.2.0 Intel
   4
   5 If you need to use ssh then you can't use lldb directly because, by default,
   6 it wants to open a dialog for your password/fingerprint. You can disable this
   7 with:
   8
   9 sudo DevToolsSecurity --enable
  10
  11 Tracing syscalls looks rather scary and involves rebooting and disabling security.
  12
  13 Launcher and initimg
  14 ~~~~~~~~~~~~~~~~~~~~
  15
  16 Things are a bit different on Darwin. Quick reminder for other platforms:
  17
  18 1. Early command line processing, specifically tool and verbosity
  19 2. Select the platform by looking at the ELF headers. Default
  20    to the build platform if the client is a script and the shebangs
  21    don't lead to an ELF binary.
  22 3. Add VALGRIND_LAUNCHER to the environment. This is based on the path.
  23 4. Get the tool path. This uses either the path baked into the build
  24    by the configure --prefix option (VG_LIBDIR) or the VALGRIND_LIB
  25    environment variable (set by the vg-in-place script for running
  26    in the build directory).
  27 5. exec the tool.
  28
  29 On Darwin that is
  30
  31 1. Early command line processing. As above but also the undocumented
  32    --arch option.
  33 2. The client exename can be an app bundle which means expanding
  34    "client" to "client.app/Contents/MacOS/client".
  35 3. Platform detection is complicated by the macOS history of
  36    having dual-platform fat binaries. A list of supported platforms
  37    is considered and compared against the Valgrind install. Then
  38    the mach_header is examined to make the final decision.
  39 4. The additions to the environment variables are also a bit more
  40    complicated. Like on ELF based systems there is VALGRIND_LAUNCHER.
  41    Additionally there is
  42    VALGRIND_STARTUP_PWD_%PID_XYZZY=current_working_dir
  43    which is used to work out the working directory.
  44    Darwin doesn't have a cwd syscall? I wonder how 'pwd' works.
  45    Looks like it does open(.) fstat to check then fcntl(F_GETPATH).
  46    The seems to only matter for %p and %q log filename expansion
  47    and reading any .valgrindrc in the working directory. Not
  48    big problems for debugging.
  49 5. Another slight complication is that dylib environment variables need
  50    protecting. Maybe because the tool is statically linked? In any
  51    case all env vars that start with "DYLD_" get changed to "VYLD_".
  52 6. The tool path is determined along the same lines as ELF.
  53 7. exec the tool.
  54
  55
  56 In stage2 on Darwin the "VYLD_" munging is undone. DYLD_INSERT_LIBRARIES
  57 gets set for core and tool preloads (the equivalent of LD_PRELOAD).
  58 DYLD_SHARED_REGION gets set to "avoid" (but note that for macOS 11
  59 Big Sur and later "avoid" is no longer an option).
  60
  61 The Darwin calstack is a bit simpler to synthesise than the ones on
  62 ELF platforms. There is no auxiliary vector (auxv) to construct.