mirror of https://github.com/mkerrisk/man-pages
perf_event_open.2: Clarify description of overflow events
Update the perf_event_open manpage to be more consistent when discussing overflow events. It merges the discussion of poll-type notifications with those generated by SIGIO signal handlers. This addresses the remaining FIXMEs is the document. Signed-off-by: Vince Weaver <vincent.weaver@maine.edu> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Vince Weaver
Michael Kerrisk
parent
223413b769
commit
21977c9d2a
|
|
@ -585,16 +585,16 @@ Its parameters are set in other places.
|
|||
.RE
|
||||
.TP
|
||||
.IR sample_period ", " sample_freq
|
||||
A "sampling" counter is one that generates an interrupt
|
||||
A "sampling" event is one that generates an overflow notification
|
||||
every N events, where N is given by
|
||||
.IR sample_period .
|
||||
A sampling counter has
|
||||
A sampling event has
|
||||
.IR sample_period " > 0."
|
||||
When an overflow interrupt occurs, requested data is recorded
|
||||
When an overflow occurs, requested data is recorded
|
||||
in the mmap buffer.
|
||||
The
|
||||
.I sample_type
|
||||
field controls what data is recorded on each interrupt.
|
||||
field controls what data is recorded on each overflow.
|
||||
|
||||
.I sample_freq
|
||||
can be used if you wish to use frequency rather than period.
|
||||
|
|
@ -894,10 +894,10 @@ If this bit is set, then
|
|||
fork/exit notifications are included in the ring buffer.
|
||||
.TP
|
||||
.IR "watermark"
|
||||
If set, have a sampling interrupt happen when we cross the
|
||||
If set, have an overflow notification happen when we cross the
|
||||
.I wakeup_watermark
|
||||
boundary.
|
||||
Otherwise, interrupts happen after
|
||||
Otherwise, overflow notifications happen after
|
||||
.I wakeup_events
|
||||
samples.
|
||||
.TP
|
||||
|
|
@ -1013,7 +1013,7 @@ This union sets how many samples
|
|||
.RI ( wakeup_events )
|
||||
or bytes
|
||||
.RI ( wakeup_watermark )
|
||||
happen before an overflow signal happens.
|
||||
happen before an overflow notification happens.
|
||||
Which one is used is selected by the
|
||||
.I watermark
|
||||
bit flag.
|
||||
|
|
@ -1022,11 +1022,16 @@ bit flag.
|
|||
only counts
|
||||
.B PERF_RECORD_SAMPLE
|
||||
record types.
|
||||
To receive a signal for every incoming
|
||||
To receive overflow notification for all
|
||||
.B PERF_RECORD
|
||||
type set
|
||||
types choose watermark and set
|
||||
.I wakeup_watermark
|
||||
to 1.
|
||||
|
||||
Prior to Linux 3.0 setting
|
||||
.I wakeup_events
|
||||
to 0 resulted in no overflow notifications;
|
||||
more recent kernels treat 0 the same as 1.
|
||||
.TP
|
||||
.IR "bp_type" " (since Linux 2.6.33)"
|
||||
This chooses the breakpoint type.
|
||||
|
|
@ -2238,52 +2243,52 @@ is the flags information.
|
|||
is a string describing the backing of the allocated memory.
|
||||
.RE
|
||||
.RE
|
||||
.SS Signal overflow
|
||||
Events can be set to deliver a signal when a threshold is crossed.
|
||||
.\" FIXME .
|
||||
.\" The following sentence doesn't seem to make sense.
|
||||
.\" These system calls do not set up signal handlers.
|
||||
The signal handler is set up using the
|
||||
.SS Overflow handling
|
||||
Events can be set to notify when a threshold is crossed,
|
||||
indicating an overflow.
|
||||
Overflow conditions can be captured by monitoring the
|
||||
event file descriptor with
|
||||
.BR poll (2),
|
||||
.BR select (2),
|
||||
.BR epoll (2)
|
||||
and
|
||||
.BR fcntl (2),
|
||||
system calls.
|
||||
or
|
||||
.BR epoll (2).
|
||||
Alternately, a SIGIO signal handler can be created and
|
||||
the event configured with
|
||||
.BR fcntl (2)
|
||||
to generate SIGIO signals.
|
||||
|
||||
To generate signals, sampling must be enabled
|
||||
Overflows are only generated by sampling events
|
||||
.RI ( sample_period
|
||||
must have a nonzero value).
|
||||
|
||||
There are two ways to generate signals.
|
||||
There are two ways to generate overflow notifications.
|
||||
|
||||
The first is to set a
|
||||
.I wakeup_events
|
||||
or
|
||||
.I wakeup_watermark
|
||||
value that will generate a signal if a certain number of samples
|
||||
value that will trigger if a certain number of samples
|
||||
or bytes have been written to the mmap ring buffer.
|
||||
In this case, a signal of type
|
||||
In this case
|
||||
.B POLL_IN
|
||||
is sent.
|
||||
is indicated.
|
||||
|
||||
The other way is by use of the
|
||||
.B PERF_EVENT_IOC_REFRESH
|
||||
ioctl.
|
||||
This ioctl adds to a counter that decrements each time the event overflows.
|
||||
When nonzero, a
|
||||
When nonzero,
|
||||
.B POLL_IN
|
||||
signal is sent on overflow, but
|
||||
once the value reaches 0, a signal is sent of type
|
||||
is indicated, but
|
||||
once the counter reaches 0
|
||||
.B POLL_HUP
|
||||
and
|
||||
is indicated and
|
||||
the underlying event is disabled.
|
||||
|
||||
Note: on newer kernels (since at least as early as Linux 3.2),
|
||||
.\" FIXME . Find out when this was introduced
|
||||
a signal is provided for every overflow, even if
|
||||
.I wakeup_events
|
||||
is not set.
|
||||
Starting with Linux 3.18
|
||||
.B POLL_HUP
|
||||
is indicated if the event being monitored is attached to a different
|
||||
process and that process exits.
|
||||
.SS rdpmc instruction
|
||||
Starting with Linux 3.4 on x86, you can use the
|
||||
.I rdpmc
|
||||
|
|
@ -2335,11 +2340,11 @@ to enable a counter for a number of overflows specified by the argument,
|
|||
after which it is disabled.
|
||||
Subsequent calls of this ioctl add the argument value to the current
|
||||
count.
|
||||
A signal with
|
||||
An overflow notification with
|
||||
.B POLL_IN
|
||||
set will happen on each overflow until the
|
||||
count reaches 0; when that happens a signal with
|
||||
POLL_HUP
|
||||
count reaches 0; when that happens a notification with
|
||||
.B POLL_HUP
|
||||
set is sent and the event is disabled.
|
||||
Using an argument of 0 is considered undefined behavior.
|
||||
.TP
|
||||
|
|
|
|||
Loading…
Reference in New Issue