[patch] perf_event_open.2 clarify description of overflow events

[patch] perf_event_open.2 clarify description of overflow events

[Vince Weaver]

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-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index cccb880..aed1449 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -591,16 +591,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.
@@ -900,10 +900,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
@@ -1019,7 +1019,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.
@@ -1028,11 +1028,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.
@@ -2244,52 +2249,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
@@ -2341,11 +2346,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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] perf_event_open.2 clarify description of overflow events

[Michael Kerrisk (man-pages)]

Hello Vince,
On 01/21/2015 06:35 AM, Vince Weaver wrote:
> 
> 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.

Thanks for that.

> This addresses the remaining FIXMEs is the document.

And especially for that, thanks.

Applied.

Cheers,

Michael


> Signed-off-by: Vince Weaver <vincent.weaver-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>
> 
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index cccb880..aed1449 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -591,16 +591,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.
> @@ -900,10 +900,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
> @@ -1019,7 +1019,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.
> @@ -1028,11 +1028,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.
> @@ -2244,52 +2249,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
> @@ -2341,11 +2346,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
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html