flow_dissector: rst'ify documentation

.. SPDX-License-Identifier: GPL-2.0

==================

BPF Flow Dissector

==================

API

===

BPF flow dissector programs operate on an __sk_buff. However, only the

limited set of fields is allowed: data, data_end and flow_keys. flow_keys

is 'struct bpf_flow_keys' and contains flow dissector input and

output arguments.

BPF flow dissector programs operate on an ``__sk_buff``. However, only the

limited set of fields is allowed: ``data``, ``data_end`` and ``flow_keys``.

``flow_keys`` is ``struct bpf_flow_keys`` and contains flow dissector input

and output arguments.

The inputs are:

  * nhoff - initial offset of the networking header

  * thoff - initial offset of the transport header, initialized to nhoff

  * n_proto - L3 protocol type, parsed out of L2 header

  * ``nhoff`` - initial offset of the networking header

  * ``thoff`` - initial offset of the transport header, initialized to nhoff

  * ``n_proto`` - L3 protocol type, parsed out of L2 header

Flow dissector BPF program should fill out the rest of the 'struct

bpf_flow_keys' fields. Input arguments nhoff/thoff/n_proto should be also

adjusted accordingly.

Flow dissector BPF program should fill out the rest of the ``struct

bpf_flow_keys`` fields. Input arguments ``nhoff/thoff/n_proto`` should be

also adjusted accordingly.

The return code of the BPF program is either BPF_OK to indicate successful

dissection, or BPF_DROP to indicate parsing error.

===============

In the VLAN-less case, this is what the initial state of the BPF flow

dissector looks like:

dissector looks like::

  +------+------+------------+-----------+

  | DMAC | SMAC | ETHER_TYPE | L3_HEADER |

  +------+------+------------+-----------+

                              |

                              +-- flow dissector starts here

skb->data + flow_keys->nhoff point to the first byte of L3_HEADER.

.. code:: c

  skb->data + flow_keys->nhoff point to the first byte of L3_HEADER

  flow_keys->thoff = nhoff

  flow_keys->n_proto = ETHER_TYPE

In case of VLAN, flow dissector can be called with the two different states.

Pre-VLAN parsing:

Pre-VLAN parsing::

  +------+------+------+-----+-----------+-----------+

  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |

  +------+------+------+-----+-----------+-----------+

                        |

                        +-- flow dissector starts here

skb->data + flow_keys->nhoff point the to first byte of TCI.

.. code:: c

  skb->data + flow_keys->nhoff point the to first byte of TCI

  flow_keys->thoff = nhoff

  flow_keys->n_proto = TPID

have to parse VLAN information twice for double tagged packets.

Post-VLAN parsing:

Post-VLAN parsing::

  +------+------+------+-----+-----------+-----------+

  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |

  +------+------+------+-----+-----------+-----------+

                                          |

                                          +-- flow dissector starts here

skb->data + flow_keys->nhoff point the to first byte of L3_HEADER.

.. code:: c

  skb->data + flow_keys->nhoff point the to first byte of L3_HEADER

  flow_keys->thoff = nhoff

  flow_keys->n_proto = ETHER_TYPE

Reference Implementation

========================

See tools/testing/selftests/bpf/progs/bpf_flow.c for the reference

implementation and tools/testing/selftests/bpf/flow_dissector_load.[hc] for

the loader. bpftool can be used to load BPF flow dissector program as well.

See ``tools/testing/selftests/bpf/progs/bpf_flow.c`` for the reference

implementation and ``tools/testing/selftests/bpf/flow_dissector_load.[hc]``

for the loader. bpftool can be used to load BPF flow dissector program as well.

The reference implementation is organized as follows:

* jmp_table map that contains sub-programs for each supported L3 protocol

* _dissect routine - entry point; it does input n_proto parsing and does

  bpf_tail_call to the appropriate L3 handler

  * ``jmp_table`` map that contains sub-programs for each supported L3 protocol

  * ``_dissect`` routine - entry point; it does input ``n_proto`` parsing and

    does ``bpf_tail_call`` to the appropriate L3 handler

Since BPF at this point doesn't support looping (or any jumping back),

jmp_table is used instead to handle multiple levels of encapsulation (and

===================

BPF flow dissector doesn't support exporting all the metadata that in-kernel

C-based implementation can export. Notable example is single VLAN (802.1Q)

and double VLAN (802.1AD) tags. Please refer to the 'struct bpf_flow_keys'

and double VLAN (802.1AD) tags. Please refer to the ``struct bpf_flow_keys``

for a set of information that's currently can be exported from the BPF context.

   netdev-FAQ

   af_xdp

   batman-adv

   bpf_flow_dissector

   can

   can_ucan_protocol

   device_drivers/freescale/dpaa2/index