Since version 2.2 of Packet Sniffer SDK HNUserFilter component contains embedded BPF assembler, which allows developer to create traffic filtering BPF programs in human-readable format. Using of the BPF assembler allows you to create and debug BPF filters more quickly.

BPF assembler language is a programming language similar to well-known assemblers like MASM or TASM, and allows to use BPF machine commands for BPF filters writing. BPF assembler allows to use labels in conditional and unconditional jump commands, set constants, and use include files containing constants definitions. Each BPF assembler instruction must be placed in a separate line.

Identifier

Identifiers may be used in declarations of labels names in conditional and unconditional jumps, and for declarations of constant expressions names. Identifier denotes a sequence of one or more letters, digits, and underscores ("_"), not longer than 32 symbols, starting with a letter.

Expression

BPF assembler expression denotes a simple arithmetic expression, that consists of digits, identifiers, predefined constant expressions, symbols '+', '-', '*', '/' , and brackets '(' and ')'.

Named constant definition directive

#define <identifier> <expression>

This directive allows to set a symbolic name for some constant expression. Named constant may be used only after its definition by #define directive.

This directive may be declared in the BPF program compiled by HNUserFilter.CompileBPFAsmFromStr and HNUserFilter.CompileBPFAsmFromFile functions, such constants may be used only in the current compiled program.

Also constants definitions may be declared and compiled separately by HNUserFilter.CompileBPFDefinesFromStr and HNUserFilter.CompileBPFDefinesFromFile functions. In this case you can use them repeatedly in all your BPF programs compiled by the HNUserFilter.CompileBPFAsmFromStr and HNUserFilter.CompileBPFAsmFromFile functions.

Pseudovariables

There is one pseudovariable in the BPF assembler language: #pktlen. It allows to refer to the full packet size from BPF program.

File include directive

#include "<file name>"

This directive may be used for inserting an external file containing named constants definitions into a BPF program. Content of a file named in #include directive will be just inserted into a BPF program text.

Label

Labels may be set as follows:

<identifier>:

To declare a label in your program, just type its name and add ":" to the end. Label can be declared on a separate line or before any other instruction. Use labels to define instructions on which you wish to jump to by conditional or unconditional jump command.

Backward jumps are not allowed.

BPF assembler instructions

BPF assembler instructions are equal to the BPF machine instructions symbolic names. Please refer to the BPF instructions topic for instructions format and parameters. All instructions may contain expressions as parameters, conditional and unconditional jump commands may contain labels.