doc: net_pkt_filter: Document priority rules

Add documentation for newly added priority rules.

Signed-off-by: Cla Mattia Galliard <[email protected]>

Author: ClaCodes

doc/connectivity/networking/api/net_pkt_filter.rst

@@ -12,8 +12,9 @@ Overview
 
 The Network Packet Filtering facility provides the infrastructure to
 construct custom rules for accepting and/or denying packet transmission
-and reception. This can be used to create a basic firewall, control
-network traffic, etc.
+and reception. It also allows to modify the priority of incoming
+network packets. This can be used to create a basic firewall, control network
+traffic, etc.
 
 The :kconfig:option:`CONFIG_NET_PKT_FILTER` must be set in order to enable the
 relevant APIs.
@@ -25,8 +26,13 @@ for a given rule are true then the packet outcome is immediately determined
 as specified by the current rule and no more rules are considered. If one
 condition is false then the next rule in the list is considered.
 
-Packet outcome is either ``NET_OK`` to accept the packet or ``NET_DROP`` to
-drop it.
+Packet outcome is either ``NET_OK`` to accept the packet, ``NET_DROP`` to
+drop it or ``NET_CONTINUE`` to modify its priority on the fly.
+
+When the outcome is ``NET_CONTINUE`` the priority is updated but the final
+outcome is not yet determined and processing continues. If all conditions of
+multiple rules are true, then the packet gets the priority of the rule last
+considered.
 
 A rule is represented by a :c:struct:`npf_rule` object. It can be inserted to,
 appended to or removed from a rule list contained in a
@@ -47,7 +53,8 @@ retrieve the outer structure from the provided ``npf_test`` structure pointer.
 
 Convenience macros are provided in :zephyr_file:`include/zephyr/net/net_pkt_filter.h`
 to statically define condition instances for various conditions, and
-:c:macro:`NPF_RULE()` to create a rule instance to tie them.
+:c:macro:`NPF_RULE()` and :c:macro:`NPF_PRIORITY()` to create a rule instance
+with an immediate outcome or a priority change.
 
 Examples
 ********
@@ -86,6 +93,42 @@ Another (less efficient) way to achieve the same result could be:
         npf_append_recv_rule(&npf_default_ok);
     }
 
+This example assigns priorities to different network traffic. It gives network
+control priority (``NET_PRIORITY_NC``) to the ``ptp`` packets, critical
+applications priority (``NET_PRIORITY_CA``) to the internet traffic of version
+6, excellent effort (``NET_PRIORITY_EE``) for internet protocol version 4
+traffic, and the lowest background priority (``NET_PRIORITY_BK``) to ``lldp``
+and ``arp``.
+
+Priority rules are only really uselfull if multiple traffic class queues are
+enabled in the project configuration :kconfig:option:`CONFIG_NET_TC_RX_COUNT`.
+The mapping from the priority of the packet to the traffic class queue is in
+accordance with the standard 802.1Q and depends on the
+:kconfig:option:`CONFIG_NET_TC_RX_COUNT`.
+
+.. code-block:: c
+
+    static NPF_ETH_TYPE_MATCH(is_arp_packet, NET_ETH_PTYPE_ARP);
+    static NPF_ETH_TYPE_MATCH(is_lldp_packet, NET_ETH_PTYPE_LLDP);
+    static NPF_ETH_TYPE_MATCH(is_ptp_packet, NET_ETH_PTYPE_PTP);
+    static NPF_ETH_TYPE_MATCH(is_ipv4_packet, NET_ETH_PTYPE_IP);
+    static NPF_ETH_TYPE_MATCH(is_ipv6_packet, NET_ETH_PTYPE_IPV6);
+
+    static NPF_PRIORITY(rule_arp, NET_PRIORITY_BK, is_arp_packet);
+    static NPF_PRIORITY(rule_lldp, NET_PRIORITY_BK, is_lldp_packet);
+    static NPF_PRIORITY(rule_ipv4, NET_PRIORITY_EE, is_ipv4_packet);
+    static NPF_PRIORITY(rule_ipv6, NET_PRIORITY_CA, is_ipv6_packet);
+    static NPF_PRIORITY(rule_ptp, NET_PRIORITY_NC, is_ptp_packet);
+
+    void install_my_filter(void) {
+        npf_append_recv_rule(&rule_arp);
+        npf_append_recv_rule(&rule_lldp);
+        npf_append_recv_rule(&rule_ipv4);
+        npf_append_recv_rule(&rule_ipv6);
+        npf_append_recv_rule(&rule_ptp);
+        npf_append_recv_rule(&npf_default_ok);
+    }
+
 API Reference
 *************