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>

man2/perf_event_open.2

@@ -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
+.SS Overflow handling
-Events can be set to deliver a signal when a threshold is crossed.
+Events can be set to notify when a threshold is crossed,
-.\" FIXME .
+indicating an overflow.
-.\" The following sentence doesn't seem to make sense.
+Overflow conditions can be captured by monitoring the
-.\" These system calls do not set up signal handlers.
+event file descriptor with
-The signal handler is set up using the
 .BR poll (2),
 .BR select (2),
-.BR epoll (2)
+or
-and
+.BR epoll (2).
-.BR fcntl (2),
+Alternately, a SIGIO signal handler can be created and
-system calls.
+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
+is indicated, but
-once the value reaches 0, a signal is sent of type
+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),
+Starting with Linux 3.18
-.\" FIXME . Find out when this was introduced
+.B POLL_HUP
-a signal is provided for every overflow, even if
+is indicated if the event being monitored is attached to a different
-.I wakeup_events
+process and that process exits.
-is not set.
 .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
+count reaches 0; when that happens a notification with
-POLL_HUP
+.B POLL_HUP
 set is sent and the event is disabled.
 Using an argument of 0 is considered undefined behavior.
 .TP