Technical Reference: Base Operating System and Extensions, Volume 1

profil Subroutine

Purpose

Starts and stops program address sampling for execution profiling.

Library

Standard C Library (libc.a)

Syntax

#include <mon.h>

void profil ( ShortBuffer, BufferSize, Offset, Scale)
OR
void profil ( ProfBuffer, -1, 0, 0)

unsigned short *ShortBuffer;
struct prof *ProfBuffer;
unsigned int Buffersize, Scale;
unsigned long Offset;

Description

The profil subroutine arranges to record a histogram of periodically sampled values of the calling process program counter. If BufferSize is not -1:

The parameters to the profil subroutine are interpreted as shown in the first syntax definition.

After this call, the program counter (pc) of the process is examined each clock tick if the process is the currently active process. The value of the Offset parameter is subtracted from the pc. The result is multiplied by the value of the Scale parameter, shifted right 16 bits, and rounded up to the next half-word aligned value. If the resulting number is less than the BufferSize value divided by sizeof(short), the corresponding short inside the ShortBuffer parameter is incremented. If the result of this increment would overflow an unsigned short, it remains USHRT_MAX.

The least significant 16 bits of the Scale parameter are interpreted as an unsigned, fixed-point fraction with a binary point at the left. The most significant 16 bits of the Scale parameter are ignored. For example:

Octal	Hex	Meaning
0177777	0xFFFF	Maps approximately each pair of bytes in the instruction space to a unique short in the ShortBuffer parameter.
077777	0x7FFF	Maps approximately every four bytes to a short in the ShortBuffer parameter.
02	0x0002	Maps all instructions to the same location, producing a noninterrupting core clock.
01	0x0001	Turns profiling off.
00	0x0000	Turns profiling off.

Note

Mapping each byte of the instruction space to an individualshort in the ShortBuffer parameter is not possible.

Profiling, using the first syntax definition, is rendered ineffective by giving a value of 0 for the BufferSize parameter.

If the value of the BufferSize parameter is -1:

The parameters to the profil subroutine are interpreted as shown in the second syntax definition. In this case, the Offset and Scale parameters are ignored, and the ProfBuffer parameter points to an array of prof structures. The prof structure is defined in the mon.h file, and it contains the following members:
```
caddr_t          p_low;
caddr_t          p_high;
HISTCOUNTER     *p_buff;
int              p_bufsize;
uint             p_scale;
```

If the p_scale member has the value of -1, a value for it is computed based on p_low, p_high, and p_bufsize; otherwise p_scale is interpreted like the scale argument in the first synopsis. The p_high members in successive structures must be in ascending sequence. The array of structures is ended with a structure containing a p_high member set to 0; all other fields in this last structure are ignored.

The p_buff buffer pointers in the array of prof structures must point into a single contiguous buffer space.

Profiling, using the second syntax definition, is turned off by giving a ProfBuffer argument such that the p_high element of the first structure is equal to 0.

In every case:

Profiling remains on in both the child process and the parent process after a fork subroutine.

Profiling is turned off when an exec subroutine is run.

A call to the profil subroutine is ineffective if profiling has been previously turned on using one syntax definition, and an attempt is made to turn profiling off using the other syntax definition.

A call to the profil subroutine is ineffective if the call is attempting to turn on profiling when profiling is already turned on, or if the call is attempting to turn off profiling when profiling is already turned off.

Parameters

ShortBuffer	Points to an area of memory in the user address space. Its length (in bytes) is given by the BufferSize parameter.
BufferSize	Specifies the length (in bytes) of the buffer.
Offset	Specifies the delta of program counter start and buffer; for example, a 0 Offset implies that text begins at 0. If the user wants to use the entry point of a routine for the Offset parameter, the syntax of the parameter is as follows: (long )RoutineName
Scale	Specifies the mapping factor between the program counter and ShortBuffer.
ProfBuffer	Points to an array of prof structures.

Return Values

The profil subroutine always returns a value of 0. Otherwise, the errno global variable is set to indicate the error.

Error Codes

The profil subroutine is unsuccessful if one or both of the following are true:

EFAULT	The address specified by the ShortBuffer or ProfBuffer parameters is not valid, or the address specified by a `p_buff` field is not valid. EFAULT can also occur if there are not sufficient resources to pin the profiling buffer in real storage.
EINVAL	The `p_high` fields in the prof structure specified by the ProfBuffer parameter are not in ascending order.

Related Information

The exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutines, fork (fork, f_fork, or vfork Subroutine) subroutine, moncontrol (moncontrol Subroutine) subroutine, monitor (monitor Subroutine) subroutine, monstartup (monstartup Subroutine) subroutine.

The prof command.