Struct nc::types::perf_event_mmap_page_t

#[repr(C)]
pub struct perf_event_mmap_page_t {
    pub version: u32,
    pub compat_version: u32,
    pub lock: u32,
    pub index: u32,
    pub offset: i64,
    pub time_enabled: u64,
    pub time_running: u64,
    pub cap: perf_event_mmap_page_cap_t,
    pub pmc_width: u16,
    pub time_shift: u16,
    pub time_mult: u32,
    pub time_offset: u64,
    pub time_zero: u64,
    pub size: u32,
    pub data_head: u64,
    pub data_tail: u64,
    pub data_offset: u64,
    pub data_size: u64,
    pub aux_head: u64,
    pub aux_tail: u64,
    pub aux_offset: u64,
    pub aux_size: u64,
    // some fields omitted
}

Structure of the page that can be mapped via mmap

Fields

version: u32

version number of this structure

compat_version: u32

lowest version this is compat with

lock: u32

Bits needed to read the hw events in user-space.

  u32 seq, time_mult, time_shift, index, width;
  u64 count, enabled, running;
  u64 cyc, time_offset;
  s64 pmc = 0;

  do {
    seq = pc->lock;
    barrier()

    enabled = pc->time_enabled;
    running = pc->time_running;

    if (pc->cap_usr_time && enabled != running) {
      cyc = rdtsc();
      time_offset = pc->time_offset;
      time_mult   = pc->time_mult;
      time_shift  = pc->time_shift;
    }

    index = pc->index;
    count = pc->offset;
    if (pc->cap_user_rdpmc && index) {
      width = pc->pmc_width;
      pmc = rdpmc(index - 1);
    }

    barrier();
  } while (pc->lock != seq);

NOTE: for obvious reason this only works on self-monitoring processes. seqlock for synchronization

index: u32

hardware event identifier

offset: i64

add to hardware event value

time_enabled: u64

time event active

time_running: u64

time event on cpu

cap: perf_event_mmap_page_cap_t

pmc_width: u16

If cap_user_rdpmc this field provides the bit-width of the value read using the rdpmc() or equivalent instruction. This can be used to sign extend the result like:

pmc <<= 64 - width; pmc >>= 64 - width; // signed shift right count += pmc;

time_shift: u16

If cap_usr_time the below fields can be used to compute the time delta since time_enabled (in ns) using rdtsc or similar.

u64 quot, rem; u64 delta;

quot = (cyc >> time_shift); rem = cyc & (((u64)1 << time_shift) - 1); delta = time_offset + quot * time_mult + ((rem * time_mult) >> time_shift);

Where time_offset,time_mult,time_shift and cyc are read in the seqcount loop described above. This delta can then be added to enabled and possible running (if index), improving the scaling:

enabled += delta; if (index) running += delta;

quot = count / running; rem = count % running; count = quot * enabled + (rem * enabled) / running;

time_mult: u32

time_offset: u64

time_zero: u64

If cap_usr_time_zero, the hardware clock (e.g. TSC) can be calculated from sample timestamps.

time = timestamp - time_zero; quot = time / time_mult; rem = time % time_mult; cyc = (quot << time_shift) + (rem << time_shift) / time_mult;

And vice versa:

quot = cyc >> time_shift; rem = cyc & (((u64)1 << time_shift) - 1); timestamp = time_zero + quot * time_mult + ((rem * time_mult) >> time_shift);

size: u32

Header size up to __reserved[] fields.

data_head: u64

Control data for the mmap() data buffer.

User-space reading the @data_head value should issue an smp_rmb() after reading this value.

When the mapping is PROT_WRITE the @data_tail value should be written by userspace to reflect the last read data, after issueing an smp_mb() to separate the data read from the ->data_tail store. In this case the kernel will not over-write unread data.

See perf_output_put_handle() for the data ordering.

data_{offset,size} indicate the location and size of the perf record buffer within the mmapped area. head in the data section

data_tail: u64

user-space written tail

data_offset: u64

where the buffer starts

data_size: u64

data buffer size

aux_head: u64

AUX area is defined by aux_{offset,size} fields that should be set by the userspace, so that

aux_offset >= data_offset + data_size

prior to mmap()ing it. Size of the mmap()ed area should be aux_size.

Ring buffer pointers aux_{head,tail} have the same semantics as data_{head,tail} and same ordering rules apply.

aux_tail: u64

aux_offset: u64

aux_size: u64