Darwin doc: describe apple pointer area and Massif woes

diff --git a/docs/internals/Darwin-debug.txt b/docs/internals/Darwin-debug.txt
index 705d6d57de5661de709b6b2b099ed8b895afe8a3..e753961c79309df56cc6f7fad836188571f7eb45 100644 (file)
--- a/docs/internals/Darwin-debug.txt
+++ b/docs/internals/Darwin-debug.txt
@@ -59,4 +59,9 @@ DYLD_SHARED_REGION gets set to "avoid" (but note that for macOS 11
 Big Sur and later "avoid" is no longer an option).
 
 The Darwin callstack is a bit simpler to synthesise than the ones on
-ELF platforms. There is no auxiliary vector (auxv) to construct.
+ELF platforms. There is no auxiliary vector (auxv) to construct. However,
+there is the "apple pointer area". At present we do not pass anything
+that we get from the loader (and this is something of an omission).
+Instead we just synthesise the small number of entries that we need.
+Mostly these values are only used by dyld and for initialising the
+system libs when they load.

diff --git a/docs/internals/Darwin-notes.txt b/docs/internals/Darwin-notes.txt
index 0cedd16981c09bedfa34312f669f9a95a65b6b1e..0eb93fc92146e117e054d98e70de8b53751cb122 100644 (file)
--- a/docs/internals/Darwin-notes.txt
+++ b/docs/internals/Darwin-notes.txt
@@ -71,6 +71,43 @@ means that I don't know which is the oldest version of macOS that
 will build Valgrind (as of December 2025). Somewhere between 10.8 (Darwin 12)
 and 10.12 (Darwin 16).
 
+Massif on Darwin
+~~~~~~~~~~~~~~~~
+
+There is one fundamental difference in the architecture of Darwin
+compared to the other ELF based systems. To start an ELF executable
+ld.so is used. This is a minimalistic binary that just does the
+loading and runtime link-editing of dependent shared libraries.
+Darwin dyld does roughly the same thing except that it triggers
+much more initialisation. Darwin does not have separate libraries
+for the C and C++ standard libraries. Instead it has libSystem.
+That is more like libc and libstdc++ and the Objective-C lib and
+libcrypto and networking libs and about 30 other libs all bundled
+into one. The result is that even before reaching "main()" a
+Darwin guest will have performed vastly more allocations than
+on an ELF system. For comparison, C++ Hello World on FreeBSD
+does one allocation. On Darwin 22 it does 178 allocations. As
+an aside, many of those are not deallocated, which also makes
+a mess of all of the memcheck leak tests.
+
+All this means that the massif tests need very extensive use
+of --ignore-fn for Darwin. There are hundreds of allocations
+and the allocator functions seem to change frequently between
+Darwin versions. For larger allocations, getting the name
+of the allocation function is just a question of looking at
+the failure diff. For small allocations the function may not
+appear in the detailed reports but still cause a diff in
+the allocation totals. In that case consider trying
+- use --threshold=0.0 --detailed-freq=1
+- rerun the test outside of regtest (you can use the
+  .vgtest.log to get the full command line)
+- if all else fails, run with --trace-malloc=yes to try to
+  find out which allocation function (malloc, calloc etc)
+  corresponds to the unaccounted size and then use gdb
+  and put a breakpoint on that allocation function.
+
+DHAT has similar issues but no --ignore-fn option (yet).
+
 
 Valgrind-developer notes, todos re the MacOSX port
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~