bpf: move BPF_PROG_TYPE_FLOW_DISSECTOR documentation to a new common place

In commit da7031491786 ("bpf: Document BPF_PROG_TYPE_CGROUP_SYSCTL")
Andrey proposes to put per-prog type docs under Documentation/bpf/

Let's move flow dissector documentation there as well.

Signed-off-by: Stanislav Fomichev <sdf@google.com>
Signed-off-by: Alexei Starovoitov <ast@kernel.org>

diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index dadcaa9a9f5fb4cb727168b9dc7b259d8fbfaa8d..d3fe4cac0c90a67c4072341ee8ca20ae9c62e573 100644 (file)
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -43,6 +43,7 @@ Program types
    :maxdepth: 1
 
    prog_cgroup_sysctl
+   prog_flow_dissector
 
 
 .. Links:

diff --git a/Documentation/bpf/prog_flow_dissector.rst b/Documentation/bpf/prog_flow_dissector.rst
new file mode 100644 (file)
index 0000000..ed343ab
--- /dev/null
+++ b/Documentation/bpf/prog_flow_dissector.rst
@@ -0,0 +1,126 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
+BPF_PROG_TYPE_FLOW_DISSECTOR
+============================
+
+Overview
+========
+
+Flow dissector is a routine that parses metadata out of the packets. It's
+used in the various places in the networking subsystem (RFS, flow hash, etc).
+
+BPF flow dissector is an attempt to reimplement C-based flow dissector logic
+in BPF to gain all the benefits of BPF verifier (namely, limits on the
+number of instructions and tail calls).
+
+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.
+
+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
+
+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.
+
+__sk_buff->data
+===============
+
+In the VLAN-less case, this is what the initial state of the BPF flow
+dissector looks like::
+
+  +------+------+------------+-----------+
+  | DMAC | SMAC | ETHER_TYPE | L3_HEADER |
+  +------+------+------------+-----------+
+                              ^
+                              |
+                              +-- flow dissector starts here
+
+
+.. 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::
+
+  +------+------+------+-----+-----------+-----------+
+  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |
+  +------+------+------+-----+-----------+-----------+
+                        ^
+                        |
+                        +-- flow dissector starts here
+
+.. code:: c
+
+  skb->data + flow_keys->nhoff point the to first byte of TCI
+  flow_keys->thoff = nhoff
+  flow_keys->n_proto = TPID
+
+Please note that TPID can be 802.1AD and, hence, BPF program would
+have to parse VLAN information twice for double tagged packets.
+
+
+Post-VLAN parsing::
+
+  +------+------+------+-----+-----------+-----------+
+  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |
+  +------+------+------+-----+-----------+-----------+
+                                          ^
+                                          |
+                                          +-- flow dissector starts here
+
+.. 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
+
+In this case VLAN information has been processed before the flow dissector
+and BPF flow dissector is not required to handle it.
+
+
+The takeaway here is as follows: BPF flow dissector program can be called with
+the optional VLAN header and should gracefully handle both cases: when single
+or double VLAN is present and when it is not present. The same program
+can be called for both cases and would have to be written carefully to
+handle both cases.
+
+
+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.
+
+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
+
+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
+IPv6 options).
+
+
+Current Limitations
+===================
+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``
+for a set of information that's currently can be exported from the BPF context.

diff --git a/Documentation/networking/bpf_flow_dissector.rst b/Documentation/networking/bpf_flow_dissector.rst
deleted file mode 100644 (file)
index b375ae2..0000000
--- a/Documentation/networking/bpf_flow_dissector.rst
+++ /dev/null
@@ -1,126 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-==================
-BPF Flow Dissector
-==================
-
-Overview
-========
-
-Flow dissector is a routine that parses metadata out of the packets. It's
-used in the various places in the networking subsystem (RFS, flow hash, etc).
-
-BPF flow dissector is an attempt to reimplement C-based flow dissector logic
-in BPF to gain all the benefits of BPF verifier (namely, limits on the
-number of instructions and tail calls).
-
-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.
-
-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
-
-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.
-
-__sk_buff->data
-===============
-
-In the VLAN-less case, this is what the initial state of the BPF flow
-dissector looks like::
-
-  +------+------+------------+-----------+
-  | DMAC | SMAC | ETHER_TYPE | L3_HEADER |
-  +------+------+------------+-----------+
-                              ^
-                              |
-                              +-- flow dissector starts here
-
-
-.. 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::
-
-  +------+------+------+-----+-----------+-----------+
-  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |
-  +------+------+------+-----+-----------+-----------+
-                        ^
-                        |
-                        +-- flow dissector starts here
-
-.. code:: c
-
-  skb->data + flow_keys->nhoff point the to first byte of TCI
-  flow_keys->thoff = nhoff
-  flow_keys->n_proto = TPID
-
-Please note that TPID can be 802.1AD and, hence, BPF program would
-have to parse VLAN information twice for double tagged packets.
-
-
-Post-VLAN parsing::
-
-  +------+------+------+-----+-----------+-----------+
-  | DMAC | SMAC | TPID | TCI |ETHER_TYPE | L3_HEADER |
-  +------+------+------+-----+-----------+-----------+
-                                          ^
-                                          |
-                                          +-- flow dissector starts here
-
-.. 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
-
-In this case VLAN information has been processed before the flow dissector
-and BPF flow dissector is not required to handle it.
-
-
-The takeaway here is as follows: BPF flow dissector program can be called with
-the optional VLAN header and should gracefully handle both cases: when single
-or double VLAN is present and when it is not present. The same program
-can be called for both cases and would have to be written carefully to
-handle both cases.
-
-
-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.
-
-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
-
-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
-IPv6 options).
-
-
-Current Limitations
-===================
-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``
-for a set of information that's currently can be exported from the BPF context.

diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index 984e68f9e0269507132846517a4c4c2b8d726216..5449149be496fa8448fa5b74bafe2c5c796cb06d 100644 (file)
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -9,7 +9,6 @@ Contents:
    netdev-FAQ
    af_xdp
    batman-adv
-   bpf_flow_dissector
    can
    can_ucan_protocol
    device_drivers/freescale/dpaa2/index