From patchwork Mon Oct 24 06:52:56 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wang Nan X-Patchwork-Id: 78861 Delivered-To: patch@linaro.org Received: by 10.140.97.247 with SMTP id m110csp2421773qge; Sun, 23 Oct 2016 23:58:00 -0700 (PDT) X-Received: by 10.99.123.90 with SMTP id k26mr5597123pgn.153.1477292280150; Sun, 23 Oct 2016 23:58:00 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id bm3si11658964pab.286.2016.10.23.23.57.59; Sun, 23 Oct 2016 23:58:00 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932736AbcJXGzP (ORCPT + 27 others); Mon, 24 Oct 2016 02:55:15 -0400 Received: from szxga03-in.huawei.com ([119.145.14.66]:39030 "EHLO szxga03-in.huawei.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751543AbcJXGxy (ORCPT ); Mon, 24 Oct 2016 02:53:54 -0400 Received: from 172.24.1.47 (EHLO szxeml431-hub.china.huawei.com) ([172.24.1.47]) by szxrg03-dlp.huawei.com (MOS 4.4.3-GA FastPath queued) with ESMTP id CKF06323; Mon, 24 Oct 2016 14:53:50 +0800 (CST) Received: from linux-4hy3.site (10.107.193.248) by szxeml431-hub.china.huawei.com (10.82.67.208) with Microsoft SMTP Server id 14.3.235.1; Mon, 24 Oct 2016 14:53:42 +0800 From: Wang Nan To: , CC: , , , , Wang Nan Subject: [PATCH v3][manpages 2/2] perf_event_open.2: Document write_backward Date: Mon, 24 Oct 2016 06:52:56 +0000 Message-ID: <20161024065256.160703-3-wangnan0@huawei.com> X-Mailer: git-send-email 2.10.1 In-Reply-To: <20161024065256.160703-1-wangnan0@huawei.com> References: <20161024065256.160703-1-wangnan0@huawei.com> MIME-Version: 1.0 X-Originating-IP: [10.107.193.248] X-CFilter-Loop: Reflected Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Linux 4.7 (9ecda41acb971ebd07c8fb35faf24005c0baea12) introduces write_backward attribute to perf_event_attr. Document this feature. Signed-off-by: Wang Nan Reviewed-by: Vince Weaver Cc: Michael Kerrisk --- man2/perf_event_open.2 | 57 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) -- 2.10.1 diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index 561331c..fccde79 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -245,7 +245,8 @@ struct perf_event_attr { use_clockid : 1, /* use clockid for time fields */ context_switch : 1, /* context switch data */ - __reserved_1 : 37; + write_backward : 1, /* Write ring buffer from end to beginning */ + __reserved_1 : 36; union { __u32 wakeup_events; /* wakeup every n events */ @@ -1127,6 +1128,31 @@ The advantage of this method is that it will give full information even with strict .I perf_event_paranoid settings. +.IR "write_backward" " (since Linux 4.7)" +.\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12 +This makes the resuling event use a backward ring-buffer, which +writes samples from the end of the ring-buffer to the beginning. + +It is not allowed to connect events with backward and forward +ring-buffer settings together using +.B PERF_EVENT_IOC_SET_OUTPUT. + +Backward ring-buffer is useful for ring-buffers created by readonly +.BR mmap (2). +In this case, +.IR data_tail +is useless (because user space programs are not allowed to write to it). +.IR data_head +points to the head of the most recent sample. In a backward +ring-buffer, it is easy to iterate over the whole ring-buffer by reading +samples one by one from +.IR data_head +because size of a sample can be found from decoding its header. + +For a forward read only ring-buffer in contract, +.IR data_head +points to the end of the most recent sample, but the size of a sample +can't be determined from the end of it. .TP .IR "wakeup_events" ", " "wakeup_watermark" This union sets how many samples @@ -1671,7 +1697,9 @@ And vice versa: .TP .I data_head This points to the head of the data section. -The value continuously increases, it does not wrap. +The value continuously increases (or decrease if +.IR write_backward +is set), it does not wrap. The value needs to be manually wrapped by the size of the mmap buffer before accessing the samples. @@ -2736,6 +2764,24 @@ 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 Reading from overwritable ring-buffer +Reader is unable to update +.IR data_tail +if the mapping is not +.BR PROT_WRITE . +In this case, kernel will overwrite data without considering whether +they are read or not, so ring-buffer is overwritable and +behaves like a flight recorder. To read from an overwritable +ring-buffer, setting +.IR write_backward +is suggested, or it would be hard to find a proper position to start +decoding. In addition, ring-buffer should be paused before reading +through +.BR ioctl (2) +with +.B PERF_EVENT_IOC_PAUSE_OUTPUT +to avoid racing between kernel and reader. Ring-buffer should be resumed +after finish reading. .SS rdpmc instruction Starting with Linux 3.4 on x86, you can use the .\" commit c7206205d00ab375839bd6c7ddb247d600693c09 @@ -2848,6 +2894,13 @@ The file descriptors must all be on the same CPU. The argument specifies the desired file descriptor, or \-1 if output should be ignored. + +Two events with different +.IR write_backward +settings are not allowed to be connected together using +.B PERF_EVENT_IOC_SET_OUTPUT. +.B EINVAL +is returned in this case. .TP .BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)" .\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830