api: packet: specify which packet flags cannot be set simultaneously

Specify which packet metadata flags cannot be set simultaneously using
odp_packet_has_XX_set() functions.

Signed-off-by: Matias Elo <matias.elo@nokia.com>
Reviewed-by: Kiran Kumar K <kirankumark@marvell.com>
Reviewed-by: Jere Leppänen <jere.leppanen@nokia.com>
Reviewed-by: Petri Savolainen <petri.savolainen@nokia.com>

1 files changed, 30 insertions, 1 deletions

diff --git a/include/odp/api/spec/packet_flags.h b/include/odp/api/spec/packet_flags.h
index 98bf2b7bf..c6ff11054 100644
--- a/include/odp/api/spec/packet_flags.h
+++ b/include/odp/api/spec/packet_flags.h
@@ -1,4 +1,5 @@
 /* Copyright (c) 2014-2018, Linaro Limited
+ * Copyright (c) 2023, Nokia
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
@@ -22,7 +23,13 @@ extern "C" {
 #include <odp/api/packet_types.h>
 
 /** @addtogroup odp_packet
- *  Operations on packet metadata flags.
+ *  @par Operations on packet metadata flags
+ *
+ * If user sets multiple conflicting packet metadata flags
+ * using odp_packet_has_XX_set() functions, only the last set flag value is
+ * guaranteed to hold. The values of other conflicting flags are implementation
+ * specific. The conflicting flag combinations are defined in function
+ * documentations.
  *  @{
  */
 
@@ -401,6 +408,8 @@ void odp_packet_has_jumbo_set(odp_packet_t pkt, int val);
 /**
  * Set flag for VLAN
  *
+ * Only one VLAN flag (VLAN/VLAN QinQ) can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -409,6 +418,8 @@ void odp_packet_has_vlan_set(odp_packet_t pkt, int val);
 /**
  * Set flag for VLAN QinQ (stacked VLAN)
  *
+ * Only one VLAN flag (VLAN/VLAN QinQ) can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -417,6 +428,8 @@ void odp_packet_has_vlan_qinq_set(odp_packet_t pkt, int val);
 /**
  * Set flag for ARP
  *
+ * Only one of ARP/IPv4/IPv6 flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -425,6 +438,8 @@ void odp_packet_has_arp_set(odp_packet_t pkt, int val);
 /**
  * Set flag for IPv4
  *
+ * Only one of ARP/IPv4/IPv6 flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -433,6 +448,8 @@ void odp_packet_has_ipv4_set(odp_packet_t pkt, int val);
 /**
  * Set flag for IPv6
  *
+ * Only one of ARP/IPv4/IPv6 flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -441,6 +458,8 @@ void odp_packet_has_ipv6_set(odp_packet_t pkt, int val);
 /**
  * Set flag for IP broadcast address
  *
+ * Only one of IP broadcast/multicast flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -449,6 +468,8 @@ void odp_packet_has_ip_bcast_set(odp_packet_t pkt, int val);
 /**
  * Set flag for IP multicast address
  *
+ * Only one of IP broadcast/multicast flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -481,6 +502,8 @@ void odp_packet_has_ipsec_set(odp_packet_t pkt, int val);
 /**
  * Set flag for UDP
  *
+ * Only one of TCP/UDP/SCTP/ICMP flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -489,6 +512,8 @@ void odp_packet_has_udp_set(odp_packet_t pkt, int val);
 /**
  * Set flag for TCP
  *
+ * Only one of TCP/UDP/SCTP/ICMP flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -497,6 +522,8 @@ void odp_packet_has_tcp_set(odp_packet_t pkt, int val);
 /**
  * Set flag for SCTP
  *
+ * Only one of TCP/UDP/SCTP/ICMP flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */
@@ -505,6 +532,8 @@ void odp_packet_has_sctp_set(odp_packet_t pkt, int val);
 /**
  * Set flag for ICMP
  *
+ * Only one of TCP/UDP/SCTP/ICMP flags can be set simultaneously.
+ *
  * @param pkt Packet handle
  * @param val Value
  */