[PATCH 7/7] tracing/user_events: Update ABI documentation to align to bits vs bytes

[Beau Belgrave]

Update the documentation to reflect the new ABI requirements and how to
use the byte index with the mask properly to check event status.

Signed-off-by: Beau Belgrave <beaub@xxxxxxxxxxxxxxxxxxx>
---
 Documentation/trace/user_events.rst | 46 +++++++++++++----------------
 1 file changed, 21 insertions(+), 25 deletions(-)

diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst
index c180936f49fc..6aabdb126f2e 100644
--- a/Documentation/trace/user_events.rst
+++ b/Documentation/trace/user_events.rst
@@ -20,14 +20,15 @@ dynamic_events is the same as the ioctl with the u: prefix applied.
 
 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 gives back two ints to the program for each event. The first int is the
-status index. This index describes which byte in the
+process gives back three ints to the program for each event. The first int is
+the status index. This index describes which byte in the
 /sys/kernel/debug/tracing/user_events_status file represents this event. The
-second int is the write index. This index describes the data when a write() or
-writev() is called on the /sys/kernel/debug/tracing/user_events_data file.
+second int is the mask to use on the byte to check the event status. The third
+int is the write index which describes the data when a write() or writev() is
+called on the /sys/kernel/debug/tracing/user_events_data file.
 
-The structures referenced in this document are contained with the
-/include/uap/linux/user_events.h file in the source tree.
+The structures referenced in this document are contained within the
+/include/uapi/linux/user_events.h file in the source tree.
 
 **NOTE:** *Both user_events_status and user_events_data are under the tracefs
 filesystem and may be mounted at different paths than above.*
@@ -44,6 +45,7 @@ This command takes a struct user_reg as an argument::
         u32 size;
         u64 name_args;
         u32 status_index;
+        u32 status_mask;
         u32 write_index;
   };
 
@@ -112,14 +114,19 @@ writev() calls when something is actively attached to the event.
 
 User programs call mmap() on /sys/kernel/debug/tracing/user_events_status to
 check the status for each event that is registered. The byte to check in the
-file is given back after the register ioctl() via user_reg.status_index.
+file is given back after the register ioctl() via user_reg.status_index. The
+byte needs to be AND'd with the user_reg.status_mask value to check if the
+event is enabled currently.
+
 Currently the size of user_events_status is a single page, however, custom
 kernel configurations can change this size to allow more user based events. In
 all cases the size of the file is a multiple of a page size.
 
-For example, if the register ioctl() gives back a status_index of 3 you would
-check byte 3 of the returned mmap data to see if anything is attached to that
-event.
+For example, if the register ioctl() gives back a status_index of 3 and a mask
+of 1 you would check byte 3 of the returned mmap data and then AND the result
+with 1 (e.g. status_page[3] & 1) to see if anything is attached to that event.
+A helper function is available called user_event_enabled() which does this for
+you.
 
 Administrators can easily check the status of all registered events by reading
 the user_events_status file directly via a terminal. The output is as follows::
@@ -137,7 +144,7 @@ For example, on a system that has a single event the output looks like this::
 
   Active: 1
   Busy: 0
-  Max: 4096
+  Max: 32768
 
 If a user enables the user event via ftrace, the output would change to this::
 
@@ -145,21 +152,10 @@ If a user enables the user event via ftrace, the output would change to this::
 
   Active: 1
   Busy: 1
-  Max: 4096
-
-**NOTE:** *A status index of 0 will never be returned. This allows user
-programs to have an index that can be used on error cases.*
-
-Status Bits
-^^^^^^^^^^^
-The byte being checked will be non-zero if anything is attached. Programs can
-check specific bits in the byte to see what mechanism has been attached.
-
-The following values are defined to aid in checking what has been attached:
-
-**EVENT_STATUS_FTRACE** - Bit set if ftrace has been attached (Bit 0).
+  Max: 32768
 
-**EVENT_STATUS_PERF** - Bit set if perf has been attached (Bit 1).
+**NOTE:** *A status index of 0 with a mask of 1 will never be returned. This
+allows user programs to have an index and mask that can be used on error cases.*
 
 Writing Data
 ------------
-- 
2.25.1