clj-ebpf.ringbuf — org.clojars.pgdad/clj-ebpf 0.6.7

Ring buffer helpers for BPF event streaming.

Ring buffers are the modern way to stream events from BPF programs to userspace. They're more efficient than perf buffers and support variable-sized records.

Usage: (require '[clj-ebpf.ringbuf :as rb])

;; Reserve space in ring buffer (rb/build-ringbuf-reserve event-ringbuf-fd 64) ;; r0 = pointer to reserved space, or NULL on failure

;; After writing data, submit (rb/build-ringbuf-submit :r9)

;; Or discard if not needed (rb/build-ringbuf-discard :r9)

BPF-FUNC-ringbuf-discard clj

BPF-FUNC-ringbuf-output clj

BPF-FUNC-ringbuf-query clj

BPF-FUNC-ringbuf-reserve clj

BPF-FUNC-ringbuf-submit clj

BPF-RB-AVAIL-DATA clj

BPF-RB-CONS-POS clj

BPF-RB-FORCE-WAKEUP clj

BPF-RB-NO-WAKEUP clj

BPF-RB-PROD-POS clj

BPF-RB-RING-SIZE clj

build-ringbuf-discard clj

(build-ringbuf-discard ptr-reg)

(build-ringbuf-discard ptr-reg flags)

Discard a previously reserved ring buffer entry.

Use this when you decide not to send an event after reserving space. After calling discard, the reserved pointer becomes invalid.

Args: ptr-reg: Register containing pointer from bpf_ringbuf_reserve flags: Discard flags (default 0): - 0: Normal discard - BPF-RB-NO-WAKEUP: Don't wake up reader

Returns: Vector of instructions

build-ringbuf-output clj

(build-ringbuf-output ringbuf-fd data-reg size flags)

Output data directly to ring buffer (combines reserve+copy+submit).

This is simpler but less flexible than the reserve/submit pattern. Use this when you have the complete event data ready to send.

Args: ringbuf-fd: Ring buffer map file descriptor data-reg: Register with pointer to data size: Size of data to output flags: Output flags: - 0: Normal output - BPF-RB-NO-WAKEUP: Don't wake up reader - BPF-RB-FORCE-WAKEUP: Force wake up reader

Returns: Vector of instructions Result: r0 = 0 on success, negative on failure

build-ringbuf-query clj

(build-ringbuf-query ringbuf-fd flags)

Query ring buffer properties.

Args: ringbuf-fd: Ring buffer map file descriptor flags: Query type: - BPF-RB-AVAIL-DATA: Available data for consumption - BPF-RB-RING-SIZE: Total ring buffer size - BPF-RB-CONS-POS: Consumer position - BPF-RB-PROD-POS: Producer position

Returns: Vector of instructions Result: r0 = queried value

build-ringbuf-reserve clj

(build-ringbuf-reserve ringbuf-fd size)

(build-ringbuf-reserve ringbuf-fd size flags)

Reserve space in a ring buffer.

Args: ringbuf-fd: Ring buffer map file descriptor size: Number of bytes to reserve flags: Reserved flags, must be 0 (default)

Returns: Vector of instructions Result: r0 = pointer to reserved space, or NULL on failure

Example: (build-ringbuf-reserve event-ringbuf-fd 64)

Usage pattern:

1. Reserve space with build-ringbuf-reserve
2. Check r0 for NULL (reservation failed)
3. Save pointer to callee-saved register (e.g., r9)
4. Write event data to reserved space
5. Submit with build-ringbuf-submit

build-ringbuf-reserve-or-skip clj

(build-ringbuf-reserve-or-skip ringbuf-fd size save-reg skip-label)

Reserve ring buffer space, jumping to skip-label if reservation fails.

This is a common pattern that combines reserve + NULL check.

Args: ringbuf-fd: Ring buffer map file descriptor size: Number of bytes to reserve save-reg: Callee-saved register to save pointer (:r6-:r9) skip-label: Label to jump to if reservation fails

Returns: Vector of instructions/pseudo-instructions Result: save-reg = pointer to reserved space (on success path)

build-ringbuf-submit clj

(build-ringbuf-submit ptr-reg)

(build-ringbuf-submit ptr-reg flags)

Submit a previously reserved ring buffer entry.

After calling submit, the reserved pointer becomes invalid and should not be used.

Args: ptr-reg: Register containing pointer from bpf_ringbuf_reserve flags: Submit flags (default 0): - 0: Normal submit - BPF-RB-NO-WAKEUP: Don't wake up reader - BPF-RB-FORCE-WAKEUP: Force wake up reader

Returns: Vector of instructions

build-write-u32-to-ringbuf clj

(build-write-u32-to-ringbuf ptr-reg offset value-reg)

Write a 32-bit value to a reserved ring buffer location.

Args: ptr-reg: Register containing pointer to ring buffer space offset: Offset within the reserved space value-reg: Register containing the value to write

Returns: Vector of 1 instruction

build-write-u64-to-ringbuf clj

(build-write-u64-to-ringbuf ptr-reg offset value-reg)

Write a 64-bit value to a reserved ring buffer location.

Args: ptr-reg: Register containing pointer to ring buffer space offset: Offset within the reserved space value-reg: Register containing the value to write

Returns: Vector of 1 instruction