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@xxxxxxxxx> 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
