source: branches/working-0711/ccl/library/chud-metering.txt @ 7620

Last change on this file since 7620 was 2594, checked in by gb, 14 years ago

Flesh out a bit more.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.4 KB
Line 
1Using Apple's CHUD metering tools from OpenMCL
2
3 Prerequisites
4
5Apple's CHUD metering tools are available (as of this writing) from:
6
7<ftp://ftp.apple.com/developer/Tool_Chest/Testing_-_Debugging/Performance_tools/>.
8
9There are also some CHUD packages distributed with some recent
10versions of Xcode; the standalone versions available via FTP seem to
11work much better with the OpenMCL interface. Both versions 4.1.1 and
124.2.2 of the CHUD tools seem to work reasonably well; earlier versions
13provide a different ABI, and it's not known whether any future
14versions will be compatible.
15
16There don't seem to be any versions of CHUD that can deal with 64-bit
17processes.
18
19Ensure that either version 4.1.1 or 4.2.2 of the CHUD tools are
20installed. One side-effect of installation is that the folder "
21/Developer/Applications/Performance Tools" will have been created and
22will contain an application called "Shark". Double-click on Shark; in
23its "Preferences" window's "Search Paths" pane, use the "+" button to
24add your home directory to the "Patch Files" search path.
25
26 Background
27
28CHUD's Shark application is a user interface to its low-level
29performance monitoring facilities; those facilities provide access to
30high-resolution timers, on-chip debugging information, and OS
31performance counters. Shark allows the user to run sampling sessions,
32which record information about the context in which sampling events
33(such as timer interrupts) occur; at the end of the session, Shark
34processes the sampled data and presents a browsable interface which
35shows the processes, threads, and functions associated with those
36events.
37
38For many processes, Shark can identify functions (the range of
39addresses corresponding to the address of the first and last
40instructions in the function) by interpreting symbolic information
41contained in the executable file. This strategy enables it to identify
42C and assembler functions in OpenMCL's lisp kernel, but doesn't help
43much in identifying Lisp functions. Fortunately, Shark does have the
44ability to read "patch files" , which associate symbolic names to
45regions of a process's address space), and fortunately OpenMCL can be
46told to move the machine code (the "code vector") associated with a
47compiled function to a static memory area (so that the addresses of
48the first and last instructions in a compiled lisp function remain
49constant); it's possible to assign fixed addresses to the code vectors
50of all functions in the lisp at a given time, and to give symbolic
51names to the memory regions that delimit those code vectors.
52
53The process of moving code vectors to a static (and incidentally
54read-only) memory area is sometimes referred to as "purification".
55
56 A Sampling Sample
57
58There's a little bit of flexibility in the order in which these steps
59are performed, but for the sake of argument we'll pretend here that
60there isn't.
61
621) Run Shark, and put it in "remote" mode.
63
64Run Shark. Ensure that it's in "Programmatic (Remote)" mode by
65selecting that option from the "Sampling" menu, or by pressing the key
66equivalent "command-shift-R". In the main Shark window, ensure that
67the sampling type is set to "Time Profile", select "Process" (instead
68of "Everything" ) from the next popup, and doing so should cause the
69third popup to select "Remote Client".
70
712) Meter some code in OpenMCL.
72
73In OpenMCL, do:
74
75? (require "CHUD-METERING")
76
77and ensure that the code that you want to profile is defined.
78
79? (defun fact (n)
80    (if (zerop n)
81      1
82      (* n (fact (1- n)))))
83FACT
84? (defun fact-n-m-times (m n)
85    (dotimes (i m)
86      (fact n)))
87FACT-N-M-TIMES
88
89Then run something with metering enabled:
90
91? (CHUD:METER (fact-n-m-times 1000 1000))
92
93The first time that CHUD:METER is invoked in a lisp session, it'll:
94
951. Ensure that Shark is running
96
972. Move the code vectors of all functions to a static
98   memory area.
99
1003. Write a Shark "spatch" file to the user's home
101   directory (which is where we configure Shark to look
102   for such files back in the "Prerequisites" section.)
103   See also CHUD:*SPATCH-DIRECTORY-PATH*.
104
1054. Try to ensure that Shark is running in "remote" mode.
106   (I don't know of any way in which this can be ensured
107   programatically, so it'll just keep asking whether or
108   not Shark's in remote mode until you say "y" and the
109   lisp metering code detects that that's the case.)
110
111Those steps may take anywhere from "a few" to "several" seconds; steps
1122 and 3 are probably the most expensive and depend on how many
113functions are in the lisp image, how big they are, etc.
114
115On every invocation of CHUD:METER, it'll tell Shark to start a
116metering session, execute the form which is its required argument,
117tell Shark to stop the session, and return the form's result(s).
118
119After it's been told to stop the sampling session, Shark will analyze
120the sampling data it obtained and display the results. In this
121example, it's reasonable to assume that some CCL package functions
122related to bignum multiplication dominate the execution time. Lisp
123functions that show up in Shark's session window will claim to be
124defined in the SPATCH library; their "names" will generally look like
125their printed representations.
126
127 Limitations
128
129It's generally tempting to start redefining functions that have
130longer-than-expected execution times. That's possibly the right thing
131to do in general, but (because of the way that the spatch mechanism
132works) it's hard to get meaningful results: Shark can only give names
133to lisp functions that're in its .spatch file, and will continue to
134use cached informaton from that .spatch file until it quits. General
135(GC-able) lisp functions - whose code-vectors might move around in
136memory - tend to confuse Shark (and at least some versions get
137confused enough that they may crash while trying to report time spent
138in functions that aren't where they used to be ...)
139
140After things get a little bit out-of-whack (in terms of newly defined
141lisp functions), it's often necessary to quit both Shark and OpenMCL,
142load the new-and-improved code into the lisp, and try again, hoping
143for better results.
144
145After CHUD:METER has done its first-time setup, it's generally
146necessary to quit both Shark and OpenMCL if either quits in order to
147get them back in synch again.
148
149Despite these limitations, it's probably fair to say that this is way,
150way better than nothing.
151
152 Reference
153
154(CHUD:METER form &key (duration 0) (frequency 1))  [Macro]
155
156Ensures that access to the "remote sampling facility" (Shark, usually)
157has been acquired, ensure that code vectors have been purified and
158that an spatch file for the current process is writen to the directory
159named by CHUD:*SPATCH-DIRECTORY-PATH* (or the user's home directory),
160and starts and stops the sampling facility around execution of <form>.
161Returns whatever values execution of <form> returns.
162
163Arguments
164  <form>        an arbitrary lisp expression
165  <frequency>   sampling frequency in milliseconds
166  <duration>    total number of sampling intervals, 0 implies "infinite".
167
168It seems that the <frequency> and <duration> arguments have no effect;
169the sampling frequency and duration can be set via Shark's "configuration
170editor" dialog.
171
172CHUD:*SPATCH-DIRECTORY-PATH*  [Special Variable]
173
174If non-NIL, should be a pathname whose directory component matches the
175"Patch FIles" search path in Shark's Preferences.  When this variable
176is NIL, USER-HOMEDIR-PATHNAME is used instead.
177
178
179 Acknowledgments
180
181Both Dan Knapp and Hamilton Link have posted similar CHUD interfaces
182to openmcl-devel in the past; Hamilton's also reported bugs in the
183spatch mechanism to CHUD developers (and gotten those bugs fixed.)
Note: See TracBrowser for help on using the repository browser.