Documentation/trace/user_events.rst

Source file repositories/reference/linux-study-clean/Documentation/trace/user_events.rst

File Facts

System
Linux kernel
Corpus path
Documentation/trace/user_events.rst
Extension
.rst
Size
11504 bytes
Lines
305
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct user_reg {
        /* Input: Size of the user_reg structure being used */
        __u32 size;

        /* Input: Bit in enable address to use */
        __u8 enable_bit;

        /* Input: Enable size in bytes at address */
        __u8 enable_size;

        /* Input: Flags to use, if any */
        __u16 flags;

        /* Input: Address to update when enabled */
        __u64 enable_addr;

        /* Input: Pointer to string with event name, description and flags */
        __u64 name_args;

        /* Output: Index of the event to use when writing data */
        __u32 write_index;
  } __attribute__((__packed__));

The struct user_reg requires all the above inputs to be set appropriately.

+ size: This must be set to sizeof(struct user_reg).

+ enable_bit: The bit to reflect the event status at the address specified by
  enable_addr.

+ enable_size: The size of the value specified by enable_addr.
  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.
  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.

+ 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.

+ 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.

+ USER_EVENT_REG_MULTI_FORMAT: The event can contain multiple formats. This
  allows programs to prevent themselves from being blocked when their event
  format changes and they wish to use the same name. When this flag is used the
  tracepoint name will be in the new format of "name.unique_id" vs the older
  format of "name". A tracepoint will be created for each unique pair of name
  and format. This means if several processes use the same name and format,
  they will use the same tracepoint. If yet another process uses the same name,
  but a different format than the other processes, it will use a different
  tracepoint with a new unique id. Recording programs need to scan tracefs for
  the various different formats of the event name they are interested in
  recording. The system name of the tracepoint will also use "user_events_multi"
  instead of "user_events". This prevents single-format event names conflicting
  with any multi-format event names within tracefs. The unique_id is output as
  a hex string. Recording programs should ensure the tracepoint name starts with
  the event name they registered and has a suffix that starts with . and only
  has hex characters. For example to find all versions of the event "test" you
  can use the regex "^test\.[0-9a-fA-F]+$".

Annotation

Implementation Notes