High-level BPF Iterator DSL for tracing programs.
BPF Iterators (bpf_iter) allow BPF programs to dump kernel data structures by iterating over them. Reading from an iterator FD triggers the BPF program for each element.
Common iterator types:
Iterator programs use:
Context varies by iterator type:
High-level BPF Iterator DSL for tracing programs. BPF Iterators (bpf_iter) allow BPF programs to dump kernel data structures by iterating over them. Reading from an iterator FD triggers the BPF program for each element. Common iterator types: - task: Iterate over all tasks/processes - bpf_map: Iterate over BPF maps - bpf_map_elem: Iterate over elements in a specific map - tcp: Iterate over TCP sockets - udp: Iterate over UDP sockets - netlink: Iterate over netlink sockets - bpf_prog: Iterate over BPF programs - bpf_link: Iterate over BPF links Iterator programs use: - bpf_seq_write: Write raw bytes to output - bpf_seq_printf: Write formatted output (like printf) Context varies by iterator type: - bpf_iter__task: struct task_struct *task - bpf_iter__bpf_map: struct bpf_map *map - etc.
(alloc-stack-buffer dst-reg offset)Generate instructions to get pointer to stack buffer.
BPF stack is accessed via r10 (frame pointer) with negative offsets.
Parameters:
Returns vector of instructions to compute buffer address.
Generate instructions to get pointer to stack buffer. BPF stack is accessed via r10 (frame pointer) with negative offsets. Parameters: - dst-reg: Register to store buffer pointer - offset: Negative offset from r10 (e.g., -64 for 64 bytes) Returns vector of instructions to compute buffer address.
(build-iter-program {:keys [ctx-reg meta-reg body default-action]
:or {ctx-reg :r6 default-action :continue}})Build a complete iterator program from components.
Parameters:
Returns assembled bytecode.
Build a complete iterator program from components. Parameters: - opts: Map with: - :ctx-reg - Register to save context (default :r6) - :meta-reg - Register for meta pointer (optional) - :body - Vector of instructions or instruction vectors - :default-action - :continue or :stop (default :continue) Returns assembled bytecode.
(htonl x)Convert 32-bit value from host to network byte order.
Convert 32-bit value from host to network byte order.
(htons x)Convert 16-bit value from host to network byte order.
Convert 16-bit value from host to network byte order.
(iter-check-null ptr-reg skip-count)Generate NULL check for iterator element.
At the end of iteration, the element pointer is NULL. This generates instructions to check and skip if NULL.
Parameters:
Returns vector of instructions.
Generate NULL check for iterator element. At the end of iteration, the element pointer is NULL. This generates instructions to check and skip if NULL. Parameters: - ptr-reg: Register containing pointer to check - skip-count: Number of instructions to skip if NULL Returns vector of instructions.
(iter-check-null-and-exit ptr-reg)Check if pointer is NULL and exit with 0 if so.
Common pattern for handling end of iteration.
Parameters:
Returns vector of instructions that exits if NULL.
Check if pointer is NULL and exit with 0 if so. Common pattern for handling end of iteration. Parameters: - ptr-reg: Register containing pointer to check Returns vector of instructions that exits if NULL.
(iter-context-offset field)Get the offset for an iterator context field.
Parameters:
Returns offset or throws on invalid field.
Get the offset for an iterator context field. Parameters: - field: Field keyword (e.g., :meta, :task, :map) Returns offset or throws on invalid field.
Context structure offsets for different iterator types. All iterator contexts start with:
bpf_iter_meta contains:
Context structure offsets for different iterator types. All iterator contexts start with: - meta (struct bpf_iter_meta *) at offset 0 - type-specific pointer at offset 8 bpf_iter_meta contains: - seq (struct seq_file *) at offset 0 - session_id at offset 8 - seq_num at offset 16
BPF helper function IDs used by iterators.
BPF helper function IDs used by iterators.
(iter-load-ctx-ptr ctx-reg dst-reg field)Load a pointer field from iterator context.
Parameters:
Returns ldx instruction.
Load a pointer field from iterator context. Parameters: - ctx-reg: Register containing context pointer - dst-reg: Destination register for loaded pointer - field: Field keyword (e.g., :task, :map, :meta) Returns ldx instruction.
(iter-load-meta-field meta-reg dst-reg field)Load a field from bpf_iter_meta structure.
Parameters:
Returns ldx instruction.
Load a field from bpf_iter_meta structure. Parameters: - meta-reg: Register containing meta pointer - dst-reg: Destination register - field: Field keyword (:seq, :session-id, :seq-num) Returns ldx instruction.
Offsets within bpf_iter_meta structure.
Offsets within bpf_iter_meta structure.
(iter-prologue ctx-reg)Generate standard iterator program prologue.
Iterator programs receive context in r1:
Parameters:
Returns vector of instructions.
Generate standard iterator program prologue. Iterator programs receive context in r1: - r1 points to iterator-specific context structure Parameters: - ctx-reg: Register to save context pointer (e.g., :r6) Returns vector of instructions.
(iter-prologue-with-meta ctx-reg meta-reg)Generate iterator prologue that also loads meta pointer.
Parameters:
Returns vector of instructions.
Generate iterator prologue that also loads meta pointer. Parameters: - ctx-reg: Register to save context pointer - meta-reg: Register to load meta pointer into Returns vector of instructions.
(iter-return action)Generate instructions to return from iterator.
Parameters:
Returns vector of instructions.
Generate instructions to return from iterator. Parameters: - action: :continue or :stop Returns vector of instructions.
(iter-return-continue)Generate instructions to continue iteration.
Returns 0 to continue to next element.
Generate instructions to continue iteration. Returns 0 to continue to next element.
(iter-return-stop)Generate instructions to stop iteration early.
Returns 1 to stop iteration.
Generate instructions to stop iteration early. Returns 1 to stop iteration.
(iter-return-value action)Get numeric value for iterator return code.
Parameters:
Returns numeric value.
Get numeric value for iterator return code. Parameters: - action: :continue or :stop Returns numeric value.
(iter-section-name iter-type)Generate ELF section name for iterator program.
Parameters:
Returns section name string.
Generate ELF section name for iterator program. Parameters: - iter-type: Iterator type keyword (e.g., :task, :bpf-map) Returns section name string.
Common BPF iterator types and their BTF names.
Common BPF iterator types and their BTF names.
(make-iter-info prog-name iter-type instructions)Create iterator program metadata.
Parameters:
Returns map with program metadata.
Create iterator program metadata. Parameters: - name: Program name - iter-type: Iterator type keyword - instructions: Vector of instructions Returns map with program metadata.
(minimal-task-iterator)Generate minimal task iterator that just returns continue.
Useful as a starting point or for testing.
Generate minimal task iterator that just returns continue. Useful as a starting point or for testing.
(probe-read-kernel dst-reg size src-reg)Generate bpf_probe_read_kernel helper call.
Safely reads kernel memory.
Signature: long bpf_probe_read_kernel(void *dst, u32 size, const void *src)
Parameters:
Returns vector of instructions.
Generate bpf_probe_read_kernel helper call. Safely reads kernel memory. Signature: long bpf_probe_read_kernel(void *dst, u32 size, const void *src) Parameters: - dst-reg: Register with destination buffer pointer - size: Number of bytes to read - src-reg: Register with source pointer Returns vector of instructions.
(probe-read-kernel-str dst-reg size src-reg)Generate bpf_probe_read_kernel_str helper call.
Safely reads null-terminated string from kernel memory.
Signature: long bpf_probe_read_kernel_str(void *dst, u32 size, const void *src)
Parameters:
Returns vector of instructions.
Generate bpf_probe_read_kernel_str helper call. Safely reads null-terminated string from kernel memory. Signature: long bpf_probe_read_kernel_str(void *dst, u32 size, const void *src) Parameters: - dst-reg: Register with destination buffer pointer - size: Max bytes to read (including null terminator) - src-reg: Register with source string pointer Returns vector of instructions.
(seq-printf-simple meta-reg fmt-ptr-reg fmt-len data-ptr-reg data-len)Generate bpf_seq_printf helper call with simple format.
Writes formatted output. Limited to 3 format arguments.
Signature: long bpf_seq_printf(struct seq_file *m, const char *fmt, u32 fmt_size, const void *data, u32 data_len)
Note: This is a simplified version. For full seq_printf with format arguments, you need to set up a data array on the stack.
Parameters:
Returns vector of instructions.
Generate bpf_seq_printf helper call with simple format.
Writes formatted output. Limited to 3 format arguments.
Signature:
long bpf_seq_printf(struct seq_file *m, const char *fmt,
u32 fmt_size, const void *data, u32 data_len)
Note: This is a simplified version. For full seq_printf with
format arguments, you need to set up a data array on the stack.
Parameters:
- meta-reg: Register with bpf_iter_meta pointer
- fmt-ptr-reg: Register with pointer to format string
- fmt-len: Format string length
- data-ptr-reg: Register with pointer to data array (or 0 for no args)
- data-len: Data array length (or 0)
Returns vector of instructions.(seq-write meta-reg data-reg len)Generate bpf_seq_write helper call.
Writes raw bytes to the seq_file output.
Signature: long bpf_seq_write(struct seq_file *m, const void *data, u32 len)
Parameters:
Returns vector of instructions.
Generate bpf_seq_write helper call. Writes raw bytes to the seq_file output. Signature: long bpf_seq_write(struct seq_file *m, const void *data, u32 len) Parameters: - meta-reg: Register with bpf_iter_meta pointer (seq is at offset 0) - data-reg: Register with pointer to data buffer - len: Length to write (immediate or register) Returns vector of instructions.
(task-load-pid task-reg dst-reg)Load task PID from task_struct.
Parameters:
Note: Offset is kernel-dependent. Use BTF for production.
Load task PID from task_struct. Parameters: - task-reg: Register containing task_struct pointer - dst-reg: Destination register for PID Note: Offset is kernel-dependent. Use BTF for production.
(task-load-tgid task-reg dst-reg)Load task TGID (thread group ID / process ID).
Parameters:
Load task TGID (thread group ID / process ID). Parameters: - task-reg: Register containing task_struct pointer - dst-reg: Destination register for TGID
(task-null-check-template body-insns)Generate task iterator template with NULL check.
Parameters:
Returns complete instruction vector.
Generate task iterator template with NULL check. Parameters: - body-insns: Instructions to execute for each non-NULL task Returns complete instruction vector.
Common offsets in struct task_struct. Note: These may vary by kernel version. Use BTF for portability.
Common offsets in struct task_struct. Note: These may vary by kernel version. Use BTF for portability.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |