bpfc (8) - Linux Manuals
bpfc: a Berkeley Packet Filter assembler and compiler
NAME
bpfc - a Berkeley Packet Filter assembler and compilerSYNOPSIS
bpfc { [options] | [source-file] }
DESCRIPTION
bpfc is a small Berkeley Packet Filter assembler and compiler which is able to translate BPF assembler-like mnemonics into a numerical or C-like format, that can be read by tools such as netsniff-ng, iptables (xt_bpf) and many others. BPF is the one and only upstream filtering construct that is used in combination with packet(7) sockets, but also seccomp-BPF for system call sandboxing.
The Linux kernel and also BSD kernels implement "virtual machine" like constructs and JIT compilers that mimic a small register-based machine in BPF architecture and execute filter code that is, for example, composed by bpfc on a data buffer that is given by network packets. The purpose of this is to shift computation in time, so that the kernel can drop or truncate incoming packets as early as possible without having to push them to user space for further analysis first. Meanwhile, BPF constructs also find application in other areas such as in the communication between user and kernel space like system call sand-boxing.
At the time of writing this man page, the only available BPF compiler is part of the pcap(3) library and accessible through a high-level filter language that might be familiar to many people as tcpdump-like filters.
However, it is quite often useful to bypass that compiler and write optimized code that cannot be produced by the pcap(3) compiler, or is wrongly optimized, or is defective on purpose in order to debug test kernel code. Also, a reason to use bpfc could be to try out some new BPF extensions that are not supported by other compilers. Furthermore, bpfc can be useful to verify JIT compiler behavior or to find possible bugs that need to be fixed.
bpfc is implemented with the help of flex(1) and bison(1), tokenizes the source file in the first stage and parses its content into an AST. In two code generation stages it emits target opcodes. bpfc furthermore supports Linux kernel BPF extensions. More about that can be found in the syntax section.
The Linux kernel BPF JIT compiler is automatically turned on if detected by netsniff-ng. However, it can also be manually turned on through the command ''echo "1" > /proc/sys/net/core/bpf_jit_enable'' (normal working mode) or ''echo "2" > /proc/sys/net/core/bpf_jit_enable'' (debug mode where emitted opcodes of the image are printed to the kernel log). An architecture agnostic BPF JIT image disassembler can be found in the kernel source tree under ''tools/net/bpf_jit_disasm.c'' or within the netsniff-ng Git repository.
OPTIONS
-i <source-file/->, --input <source-file/->
Read BPF assembly instruction from an input file or from stdin.-p, --cpp
Pass the bpf program through the C preprocessor before reading it in bpfc. This allows #define and #include directives (e.g. to include definitions from system headers) to be used in the bpf program.-f <format>, --format <format>
Specify a different output format than the default that is netsniff-ng compatible. The <format> specifier can be: C, netsniff-ng, xt_bpf, tcpdump.-b, --bypass
Bypass basic filter validation when emitting opcodes. This can be useful for explicitly creating malformed BPF expressions for injecting into the kernel, for example, for bug testing.-V, --verbose
Be more verbose and display some bpfc debugging information.-d, --dump
Dump all supported instructions to stdout.-v, --version
Show version information and exit.-h, --help
Show user help and exit.SYNTAX
The BPF architecture resp. register machine consists of the following elements:
A program, that is translated by bpfc into ''opcodes'' is an array that
consists of the following elements:
The element o is a 16 bit wide opcode that has a particular instruction
encoded, jt and jf are two 8 bit wide jump targets, one for condition
element k contains a miscellaneous argument that can be interpreted in
different ways depending on the given instruction resp. opcode.
The instruction set consists of load, store, branch, alu, miscellaneous
and return instructions that are also represented in bpfc syntax. This
table also includes bpfc's own extensions. All operations are based on
unsigned data structures:
Instruction
ld
ldi
ldh
ldb
ldx
ldxi