clj-ebpf.time — org.clojars.pgdad/clj-ebpf 0.6.6

Time and random number helpers for BPF programs.

These helpers provide access to kernel time and pseudo-random numbers. Common uses include:

• Connection tracking timestamps (created_at, last_seen)
• Rate limiting (token bucket timing)
• Load balancing (weighted random selection)
• Metrics (latency measurement)

Usage: (require '[clj-ebpf.time :as t])

;; Get current kernel time in nanoseconds (t/build-ktime-get-ns)

;; Get random number (t/build-get-prandom-u32)

;; Get random in range [0, 99] (t/build-random-mod 100)

BPF-FUNC-get-prandom-u32 clj

BPF-FUNC-jiffies64 clj

BPF-FUNC-ktime-get-boot-ns clj

BPF-FUNC-ktime-get-coarse-ns clj

BPF-FUNC-ktime-get-ns clj

BPF-FUNC-ktime-get-tai-ns clj

build-get-prandom-u32 clj

(build-get-prandom-u32)

Get a pseudo-random 32-bit number.

Returns: Vector of 1 instruction Result: r0 = random 32-bit value in [0, 2^32-1]

Note: This is a fast PRNG, suitable for load balancing. Not cryptographically secure.

Example: (build-get-prandom-u32) ;; r0 contains random value

build-jiffies64 clj

(build-jiffies64)

Get jiffies64 value.

Returns: Vector of 1 instruction Result: r0 = jiffies64 value

Note: Jiffies is the kernel's tick counter. Resolution depends on CONFIG_HZ (typically 100, 250, or 1000). Not suitable for precise timing, but useful for coarse measurements.

Minimum kernel: 5.5

build-ktime-get-boot-ns clj

(build-ktime-get-boot-ns)

Get current kernel time including suspend time in nanoseconds.

Returns: Vector of 1 instruction Result: r0 = current time in nanoseconds (boot time)

Note: This is CLOCK_BOOTTIME. Includes time spent in suspend. Useful when you need monotonic time that advances during suspend.

Minimum kernel: 5.7

build-ktime-get-coarse-ns clj

(build-ktime-get-coarse-ns)

Get coarse-grained kernel time in nanoseconds.

Returns: Vector of 1 instruction Result: r0 = current time in nanoseconds (coarse granularity)

Note: Faster but less precise than ktime-get-ns. Resolution is typically around 1-4 milliseconds. Good for cases where precision isn't critical.

Minimum kernel: 5.11

build-ktime-get-ns clj

(build-ktime-get-ns)

Get current kernel time in nanoseconds.

Returns: Vector of 1 instruction Result: r0 = current time in nanoseconds (monotonic)

Note: This is CLOCK_MONOTONIC, suitable for measuring intervals. Does not include time spent in suspend. Not suitable for wall-clock time.

Example: (build-ktime-get-ns) ;; r0 now contains nanosecond timestamp ;; Store for later comparison: [(dsl/stx :dw :r10 :r0 -16)]

build-ktime-get-tai-ns clj

(build-ktime-get-tai-ns)

Get International Atomic Time (TAI) in nanoseconds.

Returns: Vector of 1 instruction Result: r0 = TAI time in nanoseconds

Note: TAI is similar to UTC but without leap seconds. Useful for precise time synchronization.

Minimum kernel: 6.1

build-load-elapsed-ns clj

(build-load-elapsed-ns stack-offset result-reg)

Calculate elapsed time since a stored timestamp.

Gets current time and subtracts the stored timestamp.

Args: stack-offset: Stack offset of stored timestamp result-reg: Register to store elapsed time (not r0)

Returns: Vector of instructions Result: result-reg = elapsed nanoseconds Clobbers: r0, result-reg

build-random-bool clj

(build-random-bool)

Generate random boolean (0 or 1).

Returns: Vector of 2 instructions Result: r0 = 0 or 1

build-random-mod clj

(build-random-mod n)

Generate random number in range [0, n-1].

Uses BPF's native modulo operation.

Args: n: Upper bound (exclusive)

Returns: Vector of 2 instructions Result: r0 = random value in [0, n-1]

Example: ;; Random percentage (0-99) (build-random-mod 100)

;; Random index into 4 backends (build-random-mod 4)

build-random-percentage clj

(build-random-percentage)

Generate random percentage (0-99).

Convenience wrapper for percentage-based decisions.

Returns: Vector of 2 instructions Result: r0 = value in [0, 99]

build-random-weighted-select clj

(build-random-weighted-select)

Generate random for weighted selection.

Generates random in [0, 99] for use with cumulative weight tables.

Returns: Vector of 2 instructions Result: r0 = value in [0, 99]

Usage with weights: Weights: [30, 50, 20] (must sum to 100) Cumulative: [30, 80, 100] If random < 30: select backend 0 If random < 80: select backend 1 Else: select backend 2

build-store-timestamp clj

(build-store-timestamp stack-offset)

Get current time and store it on the stack.

Args: stack-offset: Where to store the 64-bit timestamp

Returns: Vector of 2 instructions Clobbers: r0

build-update-timestamp clj

(build-update-timestamp ptr-reg offset)

Update a timestamp in a value pointed to by a register.

Common pattern for connection tracking last_seen updates.

Args: ptr-reg: Register pointing to structure containing timestamp offset: Offset within structure to timestamp field

Returns: Vector of 2 instructions Clobbers: r0