X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fsb-sprof%2Fsb-sprof.texinfo;h=9f672cf0d0a988d5f5fdf6586ea629d3e8591545;hb=89c9285a01e9ccb247198b77552d48f007d20e06;hp=3031d82889eded89fa21090bf9cd2eb12b0787e4;hpb=8b64d57b865fec6ba082dda965146b5e8aa877b3;p=sbcl.git

diff --git a/contrib/sb-sprof/sb-sprof.texinfo b/contrib/sb-sprof/sb-sprof.texinfo
index 3031d82..9f672cf 100644
--- a/contrib/sb-sprof/sb-sprof.texinfo
+++ b/contrib/sb-sprof/sb-sprof.texinfo
@@ -1,13 +1,103 @@
-@node sb-sprof
-@section sb-sprof
-@cindex Profiler
+@cindex Profiling, statistical
 
-The @code{sb-sprof} module provides an alternate profiler which works by
-taking samples of the program execution at regular intervals, instead of
-instrumenting functions like @code{profile} does. You might find
-@code{sb-sprof} more useful than @code{profile} when profiling functions
-in the @code{common-lisp}-package, SBCL internals, or code where the
-instrumenting overhead is excessive.
+The @code{sb-sprof} module, loadable by 
+@lisp
+(require :sb-sprof)
+@end lisp
+provides an alternate profiler which works by taking samples of the
+program execution at regular intervals, instead of instrumenting
+functions like @code{sb-profile:profile} does. You might find
+@code{sb-sprof} more useful than the deterministic profiler when profiling
+functions in the @code{common-lisp}-package, SBCL internals, or code
+where the instrumenting overhead is excessive.
+
+@subsection Example Usage
+
+@lisp
+(require :sb-sprof)
+
+(declaim (optimize speed))
+
+(defun cpu-test (n)
+  (let ((a 0))
+    (dotimes (i (expt 2 n) a)
+      (setf a (logxor a
+                      (* i 5)
+                      (+ a i))))))
+
+;;;; CPU profiling
+
+;;; Take up to 1000 samples of running (CPU-TEST 26), and give a flat
+;;; table report at the end. Profiling will end one the body has been
+;;; evaluated once, whether or not 1000 samples have been taken.
+(sb-sprof:with-profiling (:max-samples 1000
+                          :report :flat
+                          :loop nil)
+  (cpu-test 26))
+
+;;; Take 1000 samples of running (CPU-TEST 24), and give a flat
+;;; table report at the end. The body will be re-evaluated in a loop
+;;; until 1000 samples have been taken. A sample count will be printed
+;;; after each iteration.
+(sb-sprof:with-profiling (:max-samples 1000
+                          :report :flat
+                          :loop t
+                          :show-progress t)
+  (cpu-test 24))
+  
+;;;; Allocation profiling 
+
+(defun foo (&rest args)
+  (mapcar (lambda (x) (float x 1d0)) args))
+
+(defun bar (n)
+  (declare (fixnum n))
+  (apply #'foo (loop repeat n collect n)))
+
+(sb-sprof:with-profiling (:max-samples 10000
+                          :mode :alloc 
+                          :report :flat)
+  (bar 1000))
+@end lisp
+
+@subsection Output
+
+The flat report format will show a table of all functions that the
+profiler encountered on the call stack during sampling, ordered by the
+number of samples taken while executing that function. 
+
+@lisp
+           Self        Total        Cumul
+  Nr  Count     %  Count     %  Count     % Function
+------------------------------------------------------------------------
+   1    165  38.3    165  38.3    165  38.3 SB-KERNEL:TWO-ARG-XOR
+   2    141  32.7    141  32.7    306  71.0 SB-VM::GENERIC-+
+   3     67  15.5    145  33.6    373  86.5 CPU-TEST-2
+@end lisp
+
+For each function, the table will show three absolute and relative
+sample counts. The Self column shows samples taken while directly
+executing that function. The Total column shows samples taken while
+executing that function or functions called from it (sampled to a 
+platform-specific depth). The Cumul column shows the sum of all
+Self columns up to and including that line in the table.
+
+The profiler also hooks into the disassembler such that instructions which
+have been sampled are annotated with their relative frequency of
+sampling.  This information is not stored across different sampling
+runs.
+
+@lisp
+;      6CF:       702E             JO L4              ; 6/242 samples
+;      6D1:       D1E3             SHL EBX, 1
+;      6D3:       702A             JO L4
+;      6D5: L2:   F6C303           TEST BL, 3         ; 2/242 samples
+;      6D8:       756D             JNE L8
+;      6DA:       8BC3             MOV EAX, EBX       ; 5/242 samples
+;      6DC: L3:   83F900           CMP ECX, 0         ; 4/242 samples
+@end lisp
+
+@subsection Platform support
 
 This module is known not to work consistently on the Alpha platform,
 for technical reasons related to the implementation of a machine
@@ -15,20 +105,14 @@ language idiom for marking sections of code to be treated as atomic by
 the garbage collector;  However, it should work on other platforms,
 and the deficiency on the Alpha will eventually be rectified.
 
-@subsection Example Usage
-
-@lisp
-(require :sb-sprof)
-(sb-sprof:start-profiling)
+Allocation profiling is only supported on SBCL builds that use 
+the generational garbage collector. Tracking of call stacks at a
+depth of more than two levels is only supported on x86 and x86-64.
 
-(defvar *a* 0)
-(dotimes (i (expt 2 26))
-  (setf *a* (logxor *a* (* i 5)
-                    (+ *a* i))))
+@subsection Macros
 
-(sb-sprof:stop-profiling)
-(sb-sprof:report)
-@end lisp
+@include macro-sb-sprof-with-profiling.texinfo
+@include macro-sb-sprof-with-sampling.texinfo
 
 @subsection Functions
 
@@ -40,10 +124,6 @@ and the deficiency on the Alpha will eventually be rectified.
 
 @include fun-sb-sprof-stop-profiling.texinfo
 
-@subsection Macros
-
-@include macro-sb-sprof-with-profiling.texinfo
-
 @subsection Variables
 
 @include var-sb-sprof-star-max-samples-star.texinfo
@@ -52,5 +132,5 @@ and the deficiency on the Alpha will eventually be rectified.
    
 @subsection Credits
 
-@code{sb-sprof} is an SBCL port of Gerd Moellmann's statistical profiler
-for CMUCL.
+@code{sb-sprof} is an SBCL port, with enhancements, of Gerd
+Moellmann's statistical profiler for CMUCL.