[linux-block.git] / Documentation / bpf / linux-notes.rst

.. contents::
.. sectnum::

==========================
Linux implementation notes
==========================

This document provides more details specific to the Linux kernel implementation of the eBPF instruction set.

Byte swap instructions
======================

``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively.

Legacy BPF Packet access instructions
=====================================

As mentioned in the `ISA standard documentation <instruction-set.rst#legacy-bpf-packet-access-instructions>`_,
Linux has special eBPF instructions for access to packet data that have been
carried over from classic BPF to retain the performance of legacy socket
filters running in the eBPF interpreter.

The instructions come in two forms: ``BPF_ABS | <size> | BPF_LD`` and
``BPF_IND | <size> | BPF_LD``.

These instructions are used to access packet data and can only be used when
the program context is a pointer to a networking packet.  ``BPF_ABS``
accesses packet data at an absolute offset specified by the immediate data
and ``BPF_IND`` access packet data at an offset that includes the value of
a register in addition to the immediate data.

These instructions have seven implicit operands:

* Register R6 is an implicit input that must contain a pointer to a
  struct sk_buff.
* Register R0 is an implicit output which contains the data fetched from
  the packet.
* Registers R1-R5 are scratch registers that are clobbered by the
  instruction.

These instructions have an implicit program exit condition as well. If an
eBPF program attempts access data beyond the packet boundary, the
program execution will be aborted.

``BPF_ABS | BPF_W | BPF_LD`` (0x20) means::

  R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + imm))

where ``ntohl()`` converts a 32-bit value from network byte order to host byte order.

``BPF_IND | BPF_W | BPF_LD`` (0x40) means::

  R0 = ntohl(*(u32 *) ((struct sk_buff *) R6->data + src + imm))
Commit	Line	Data
6166da0a DT	1	.. contents::
	2	.. sectnum::
	3
	4	==========================
	5	Linux implementation notes
	6	==========================
	7
	8	This document provides more details specific to the Linux kernel implementation of the eBPF instruction set.
	9
9a0bf213 DT	10	Byte swap instructions
	11	======================
	12
	13	``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively.
	14
6166da0a DT	15	Legacy BPF Packet access instructions
	16	=====================================
	17
	18	As mentioned in the `ISA standard documentation <instruction-set.rst#legacy-bpf-packet-access-instructions>`_,
	19	Linux has special eBPF instructions for access to packet data that have been
	20	carried over from classic BPF to retain the performance of legacy socket
	21	filters running in the eBPF interpreter.
	22
	23	The instructions come in two forms: ``BPF_ABS \| <size> \| BPF_LD`` and
	24	``BPF_IND \| <size> \| BPF_LD``.
	25
	26	These instructions are used to access packet data and can only be used when
	27	the program context is a pointer to a networking packet. ``BPF_ABS``
	28	accesses packet data at an absolute offset specified by the immediate data
	29	and ``BPF_IND`` access packet data at an offset that includes the value of
	30	a register in addition to the immediate data.
	31
	32	These instructions have seven implicit operands:
	33
	34	* Register R6 is an implicit input that must contain a pointer to a
	35	struct sk_buff.
	36	* Register R0 is an implicit output which contains the data fetched from
	37	the packet.
	38	* Registers R1-R5 are scratch registers that are clobbered by the
	39	instruction.
	40
	41	These instructions have an implicit program exit condition as well. If an
	42	eBPF program attempts access data beyond the packet boundary, the
	43	program execution will be aborted.
	44
	45	``BPF_ABS \| BPF_W \| BPF_LD`` (0x20) means::
	46
	47	R0 = ntohl((u32 ) ((struct sk_buff *) R6->data + imm))
	48
	49	where ``ntohl()`` converts a 32-bit value from network byte order to host byte order.
	50
	51	``BPF_IND \| BPF_W \| BPF_LD`` (0x40) means::
	52
	53	R0 = ntohl((u32 ) ((struct sk_buff *) R6->data + src + imm))