[PATCH net v2] net: openvswitch: clean up some kernel-doc warnings

[PATCH net v2] net: openvswitch: clean up some kernel-doc warnings

[Randy Dunlap]

Fix some kernel-doc warnings in openvswitch.h:

Mark enum placeholders that are not used as "private" so that kernel-doc
comments are not needed for them.

Correct names for 2 enum values:
Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
 '@OVS_VPORT_UPCALL_SUCCESS' description in 'ovs_vport_upcall_attr'
Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
 '@OVS_VPORT_UPCALL_FAIL' description in 'ovs_vport_upcall_attr'

Convert one comment from "/**" kernel-doc to a plain C "/*" comment:
Warning: include/uapi/linux/openvswitch.h:638 This comment starts with
 '/**', but isn't a kernel-doc comment.
 * Omit attributes for notifications.

Add more kernel-doc:
- add kernel-doc for kernel-only enums;
- add missing kernel-doc for enum ovs_datapath_attr;
- add missing kernel-doc for enum ovs_flow_attr;
- add missing kernel-doc for enum ovs_sample_attr;
- add kernel-doc for enum ovs_check_pkt_len_attr;
- add kernel-doc for enum ovs_action_attr;
- add kernel-doc for enum ovs_action_push_eth;
- add kernel-doc for enum ovs_vport_attr;

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
v2: correct -net to net for tree destination/designation;
    add more kernel-doc for various enums;

Cc: Aaron Conole <aconole@redhat.com>
Cc: Eelco Chaudron <echaudro@redhat.com>
Cc: Ilya Maximets <i.maximets@ovn.org>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: Eric Dumazet <edumazet@google.com>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Paolo Abeni <pabeni@redhat.com>
Cc: Simon Horman <horms@kernel.org>
Cc: dev@openvswitch.org

 include/uapi/linux/openvswitch.h |   72 ++++++++++++++++++++++++++---
 1 file changed, 65 insertions(+), 7 deletions(-)

--- linux-next-20260227.orig/include/uapi/linux/openvswitch.h
+++ linux-next-20260227/include/uapi/linux/openvswitch.h
@@ -70,12 +70,14 @@ enum ovs_datapath_cmd {
  * set on the datapath port (for OVS_ACTION_ATTR_MISS).  Only valid on
  * %OVS_DP_CMD_NEW requests. A value of zero indicates that upcalls should
  * not be sent.
+ * @OVS_DP_ATTR_MASKS_CACHE_SIZE: Size of the flow table masks cache (bytes).
  * @OVS_DP_ATTR_PER_CPU_PIDS: Per-cpu array of PIDs for upcalls when
  * OVS_DP_F_DISPATCH_UPCALL_PER_CPU feature is set.
  * @OVS_DP_ATTR_STATS: Statistics about packets that have passed through the
  * datapath.  Always present in notifications.
  * @OVS_DP_ATTR_MEGAFLOW_STATS: Statistics about mega flow masks usage for the
  * datapath. Always present in notifications.
+ * @OVS_DP_ATTR_USER_FEATURES: OVS_DP_F_* flags.
  * @OVS_DP_ATTR_IFINDEX: Interface index for a new datapath netdev. Only
  * valid for %OVS_DP_CMD_NEW requests.
  *
@@ -83,18 +85,23 @@ enum ovs_datapath_cmd {
  * payload for %OVS_DP_* commands.
  */
 enum ovs_datapath_attr {
+	/* private: */
 	OVS_DP_ATTR_UNSPEC,
+	/* public: */
 	OVS_DP_ATTR_NAME,		/* name of dp_ifindex netdev */
 	OVS_DP_ATTR_UPCALL_PID,		/* Netlink PID to receive upcalls */
 	OVS_DP_ATTR_STATS,		/* struct ovs_dp_stats */
 	OVS_DP_ATTR_MEGAFLOW_STATS,	/* struct ovs_dp_megaflow_stats */
 	OVS_DP_ATTR_USER_FEATURES,	/* OVS_DP_F_*  */
+	/* private: */
 	OVS_DP_ATTR_PAD,
+	/* public: */
 	OVS_DP_ATTR_MASKS_CACHE_SIZE,
 	OVS_DP_ATTR_PER_CPU_PIDS,   /* Netlink PIDS to receive upcalls in
 				     * per-cpu dispatch mode
 				     */
 	OVS_DP_ATTR_IFINDEX,
+	/* private: */
 	__OVS_DP_ATTR_MAX
 };
 
@@ -181,6 +188,7 @@ enum ovs_packet_cmd {
  * %OVS_USERSPACE_ATTR_EGRESS_TUN_PORT attribute, which is sent only if the
  * output port is actually a tunnel port. Contains the output tunnel key
  * extracted from the packet as nested %OVS_TUNNEL_KEY_ATTR_* attributes.
+ * @OVS_PACKET_ATTR_PROBE: Packet operation is a feature probe.
  * @OVS_PACKET_ATTR_MRU: Present for an %OVS_PACKET_CMD_ACTION and
  * @OVS_PACKET_ATTR_LEN: Packet size before truncation.
  * %OVS_PACKET_ATTR_USERSPACE action specify the Maximum received fragment
@@ -196,21 +204,26 @@ enum ovs_packet_cmd {
  * payload for %OVS_PACKET_* commands.
  */
 enum ovs_packet_attr {
+	/* private: */
 	OVS_PACKET_ATTR_UNSPEC,
+	/* public: */
 	OVS_PACKET_ATTR_PACKET,      /* Packet data. */
 	OVS_PACKET_ATTR_KEY,         /* Nested OVS_KEY_ATTR_* attributes. */
 	OVS_PACKET_ATTR_ACTIONS,     /* Nested OVS_ACTION_ATTR_* attributes. */
 	OVS_PACKET_ATTR_USERDATA,    /* OVS_ACTION_ATTR_USERSPACE arg. */
 	OVS_PACKET_ATTR_EGRESS_TUN_KEY,  /* Nested OVS_TUNNEL_KEY_ATTR_*
 					    attributes. */
+	/* private: */
 	OVS_PACKET_ATTR_UNUSED1,
 	OVS_PACKET_ATTR_UNUSED2,
+	/* public: */
 	OVS_PACKET_ATTR_PROBE,      /* Packet operation is a feature probe,
 				       error logging should be suppressed. */
 	OVS_PACKET_ATTR_MRU,	    /* Maximum received IP fragment size. */
 	OVS_PACKET_ATTR_LEN,	    /* Packet size before truncation. */
 	OVS_PACKET_ATTR_HASH,	    /* Packet hash. */
 	OVS_PACKET_ATTR_UPCALL_PID, /* u32 Netlink PID. */
+	/* private: */
 	__OVS_PACKET_ATTR_MAX
 };
 
@@ -257,6 +270,10 @@ enum ovs_vport_type {
  * upcalls should not be sent.
  * @OVS_VPORT_ATTR_STATS: A &struct ovs_vport_stats giving statistics for
  * packets sent or received through the vport.
+ * @OVS_VPORT_ATTR_IFINDEX: Get the vport ifindex or put the desired ifindex
+ * @OVS_VPORT_ATTR_NETNSID: Get the vport id of a peer netns. If there isn't
+ * one, a new netns is allocated.
+ * @OVS_VPORT_ATTR_UPCALL_STATS: Provides upcall stats for a device.
  *
  * These attributes follow the &struct ovs_header within the Generic Netlink
  * payload for %OVS_VPORT_* commands.
@@ -272,7 +289,9 @@ enum ovs_vport_type {
  * ovs_header plus %OVS_VPORT_ATTR_PORT_NO determine the vport.
  */
 enum ovs_vport_attr {
+	/* private: */
 	OVS_VPORT_ATTR_UNSPEC,
+	/* public: */
 	OVS_VPORT_ATTR_PORT_NO,	/* u32 port number within datapath */
 	OVS_VPORT_ATTR_TYPE,	/* u32 OVS_VPORT_TYPE_* constant. */
 	OVS_VPORT_ATTR_NAME,	/* string name, up to IFNAMSIZ bytes long */
@@ -280,10 +299,13 @@ enum ovs_vport_attr {
 	OVS_VPORT_ATTR_UPCALL_PID, /* array of u32 Netlink socket PIDs for */
 				/* receiving upcalls */
 	OVS_VPORT_ATTR_STATS,	/* struct ovs_vport_stats */
+	/* private: */
 	OVS_VPORT_ATTR_PAD,
+	/* public: */
 	OVS_VPORT_ATTR_IFINDEX,
 	OVS_VPORT_ATTR_NETNSID,
 	OVS_VPORT_ATTR_UPCALL_STATS,
+	/* private: */
 	__OVS_VPORT_ATTR_MAX
 };
 
@@ -291,12 +313,13 @@ enum ovs_vport_attr {
 
 /**
  * enum ovs_vport_upcall_attr - attributes for %OVS_VPORT_UPCALL* commands
- * @OVS_VPORT_UPCALL_SUCCESS: 64-bit upcall success packets.
- * @OVS_VPORT_UPCALL_FAIL: 64-bit upcall fail packets.
+ * @OVS_VPORT_UPCALL_ATTR_SUCCESS: 64-bit upcall success packets.
+ * @OVS_VPORT_UPCALL_ATTR_FAIL: 64-bit upcall fail packets.
  */
 enum ovs_vport_upcall_attr {
 	OVS_VPORT_UPCALL_ATTR_SUCCESS,
 	OVS_VPORT_UPCALL_ATTR_FAIL,
+	/* private: */
 	__OVS_VPORT_UPCALL_ATTR_MAX
 };
 
@@ -431,6 +454,7 @@ enum ovs_frag_type {
 	OVS_FRAG_TYPE_NONE,
 	OVS_FRAG_TYPE_FIRST,
 	OVS_FRAG_TYPE_LATER,
+	/* private: */
 	__OVS_FRAG_TYPE_MAX
 };
 
@@ -604,6 +628,8 @@ struct ovs_nsh_key_md1 {
  * a wildcarded match. Omitting attribute is treated as wildcarding all
  * corresponding fields. Optional for all requests. If not present,
  * all flow key bits are exact match bits.
+ * @OVS_FLOW_ATTR_PROBE: Flow operation is a feature probe, error logging
+ * should be suppressed.
  * @OVS_FLOW_ATTR_UFID: A value between 1-16 octets specifying a unique
  * identifier for the flow. Causes the flow to be indexed by this value rather
  * than the value of the %OVS_FLOW_ATTR_KEY attribute. Optional for all
@@ -617,7 +643,9 @@ struct ovs_nsh_key_md1 {
  * payload for %OVS_FLOW_* commands.
  */
 enum ovs_flow_attr {
+	/* private: */
 	OVS_FLOW_ATTR_UNSPEC,
+	/* public: */
 	OVS_FLOW_ATTR_KEY,       /* Sequence of OVS_KEY_ATTR_* attributes. */
 	OVS_FLOW_ATTR_ACTIONS,   /* Nested OVS_ACTION_ATTR_* attributes. */
 	OVS_FLOW_ATTR_STATS,     /* struct ovs_flow_stats. */
@@ -629,13 +657,14 @@ enum ovs_flow_attr {
 				  * logging should be suppressed. */
 	OVS_FLOW_ATTR_UFID,      /* Variable length unique flow identifier. */
 	OVS_FLOW_ATTR_UFID_FLAGS,/* u32 of OVS_UFID_F_*. */
+	/* private: */
 	OVS_FLOW_ATTR_PAD,
 	__OVS_FLOW_ATTR_MAX
 };
 
 #define OVS_FLOW_ATTR_MAX (__OVS_FLOW_ATTR_MAX - 1)
 
-/**
+/*
  * Omit attributes for notifications.
  *
  * If a datapath request contains an %OVS_UFID_F_OMIT_* flag, then the datapath
@@ -652,6 +681,8 @@ enum ovs_flow_attr {
  * %UINT32_MAX samples all packets and intermediate values sample intermediate
  * fractions of packets.
  * @OVS_SAMPLE_ATTR_ACTIONS: Set of actions to execute in sampling event.
+ * @OVS_SAMPLE_ATTR_ARG: same as @OVS_SAMPLE_ATTR_PROBABILITY, for in-kernel
+ * use, passing &struct sample_arg.
  * Actions are passed as nested attributes.
  *
  * Executes the specified actions with the given probability on a per-packet
@@ -659,11 +690,15 @@ enum ovs_flow_attr {
  * parent @OVS_ACTION_ATTR_SAMPLE.
  */
 enum ovs_sample_attr {
+	/* private: */
 	OVS_SAMPLE_ATTR_UNSPEC,
+	/* public: */
 	OVS_SAMPLE_ATTR_PROBABILITY, /* u32 number */
 	OVS_SAMPLE_ATTR_ACTIONS,     /* Nested OVS_ACTION_ATTR_* attributes. */
+	/* private: */
 	__OVS_SAMPLE_ATTR_MAX,
 
+	/* public: */
 #ifdef __KERNEL__
 	OVS_SAMPLE_ATTR_ARG          /* struct sample_arg  */
 #endif
@@ -693,12 +728,15 @@ struct sample_arg {
  * @OVS_USERSPACE_ATTR_ACTIONS: If present, send actions with upcall.
  */
 enum ovs_userspace_attr {
+	/* private: */
 	OVS_USERSPACE_ATTR_UNSPEC,
+	/* public: */
 	OVS_USERSPACE_ATTR_PID,	      /* u32 Netlink PID to receive upcalls. */
 	OVS_USERSPACE_ATTR_USERDATA,  /* Optional user-specified cookie. */
 	OVS_USERSPACE_ATTR_EGRESS_TUN_PORT,  /* Optional, u32 output port
 					      * to get tunnel info. */
 	OVS_USERSPACE_ATTR_ACTIONS,   /* Optional flag to get actions. */
+	/* private: */
 	__OVS_USERSPACE_ATTR_MAX
 };
 
@@ -819,7 +857,9 @@ struct ovs_action_hash {
  * @OVS_CT_ATTR_TIMEOUT: Variable length string defining conntrack timeout.
  */
 enum ovs_ct_attr {
+	/* private: */
 	OVS_CT_ATTR_UNSPEC,
+	/* public: */
 	OVS_CT_ATTR_COMMIT,     /* No argument, commits connection. */
 	OVS_CT_ATTR_ZONE,       /* u16 zone id. */
 	OVS_CT_ATTR_MARK,       /* mark to associate with this connection. */
@@ -831,6 +871,7 @@ enum ovs_ct_attr {
 	OVS_CT_ATTR_EVENTMASK,  /* u32 mask of IPCT_* events. */
 	OVS_CT_ATTR_TIMEOUT,	/* Associate timeout with this connection for
 				 * fine-grain timeout tuning. */
+	/* private: */
 	__OVS_CT_ATTR_MAX
 };
 
@@ -859,7 +900,9 @@ enum ovs_ct_attr {
  * @OVS_NAT_ATTR_PROTO_RANDOM: Flag for fully randomized L4 port mapping
  */
 enum ovs_nat_attr {
+	/* private: */
 	OVS_NAT_ATTR_UNSPEC,
+	/* public: */
 	OVS_NAT_ATTR_SRC,
 	OVS_NAT_ATTR_DST,
 	OVS_NAT_ATTR_IP_MIN,
@@ -869,38 +912,44 @@ enum ovs_nat_attr {
 	OVS_NAT_ATTR_PERSISTENT,
 	OVS_NAT_ATTR_PROTO_HASH,
 	OVS_NAT_ATTR_PROTO_RANDOM,
+	/* private: */
 	__OVS_NAT_ATTR_MAX,
 };
 
 #define OVS_NAT_ATTR_MAX (__OVS_NAT_ATTR_MAX - 1)
 
-/*
+/**
  * struct ovs_action_push_eth - %OVS_ACTION_ATTR_PUSH_ETH action argument.
  * @addresses: Source and destination MAC addresses.
- * @eth_type: Ethernet type
  */
 struct ovs_action_push_eth {
 	struct ovs_key_ethernet addresses;
 };
 
-/*
+/**
  * enum ovs_check_pkt_len_attr - Attributes for %OVS_ACTION_ATTR_CHECK_PKT_LEN.
  *
  * @OVS_CHECK_PKT_LEN_ATTR_PKT_LEN: u16 Packet length to check for.
  * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_GREATER: Nested OVS_ACTION_ATTR_*
  * actions to apply if the packer length is greater than the specified
  * length in the attr - OVS_CHECK_PKT_LEN_ATTR_PKT_LEN.
- * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL - Nested OVS_ACTION_ATTR_*
+ * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL: Nested OVS_ACTION_ATTR_*
  * actions to apply if the packer length is lesser or equal to the specified
  * length in the attr - OVS_CHECK_PKT_LEN_ATTR_PKT_LEN.
+ * @OVS_CHECK_PKT_LEN_ATTR_ARG: similar to @OVS_CHECK_PKT_LEN_ATTR_PKT_LEN,
+ * used in-kernel, passes &struct check_pkt_len_arg.
  */
 enum ovs_check_pkt_len_attr {
+	/* private: */
 	OVS_CHECK_PKT_LEN_ATTR_UNSPEC,
+	/* public: */
 	OVS_CHECK_PKT_LEN_ATTR_PKT_LEN,
 	OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_GREATER,
 	OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL,
+	/* private: */
 	__OVS_CHECK_PKT_LEN_ATTR_MAX,
 
+	/* public: */
 #ifdef __KERNEL__
 	OVS_CHECK_PKT_LEN_ATTR_ARG          /* struct check_pkt_len_arg  */
 #endif
@@ -968,6 +1017,10 @@ enum ovs_psample_attr {
  * from the packet.
  * @OVS_ACTION_ATTR_SAMPLE: Probabilitically executes actions, as specified in
  * the nested %OVS_SAMPLE_ATTR_* attributes.
+ * @OVS_ACTION_ATTR_RECIRC: Execute actions on the clone of the packet
+ * (u32 recirc_id).
+ * @OVS_ACTION_ATTR_HASH: Compute hash prior to recirculation, using
+ * &struct ovs_action_hash.
  * @OVS_ACTION_ATTR_PUSH_MPLS: Push a new MPLS label stack entry onto the
  * top of the packets MPLS label stack.  Set the ethertype of the
  * encapsulating frame to either %ETH_P_MPLS_UC or %ETH_P_MPLS_MC to
@@ -997,6 +1050,7 @@ enum ovs_psample_attr {
  * start of the packet or at the start of the l3 header depending on the value
  * of l3 tunnel flag in the tun_flags field of OVS_ACTION_ATTR_ADD_MPLS
  * argument.
+ * @OVS_ACTION_ATTR_DEC_TTL: Nested OVS_DEC_TTL_ATTR_* action.
  * @OVS_ACTION_ATTR_DROP: Explicit drop action.
  * @OVS_ACTION_ATTR_PSAMPLE: Send a sample of the packet to external observers
  * via psample.
@@ -1010,7 +1064,9 @@ enum ovs_psample_attr {
  */
 
 enum ovs_action_attr {
+	/* private: */
 	OVS_ACTION_ATTR_UNSPEC,
+	/* public: */
 	OVS_ACTION_ATTR_OUTPUT,	      /* u32 port number. */
 	OVS_ACTION_ATTR_USERSPACE,    /* Nested OVS_USERSPACE_ATTR_*. */
 	OVS_ACTION_ATTR_SET,          /* One nested OVS_KEY_ATTR_*. */
@@ -1040,9 +1096,11 @@ enum ovs_action_attr {
 	OVS_ACTION_ATTR_DROP,         /* u32 error code. */
 	OVS_ACTION_ATTR_PSAMPLE,      /* Nested OVS_PSAMPLE_ATTR_*. */
 
+	/* private: */
 	__OVS_ACTION_ATTR_MAX,	      /* Nothing past this will be accepted
 				       * from userspace. */
 
+	/* public: */
 #ifdef __KERNEL__
 	OVS_ACTION_ATTR_SET_TO_MASKED, /* Kernel module internal masked
 					* set action converted from

Re: [PATCH net v2] net: openvswitch: clean up some kernel-doc warnings

[Ilya Maximets]

On 2/28/26 2:00 AM, Randy Dunlap wrote:
> Fix some kernel-doc warnings in openvswitch.h:
> 
> Mark enum placeholders that are not used as "private" so that kernel-doc
> comments are not needed for them.
> 
> Correct names for 2 enum values:
> Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
>  '@OVS_VPORT_UPCALL_SUCCESS' description in 'ovs_vport_upcall_attr'
> Warning: include/uapi/linux/openvswitch.h:300 Excess enum value
>  '@OVS_VPORT_UPCALL_FAIL' description in 'ovs_vport_upcall_attr'
> 
> Convert one comment from "/**" kernel-doc to a plain C "/*" comment:
> Warning: include/uapi/linux/openvswitch.h:638 This comment starts with
>  '/**', but isn't a kernel-doc comment.
>  * Omit attributes for notifications.
> 
> Add more kernel-doc:
> - add kernel-doc for kernel-only enums;
> - add missing kernel-doc for enum ovs_datapath_attr;
> - add missing kernel-doc for enum ovs_flow_attr;
> - add missing kernel-doc for enum ovs_sample_attr;
> - add kernel-doc for enum ovs_check_pkt_len_attr;
> - add kernel-doc for enum ovs_action_attr;
> - add kernel-doc for enum ovs_action_push_eth;
> - add kernel-doc for enum ovs_vport_attr;
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> v2: correct -net to net for tree destination/designation;
>     add more kernel-doc for various enums;
> 
> Cc: Aaron Conole <aconole@redhat.com>
> Cc: Eelco Chaudron <echaudro@redhat.com>
> Cc: Ilya Maximets <i.maximets@ovn.org>
> Cc: "David S. Miller" <davem@davemloft.net>
> Cc: Eric Dumazet <edumazet@google.com>
> Cc: Jakub Kicinski <kuba@kernel.org>
> Cc: Paolo Abeni <pabeni@redhat.com>
> Cc: Simon Horman <horms@kernel.org>
> Cc: dev@openvswitch.org
> 
>  include/uapi/linux/openvswitch.h |   72 ++++++++++++++++++++++++++---
>  1 file changed, 65 insertions(+), 7 deletions(-)
> 
> --- linux-next-20260227.orig/include/uapi/linux/openvswitch.h
> +++ linux-next-20260227/include/uapi/linux/openvswitch.h
> @@ -70,12 +70,14 @@ enum ovs_datapath_cmd {
>   * set on the datapath port (for OVS_ACTION_ATTR_MISS).  Only valid on
>   * %OVS_DP_CMD_NEW requests. A value of zero indicates that upcalls should
>   * not be sent.
> + * @OVS_DP_ATTR_MASKS_CACHE_SIZE: Size of the flow table masks cache (bytes).

This one is not in bytes, it's number or cache entries.  See the
net/openvswitch/flow_table.c:tbl_mask_cache_alloc().

>   * @OVS_DP_ATTR_PER_CPU_PIDS: Per-cpu array of PIDs for upcalls when
>   * OVS_DP_F_DISPATCH_UPCALL_PER_CPU feature is set.
>   * @OVS_DP_ATTR_STATS: Statistics about packets that have passed through the
>   * datapath.  Always present in notifications.
>   * @OVS_DP_ATTR_MEGAFLOW_STATS: Statistics about mega flow masks usage for the
>   * datapath. Always present in notifications.
> + * @OVS_DP_ATTR_USER_FEATURES: OVS_DP_F_* flags.
>   * @OVS_DP_ATTR_IFINDEX: Interface index for a new datapath netdev. Only
>   * valid for %OVS_DP_CMD_NEW requests.
>   *
> @@ -83,18 +85,23 @@ enum ovs_datapath_cmd {
>   * payload for %OVS_DP_* commands.
>   */
>  enum ovs_datapath_attr {
> +	/* private: */
>  	OVS_DP_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_DP_ATTR_NAME,		/* name of dp_ifindex netdev */
>  	OVS_DP_ATTR_UPCALL_PID,		/* Netlink PID to receive upcalls */
>  	OVS_DP_ATTR_STATS,		/* struct ovs_dp_stats */
>  	OVS_DP_ATTR_MEGAFLOW_STATS,	/* struct ovs_dp_megaflow_stats */
>  	OVS_DP_ATTR_USER_FEATURES,	/* OVS_DP_F_*  */
> +	/* private: */
>  	OVS_DP_ATTR_PAD,
> +	/* public: */
>  	OVS_DP_ATTR_MASKS_CACHE_SIZE,
>  	OVS_DP_ATTR_PER_CPU_PIDS,   /* Netlink PIDS to receive upcalls in
>  				     * per-cpu dispatch mode
>  				     */
>  	OVS_DP_ATTR_IFINDEX,
> +	/* private: */
>  	__OVS_DP_ATTR_MAX
>  };
>  
> @@ -181,6 +188,7 @@ enum ovs_packet_cmd {
>   * %OVS_USERSPACE_ATTR_EGRESS_TUN_PORT attribute, which is sent only if the
>   * output port is actually a tunnel port. Contains the output tunnel key
>   * extracted from the packet as nested %OVS_TUNNEL_KEY_ATTR_* attributes.
> + * @OVS_PACKET_ATTR_PROBE: Packet operation is a feature probe.
>   * @OVS_PACKET_ATTR_MRU: Present for an %OVS_PACKET_CMD_ACTION and
>   * @OVS_PACKET_ATTR_LEN: Packet size before truncation.
>   * %OVS_PACKET_ATTR_USERSPACE action specify the Maximum received fragment
> @@ -196,21 +204,26 @@ enum ovs_packet_cmd {
>   * payload for %OVS_PACKET_* commands.
>   */
>  enum ovs_packet_attr {
> +	/* private: */
>  	OVS_PACKET_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_PACKET_ATTR_PACKET,      /* Packet data. */
>  	OVS_PACKET_ATTR_KEY,         /* Nested OVS_KEY_ATTR_* attributes. */
>  	OVS_PACKET_ATTR_ACTIONS,     /* Nested OVS_ACTION_ATTR_* attributes. */
>  	OVS_PACKET_ATTR_USERDATA,    /* OVS_ACTION_ATTR_USERSPACE arg. */
>  	OVS_PACKET_ATTR_EGRESS_TUN_KEY,  /* Nested OVS_TUNNEL_KEY_ATTR_*
>  					    attributes. */
> +	/* private: */
>  	OVS_PACKET_ATTR_UNUSED1,
>  	OVS_PACKET_ATTR_UNUSED2,
> +	/* public: */
>  	OVS_PACKET_ATTR_PROBE,      /* Packet operation is a feature probe,
>  				       error logging should be suppressed. */
>  	OVS_PACKET_ATTR_MRU,	    /* Maximum received IP fragment size. */
>  	OVS_PACKET_ATTR_LEN,	    /* Packet size before truncation. */
>  	OVS_PACKET_ATTR_HASH,	    /* Packet hash. */
>  	OVS_PACKET_ATTR_UPCALL_PID, /* u32 Netlink PID. */
> +	/* private: */
>  	__OVS_PACKET_ATTR_MAX
>  };
>  
> @@ -257,6 +270,10 @@ enum ovs_vport_type {
>   * upcalls should not be sent.
>   * @OVS_VPORT_ATTR_STATS: A &struct ovs_vport_stats giving statistics for
>   * packets sent or received through the vport.
> + * @OVS_VPORT_ATTR_IFINDEX: Get the vport ifindex or put the desired ifindex

May want to clarify that a desired ifindex can only be requested for the
vport type %OVS_VPORT_TYPE_INTERNAL.

> + * @OVS_VPORT_ATTR_NETNSID: Get the vport id of a peer netns. If there isn't
> + * one, a new netns is allocated.

'vport id of a peer netns' is confusing.  It'd say 'netns id of the vport,
if it's not local'.  The allocation part is an internal detail, I don't
think we need to document that.

> + * @OVS_VPORT_ATTR_UPCALL_STATS: Provides upcall stats for a device.

s/device/vport/
s/stats/statistics/

But also, this one contains nested %OVS_VPORT_UPCALL_ATTR_* attributes.

>   *
>   * These attributes follow the &struct ovs_header within the Generic Netlink
>   * payload for %OVS_VPORT_* commands.
> @@ -272,7 +289,9 @@ enum ovs_vport_type {
>   * ovs_header plus %OVS_VPORT_ATTR_PORT_NO determine the vport.
>   */
>  enum ovs_vport_attr {
> +	/* private: */
>  	OVS_VPORT_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_VPORT_ATTR_PORT_NO,	/* u32 port number within datapath */
>  	OVS_VPORT_ATTR_TYPE,	/* u32 OVS_VPORT_TYPE_* constant. */
>  	OVS_VPORT_ATTR_NAME,	/* string name, up to IFNAMSIZ bytes long */
> @@ -280,10 +299,13 @@ enum ovs_vport_attr {
>  	OVS_VPORT_ATTR_UPCALL_PID, /* array of u32 Netlink socket PIDs for */
>  				/* receiving upcalls */
>  	OVS_VPORT_ATTR_STATS,	/* struct ovs_vport_stats */
> +	/* private: */
>  	OVS_VPORT_ATTR_PAD,
> +	/* public: */
>  	OVS_VPORT_ATTR_IFINDEX,
>  	OVS_VPORT_ATTR_NETNSID,
>  	OVS_VPORT_ATTR_UPCALL_STATS,
> +	/* private: */
>  	__OVS_VPORT_ATTR_MAX
>  };
>  
> @@ -291,12 +313,13 @@ enum ovs_vport_attr {
>  
>  /**
>   * enum ovs_vport_upcall_attr - attributes for %OVS_VPORT_UPCALL* commands

Not a problem of this patch, but this line is also wrong, there are no
such commands.  These are attributes for OVS_VPORT_ATTR_UPCALL_STATS.

> - * @OVS_VPORT_UPCALL_SUCCESS: 64-bit upcall success packets.
> - * @OVS_VPORT_UPCALL_FAIL: 64-bit upcall fail packets.
> + * @OVS_VPORT_UPCALL_ATTR_SUCCESS: 64-bit upcall success packets.
> + * @OVS_VPORT_UPCALL_ATTR_FAIL: 64-bit upcall fail packets.
>   */
>  enum ovs_vport_upcall_attr {
>  	OVS_VPORT_UPCALL_ATTR_SUCCESS,
>  	OVS_VPORT_UPCALL_ATTR_FAIL,
> +	/* private: */
>  	__OVS_VPORT_UPCALL_ATTR_MAX
>  };
>  
> @@ -431,6 +454,7 @@ enum ovs_frag_type {
>  	OVS_FRAG_TYPE_NONE,
>  	OVS_FRAG_TYPE_FIRST,
>  	OVS_FRAG_TYPE_LATER,
> +	/* private: */
>  	__OVS_FRAG_TYPE_MAX
>  };
>  
> @@ -604,6 +628,8 @@ struct ovs_nsh_key_md1 {
>   * a wildcarded match. Omitting attribute is treated as wildcarding all
>   * corresponding fields. Optional for all requests. If not present,
>   * all flow key bits are exact match bits.
> + * @OVS_FLOW_ATTR_PROBE: Flow operation is a feature probe, error logging
> + * should be suppressed.
>   * @OVS_FLOW_ATTR_UFID: A value between 1-16 octets specifying a unique
>   * identifier for the flow. Causes the flow to be indexed by this value rather
>   * than the value of the %OVS_FLOW_ATTR_KEY attribute. Optional for all
> @@ -617,7 +643,9 @@ struct ovs_nsh_key_md1 {
>   * payload for %OVS_FLOW_* commands.
>   */
>  enum ovs_flow_attr {
> +	/* private: */
>  	OVS_FLOW_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_FLOW_ATTR_KEY,       /* Sequence of OVS_KEY_ATTR_* attributes. */
>  	OVS_FLOW_ATTR_ACTIONS,   /* Nested OVS_ACTION_ATTR_* attributes. */
>  	OVS_FLOW_ATTR_STATS,     /* struct ovs_flow_stats. */
> @@ -629,13 +657,14 @@ enum ovs_flow_attr {
>  				  * logging should be suppressed. */
>  	OVS_FLOW_ATTR_UFID,      /* Variable length unique flow identifier. */
>  	OVS_FLOW_ATTR_UFID_FLAGS,/* u32 of OVS_UFID_F_*. */
> +	/* private: */
>  	OVS_FLOW_ATTR_PAD,
>  	__OVS_FLOW_ATTR_MAX
>  };
>  
>  #define OVS_FLOW_ATTR_MAX (__OVS_FLOW_ATTR_MAX - 1)
>  
> -/**
> +/*
>   * Omit attributes for notifications.
>   *
>   * If a datapath request contains an %OVS_UFID_F_OMIT_* flag, then the datapath
> @@ -652,6 +681,8 @@ enum ovs_flow_attr {
>   * %UINT32_MAX samples all packets and intermediate values sample intermediate
>   * fractions of packets.
>   * @OVS_SAMPLE_ATTR_ACTIONS: Set of actions to execute in sampling event.
> + * @OVS_SAMPLE_ATTR_ARG: same as @OVS_SAMPLE_ATTR_PROBABILITY, for in-kernel
> + * use, passing &struct sample_arg.

I wouldn't call it 'the same', more like 'extended', or just omit that part of
the description, keeping only what's after the comma.  Or maybe "For in-kernel
use, passing &struct sample_arg derived from other attributes.".

>   * Actions are passed as nested attributes.

This line belongs to OVS_SAMPLE_ATTR_ACTIONS.

>   *
>   * Executes the specified actions with the given probability on a per-packet
> @@ -659,11 +690,15 @@ enum ovs_flow_attr {
>   * parent @OVS_ACTION_ATTR_SAMPLE.
>   */
>  enum ovs_sample_attr {
> +	/* private: */
>  	OVS_SAMPLE_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_SAMPLE_ATTR_PROBABILITY, /* u32 number */
>  	OVS_SAMPLE_ATTR_ACTIONS,     /* Nested OVS_ACTION_ATTR_* attributes. */
> +	/* private: */
>  	__OVS_SAMPLE_ATTR_MAX,
>  
> +	/* public: */
>  #ifdef __KERNEL__
>  	OVS_SAMPLE_ATTR_ARG          /* struct sample_arg  */
>  #endif
> @@ -693,12 +728,15 @@ struct sample_arg {
>   * @OVS_USERSPACE_ATTR_ACTIONS: If present, send actions with upcall.
>   */
>  enum ovs_userspace_attr {
> +	/* private: */
>  	OVS_USERSPACE_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_USERSPACE_ATTR_PID,	      /* u32 Netlink PID to receive upcalls. */
>  	OVS_USERSPACE_ATTR_USERDATA,  /* Optional user-specified cookie. */
>  	OVS_USERSPACE_ATTR_EGRESS_TUN_PORT,  /* Optional, u32 output port
>  					      * to get tunnel info. */
>  	OVS_USERSPACE_ATTR_ACTIONS,   /* Optional flag to get actions. */
> +	/* private: */
>  	__OVS_USERSPACE_ATTR_MAX
>  };
>  
> @@ -819,7 +857,9 @@ struct ovs_action_hash {
>   * @OVS_CT_ATTR_TIMEOUT: Variable length string defining conntrack timeout.
>   */
>  enum ovs_ct_attr {
> +	/* private: */
>  	OVS_CT_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_CT_ATTR_COMMIT,     /* No argument, commits connection. */
>  	OVS_CT_ATTR_ZONE,       /* u16 zone id. */
>  	OVS_CT_ATTR_MARK,       /* mark to associate with this connection. */
> @@ -831,6 +871,7 @@ enum ovs_ct_attr {
>  	OVS_CT_ATTR_EVENTMASK,  /* u32 mask of IPCT_* events. */
>  	OVS_CT_ATTR_TIMEOUT,	/* Associate timeout with this connection for
>  				 * fine-grain timeout tuning. */
> +	/* private: */
>  	__OVS_CT_ATTR_MAX
>  };
>  
> @@ -859,7 +900,9 @@ enum ovs_ct_attr {
>   * @OVS_NAT_ATTR_PROTO_RANDOM: Flag for fully randomized L4 port mapping
>   */
>  enum ovs_nat_attr {
> +	/* private: */
>  	OVS_NAT_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_NAT_ATTR_SRC,
>  	OVS_NAT_ATTR_DST,
>  	OVS_NAT_ATTR_IP_MIN,
> @@ -869,38 +912,44 @@ enum ovs_nat_attr {
>  	OVS_NAT_ATTR_PERSISTENT,
>  	OVS_NAT_ATTR_PROTO_HASH,
>  	OVS_NAT_ATTR_PROTO_RANDOM,
> +	/* private: */
>  	__OVS_NAT_ATTR_MAX,
>  };
>  
>  #define OVS_NAT_ATTR_MAX (__OVS_NAT_ATTR_MAX - 1)
>  
> -/*
> +/**
>   * struct ovs_action_push_eth - %OVS_ACTION_ATTR_PUSH_ETH action argument.
>   * @addresses: Source and destination MAC addresses.
> - * @eth_type: Ethernet type
>   */
>  struct ovs_action_push_eth {
>  	struct ovs_key_ethernet addresses;
>  };
>  
> -/*
> +/**
>   * enum ovs_check_pkt_len_attr - Attributes for %OVS_ACTION_ATTR_CHECK_PKT_LEN.
>   *
>   * @OVS_CHECK_PKT_LEN_ATTR_PKT_LEN: u16 Packet length to check for.
>   * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_GREATER: Nested OVS_ACTION_ATTR_*
>   * actions to apply if the packer length is greater than the specified
>   * length in the attr - OVS_CHECK_PKT_LEN_ATTR_PKT_LEN.
> - * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL - Nested OVS_ACTION_ATTR_*
> + * @OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL: Nested OVS_ACTION_ATTR_*
>   * actions to apply if the packer length is lesser or equal to the specified
>   * length in the attr - OVS_CHECK_PKT_LEN_ATTR_PKT_LEN.
> + * @OVS_CHECK_PKT_LEN_ATTR_ARG: similar to @OVS_CHECK_PKT_LEN_ATTR_PKT_LEN,
> + * used in-kernel, passes &struct check_pkt_len_arg.

Similar commenent as for OVS_SAMPLE_ATTR_ARG.

>   */
>  enum ovs_check_pkt_len_attr {
> +	/* private: */
>  	OVS_CHECK_PKT_LEN_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_CHECK_PKT_LEN_ATTR_PKT_LEN,
>  	OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_GREATER,
>  	OVS_CHECK_PKT_LEN_ATTR_ACTIONS_IF_LESS_EQUAL,
> +	/* private: */
>  	__OVS_CHECK_PKT_LEN_ATTR_MAX,
>  
> +	/* public: */
>  #ifdef __KERNEL__
>  	OVS_CHECK_PKT_LEN_ATTR_ARG          /* struct check_pkt_len_arg  */
>  #endif
> @@ -968,6 +1017,10 @@ enum ovs_psample_attr {
>   * from the packet.
>   * @OVS_ACTION_ATTR_SAMPLE: Probabilitically executes actions, as specified in
>   * the nested %OVS_SAMPLE_ATTR_* attributes.
> + * @OVS_ACTION_ATTR_RECIRC: Execute actions on the clone of the packet
> + * (u32 recirc_id).

I'd say "Recirculate the clone of the packet through the datapath with the new id".

> + * @OVS_ACTION_ATTR_HASH: Compute hash prior to recirculation, using
> + * &struct ovs_action_hash.

s/Compute hash prior to recirculation/Compute the packet hash/
or something like that.  The action itself is not tied to recirculation,
even though it's most commonly used together with it.

>   * @OVS_ACTION_ATTR_PUSH_MPLS: Push a new MPLS label stack entry onto the
>   * top of the packets MPLS label stack.  Set the ethertype of the
>   * encapsulating frame to either %ETH_P_MPLS_UC or %ETH_P_MPLS_MC to
> @@ -997,6 +1050,7 @@ enum ovs_psample_attr {
>   * start of the packet or at the start of the l3 header depending on the value
>   * of l3 tunnel flag in the tun_flags field of OVS_ACTION_ATTR_ADD_MPLS
>   * argument.
> + * @OVS_ACTION_ATTR_DEC_TTL: Nested OVS_DEC_TTL_ATTR_* action.

"Decreate TTL or hop limit of the packet.  Execute nested %OVS_DEC_TTL_ATTR_*
actions if the value is less or equal to 1."

>   * @OVS_ACTION_ATTR_DROP: Explicit drop action.
>   * @OVS_ACTION_ATTR_PSAMPLE: Send a sample of the packet to external observers
>   * via psample.
> @@ -1010,7 +1064,9 @@ enum ovs_psample_attr {
>   */
>  
>  enum ovs_action_attr {
> +	/* private: */
>  	OVS_ACTION_ATTR_UNSPEC,
> +	/* public: */
>  	OVS_ACTION_ATTR_OUTPUT,	      /* u32 port number. */
>  	OVS_ACTION_ATTR_USERSPACE,    /* Nested OVS_USERSPACE_ATTR_*. */
>  	OVS_ACTION_ATTR_SET,          /* One nested OVS_KEY_ATTR_*. */
> @@ -1040,9 +1096,11 @@ enum ovs_action_attr {
>  	OVS_ACTION_ATTR_DROP,         /* u32 error code. */
>  	OVS_ACTION_ATTR_PSAMPLE,      /* Nested OVS_PSAMPLE_ATTR_*. */
>  
> +	/* private: */
>  	__OVS_ACTION_ATTR_MAX,	      /* Nothing past this will be accepted
>  				       * from userspace. */
>  
> +	/* public: */
>  #ifdef __KERNEL__
>  	OVS_ACTION_ATTR_SET_TO_MASKED, /* Kernel module internal masked
>  					* set action converted from

Re: [PATCH net v2] net: openvswitch: clean up some kernel-doc warnings

[Randy Dunlap]

Hi Ilya,
Thanks for your careful review of these changes.

On 2/28/26 9:55 AM, Ilya Maximets wrote:
> On 2/28/26 2:00 AM, Randy Dunlap wrote:

>>
>>  include/uapi/linux/openvswitch.h |   72 ++++++++++++++++++++++++++---
>>  1 file changed, 65 insertions(+), 7 deletions(-)
>>
>> --- linux-next-20260227.orig/include/uapi/linux/openvswitch.h
>> +++ linux-next-20260227/include/uapi/linux/openvswitch.h



>> @@ -291,12 +313,13 @@ enum ovs_vport_attr {
>>  
>>  /**
>>   * enum ovs_vport_upcall_attr - attributes for %OVS_VPORT_UPCALL* commands
> 
> Not a problem of this patch, but this line is also wrong, there are no
> such commands.  These are attributes for OVS_VPORT_ATTR_UPCALL_STATS.

I corrected that.


>> @@ -652,6 +681,8 @@ enum ovs_flow_attr {
>>   * %UINT32_MAX samples all packets and intermediate values sample intermediate
>>   * fractions of packets.
>>   * @OVS_SAMPLE_ATTR_ACTIONS: Set of actions to execute in sampling event.
>> + * @OVS_SAMPLE_ATTR_ARG: same as @OVS_SAMPLE_ATTR_PROBABILITY, for in-kernel
>> + * use, passing &struct sample_arg.
> 
> I wouldn't call it 'the same', more like 'extended', or just omit that part of
> the description, keeping only what's after the comma.  Or maybe "For in-kernel
> use, passing &struct sample_arg derived from other attributes.".
> 
>>   * Actions are passed as nested attributes.
> 
> This line belongs to OVS_SAMPLE_ATTR_ACTIONS.

OK, moved it.


>>   * @OVS_ACTION_ATTR_PUSH_MPLS: Push a new MPLS label stack entry onto the
>>   * top of the packets MPLS label stack.  Set the ethertype of the
>>   * encapsulating frame to either %ETH_P_MPLS_UC or %ETH_P_MPLS_MC to
>> @@ -997,6 +1050,7 @@ enum ovs_psample_attr {
>>   * start of the packet or at the start of the l3 header depending on the value
>>   * of l3 tunnel flag in the tun_flags field of OVS_ACTION_ATTR_ADD_MPLS
>>   * argument.
>> + * @OVS_ACTION_ATTR_DEC_TTL: Nested OVS_DEC_TTL_ATTR_* action.
> 
> "Decreate TTL or hop limit of the packet.  Execute nested %OVS_DEC_TTL_ATTR_*

   Decrement
?

> actions if the value is less or equal to 1."

thanks.
-- 
~Randy

Re: [PATCH net v2] net: openvswitch: clean up some kernel-doc warnings

[Ilya Maximets]

On 2/28/26 9:47 PM, Randy Dunlap wrote:
> Hi Ilya,
> Thanks for your careful review of these changes.
> 
> On 2/28/26 9:55 AM, Ilya Maximets wrote:
>> On 2/28/26 2:00 AM, Randy Dunlap wrote:
> 
>>>
>>>  include/uapi/linux/openvswitch.h |   72 ++++++++++++++++++++++++++---
>>>  1 file changed, 65 insertions(+), 7 deletions(-)
>>>
>>> --- linux-next-20260227.orig/include/uapi/linux/openvswitch.h
>>> +++ linux-next-20260227/include/uapi/linux/openvswitch.h
> 
> 
> 
>>> @@ -291,12 +313,13 @@ enum ovs_vport_attr {
>>>  
>>>  /**
>>>   * enum ovs_vport_upcall_attr - attributes for %OVS_VPORT_UPCALL* commands
>>
>> Not a problem of this patch, but this line is also wrong, there are no
>> such commands.  These are attributes for OVS_VPORT_ATTR_UPCALL_STATS.
> 
> I corrected that.
> 
> 
>>> @@ -652,6 +681,8 @@ enum ovs_flow_attr {
>>>   * %UINT32_MAX samples all packets and intermediate values sample intermediate
>>>   * fractions of packets.
>>>   * @OVS_SAMPLE_ATTR_ACTIONS: Set of actions to execute in sampling event.
>>> + * @OVS_SAMPLE_ATTR_ARG: same as @OVS_SAMPLE_ATTR_PROBABILITY, for in-kernel
>>> + * use, passing &struct sample_arg.
>>
>> I wouldn't call it 'the same', more like 'extended', or just omit that part of
>> the description, keeping only what's after the comma.  Or maybe "For in-kernel
>> use, passing &struct sample_arg derived from other attributes.".
>>
>>>   * Actions are passed as nested attributes.
>>
>> This line belongs to OVS_SAMPLE_ATTR_ACTIONS.
> 
> OK, moved it.
> 
> 
>>>   * @OVS_ACTION_ATTR_PUSH_MPLS: Push a new MPLS label stack entry onto the
>>>   * top of the packets MPLS label stack.  Set the ethertype of the
>>>   * encapsulating frame to either %ETH_P_MPLS_UC or %ETH_P_MPLS_MC to
>>> @@ -997,6 +1050,7 @@ enum ovs_psample_attr {
>>>   * start of the packet or at the start of the l3 header depending on the value
>>>   * of l3 tunnel flag in the tun_flags field of OVS_ACTION_ATTR_ADD_MPLS
>>>   * argument.
>>> + * @OVS_ACTION_ATTR_DEC_TTL: Nested OVS_DEC_TTL_ATTR_* action.
>>
>> "Decreate TTL or hop limit of the packet.  Execute nested %OVS_DEC_TTL_ATTR_*
> 
>    Decrement
> ?

Ugh.  Yes.  Certainly a typo.  A fairly strange one. :)

> 
>> actions if the value is less or equal to 1."
> 
> thanks.