docs: XDP troubleshooting and monitoring

Userspace need some method of Troubleshooting and Monitoring.

Document the need, so we don't forget.  Upstream have not settled on
on a solution yet.  Docuemnt the two options currently being discussed.

Signed-off-by: Jesper Dangaard Brouer <brouer@redhat.com>

kernel/Documentation/networking/XDP/implementation/userspace_api.rst

@@ -60,3 +60,36 @@ The features that need this is:
    struct change and have even benchmarked that it does not hurt
    performance).
 
+
+.. _`Troubleshooting and Monitoring`:
+
+Troubleshooting and Monitoring
+==============================
+
+Users need the ability to both monitor and troubleshoot an XDP
+program. Partigular in case of error events like :ref:`XDP_ABORTED`,
+and in case a XDP programs starts to return invalid and unsupported
+action code (caught by the :ref:`action fall-through`).
+
+.. Warning::
+
+   The current (4.8-rc6) implementation is not optimal in this area.
+   In case of the :ref:`action fall-through` packets is dropped and a
+   warning is generated **only once** about the invalid XDP program
+   action code, by calling: bpf_warn_invalid_xdp_action(action_code);
+
+The facilities and behavior need to be improved in this area.
+
+Two options are on the table currently:
+
+* Counters.
+
+  Simply add counters to track these events.  This allow admins and
+  monitor tools to catch and count these events.  This does requires
+  standardizing these counters to help monitor tools.
+
+* Tracepoints.
+
+  Another option is adding tracepoint to these situations.  It is much
+  more flexible than counters.  The downside is that these error
+  events might never be caught, if the tracepoint isn't active.

kernel/Documentation/networking/XDP/implementation/xdp_actions.rst

@@ -8,9 +8,7 @@
 XDP actions
 ===========
 
-.. TODO:: Describe the action currently implemented here. For now this
-          was primairly created to allow referencing these actions
-          with links
+.. TODO:: Missing desc for XDP_TX.
 
 .. _XDP_PASS:
 
@@ -48,27 +46,27 @@ XDP_ABORTED
 
 The XDP_ABORTED action is not something a functional program should
 ever use as a return code.  This return code is something an ``eBPF``
-program returns in case of an eBPF program error.  For this reason
-XDP_ABORTED will always be the value zero.
+program returns in case of an eBPF program error, e.g. division by
+zero.  For this reason XDP_ABORTED will always be the value zero.
 
-.. warning :: (v4.8-rc6)
-   I noticed mlx4 driver just drop packet with XDP_ABORTED.  The
-   semantics should likely be to, generating an error message of
-   invalid action like the fall-through.
+ This XDP_ABORTED action results in the packet getting dropped.
+
+For how to troubleshoot this kind of unlikely error event, see the
+section :ref:`Troubleshooting and Monitoring`.
+
+.. _`action fall-through`:
 
 Fall-through
-------------
+============
 
 There must also be a fall-through ``default:`` case, which is hit if
 the program returns an unknown action code (e.g. future action this
 driver does not support).
 
-In that case the packets is dropped and a warning is generated (once)
-about the invalid XDP program action code, by calling::
+ These unknown return codes will result in packet drop.
 
- bpf_warn_invalid_xdp_action(action_code);
-
-This implies: *Unknown return codes will result in packet drop*.
+See the section :ref:`Troubleshooting and Monitoring` for how to catch
+these kind of situations.
 
 
 Code example
@@ -87,8 +85,8 @@ statement as below.
 				goto consumed;
 			goto xdp_drop; /* Drop on xmit failure */
 		default:
-		case XDP_ABORTED:
 			bpf_warn_invalid_xdp_action(action);
+		case XDP_ABORTED:
 		case XDP_DROP:
 	xdp_drop:
 			if (driver_recycle(page, ring))