Add a bit more caveat text about MUTEX_PROFILING -- try to avoid using it

with other profiling and debugging options, such as INVARIANTS, WITNESS,
kernel profiling, etc.  They all interfere with each other nastily and
will generate fairly useless results.

1 files changed, 23 insertions, 0 deletions

diff --git a/share/man/man9/MUTEX_PROFILING.9 b/share/man/man9/MUTEX_PROFILING.9
index bbca8ab..7f8baf2 100644
--- a/share/man/man9/MUTEX_PROFILING.9
+++ b/share/man/man9/MUTEX_PROFILING.9
@@ -1,5 +1,6 @@
 .\"-
 .\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav
+.\" Copyright (c) 2005 Robert N. M. Watson
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -158,6 +159,12 @@ option also prevents inlining of the mutex code, which results in a
 fairly severe performance penalty.
 It should therefore only be enabled on systems where mutex profiling
 is actually needed.
+.Dv MUTEX_PROFILING
+will introduce a substantial performance overhead that is easily
+monitorable using other profiling tools, so combining profiling tools
+with
+.Dv MUTEX_PROFILING
+is not recommended.
 .Pp
 Measurements are made and stored in nanoseconds using
 .Xr nanotime 9 ,
@@ -165,3 +172,19 @@ but are presented in microseconds.
 This should still be sufficient for the locks one would be most
 interested in profiling (those that are held long and/or acquired
 often).
+.Pp
+.Dv MUTEX_PROFILING
+should generally not be used in combination with other debugging options, as
+the results may be strongly affected by interactions between the features.
+In particular,
+.Dv MUTEX_PROFILING
+will report higher than normal
+.Xr uma 9
+lock contention when run with
+.Dv INVARIANTS
+due to extra locking that occurs when
+.Dv INVARIANTS
+is present; likewise, using it in combination with
+.Dv WITNESS
+with
+will lead to much higher lock hold times and contention in profiling output.