High-level tracepoint definition macros for BPF programs.
Provides the deftracepoint macro for defining tracepoint handlers with automatic field extraction from tracepoint format files.
Tracepoints are static kernel instrumentation points that provide a stable ABI, unlike kprobes which depend on function signatures.
Example: (deftracepoint-instructions sched-switch {:category "sched" :name "sched_switch" :fields [:prev_pid :next_pid]} (concat (helper-get-current-pid-tgid) [(mov-reg :r6 :r0)] [(exit-insn)]))
High-level tracepoint definition macros for BPF programs.
Provides the deftracepoint macro for defining tracepoint handlers with
automatic field extraction from tracepoint format files.
Tracepoints are static kernel instrumentation points that provide a
stable ABI, unlike kprobes which depend on function signatures.
Example:
(deftracepoint-instructions sched-switch
{:category "sched"
:name "sched_switch"
:fields [:prev_pid :next_pid]}
(concat
(helper-get-current-pid-tgid)
[(mov-reg :r6 :r0)]
[(exit-insn)]))(build-tracepoint-program {:keys [category name ctx-reg fields body
return-value]
:or {fields {} return-value 0}})Build a complete tracepoint program with standard structure.
Parameters:
Returns assembled program bytes.
Example: (build-tracepoint-program {:category "sched" :name "sched_switch" :fields {:prev_pid :r6 :next_pid :r7} :body [(mov :r0 0)] :return-value 0})
Build a complete tracepoint program with standard structure.
Parameters:
- opts: Map with:
:category - Tracepoint category
:name - Tracepoint name
:ctx-reg - Register to save context pointer (optional)
:fields - Map of {field-name dest-reg} bindings
:body - Vector of body instructions
:return-value - Value to return (default 0)
Returns assembled program bytes.
Example:
(build-tracepoint-program
{:category "sched"
:name "sched_switch"
:fields {:prev_pid :r6 :next_pid :r7}
:body [(mov :r0 0)]
:return-value 0})(clear-format-cache!)Clear the tracepoint format cache.
Clear the tracepoint format cache.
Pre-defined formats for commonly used tracepoints. These can be used when tracefs is not available (e.g., in CI).
Pre-defined formats for commonly used tracepoints. These can be used when tracefs is not available (e.g., in CI).
(defraw-tracepoint-instructions fn-name options & body)Define a raw tracepoint program as a function returning instructions.
Raw tracepoints have lower overhead but provide raw context access. The context structure depends on the specific tracepoint.
Parameters:
Example: (defraw-tracepoint-instructions sys-enter-handler {:name "sys_enter" :ctx-reg :r9} (concat [(ldxdw :r6 :r1 0)] ; Load syscall number [(mov :r0 0) (exit-insn)]))
Define a raw tracepoint program as a function returning instructions.
Raw tracepoints have lower overhead but provide raw context access.
The context structure depends on the specific tracepoint.
Parameters:
- name: Name for the defined function
- options: Map with :name (raw tracepoint name), :ctx-reg
- body: Body instructions
Example:
(defraw-tracepoint-instructions sys-enter-handler
{:name "sys_enter"
:ctx-reg :r9}
(concat
[(ldxdw :r6 :r1 0)] ; Load syscall number
[(mov :r0 0)
(exit-insn)]))(deftracepoint-instructions fn-name options & body)Define a tracepoint program as a function returning instructions.
This macro creates a function that returns a vector of BPF instructions for a tracepoint handler. It sets up automatic field loading based on the tracepoint format.
Parameters:
Note: Uses static format definitions when tracefs is not available.
Example: (deftracepoint-instructions sched-switch-handler {:category "sched" :name "sched_switch" :fields {:prev_pid :r6 :next_pid :r7} :ctx-reg :r9} (concat (helper-get-current-pid-tgid) [(mov-reg :r8 :r0)] [(mov :r0 0) (exit-insn)]))
Define a tracepoint program as a function returning instructions.
This macro creates a function that returns a vector of BPF instructions
for a tracepoint handler. It sets up automatic field loading based on
the tracepoint format.
Parameters:
- name: Name for the defined function
- options: Map with:
:category - Tracepoint category (e.g., "sched")
:name - Tracepoint name (e.g., "sched_switch")
:fields - Map of {field-name dest-reg} bindings
:ctx-reg - Register to save context pointer (optional)
- body: Body instructions (should return vector of instructions)
Note: Uses static format definitions when tracefs is not available.
Example:
(deftracepoint-instructions sched-switch-handler
{:category "sched"
:name "sched_switch"
:fields {:prev_pid :r6 :next_pid :r7}
:ctx-reg :r9}
(concat
(helper-get-current-pid-tgid)
[(mov-reg :r8 :r0)]
[(mov :r0 0)
(exit-insn)]))(find-tracefs)Find the tracefs mount point. Returns the path or nil if not found.
Find the tracefs mount point. Returns the path or nil if not found.
(get-format category tp-name)Get tracepoint format, preferring runtime parsing with static fallback.
Parameters:
Returns format map.
Get tracepoint format, preferring runtime parsing with static fallback. Parameters: - category: Tracepoint category - name: Tracepoint name Returns format map.
(get-static-format category tp-name)Get a static tracepoint format definition.
Parameters:
Returns format map or nil if not in static definitions.
Get a static tracepoint format definition. Parameters: - category: Tracepoint category - name: Tracepoint name Returns format map or nil if not in static definitions.
(get-tracepoint-format category tp-name)Get parsed tracepoint format, using cache if available.
Parameters:
Returns parsed format map.
Get parsed tracepoint format, using cache if available. Parameters: - category: Tracepoint category - name: Tracepoint name Returns parsed format map.
(list-tracepoint-categories)List available tracepoint categories.
Returns vector of category names, or nil if tracefs not available.
List available tracepoint categories. Returns vector of category names, or nil if tracefs not available.
(list-tracepoints category)List available tracepoints in a category.
Parameters:
Returns vector of tracepoint names, or nil if not available.
List available tracepoints in a category. Parameters: - category: Category name (e.g., "sched") Returns vector of tracepoint names, or nil if not available.
(make-raw-tracepoint-program-info tp-name program-name instructions)Create program metadata for a raw tracepoint.
Parameters:
Returns map with program metadata for loading.
Create program metadata for a raw tracepoint. Parameters: - tp-name: Raw tracepoint name - program-name: Name for the BPF program - instructions: Program instructions Returns map with program metadata for loading.
(make-tracepoint-program-info category tp-name program-name instructions)Create program metadata for a tracepoint.
Parameters:
Returns map with program metadata for loading.
Create program metadata for a tracepoint. Parameters: - category: Tracepoint category - tp-name: Tracepoint name - program-name: Name for the BPF program - instructions: Program instructions Returns map with program metadata for loading.
(parse-tracepoint-format category tp-name)Parse a tracepoint format file and extract field information.
Parameters:
Returns map with:
Throws if format file cannot be read.
Parse a tracepoint format file and extract field information. Parameters: - category: Tracepoint category (e.g., "sched") - name: Tracepoint name (e.g., "sched_switch") Returns map with: - :category - Category name - :name - Tracepoint name - :id - Tracepoint ID (if available) - :fields - Vector of field maps with :name, :offset, :size, :type - :common-fields - Vector of common field maps Throws if format file cannot be read.
(raw-tracepoint-section-name tp-name)Generate ELF section name for a raw tracepoint program.
Parameters:
Returns section name like "raw_tracepoint/sys_enter"
Generate ELF section name for a raw tracepoint program. Parameters: - name: Raw tracepoint name Returns section name like "raw_tracepoint/sys_enter"
(tracepoint-exists? category tp-name)Check if a tracepoint exists.
Parameters:
Returns true if the tracepoint exists.
Check if a tracepoint exists. Parameters: - category: Tracepoint category - name: Tracepoint name Returns true if the tracepoint exists.
(tracepoint-field-info format field-name)Get complete information about a tracepoint field.
Parameters:
Returns field map with :name, :offset, :size, :type, :signed.
Get complete information about a tracepoint field. Parameters: - format: Parsed format map - field-name: Keyword name of the field Returns field map with :name, :offset, :size, :type, :signed.
(tracepoint-field-offset format field-name)Get the byte offset of a field in a tracepoint context.
Parameters:
Returns offset as long, or throws if field not found.
Get the byte offset of a field in a tracepoint context. Parameters: - format: Parsed format map from parse-tracepoint-format - field-name: Keyword name of the field Returns offset as long, or throws if field not found.
(tracepoint-field-size format field-name)Get the size in bytes of a field in a tracepoint context.
Parameters:
Returns size as long.
Get the size in bytes of a field in a tracepoint context. Parameters: - format: Parsed format map - field-name: Keyword name of the field Returns size as long.
(tracepoint-fields format)(tracepoint-fields format include-common?)Get all field names from a tracepoint format.
Parameters:
Returns vector of field name keywords.
Get all field names from a tracepoint format. Parameters: - format: Parsed format map - include-common?: Include common_ fields (default false) Returns vector of field name keywords.
(tracepoint-format-path category name)Get the path to a tracepoint's format file.
Parameters:
Returns path string.
Get the path to a tracepoint's format file. Parameters: - category: Tracepoint category (e.g., "sched", "syscalls") - name: Tracepoint name (e.g., "sched_switch") Returns path string.
(tracepoint-id-path category name)Get the path to a tracepoint's ID file.
Parameters:
Returns path string.
Get the path to a tracepoint's ID file. Parameters: - category: Tracepoint category - name: Tracepoint name Returns path string.
(tracepoint-prologue format field-bindings)(tracepoint-prologue ctx-save-reg format field-bindings)Generate standard tracepoint prologue instructions.
Saves the context pointer and reads specified fields.
Parameters:
Returns vector of instructions.
Example: (tracepoint-prologue :r9 format {:prev_pid :r6 :next_pid :r7}) ;; Generates: ;; mov r9, r1 ; Save context pointer ;; ldxw r6, [r1 + 8] ; Load prev_pid ;; ldxw r7, [r1 + 12] ; Load next_pid
Generate standard tracepoint prologue instructions.
Saves the context pointer and reads specified fields.
Parameters:
- ctx-save-reg: Register to save context pointer (optional)
- format: Parsed format map
- field-bindings: Map of {field-name dest-reg}
Returns vector of instructions.
Example:
(tracepoint-prologue :r9 format {:prev_pid :r6 :next_pid :r7})
;; Generates:
;; mov r9, r1 ; Save context pointer
;; ldxw r6, [r1 + 8] ; Load prev_pid
;; ldxw r7, [r1 + 12] ; Load next_pid(tracepoint-read-field ctx-reg format field-name dst-reg)Generate instruction to read a field from tracepoint context.
Parameters:
Returns ldx instruction with appropriate size.
Generate instruction to read a field from tracepoint context. Parameters: - ctx-reg: Register containing context pointer (typically :r1) - format: Parsed format map - field-name: Keyword name of the field to read - dst-reg: Destination register Returns ldx instruction with appropriate size.
(tracepoint-read-fields ctx-reg format field-bindings)Generate instructions to read multiple fields into registers.
Parameters:
Returns vector of ldx instructions.
Generate instructions to read multiple fields into registers.
Parameters:
- ctx-reg: Register containing context pointer
- format: Parsed format map
- field-bindings: Map of {field-name dest-reg}
Returns vector of ldx instructions.(tracepoint-section-name category tp-name)Generate ELF section name for a tracepoint program.
Parameters:
Returns section name like "tracepoint/sched/sched_switch"
Generate ELF section name for a tracepoint program. Parameters: - category: Tracepoint category - name: Tracepoint name Returns section name like "tracepoint/sched/sched_switch"
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 |