Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5eed7898 authored by Stanislav Fomichev's avatar Stanislav Fomichev Committed by Daniel Borkmann
Browse files

flow_dissector: rst'ify documentation 



Rename bpf_flow_dissector.txt to bpf_flow_dissector.rst and fix
formatting. Also, link it from the Documentation/networking/index.rst.

Tested with 'make htmldocs' to make sure it looks reasonable.

Fixes: ae82899b ("flow_dissector: document BPF flow dissector environment")
Signed-off-by: default avatarStanislav Fomichev <sdf@google.com>
Acked-by: default avatarMartin KaFai Lau <kafai@fb.com>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
parent a090dbf2

Documentation/networking/bpf_flow_dissector.txt→Documentation/networking/bpf_flow_dissector.rst

+126 −0
Original line number Original line Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



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

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

BPF Flow Dissector

BPF Flow Dissector

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

==================
@@ -15,19 +17,19 @@ number of instructions and tail calls). 
API

API

===

===





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

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

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

is 'struct bpf_flow_keys' and contains flow dissector input and

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

output arguments.

and output arguments.





The inputs are:

The inputs are:

  * nhoff - initial offset of the networking header

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

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

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

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

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





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

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

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

adjusted accordingly.

also adjusted accordingly.





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

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

dissection, or BPF_DROP to indicate parsing error.

dissection, or BPF_DROP to indicate parsing error.
@@ -36,7 +38,8 @@ __sk_buff->data 
===============

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





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

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 |

  | DMAC | SMAC | ETHER_TYPE | L3_HEADER |

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

  +------+------+------------+-----------+
@@ -44,14 +47,17 @@ dissector looks like: 
                              |

                              |

                              +-- flow dissector starts here

                              +-- 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->thoff = nhoff

  flow_keys->n_proto = ETHER_TYPE

  flow_keys->n_proto = ETHER_TYPE







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

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 |

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

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

  +------+------+------+-----+-----------+-----------+
@@ -59,7 +65,9 @@ Pre-VLAN parsing: 
                        |

                        |

                        +-- flow dissector starts here

                        +-- 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->thoff = nhoff

  flow_keys->n_proto = TPID

  flow_keys->n_proto = TPID
@@ -67,7 +75,8 @@ Please note that TPID can be 802.1AD and, hence, BPF program would 
have to parse VLAN information twice for double tagged packets.

have to parse VLAN information twice for double tagged packets.









Post-VLAN parsing:

Post-VLAN parsing::



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

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

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

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

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

  +------+------+------+-----+-----------+-----------+
@@ -75,7 +84,9 @@ Post-VLAN parsing: 
                                          |

                                          |

                                          +-- flow dissector starts here

                                          +-- 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->thoff = nhoff

  flow_keys->n_proto = ETHER_TYPE

  flow_keys->n_proto = ETHER_TYPE
@@ -93,14 +104,14 @@ handle both cases. 
Reference Implementation

Reference Implementation

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

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





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

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

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

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

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

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





The reference implementation is organized as follows:

The reference implementation is organized as follows:

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

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

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

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

  bpf_tail_call to the appropriate L3 handler

    does ``bpf_tail_call`` to the appropriate L3 handler





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

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

jmp_table is used instead to handle multiple levels of encapsulation (and
@@ -111,5 +122,5 @@ Current Limitations 
===================

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

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

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)

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.
 
for a set of information that's currently can be exported from the BPF context.

Documentation/networking/index.rst

+1 −0
Original line number Original line Diff line number Diff line
@@ -9,6 +9,7 @@ Contents: 
   netdev-FAQ

   netdev-FAQ

   af_xdp

   af_xdp

   batman-adv

   batman-adv

   bpf_flow_dissector

   can

   can

   can_ucan_protocol

   can_ucan_protocol

   device_drivers/freescale/dpaa2/index

   device_drivers/freescale/dpaa2/index