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

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

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