tools/lib/perf/Documentation/libperf.txt

File Facts

System

Linux kernel

Corpus path

tools/lib/perf/Documentation/libperf.txt

Extension

.txt

Size

7854 bytes

Lines

254

Domain

Support Tooling And Documentation

Bucket

tools

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.

• Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
• Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

• perf/core.h
• perf/cpumap.h
• perf/threadmap.h
• perf/evlist.h
• perf/evsel.h
• perf/mmap.h
• perf/event.h

Detected Declarations

• struct perf_cpu_map
• struct perf_thread_map
• struct perf_evlist
• struct perf_evsel
• struct perf_counts_values
• struct perf_mmap
• struct perf_record_mmap
• struct perf_record_mmap2
• struct perf_record_comm
• struct perf_record_namespaces
• struct perf_record_fork
• struct perf_record_lost
• struct perf_record_lost_samples
• struct perf_record_read
• struct perf_record_throttle
• struct perf_record_ksymbol
• struct perf_record_bpf_event
• struct perf_record_sample
• struct perf_record_switch
• struct perf_record_header_attr
• struct perf_record_record_cpu_map
• struct perf_record_cpu_map_data
• struct perf_record_cpu_map
• struct perf_record_event_update_cpus
• struct perf_record_event_update_scale
• struct perf_record_event_update
• struct perf_trace_event_type
• struct perf_record_header_event_type
• struct perf_record_header_tracing_data
• struct perf_record_header_build_id
• struct perf_record_id_index
• struct perf_record_auxtrace_info
• struct perf_record_auxtrace
• struct perf_record_auxtrace_error
• struct perf_record_aux
• struct perf_record_itrace_start
• struct perf_record_thread_map_entry
• struct perf_record_thread_map
• struct perf_record_stat_config_entry
• struct perf_record_stat_config
• struct perf_record_stat
• struct perf_record_stat_round
• struct perf_record_time_conv
• struct perf_record_header_feature
• struct perf_record_compressed
• struct perf_record_compressed2
• struct perf_record_schedstat_cpu
• struct perf_record_schedstat_domain

Annotated Snippet

struct perf_counts_values {
          union {
                  struct {
                          uint64_t val;
                          uint64_t ena;
                          uint64_t run;
                  };
                  uint64_t values[3];
          };
  };

  struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
  void perf_evsel__delete(struct perf_evsel *evsel);
  int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
                       struct perf_thread_map *threads);
  void perf_evsel__close(struct perf_evsel *evsel);
  void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx);
  int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
  void perf_evsel__munmap(struct perf_evsel *evsel);
  void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread);
  int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread,
                       struct perf_counts_values *count);
  int perf_evsel__enable(struct perf_evsel *evsel);
  int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
  int perf_evsel__disable(struct perf_evsel *evsel);
  int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
  struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
  struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
  struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
--

*API to handle maps (perf ring buffers):*

[source,c]
--
  #include <perf/mmap.h>

  struct perf_mmap;

  void perf_mmap__consume(struct perf_mmap *map);
  int perf_mmap__read_init(struct perf_mmap *map);
  void perf_mmap__read_done(struct perf_mmap *map);
  union perf_event *perf_mmap__read_event(struct perf_mmap *map);
--

*Structures to access perf API events:*

[source,c]
--
  #include <perf/event.h>

  struct perf_record_mmap;
  struct perf_record_mmap2;
  struct perf_record_comm;
  struct perf_record_namespaces;
  struct perf_record_fork;
  struct perf_record_lost;
  struct perf_record_lost_samples;
  struct perf_record_read;
  struct perf_record_throttle;
  struct perf_record_ksymbol;
  struct perf_record_bpf_event;
  struct perf_record_sample;
  struct perf_record_switch;
  struct perf_record_header_attr;
  struct perf_record_record_cpu_map;
  struct perf_record_cpu_map_data;
  struct perf_record_cpu_map;
  struct perf_record_event_update_cpus;
  struct perf_record_event_update_scale;

Annotation

• Immediate include surface: `perf/core.h`, `perf/cpumap.h`, `perf/threadmap.h`, `perf/evlist.h`, `perf/evsel.h`, `perf/mmap.h`, `perf/event.h`.
• Detected declarations: `struct perf_cpu_map`, `struct perf_thread_map`, `struct perf_evlist`, `struct perf_evsel`, `struct perf_counts_values`, `struct perf_mmap`, `struct perf_record_mmap`, `struct perf_record_mmap2`, `struct perf_record_comm`, `struct perf_record_namespaces`.
• Atlas domain: Support Tooling And Documentation / tools.
• Implementation status: atlas-only.

Implementation Notes

• This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
• Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
• Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.