rte_pmu.h(3)

💖 NAME 💖

rte_pmu.h — bestie, this is the header that runs the whole Performance Monitoring Unit situation in DPDK. It's a library functions manual page, and we are gonna get into it. 🎀

---

✨ SYNOPSIS ✨

First, the includes, no cap, exactly these:

#include <linux/perf_event.h>
#include <rte_atomic.h>
#include <rte_branch_prediction.h>
#include <rte_common.h>
#include <rte_compat.h>
#include <rte_debug.h>
#include <rte_lcore.h>

🧸 Data Structures

• struct rte_pmu_event_group
• struct rte_pmu

🧸 Macros

• #define RTE_MAX_NUM_GROUP_EVENTS 8

🧸 Functions

static __rte_experimental __rte_always_inline uint64_t
    __rte_pmu_read_userpage (struct perf_event_mmap_page *pc)
__rte_experimental int __rte_pmu_enable_group (struct
    rte_pmu_event_group *group)
__rte_experimental int rte_pmu_init (void)
__rte_experimental void rte_pmu_fini (void)
__rte_experimental int rte_pmu_add_event (const char *name)
static __rte_experimental __rte_always_inline uint64_t rte_pmu_read
    (unsigned int index)

🧸 Variables

• struct rte_pmu rte_pmu

---

🌸 Detailed Description 🌸

Performance Monitoring Unit (PMU) event tracing operations 💅

So like, what is this file even doing? It defines the generic API and types you need to set up PMU and read selected counters at runtime. And here's the tea: the exported functions are generally not MT-safe. The one glow-up exception is rte_pmu_read(), which is totally fine to call concurrently once everything has been set up. ✨

To initialize the library, you need this exact sequence of calls, and they all have to be performed by the same EAL thread:

rte_pmu_init() rte_pmu_add_event()

Afterwards all threads can read events by calling rte_pmu_read(). Slay. 👑

Definition in file rte_pmu.h.

---

🎀 Macro Definition Documentation 🎀

#define RTE_MAX_NUM_GROUP_EVENTS 8

Maximum number of events in a group. That's it, that's the whole vibe — 8, periodt. 🦋

Definition at line 48 of file rte_pmu.h.

---

💜 Function Documentation 💜

__rte_experimental __rte_always_inline uint64_t __rte_pmu_read_userpage (struct perf_event_mmap_page * pc) [static]

⚠️ EXPERIMENTAL: this API may change without prior notice.

Read PMU counter. 🫶

🚨 This should not be called directly. Bestie, do NOT just ring it up. It's not for you, it's an internal situation.

Parameters

• pc — Pointer to the mmapped user page.

Returns

• Counter value read from hardware.

Definition at line 95 of file rte_pmu.h.

---

__rte_experimental int __rte_pmu_enable_group (struct rte_pmu_event_group * group)

⚠️ EXPERIMENTAL: this API may change without prior notice.

Enable group of events on the calling lcore. 💫

🚨 This should not be called directly. Same energy as above — hands off, it's internal.

Parameters

• group — Pointer to the group which will be enabled.

Returns

• 0 in case of success, negative value otherwise.

---

__rte_experimental int rte_pmu_init (void )

⚠️ EXPERIMENTAL: this API may change without prior notice.

Initialize PMU library. The opening act. 🎬

Returns

• 0 in case of success, negative value otherwise.

---

__rte_experimental void rte_pmu_fini (void )

⚠️ EXPERIMENTAL: this API may change without prior notice.

Finalize PMU library. Closing time, pack it up. 🧹

---

__rte_experimental int rte_pmu_add_event (const char * name)

⚠️ EXPERIMENTAL: this API may change without prior notice.

Add event to the group of enabled events. ✨

Parameters

• name — Name of an event listed under /sys/bus/event_source/devices/pmu/events, where PMU is a placeholder for an event source.

Returns

• Event index in case of success, negative value otherwise.

---

__rte_experimental __rte_always_inline uint64_t rte_pmu_read (unsigned int index) [static]

⚠️ EXPERIMENTAL: this API may change without prior notice.

Read hardware counter configured to count occurrences of an event. 🔥

Okay this one's important so listen up: this is called by an lcore (EAL thread) bound exclusively to particular CPU and may not work as expected if it gets migrated elsewhere. The reason being, the event group is pinned hence not supposed to be multiplexed with any other events. Also!! This is the only API which can be called concurrently by different lcores. Main character behavior, honestly. 👑

Parameters

• index — Index of an event to be read.

Returns

• Event value read from register. In case of errors or lack of support, 0 is returned. In other words, stream of zeros in a trace file indicates problem with reading particular PMU event register. 😭

Definition at line 204 of file rte_pmu.h.

---

🦋 Variable Documentation 🦋

struct rte_pmu rte_pmu [extern]

PMU state container. It holds the state. That's the job. 💅

---

⭐ Author ⭐

Generated automatically by Doxygen for DPDK from the source code. (Not a human, just a robot doing its little thing. Respect. 🤖)

---

And that's the whole page, bestie!! This fine piece of documentation came to you courtesy of DPDK, Version 25.11.3, filed under rte_pmu.h(3) — go read some counters and hydrate. 💖✨🎀🫶