PROFILE(2)PROFILE(2)NAME
profile - profiling library
SYNOPSIS
include "profile.m";
profile := load Profile Profile->PATH;
Range: adt{
l: int;
u: int;
f: int;
n: cyclic ref Range;
};
Funprof: adt{
name: string;
line: int;
count: int;
counte: int;
};
Modprof: adt{
name: string;
path: string;
srcpath: string;
rawtab: array of (int, int);
linetab: array of int;
rngtab: array of ref Range;
funtab: array of Funprof;
total: int;
totals: array of int;
covered: int;
};
Prof: adt{
mods: list of Modprof;
total: int;
totals: array of int;
};
Coverage: type list of (string, int, list of (list of (int, int, byte), string));
MODULE: con 1; # give stats for each module
FUNCTION: con 2; # give stats for each function
LINE: con 4; # give stats for each line
VERBOSE: con 8; # full stats
FULLHDR: con 16; # file:lineno: on each line of output
FREQUENCY: con 32; # show frequency rather than coverage
init: fn(): int;
profile: fn(m: string): int;
sample: fn(i: int): int;
start: fn(): int;
stop: fn(): int;
stats: fn() : Prof;
show: fn(p: Prof, v: int): int;
end: fn(): int;
# coverage profiling specific functions
cpstart: fn(pid: int): int;
cpstats: fn(rec: int, v: int): Prof;
cpfstats: fn(v: int): Prof;
cpshow: fn(p: Prof, v: int): int;
coverage: fn(p: Prof, v: int): Coverage;
# memory profiling specific functions
memstart: fn(): int;
memstats: fn(): Prof;
memshow: fn(p: Prof, v: int): int;
lasterror: fn(): string;
DESCRIPTION
Profile provides an interface to the kernel profile device. It contains
routines to start and stop profiling, to gather profiling statistics
and to display these statistics in relation to the relevant limbo
source code. All of these routines apart from lasterror return a nega‐
tive integer if an error occurred during their execution. Once this
happens, a call to lasterror will give the error message.
init initializes the module and binds the kernel profile device onto
the /prof directory. It should be called before any other functions in
this module.
profile takes a module name or a path name as its argument and indi‐
cates a module to be profiled. Repeated calls of this function allow a
number of modules to be profiled together. In the absence of any calls
to this routine, the profile device profiles all modules loaded by the
kernel.
sample sets the sampling interval of the profiling. The argument is in
ms. The default value in the profile device is 100ms.
start starts profiling.
stop stops profiling.
stats returns profiling statistics. It is recommended that this is
called once profiling has been stopped, otherwise the results may be
slightly inaccurate. It returns an adt of type Prof. Its first field
mods is a list of profile statistics for each module under profile.
Its second field total is the number of samples made altogether. The
statistics for each module are represented in the Modprof adt. Its
fields are
name The name of the module.
path The path of the module's corresponding dis file.
srcpath The path of the module's corresponding source file.
linetab The line frequency count table. The number of samples made on
a particular line of the above source file is found by index‐
ing this table.
funtab The function frequency count table. This array of Funprof adt
gives the name, line number and number of samples made for
each function in the above source file.
total The total number of samples made in this module.
stats will ignore modules if it fails to locate the symbol (.sbl) file
for a particular dis file.
show simply prints out the profile information returned by stats. For
each module it will print out either the line number statistics or the
function statistics or both. The former gives the line number, percent‐
age of time spent on this line and the source code for each line in the
source file. The latter gives the line number, function name and per‐
centage of time spent in this function for each function in the source
file. The amount of output can be controlled by the second argument to
show. The following should be ored together in the required combina‐
tion to get the desired effect.
FUNCTION Print the function table.
LINE Print the line number table.
VERBOSE Normally lines and functions are not shown if the sample fre‐
quency for them is zero. This option prevents this.
FULLHDR Prints the file name as well as the line number in a form
that can be selected in acme to show that particular line in
a window.
show will ignore modules if it fails to locate the source (.b) file for
a particular dis file.
end ends the profiling session. This should be called when all statis‐
tics have been gathered in order to clean up the device profile's data
structures.
In order to support coverage profiling as well the following new rou‐
tines are provided.
cpstart Start coverage profiling on the process whose pid is given.
cpstats Returns coverage profiling statistics from the profile device.
If the first argument is true, the raw results will be stored in a pro‐
file file whose name is <file>.prf where <file> is the prefix of the
corresponding dis file.
cpfstats Returns coverage profiling statistics from any saved profile
files.
cpshow Shows the coverage profiling statistics.
coverage Given the coverage profiler statistics this returns the list
of modules profiled. Each module has a name, a boolean indicating
whether all instructions in the module were executed and a list of
lines. Each line consists of a list of ranges and the source code. The
list of ranges contains the character positions on the line of code
corresponding to instructions that were not executed and an indicator
of whether partial execution was performed.
For the further support of memory profiling the following routines are
available.
memstart Start memory profiling.
memstats Return the memory profile statisics.
memshow Send memory profile statistics to standard output.
SOURCE
/module/profile.m
/appl/lib/profile.b
SEE ALSOprof(3)PROFILE(2)
