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
