From patchwork Thu Oct 5 01:53:15 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steven Rostedt X-Patchwork-Id: 148665 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2016:b0:403:3b70:6f57 with SMTP id fe22csp14261vqb; Wed, 4 Oct 2023 18:52:52 -0700 (PDT) X-Google-Smtp-Source: AGHT+IGREAc+I71xGTql5+qFZ9mF8uLu5Wkg24G4XJTM0i3jwrraABGKBaadJeDvJH/Qlnh1W3S+ X-Received: by 2002:a17:902:e547:b0:1c7:56d8:9068 with SMTP id n7-20020a170902e54700b001c756d89068mr4046772plf.31.1696470772010; Wed, 04 Oct 2023 18:52:52 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1696470771; cv=none; d=google.com; s=arc-20160816; b=HuI9lmNk5w/W2gP/fajDwN9aAxN/dHJZtJKHNozjKjhFHXnNxgTv2MgE8oGywBZHIn O/U0QKUWrdOetGuNGF1rZc/v7mveGHKkfumIKa6IIi30ezMfmuaBQT8sRo73+DcCfe8O y2GhOU+3L6qvWSs7ceLm+4F8+QOod2Um4e81LrpUfOSljMhAAaWews5n8IIjU1YhTbat 9qgTe/Z6Um4jbMHvRxL+KpCMBGwNUZf4Ekha5SApM5TSzbrwSvhDKJ+YbrtoTNcR7+PP gvh8CWCRCUNkOmgQJ6h7ORGcTIFSznZv82b+FlZQ9drFzALkao4pzkqmJg+8yHoy8HOy 0k+g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:mime-version:references:subject:cc:to:from:date :user-agent:message-id; bh=cZ2pn8Hu5CPQT/93VuTAIHAT67G0PNB9WikvLnsefNI=; fh=ozzW+1tVKI85SOasb1/L7GiS+b2ejaUssMTcKhKt6Zw=; b=FT+cOA5jReujf6xDa11cldpVVTgSGg8E0CFgUHYUIHz6NMwmwdncPxw+gZHvAAtd28 laCktLMQ5K4Ai4hD9q4LxPe5eKa2XstmA35xQIZ0wbtQ+tUADY6OwkiCW9YLkR7v8Ejt YGgpu+NwD8Q5I/TLMG2aVtPRSeNVJEat864Z6FUjWx1cZ1XtJ6wkQcS/Op2egYHP0M6L 88IyEhjiKDC57M+lMRRuOHonyNqXs+2vK1lLM1XjpVAgaWIzId2PfCrd7LR6j2j2wpDk 1pfPn2AR6ri/vUVvbdkDoCxo31jcWsIsRW5HFHoXhCjPGx8+Mznpi5/fcp8HmWXLB0v0 ZLtw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:4 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from howler.vger.email (howler.vger.email. [2620:137:e000::3:4]) by mx.google.com with ESMTPS id q7-20020a17090311c700b001bde9e8a29fsi484557plh.183.2023.10.04.18.52.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 04 Oct 2023 18:52:51 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:4 as permitted sender) client-ip=2620:137:e000::3:4; Authentication-Results: mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:4 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: from out1.vger.email (depot.vger.email [IPv6:2620:137:e000::3:0]) by howler.vger.email (Postfix) with ESMTP id 44B9A856166D; Wed, 4 Oct 2023 18:52:51 -0700 (PDT) X-Virus-Status: Clean X-Virus-Scanned: clamav-milter 0.103.10 at howler.vger.email Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S244419AbjJEBwt (ORCPT + 19 others); Wed, 4 Oct 2023 21:52:49 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:32978 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S244371AbjJEBwq (ORCPT ); Wed, 4 Oct 2023 21:52:46 -0400 Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2FF0D9E for ; Wed, 4 Oct 2023 18:52:43 -0700 (PDT) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A8139C43397; Thu, 5 Oct 2023 01:52:42 +0000 (UTC) Received: from rostedt by gandalf with local (Exim 4.96) (envelope-from ) id 1qoDYl-005FKc-1x; Wed, 04 Oct 2023 21:53:51 -0400 Message-ID: <20231005015351.417870465@goodmis.org> User-Agent: quilt/0.66 Date: Wed, 04 Oct 2023 21:53:15 -0400 From: Steven Rostedt To: linux-kernel@vger.kernel.org Cc: Masami Hiramatsu , Mark Rutland , Andrew Morton , Beau Belgrave Subject: [for-next][PATCH 5/7] tracing/user_events: Document persist event flags References: <20231005015310.859143353@goodmis.org> MIME-Version: 1.0 X-Spam-Status: No, score=-1.6 required=5.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,RCVD_IN_DNSWL_BLOCKED,SPF_HELO_NONE, SPF_PASS autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (howler.vger.email [0.0.0.0]); Wed, 04 Oct 2023 18:52:51 -0700 (PDT) X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1778878536050929330 X-GMAIL-MSGID: 1778878536050929330 From: Beau Belgrave Users need to know how to make events persist now that we allow for that. We also now allow the dynamic_events file to create events by utilizing the persist flag during event register. Add back in to documentation how /sys/kernel/tracing/dynamic_events can be used to create persistent user_events. Add a section under registering for the currently supported flags (USER_EVENT_REG_PERSIST) and the required permissions. Add a note under deleting that deleting a persistent event also requires sufficient permission. Link: https://lkml.kernel.org/r/20230912180704.1284-4-beaub@linux.microsoft.com Signed-off-by: Beau Belgrave Signed-off-by: Steven Rostedt (Google) --- Documentation/trace/user_events.rst | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst index f9530d0ac5d3..d8f12442aaa6 100644 --- a/Documentation/trace/user_events.rst +++ b/Documentation/trace/user_events.rst @@ -14,6 +14,11 @@ Programs can view status of the events via /sys/kernel/tracing/user_events_status and can both register and write data out via /sys/kernel/tracing/user_events_data. +Programs can also use /sys/kernel/tracing/dynamic_events to register and +delete user based events via the u: prefix. The format of the command to +dynamic_events is the same as the ioctl with the u: prefix applied. This +requires CAP_PERFMON due to the event persisting, otherwise -EPERM is returned. + Typically programs will register a set of events that they wish to expose to tools that can read trace_events (such as ftrace and perf). The registration process tells the kernel which address and bit to reflect if any tool has @@ -45,7 +50,7 @@ This command takes a packed struct user_reg as an argument:: /* Input: Enable size in bytes at address */ __u8 enable_size; - /* Input: Flags for future use, set to 0 */ + /* Input: Flags to use, if any */ __u16 flags; /* Input: Address to update when enabled */ @@ -69,7 +74,7 @@ The struct user_reg requires all the above inputs to be set appropriately. This must be 4 (32-bit) or 8 (64-bit). 64-bit values are only allowed to be used on 64-bit kernels, however, 32-bit can be used on all kernels. -+ flags: The flags to use, if any. For the initial version this must be 0. ++ flags: The flags to use, if any. Callers should first attempt to use flags and retry without flags to ensure support for lower versions of the kernel. If a flag is not supported -EINVAL is returned. @@ -80,6 +85,13 @@ The struct user_reg requires all the above inputs to be set appropriately. + name_args: The name and arguments to describe the event, see command format for details. +The following flags are currently supported. + ++ USER_EVENT_REG_PERSIST: The event will not delete upon the last reference + closing. Callers may use this if an event should exist even after the + process closes or unregisters the event. Requires CAP_PERFMON otherwise + -EPERM is returned. + Upon successful registration the following is set. + write_index: The index to use for this file descriptor that represents this @@ -141,7 +153,10 @@ event (in both user and kernel space). User programs should use a separate file to request deletes than the one used for registration due to this. **NOTE:** By default events will auto-delete when there are no references left -to the event. Flags in the future may change this logic. +to the event. If programs do not want auto-delete, they must use the +USER_EVENT_REG_PERSIST flag when registering the event. Once that flag is used +the event exists until DIAG_IOCSDEL is invoked. Both register and delete of an +event that persists requires CAP_PERFMON, otherwise -EPERM is returned. Unregistering -------------