linux-kernel - [PATCH 5/5] tracing/user_events: Add auto-del flag documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20230530235304.2726-6-beaub@linux.microsoft.com>
Date:   Tue, 30 May 2023 16:53:04 -0700
From:   Beau Belgrave <beaub@...ux.microsoft.com>
To:     rostedt@...dmis.org, mhiramat@...nel.org
Cc:     linux-kernel@...r.kernel.org, linux-trace-kernel@...r.kernel.org,
        ast@...nel.org, dcook@...ux.microsoft.com
Subject: [PATCH 5/5] tracing/user_events: Add auto-del flag documentation

There is now a flag for user_events to use when registering events to
auto delete events upon the last reference put. Add the new flag,
USER_EVENT_REG_AUTO_DEL, to user_events documentation files to let
people know how to use it.

Signed-off-by: Beau Belgrave <beaub@...ux.microsoft.com>
---
 Documentation/trace/user_events.rst | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst
index f79987e16cf4..946da25be812 100644
--- a/Documentation/trace/user_events.rst
+++ b/Documentation/trace/user_events.rst
@@ -39,6 +39,14 @@ DIAG_IOCSREG.
 
 This command takes a packed struct user_reg as an argument::
 
+  enum user_reg_flag {
+        /* Event will auto delete upon last reference closing */
+        USER_EVENT_REG_AUTO_DEL		= 1U << 0,
+
+        /* This value or above is currently non-ABI */
+        USER_EVENT_REG_MAX		= 1U << 1,
+  };
+
   struct user_reg {
         /* Input: Size of the user_reg structure being used */
         __u32 size;
@@ -49,7 +57,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 can be any of the above user_reg_flag values */
         __u16 flags;
 
         /* Input: Address to update when enabled */
@@ -73,10 +81,13 @@ 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.
-  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.
++ 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.
+
+  **USER_EVENT_REG_AUTO_DEL**
+        When the last reference is closed for the event, the event will delete
+        itself automatically as if the delete IOCTL was issued by a user.
 
 + enable_addr: The address of the value to use to reflect event status. This
   must be naturally aligned and write accessible within the user program.
-- 
2.25.1