newprf(7)
_________________________________________________________________
prf Special File
DG/UX 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.
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 object 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.
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
newprf(7)
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.
ERROR MESSAGES
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.
Ioctl
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 adresses. See the type
descriptions at the beginning of the chapter.
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.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
newprf(7)
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
config(1M), profiler(1M).
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)