
	HierProf 2.06 - Hierachical profiling for C programs
	



Contents


Introduction
How to use HierProf
Contents of the '!HierProf' application-directory
How HierProf works
Manual control of profiling
Timing overheads and restrictions
Use with C++
System variables used/changed
Other things



Introduction


	The !HierProf application-directory contains a C library and C
	preprocessor which can be used to add time-profiling of
	functions to any C program.
	
	The profiling output is a full hierachical listing of the time
	spent in each function, so you get told how much time was spent
	in function X as percentages of the amount of time spent in all
	other functions that indirectly or directly called X.
	
	For example, here is part of the profiling output from one of
	the programs in the '!HierProf.Examples' directory:
	
	   1   Outermost loop                                               
	   2   *   99.60%   main                                            
	   3       84.98%   *   85.32%   FunctionC                          
	   4        0.79%        0.79%   *    0.93%   NullFunction          
	   5       60.47%       60.71%   *   71.16%   FunctionA             
	   6       30.43%       30.56%       35.81%   *   50.33%   FunctionD
	   7       10.67%       10.71%   *   12.56%   FunctionB             
	
	The '*' indicate direct calls, to help you to follow the
	tree-structure.
	
	HierProf works by preprocesing C source code to make calls to
	special timing functions at the start and end of each function.
	This is done by compiling with HierProf's cc-frontend program,
	'HierProfCC', and linking with the HierProf library. This is
	very straightforward - see the next section for the details.
	
	By default, the profiling output is sent to stderr when the
	program finishes, using atexit(). There are functions to send 
	the output to temporary files etc instead.
	
	Demonstration versions of HierProf will ignore any nested function 
	calls beyond 5 levels. The full version copes with up to 62 
	levels.
	
	




How to use HierProf


	To make a profiled version of a project, do the following:
	
	
	1)	Ensure that the '!HierProf' application-directory has
		been seen by the Filer.
	
	2)	Compile each C source file by calling 'HierProfCC'
		rather than your normal compiler, passing the full call
		to your compiler as the arguments to HierProfCC.
	
	3)	Link with 'HierProf:o.HPLib'.
	
	
	For example, if you normally build with:
	
		cc -c -I,C: -o o.main c.main
		link -o !RunImage o.main C:o.Stubs
	
	then to include function profiling, do:
	
		HierProfCC cc -c -I,C: -o o.main c.main
		link -o !RunImage o.main HierProf:o.HPLib C:o.Stubs
	
	(Desktop C users should use HierProf:o.HP4Lib)
	
	The 'HierProfCC' command is in the '!HierProf.Bin.' directory,
	which is automatically added to your run-path by
	'!HierProf.!Boot'.
	
	
	
	Examples
	
	
	The '!HierProf.Example' directory contains two example projects
	with makefiles that can be used to make normal or profiled
	versions of the project. 
	
	This is done in the makefiles by prefixing the command 'cc' 
	with '$(HierProfCC)'. This AMU macro is not defined in the 
	makefile, so normaly reduced to nothing. To build a profiled 
	version, the makefile is simply called with:
	
		Amu ... HierProfCC=HierProfCC
	
	
	Minor restrictions when using HierProfCC
	
	
	HierProfCC has a small restriction compared to a normal C
	compiler - it will only process one .c file in the command line
	parameters, so you will have to compile multiple .c files
	individually.
	
	You should ensure that the C source code will compile ok without
	HierProcCC, because HierProfCC will not be particularly helpful
	if it can't parse the C source.
	
	HierProfCC can fail to correctly parse C source code which omits
	white space between a ')' and a '{'.
	



Contents of the '!HierProf' application-directory



	Some of the following (eg source code) may not be included in
	the distribution.
	
	
	!HierProf.
	
		!Help	This file
		
		History	Some info on HierProf development.
		
		!Boot	Sets HierProf$Dir and HierProf$Path
			Sets Alias$HierProfCC
			Creates the directory <Wimp$ScrapDir>.HierProf.c
			
		!Run	Runs !Boot and opens !Help.
		
		
		o.	
			HPLib	Library to link with profiled programs. 
				This contains all the time-measuring 
				code etc.
			
			HP4Lib	As above, except compatible with Acorn's
				Desktop C (C5 uses new stubs symbols).
			
			HPLibDebug	A version of the HierProf 
					library which outputs 
					diagnostics.
			
			Sources.	Source code for HPLib
			
		
		h.
			HierProf	Header file for HPLib. Contains
					#defines for HierProf_Start etc,
					and declarations for the 
					functions in HPLib
			
		
		Bin.
			HierProfCC	Frontend to any C compiler,
					which adds profile calls to C
					source code before compilation.
			
			HPCCDebug	HierProfCC compiled with
					debugging enabled.
			
			Sources.	Source code for HierProfCC
		
		
		Examples.
		
			Simple.		This contains an example C
					project which can be compiled
					for normal or profiling use.
					
				c.		C source code.
				h.
				Makefile.
			
				!Normal.	Directory containing
						normally-compiled .o
						files etc.
						Double-clicking this
						directory will (re)build
						the project.
												
					RunProg This runs the program.
					
				!HierProf.	Directory containing 
						.o files compiled for
						profiling.
						Double-clicking this
						directory will (rebuild
						the project.
						
					RunProg This runs the program.
			
			
			Recursive.	Another example C project which
					tests HierProf on recursive 
					functions.
				
		
		HierProf	A StrongHelp manual for the HierProf
				header file.





How HierProfCC works


	HierProfCC first makes an altered version of the C source file
	it is given, and saves it as '<Wimp$ScrapDir>.HierProf.c.main'.
	It then calls cc (or whatever HierProfCC's first parameter is)
	by sending the string of its arguments to the
	command-line-interpreter.
	
	HierProfCC adds some macros to the source-code at the start and
	end of every function. These macros are defined in the header
	file 'HierProf:HierProf.h', and call functions in the C libraray
	'HierProf:o.HPLib' which store and calculate time intervals. 
	
	HierProf will also add a '#include "HierProf.h"' line to the
	start of the file, and the search path of cc is modified so that
	this header file will be found inside the '!HierProf' directory.
	
	At run-time, when the first HierProf macro is reached, an exit
	handler is registered. When the program finishes, this causes
	the profile output to be printed to stderr. You can change where
	the output goes by calling the various functions declared in
	'HierProf:HierProf.h'. For example, you can send output to a
	filename or a filestream.
	
	You can also tell HierProf to output the data before your
	program has finished. You can send output to one of your own
	functions to display the data in a window if you like, as long
	as the function is similar to fprintf.
	
	The altered version of the C source file is not deleted after it
	has been compiled, so you can have a look at it to get an idea
	of what HierProfCC has done.





Manual control of profiling


	You can manually profile any region of code inside a function by
	adding pairs of the macros 'HierProf_Start( "any text")' and
	'HierProf_Stop()' lines (with no terminating semicolons) around
	the code you want profiled.
	
	These macros will be removed unless compilation is with
	HierProfCC, but you have to explicitly '#include
	"HierProf:HierProf.h"' in your source code for this to work.
	
	You can also make HierProfCC ignore a function by putting
	'HierProf_DontProfile()' immediately after the opening '{' of
	the function.
	
	For example:
	
	int FunctionWeDontWantToProfile( int x)
	{
	HierProf_DontProfile()
	...
	}
	
	
	There are various functions which can be used to control where 
	profiling is sent to, in 'HierProf:HierProf.h'.




Timing overheads and restrictions


	As you may have been thinking, two function calls per profile
	block is going to give a hefty overhead for each profiled block.
	On my 25MHz A5000, this overhead is around 0.15 ms. Hence
	programs compiled with HierProfCC will run rather slowly.
	
	HierProf meausures how long is spent in its start/stop
	functions, and uses this information to correct (as much as
	possible) the timing information.
	
	The actual timing is done with the ANSI C 'clock()' function.
	This has a resolution of 1/100th of a second in RISC OS. Usually
	however, you will be looking at functions that are called many 
	times, so the average time calculated by HierProf will be much 
	more accurate.
	
	You can't have more than 255 different profiled functions or
	blocks. This limitation may be removed in future.
	
	A maximum of 62 nested function levels are handled - higher
	nestings are ignored. HierProf will also ignore all but the
	initial call to a recursive function (including mutually
	recursive functions).




Use with C++


	I've made a few tweaks so that HierProf semi-works with C++
	code and Acorn's C++ compiler 5.06, but this hasn't been tested
	very much. 
	
	Only class-method names are noticed by the source parser, so
	'SomeClass::dosomething(...)' will appear as 'dosomething' in
	the profile output. Similarly, parameter types are ignored.
	
	Owing to the way HierProf works though, methods with the same
	names in different classes will still be individually profiled, 
	even though they have the same name in the output.
	
	Converted C++ files are put into '<Wimp$ScrapDir>.HierProf.c++.'
	- Acorn C++ 5.06 doesn't cope very well with files inside .c
	directories.
	
	Because of (what I think is) a bug in Acorn C++ 5.06, HierProf
	has to use the leafname of the input file as the temporary
	leafname when the input file is in a c++ directory - C++ 5.06
	seems to ignore any -o directive, and always uses the input
	source leafname as the output leafname. This will result in
	'<Wimp$ScrapDir>.HierProf.c++.' filling up with old converted
	files.




System variables used/changed


	When seen by the Filer, the '!HierProf' application directory
	affects the following system variables:
	
	Run$Path	('HierProf:Bin.' is added)
	HierProf$Dir
	HierProf$Path
	
	(C$Path is not changed)
	
	Also, the directories <Wimp$ScrapDir>.HierProf.c/c++ are
	created.





Other things


	Please feel free to contact me at the address below if you have
	any problems, queries or suggestions.
	
	All the HierProf files are Copyright  Julian Smith 1995.




- Julian Smith



 ---------------------------------------------------------------------------
 Julian Smith                              Dept of Experimental Psychology
 julian.smith@psy.ox.ac.uk                 South Parks Road, Oxford, OX1 3UD
 http://cogsci1.psych.ox.ac.uk/~julians/   UK
 ---------------------------------------------------------------------------
