From nobody Sat Jan 3 06:31:38 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A88ABE936F4 for ; Thu, 5 Oct 2023 01:52:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S244431AbjJEBwt (ORCPT ); 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 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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. =20 +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 retu= rned. + 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 registrati= on 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 argumen= t:: /* Input: Enable size in bytes at address */ __u8 enable_size; =20 - /* Input: Flags for future use, set to 0 */ + /* Input: Flags to use, if any */ __u16 flags; =20 /* Input: Address to update when enabled */ @@ -69,7 +74,7 @@ The struct user_reg requires all the above inputs to be s= et 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. =20 -+ 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 ens= ure support for lower versions of the kernel. If a flag is not supported -EI= NVAL 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 for= mat for details. =20 +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. =20 + write_index: The index to use for this file descriptor that represents t= his @@ -141,7 +153,10 @@ event (in both user and kernel space). User programs s= hould use a separate file to request deletes than the one used for registration due to this. =20 **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 o= f an +event that persists requires CAP_PERFMON, otherwise -EPERM is returned. =20 Unregistering ------------- --=20 2.40.1