[RFC] introduce periodic BPF programs

internal/unix/types_linux.go

@@ -27,6 +27,10 @@ const (
 	EOPNOTSUPP = linux.EOPNOTSUPP
 )
 
+const (
+	PerfBitFreq = linux.PerfBitFreq
+)
+
 const (
 	BPF_F_NO_PREALLOC         = linux.BPF_F_NO_PREALLOC
 	BPF_F_NUMA_NODE           = linux.BPF_F_NUMA_NODE
@@ -58,6 +62,7 @@ const (
 	PERF_ATTR_SIZE_VER1       = linux.PERF_ATTR_SIZE_VER1
 	PERF_TYPE_SOFTWARE        = linux.PERF_TYPE_SOFTWARE
 	PERF_TYPE_TRACEPOINT      = linux.PERF_TYPE_TRACEPOINT
+	PERF_COUNT_SW_CPU_CLOCK   = linux.PERF_COUNT_SW_CPU_CLOCK
 	PERF_COUNT_SW_BPF_OUTPUT  = linux.PERF_COUNT_SW_BPF_OUTPUT
 	PERF_EVENT_IOC_DISABLE    = linux.PERF_EVENT_IOC_DISABLE
 	PERF_EVENT_IOC_ENABLE     = linux.PERF_EVENT_IOC_ENABLE

internal/unix/types_other.go

@@ -29,6 +29,10 @@ const (
 	EOPNOTSUPP
 )
 
+const (
+	PerfBitFreq = iota
+)
+
 // Constants are distinct to avoid breaking switch statements.
 const (
 	BPF_F_NO_PREALLOC = iota
@@ -62,6 +66,7 @@ const (
 	PERF_ATTR_SIZE_VER1
 	PERF_TYPE_SOFTWARE
 	PERF_TYPE_TRACEPOINT
+	PERF_COUNT_SW_CPU_CLOCK
 	PERF_COUNT_SW_BPF_OUTPUT
 	PERF_EVENT_IOC_DISABLE
 	PERF_EVENT_IOC_ENABLE

link/perf_event.go

@@ -59,6 +59,7 @@ const (
 	kretprobeEvent
 	uprobeEvent
 	uretprobeEvent
+	periodicEvent
 )
 
 // A perfEvent represents a perf event kernel object. Exactly one eBPF program
@@ -200,6 +201,10 @@ func attachPerfEvent(pe *perfEvent, prog *ebpf.Program) (Link, error) {
 		if t := prog.Type(); t != ebpf.TracePoint {
 			return nil, fmt.Errorf("invalid program type (expected %s): %s", ebpf.TracePoint, t)
 		}
+	case periodicEvent:
+		if t := prog.Type(); t != ebpf.PerfEvent {
+			return nil, fmt.Errorf("invalid program type (expected %s): %s", ebpf.PerfEvent, t)
+		}
 	default:
 		return nil, fmt.Errorf("unknown perf event type: %d", pe.typ)
 	}
@@ -305,6 +310,26 @@ func openTracepointPerfEvent(tid uint64, pid int) (*sys.FD, error) {
 	return sys.NewFD(fd)
 }
 
+// openPeriodicPerfEvent opens a software event based on the CPU clock and
+// sampled at specified frequency.
+func openPeriodicPerfEvent(frequency uint64, cpu int) (*sys.FD, error) {
+	attr := unix.PerfEventAttr{
+		Type:        unix.PERF_TYPE_SOFTWARE,
+		Config:      unix.PERF_COUNT_SW_CPU_CLOCK,
+		Sample_type: unix.PERF_SAMPLE_RAW,
+		Bits:        unix.PerfBitFreq,
+		Sample:      frequency,
+		Wakeup:      1,
+	}
+
+	fd, err := unix.PerfEventOpen(&attr, -1, cpu, -1, unix.PERF_FLAG_FD_CLOEXEC)
+	if err != nil {
+		return nil, fmt.Errorf("opening periodic perf event: %w", err)
+	}
+
+	return sys.NewFD(fd)
+}
+
 func sanitizePath(base string, path ...string) (string, error) {
 	l := filepath.Join(path...)
 	p := filepath.Join(base, l)

link/periodic.go

@@ -0,0 +1,93 @@
+package link
+
+import (
+	"fmt"
+
+	"github.com/cilium/ebpf"
+	"github.com/cilium/ebpf/internal"
+)
+
+// PeriodicOptions defines additional parameters that will be used
+// when loading periodic samplers.
+type PeriodicOptions struct {
+	// Arbitrary value that can be fetched from an eBPF program
+	// via `bpf_get_attach_cookie()`.
+	//
+	// Needs kernel 5.15+.
+	Cookie uint64
+}
+
+// Periodic attaches the given eBPF program to a periodic perf event on given
+// cpu and given frequency.
+//
+// This is mainly useful when doing sample-based tracing or monitoring.
+//
+// Losing the reference to the resulting Link (tp) will close the Periodic event
+// and prevent further execution of prog. The Link must be Closed during
+// program shutdown to avoid leaking system resources.
+func Periodic(frequency uint64, cpu int, prog *ebpf.Program, opts *PeriodicOptions) (Link, error) {
+	possibleCPUs, err := internal.PossibleCPUs()
+	if err != nil {
+		return nil, err
+	}
+
+	if frequency == 0 {
+		return nil, fmt.Errorf("frequency can not be 0: %w", errInvalidInput)
+	}
+	if cpu < 0 || cpu > possibleCPUs {
+		return nil, fmt.Errorf("cpu must be greater to 0 and lower than %d: %w", possibleCPUs, errInvalidInput)
+	}
+	if prog == nil {
+		return nil, fmt.Errorf("prog cannot be nil: %w", errInvalidInput)
+	}
+	if prog.Type() != ebpf.PerfEvent {
+		return nil, fmt.Errorf("eBPF program type %s is not a PerfEvent: %w", prog.Type(), errInvalidInput)
+	}
+
+	fd, err := openPeriodicPerfEvent(frequency, cpu)
+	if err != nil {
+		return nil, err
+	}
+
+	var cookie uint64
+	if opts != nil {
+		cookie = opts.Cookie
+	}
+
+	pe := &perfEvent{
+		typ:    periodicEvent,
+		cookie: cookie,
+		fd:     fd,
+	}
+
+	lnk, err := attachPerfEvent(pe, prog)
+	if err != nil {
+		pe.Close()
+		return nil, err
+	}
+
+	return lnk, nil
+}
+
+// PeriodicAllCpus attaches the given eBPF program to a periodic event fired at
+// given frequency on each cpu.
+//
+// See Periodic above for more information.
+func PeriodicAllCpus(frequency uint64, prog *ebpf.Program, opts *PeriodicOptions) ([]Link, error) {
+	possibleCPUs, err := internal.PossibleCPUs()
+	if err != nil {
+		return nil, err
+	}
+
+	links := make([]Link, possibleCPUs)
+
+	for i := 0; i < len(links); i++ {
+		links[i], err = Periodic(frequency, i, prog, opts)
+		if err != nil {
+			// Links are automatically closed "some" time after the last reference is lost
+			return nil, fmt.Errorf("failed to link periodic prog on CPU %d: %w", i, err)
+		}
+	}
+
+	return links, nil
+}