From patchwork Mon Oct 24 06:52:55 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Wang Nan X-Patchwork-Id: 78859 Delivered-To: patch@linaro.org Received: by 10.140.97.247 with SMTP id m110csp2421615qge; Sun, 23 Oct 2016 23:57:27 -0700 (PDT) X-Received: by 10.98.196.17 with SMTP id y17mr25748945pff.172.1477292247376; Sun, 23 Oct 2016 23:57:27 -0700 (PDT) Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id r132si13966860pgr.231.2016.10.23.23.57.27; Sun, 23 Oct 2016 23:57:27 -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 S1757311AbcJXGzQ (ORCPT + 27 others); Mon, 24 Oct 2016 02:55:16 -0400 Received: from szxga03-in.huawei.com ([119.145.14.66]:39025 "EHLO szxga03-in.huawei.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756676AbcJXGx5 (ORCPT ); Mon, 24 Oct 2016 02:53:57 -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 CKF06322; 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:41 +0800 From: Wang Nan To: , CC: , , , , Wang Nan Subject: [PATCH v3][manpages 1/2] perf_event_open.2: Document PERF_EVENT_IOC_PAUSE_OUTPUT Date: Mon, 24 Oct 2016 06:52:55 +0000 Message-ID: <20161024065256.160703-2-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 (86e7972f690c1017fd086cdfe53d8524e68c661c) introduces PERF_EVENT_IOC_PAUSE_OUTPUT feature. Document it. Signed-off-by: Wang Nan Reviewed-by: Vince Weaver Cc: Michael Kerrisk --- man2/perf_event_open.2 | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) -- 2.10.1 diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index fade28c..561331c 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -1687,6 +1687,15 @@ the .I data_tail value should be written by user space to reflect the last read data. In this case, the kernel will not overwrite unread data. + +When the mapping is read only (without +.BR PROT_WRITE ), +setting .I data_tail is not allowed. +In this case, the kernel will overwrite data when sample coming, unless +the ring buffer is paused by a +.BR PERF_EVENT_IOC_PAUSE_OUTPUT +.BR ioctl (2) +system call before reading. .TP .IR data_offset " (since Linux 4.1)" .\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f @@ -2865,6 +2874,21 @@ The argument is a BPF program file descriptor that was created by a previous .BR bpf (2) system call. +.TP +.BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)" +.\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c +This allows pausing and resuming the event's ring-buffer. A +paused ring-buffer does not prevent generation of samples, but simply +discards the samples. The discarded samples are considered lost, +causing +.BR PERF_RECORD_LOST +to be generated when possible. + +The argument is an integer. A nonzero value pauses the ring-buffer, +zero resumes the ring-buffer. + +Pausing a read only ring buffer before reading from it without having +to worry about data being overwritten. .SS Using prctl(2) A process can enable or disable all the event groups that are attached to it using the