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