prf(7) DG/UX R4.11 prf(7)
NAME
prf - operating system profiler
DESCRIPTION
prf is a character special pseudo-device that is used to profile the
kernel. The profiler is loaded with an array of kernel addresses and
is turned ON. Then, every 100th of a second, the value of the
program counter is recorded; if the processor was executing in kernel
code, a counter associated with the largest address less than the PC
is incremented. In this way, you can obtain some indication of the
time spent in various portions of the kernel.
The array of kernel addresses is loaded into the profiler using the
write system call on the prf pseudo-device. The profiler can be
turned ON or OFF and its current status can be obtained using an
ioctl system call. The results of a profiling interval can be
obtained using the read system call.
Two bits indicate the state of the profiler. One bit indicates
whether it is loaded with a valid set of kernel addresses. The other
bit indicates whether the profiler is ON or OFF, where ON means that
a sample of the PC is being collected every 100th of a second and the
appropriate counter incremented. The two bits allow only three
possible states as the profiler cannot be ON unless it is loaded with
a valid set of addresses.
In addition to a counter for each kernel address, the counter after
the last kernel address records the number of times the PC was at a
user address, and the counter after that records the number of times
the PC indicates the system was idle.
In a multiprocessor system, each processor may be independently
profiled, or all processors may be profiled together. If a prf
special file with minor device number 255 is opened, all processors
will be profiled together. If a prf special file with minor device
number other than 255 is opened, the processor with id equal to the
minor device number is profiled. For example, on an AV 5120, opening
minor device 0 will profile processor 0, opening minor device 1 will
profile processor 1, opening minor device 255 will profile both
together, and any other minor device number is illegal.
NOTE: If multiple processors are profiled together, each processor
generates counter increments. The total of all counters on a
dual processor, for example, will be twice that of a single
processor.
For the open and close system calls, user visible functionality is
the same as for an ordinary disk file.
The read system call allows the caller to obtain the current array of
kernel addresses and the corresponding counter values. The data is
arranged as an array of N addresses followed by N+2 counter values,
where N is the number of addresses stored in the profiler using the
write system call. The file pointer is ignored by the profiler; each
call to read transfers information into the caller's buffer starting
at the beginning of the array of N addresses and continuing up
through the last counter value or to the end of the user's buffer.
If the profiler state does not indicate that it contains a valid set
of kernel addresses, the "read" system call returns the error ENXIO
and the caller's buffer is not modified. If profiling is enabled,
the counter values returned may not be consistent because they are
modified while the read is in progress.
The write system call allows the caller to store a set of kernel
addresses into the profiler. The caller's buffer is presumed to
contain an array of kernel addresses in ascending numerical order.
The array is copied into the profiler's storage area, the counters
associated with the addresses are initialized to zero, and the
profiler state is marked as containing a valid set of addresses. The
number of kernel addresses stored, as determined from the size of the
caller's buffer, is recorded in the profiler. If profiling is
enabled, the write call will fail and the error EBUSY will be
returned.
DIAGNOSTICS
Several consistency checks are made, and errors may be returned as
indicated below:
ENOSPC The size of the caller's buffer indicates that it contains
more kernel addresses than the implementation defined maximum
the profiler can store. The state of the profiler is left
unchanged.
E2BIG The size of the caller's buffer indicates that it contains
fewer than 3 kernel addresses, or the size modulo the size of
an address is not zero. The state of the profiler is left
unchanged.
EBUSY The profiler is currently ON. The state of the profiler is
left unchanged.
EINVAL The array of kernel addresses is not in ascending numerical
order. The profiler is left in the state of not containing a
valid set of kernel addresses.
The ioctl system calls allows the caller to obtain the current status
of the profiler and to turn it ON and OFF. Each of the "command"
arguments to ioctl is described below:
PRF_GETSTATUS The current status of the profiler is returned as an
integer in "arg". The low-order bit set indicates the
profiler is ON; the next to low-order bit indicates
the profiler is loaded with a valid set of addresses.
PRF_GETSIZE The number of kernel addresses currently in the
profiler is returned as an integer in "arg". If the
profiler does not contain a valid set of addresses,
the results are undefined.
PRF_SETSTATE The low-order bit of "arg" is used to set the state of
the profiler to ON (the bit is set) or OFF (the bit is
clear). If the profiler does not contain a valid set
of addresses, this command has no effect.
PRF_GETMAX The maximum number of kernel addresses the profiler
can store is returned.
If "command" is other than those listed above, the error EINVAL is
returned.
select always returns READY for both read and write operations.
FILES
/dev/prf
SEE ALSO
profiler(1M).
Licensed material--property of copyright holder(s)