On 3/3/26 2:20 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 <[email protected]>
> ---
> v4: more updates/corrections from Ilya (Thanks!);
> use "net-next" (Jakub);
> v3: update descriptions based on Ilya's feedback;
> v2: correct -net to net for tree destination/designation;
> add more kernel-doc for various enums;
>
> Cc: Aaron Conole <[email protected]>
> Cc: Eelco Chaudron <[email protected]>
> Cc: Ilya Maximets <[email protected]>
> Cc: "David S. Miller" <[email protected]>
> Cc: Eric Dumazet <[email protected]>
> Cc: Jakub Kicinski <[email protected]>
> Cc: Paolo Abeni <[email protected]>
> Cc: Simon Horman <[email protected]>
> Cc: [email protected]
>
> include/uapi/linux/openvswitch.h | 76 +++++++++++++++++++++++++----
> 1 file changed, 68 insertions(+), 8 deletions(-)
>
> --- linux-next-20260227.orig/include/uapi/linux/openvswitch.h
> +++ linux-next-20260227/include/uapi/linux/openvswitch.h
> @@ -70,12 +70,15 @@ 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: Number of the entries in the flow table
> + * masks cache.
> * @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 +86,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 +189,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 +205,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 +271,11 @@ 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.
> + * Only valid for vport type %OVS_VPORT_TYPE_INTERNAL.
This one is still a bit misleading. How about:
"Provides the ifindex of a vport, or sets the desired ifindex while
creating a new vport with type %OVS_VPORT_TYPE_INTERNAL." ?
> + * @OVS_VPORT_ATTR_NETNSID: Provides the netns id of the vport if it's not
> local.
> + * @OVS_VPORT_ATTR_UPCALL_STATS: Provides upcall statistics for a vport.
> + * 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 +291,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,23 +301,27 @@ 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
> };
>
> #define OVS_VPORT_ATTR_MAX (__OVS_VPORT_ATTR_MAX - 1)
>
> /**
> - * 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.
> + * enum ovs_vport_upcall_attr - attributes for %OVS_VPORT_ATTR_UPCALL_STATS
nit: May be good to add a period at the end.
> + * @OVS_VPORT_UPCALL_ATTR_SUCCESS: 64-bit upcall success packets.
> + * @OVS_VPORT_UPCALL_ATTR_FAIL: 64-bit upcall fail packets.
> */
Best regards, Ilya Maximets.
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
