clj-ebpf.dsl.xdp — org.clojars.pgdad/clj-ebpf 0.2.3

High-level XDP (eXpress Data Path) DSL for BPF programs.

XDP programs run at the earliest point in the network stack, before the kernel allocates an sk_buff. This makes them extremely fast for packet filtering, forwarding, and modification.

XDP Actions:

• XDP_ABORTED (0): Error, packet dropped
• XDP_DROP (1): Silently drop packet
• XDP_PASS (2): Pass to normal network stack
• XDP_TX (3): Transmit back out same interface
• XDP_REDIRECT(4): Redirect to another interface or CPU

Example: (defxdp-instructions simple-drop {:action :drop} ;; All packets dropped [])

build-xdp-program clj

(build-xdp-program {:keys [ctx-reg data-reg data-end-reg body default-action]
                    :or {data-reg :r2 data-end-reg :r3 default-action :pass}})

Build a complete XDP program with standard structure.

Parameters:

• opts: Map with: :ctx-reg - Register to save xdp_md pointer (optional) :data-reg - Register for data pointer (default :r2) :data-end-reg - Register for data_end (default :r3) :body - Vector of body instructions :default-action - Default return action (default :pass)

Returns assembled program bytes.

defxdp-instructions clj macro

(defxdp-instructions fn-name options & body)

Define an XDP program as a function returning instructions.

Parameters:

• fn-name: Name for the defined function
• options: Map with: :ctx-reg - Register to save context (optional) :data-reg - Register for data pointer (default :r2) :data-end-reg - Register for data_end (default :r3) :default-action - Default return action (default :pass)
• body: Body expressions (should return vectors of instructions)

Example: (defxdp-instructions drop-all {:default-action :drop} [])

ethernet-header-size clj

ethernet-offsets clj

ethertypes clj

icmp-header-size clj

ip-protocols clj

ipv4-header-min-size clj

ipv4-offsets clj

ipv4-to-int clj

(ipv4-to-int ip-str)

Convert IPv4 address string to integer (network byte order).

Parameters:

• ip-str: IP address string like "192.168.1.1"

Returns 32-bit integer.

ipv6-header-size clj

ipv6-offsets clj

make-xdp-program-info clj

(make-xdp-program-info program-name instructions)

(make-xdp-program-info program-name instructions interface)

Create program metadata for an XDP program.

Parameters:

• program-name: Name for the BPF program
• instructions: Program instructions
• interface: Optional interface name

Returns map with program metadata.

tcp-flags clj

tcp-header-min-size clj

tcp-offsets clj

udp-header-size clj

udp-offsets clj

xdp-action clj

(xdp-action action)

Get XDP action value by keyword.

Parameters:

• action: Action keyword (:drop, :pass, :tx, :redirect, :aborted)

Returns integer action value.

Example: (xdp-action :drop) ;; => 1

xdp-actions clj

XDP action return values.

xdp-adjust-head clj

(xdp-adjust-head ctx-reg delta)

Generate call to bpf_xdp_adjust_head helper.

Moves the packet data pointer by delta bytes. Positive delta adds headroom, negative removes.

Parameters:

• ctx-reg: Register containing xdp_md pointer
• delta: Bytes to adjust (can be negative)

Returns vector of instructions.

xdp-adjust-meta clj

(xdp-adjust-meta ctx-reg delta)

Generate call to bpf_xdp_adjust_meta helper.

Adjusts metadata area before packet data.

Parameters:

• ctx-reg: Register containing xdp_md pointer
• delta: Bytes to adjust

Returns vector of instructions.

xdp-adjust-tail clj

(xdp-adjust-tail ctx-reg delta)

Generate call to bpf_xdp_adjust_tail helper.

Moves the packet data_end pointer by delta bytes.

Parameters:

• ctx-reg: Register containing xdp_md pointer
• delta: Bytes to adjust

Returns vector of instructions.

xdp-bounds-check clj

(xdp-bounds-check data-reg data-end-reg size)

(xdp-bounds-check data-reg data-end-reg size action-on-fail)

Generate verifier-friendly bounds check.

This is CRITICAL for XDP programs. The verifier requires bounds checks before accessing any packet data.

Parameters:

• data-reg: Register containing current data pointer
• data-end-reg: Register containing data_end pointer
• size: Number of bytes we want to access
• action-on-fail: XDP action if check fails (default :pass)

Returns vector of instructions that:

• Computes data + size
• Compares with data_end
• Returns action-on-fail if bounds exceeded

Example: (xdp-bounds-check :r2 :r3 14 :pass) ;; If r2 + 14 > r3, return XDP_PASS

xdp-bounds-check-var clj

(xdp-bounds-check-var data-reg data-end-reg offset-reg)

(xdp-bounds-check-var data-reg data-end-reg offset-reg action-on-fail)

Generate bounds check with variable offset.

Parameters:

• data-reg: Current data pointer
• data-end-reg: Data end pointer
• offset-reg: Register containing offset to add
• action-on-fail: XDP action if check fails

Returns vector of instructions.

xdp-bswap16 clj

(xdp-bswap16 reg)

Byte swap 16-bit value (network to host order or vice versa).

Parameters:

• reg: Register to byte-swap in place

Returns vector of instructions (manual swap since BPF doesn't have bswap16).

xdp-bswap32 clj

(xdp-bswap32 reg tmp-reg)

Byte swap 32-bit value.

Parameters:

• reg: Register containing 32-bit value
• tmp-reg: Temporary register for computation (unused, kept for API compat)

Returns BPF endianness instruction.

xdp-drop-if-port clj

(xdp-drop-if-port data-reg data-end-reg l4-offset port-offset port is-tcp)

Generate instructions to drop packets to/from a specific port.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• l4-offset: Layer 4 header offset
• port-offset: Offset within L4 header (0 for src, 2 for dst)
• port: Port number to match
• is-tcp: true for TCP, false for UDP

Returns vector of instructions.

xdp-get-ipv4-header-length clj

(xdp-get-ipv4-header-length data-reg l3-offset dst-reg)

Get IPv4 header length in bytes (including options).

Parameters:

• data-reg: Data pointer
• l3-offset: Offset to IPv4 header
• dst-reg: Destination register for header length

Note: Caller should multiply by 4 after loading IHL nibble.

Returns vector of instructions.

xdp-load-byte clj

(xdp-load-byte data-reg offset dst-reg)

Load a byte from packet at offset.

IMPORTANT: Caller must ensure bounds check was done first!

Parameters:

• data-reg: Register containing data pointer
• offset: Byte offset from data
• dst-reg: Destination register

Returns ldx instruction.

xdp-load-ctx-field clj

(xdp-load-ctx-field ctx-reg field dst-reg)

Load a field from xdp_md context.

Parameters:

• ctx-reg: Register containing xdp_md pointer (typically :r1 at entry)
• field: Field keyword from xdp-md-offsets
• dst-reg: Destination register

Returns ldx instruction.

xdp-load-data-pointers clj

(xdp-load-data-pointers ctx-reg data-reg data-end-reg)

Load data and data_end pointers from xdp_md.

Parameters:

• ctx-reg: Register containing xdp_md pointer
• data-reg: Destination register for data pointer
• data-end-reg: Destination register for data_end pointer

Returns vector of instructions.

Example: (xdp-load-data-pointers :r1 :r2 :r3) ;; r2 = data, r3 = data_end

xdp-load-dst-mac clj

(xdp-load-dst-mac data-reg dst-regs)

Load destination MAC address bytes.

Parameters:

• data-reg: Data pointer (after Ethernet bounds check)
• dst-regs: Vector of 6 registers for each MAC byte

Returns vector of ldx instructions.

xdp-load-half clj

(xdp-load-half data-reg offset dst-reg)

Load a half-word (2 bytes) from packet at offset.

Note: Network byte order (big-endian). Use bswap16 if you need host byte order.

Parameters:

• data-reg: Register containing data pointer
• offset: Byte offset from data
• dst-reg: Destination register

Returns ldx instruction.

xdp-load-src-mac clj

(xdp-load-src-mac data-reg dst-regs)

Load source MAC address bytes.

Parameters:

• data-reg: Data pointer (after Ethernet bounds check)
• dst-regs: Vector of 6 registers for each MAC byte

Returns vector of ldx instructions.

xdp-load-word clj

(xdp-load-word data-reg offset dst-reg)

Load a word (4 bytes) from packet at offset.

Note: Network byte order (big-endian). Use bswap32 if you need host byte order.

Parameters:

• data-reg: Register containing data pointer
• offset: Byte offset from data
• dst-reg: Destination register

Returns ldx instruction.

xdp-match-ipv4 clj

(xdp-match-ipv4 data-reg data-end-reg ip-addr match-src action-on-match)

Generate instructions to match IPv4 source or destination.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• ip-addr: IP address integer (network byte order)
• match-src: true for source, false for destination
• action-on-match: Action if IP matches

Returns vector of instructions.

xdp-md-offset clj

(xdp-md-offset field)

Get offset for xdp_md field.

Parameters:

• field: Field keyword

Returns offset in bytes.

xdp-md-offsets clj

xdp_md structure field offsets.

xdp-parse-ethernet clj

(xdp-parse-ethernet data-reg data-end-reg ethertype-reg)

Parse Ethernet header and extract EtherType.

Parameters:

• data-reg: Register containing data pointer
• data-end-reg: Register containing data_end
• ethertype-reg: Destination for EtherType value

Returns vector of instructions including bounds check.

After execution:

• ethertype-reg contains EtherType (in network byte order)
• Returns XDP_PASS if packet too small

xdp-parse-ipv4 clj

(xdp-parse-ipv4 data-reg data-end-reg l3-offset protocol-reg)

(xdp-parse-ipv4 data-reg
                data-end-reg
                l3-offset
                protocol-reg
                src-ip-reg
                dst-ip-reg)

Parse IPv4 header at given offset.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• l3-offset: Offset to IPv4 header (typically 14 for Ethernet)
• protocol-reg: Destination for IP protocol
• src-ip-reg: Destination for source IP (optional)
• dst-ip-reg: Destination for destination IP (optional)

Returns vector of instructions including bounds check.

xdp-parse-ipv6 clj

(xdp-parse-ipv6 data-reg data-end-reg l3-offset next-header-reg)

Parse IPv6 header at given offset.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• l3-offset: Offset to IPv6 header (typically 14)
• next-header-reg: Destination for next header value

Returns vector of instructions.

xdp-parse-tcp clj

(xdp-parse-tcp data-reg
               data-end-reg
               l4-offset
               &
               {:keys [src-port dst-port flags]})

Parse TCP header at given offset.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• l4-offset: Offset to TCP header
• src-port-reg: Destination for source port (optional)
• dst-port-reg: Destination for destination port (optional)
• flags-reg: Destination for TCP flags (optional)

Returns vector of instructions.

xdp-parse-udp clj

(xdp-parse-udp data-reg data-end-reg l4-offset & {:keys [src-port dst-port]})

Parse UDP header at given offset.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer
• l4-offset: Offset to UDP header
• src-port-reg: Destination for source port (optional)
• dst-port-reg: Destination for destination port (optional)

Returns vector of instructions.

xdp-pass-only-tcp clj

(xdp-pass-only-tcp data-reg data-end-reg)

Generate instructions that pass only TCP packets.

Drops all non-TCP packets.

Parameters:

• data-reg: Data pointer
• data-end-reg: Data end pointer

Returns vector of instructions.

xdp-prologue clj

(xdp-prologue data-reg data-end-reg)

(xdp-prologue ctx-save-reg data-reg data-end-reg)

Generate standard XDP program prologue.

Saves context and loads data pointers.

Parameters:

• ctx-save-reg: Register to save xdp_md pointer (optional)
• data-reg: Register for data pointer
• data-end-reg: Register for data_end pointer

Returns vector of instructions.

xdp-return-action clj

(xdp-return-action action)

Generate instructions to return an XDP action.

Parameters:

• action: Action keyword or integer

Returns vector of [mov, exit] instructions.

xdp-section-name clj

(xdp-section-name)

(xdp-section-name interface)

Generate ELF section name for XDP program.

Parameters:

• interface: Optional interface name for attachment hint

Returns section name like "xdp" or "xdp/eth0"