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
Page 1 Plan 9 (printed 12/21/24)
PROFILE(2) PROFILE(2)
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 negative 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 indicates 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.
Page 2 Plan 9 (printed 12/21/24)
PROFILE(2) PROFILE(2)
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 statis-
tics 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 sam-
ples made on a particular line of the above source
file is found by indexing 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, percentage 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
percentage 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 combination 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 frequency 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
Page 3 Plan 9 (printed 12/21/24)
PROFILE(2) PROFILE(2)
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 statistics 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 routines are provided.
cpstart Start coverage profiling on the process whose pid is
given.
cpstats Returns coverage profiling statistics from the pro-
file device. If the first argument is true, the raw results
will be stored in a profile 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 con-
tains the character positions on the line of code corre-
sponding to instructions that were not executed and an indi-
cator 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 ALSO
prof(3)
Page 4 Plan 9 (printed 12/21/24)