Re: [PATCH net-next v3 2/3] net: ynl: add generated kdoc to UAPI headers

[ALOK TIWARI <alok.a.tiwari@oracle.com>]

On 8/20/2025 6:40 PM, Oleksij Rempel wrote:
> Run the ynl regeneration script to apply the kdoc generation
> support added in the previous commit.
> 
> This updates the generated UAPI headers for dpll, ethtool, team,
> net_shaper, netdev, and ovpn with documentation parsed from their
> respective YAML specifications.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
>   include/uapi/linux/dpll.h                     |  30 ++++
>   .../uapi/linux/ethtool_netlink_generated.h    |  29 +++
>   include/uapi/linux/if_team.h                  |  11 ++
>   include/uapi/linux/net_shaper.h               |  50 ++++++
>   include/uapi/linux/netdev.h                   | 165 ++++++++++++++++++
>   include/uapi/linux/ovpn.h                     |  62 +++++++
>   tools/include/uapi/linux/netdev.h             | 165 ++++++++++++++++++
>   7 files changed, 512 insertions(+)
> 
> diff --git a/include/uapi/linux/dpll.h b/include/uapi/linux/dpll.h
> index 37b438ce8efc..23a4e3598650 100644
> --- a/include/uapi/linux/dpll.h
> +++ b/include/uapi/linux/dpll.h
> @@ -203,6 +203,18 @@ enum dpll_feature_state {
>   	DPLL_FEATURE_STATE_ENABLE,
>   };
>   
> +/**
> + * enum dpll_dpll
> + * @DPLL_A_CLOCK_QUALITY_LEVEL: Level of quality of a clock device. This mainly
> + *   applies when the dpll lock-status is DPLL_LOCK_STATUS_HOLDOVER. This could
> + *   be put to message multiple times to indicate possible parallel quality
> + *   levels (e.g. one specified by ITU option 1 and another one specified by
> + *   option 2).
> + * @DPLL_A_PHASE_OFFSET_MONITOR: Receive or request state of phase offset
> + *   monitor feature. If enabled, dpll device shall monitor and notify all
> + *   currently available inputs for changes of their phase offset against the
> + *   dpll device.
> + */
>   enum dpll_a {
>   	DPLL_A_ID = 1,
>   	DPLL_A_MODULE_NAME,
> @@ -221,6 +233,24 @@ enum dpll_a {
>   	DPLL_A_MAX = (__DPLL_A_MAX - 1)
>   };
>   
> +/**
> + * enum dpll_pin
> + * @DPLL_A_PIN_FRACTIONAL_FREQUENCY_OFFSET: The FFO (Fractional Frequency
> + *   Offset) between the RX and TX symbol rate on the media associated with the
> + *   pin: (rx_frequency-tx_frequency)/rx_frequency Value is in PPM (parts per

spacing for clarity (rx_frequency - tx_frequency) / rx_frequency

> + *   million). This may be implemented for example for pin of type
> + *   PIN_TYPE_SYNCE_ETH_PORT.
> + * @DPLL_A_PIN_ESYNC_FREQUENCY: Frequency of Embedded SYNC signal. If provided,
> + *   the pin is configured with a SYNC signal embedded into its base clock
> + *   frequency.
> + * @DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED: If provided a pin is capable of
> + *   embedding a SYNC signal (within given range) into its base frequency
> + *   signal.
> + * @DPLL_A_PIN_ESYNC_PULSE: A ratio of high to low state of a SYNC signal pulse
> + *   embedded into base clock frequency. Value is in percents.

should be "percent"

> + * @DPLL_A_PIN_REFERENCE_SYNC: Capable pin provides list of pins that can be
> + *   bound to create a reference-sync pin pair.
> + */
[clip]
> +/**
> + * enum ovpn_keyconf
> + * @OVPN_A_KEYCONF_PEER_ID: The unique ID of the peer in the device context. To
> + *   be used to identify peers during key operations
> + * @OVPN_A_KEYCONF_SLOT: The slot where the key should be stored
> + * @OVPN_A_KEYCONF_KEY_ID: The unique ID of the key in the peer context. Used
> + *   to fetch the correct key upon decryption
> + * @OVPN_A_KEYCONF_CIPHER_ALG: The cipher to be used when communicating with
> + *   the peer
> + * @OVPN_A_KEYCONF_ENCRYPT_DIR: Key material for encrypt direction
> + * @OVPN_A_KEYCONF_DECRYPT_DIR: Key material for decrypt direction
> + */
>   enum {
>   	OVPN_A_KEYCONF_PEER_ID = 1,
>   	OVPN_A_KEYCONF_SLOT,
> @@ -71,6 +120,12 @@ enum {
>   	OVPN_A_KEYCONF_MAX = (__OVPN_A_KEYCONF_MAX - 1)
>   };
>   
> +/**
> + * enum ovpn_keydir
> + * @OVPN_A_KEYDIR_CIPHER_KEY: The actual key to be used by the cipher
> + * @OVPN_A_KEYDIR_NONCE_TAIL: Random nonce to be concatenated to the packet ID,
> + *   in order to obtain the actual cipher IV
> + */
>   enum {
>   	OVPN_A_KEYDIR_CIPHER_KEY = 1,
>   	OVPN_A_KEYDIR_NONCE_TAIL,
> @@ -79,6 +134,13 @@ enum {
>   	OVPN_A_KEYDIR_MAX = (__OVPN_A_KEYDIR_MAX - 1)
>   };
>   
> +/**
> + * enum ovpn_ovpn
> + * @OVPN_A_IFINDEX: Index of the ovpn interface to operate on
> + * @OVPN_A_PEER: The peer object containing the attributed of interest for the

typo attributed -> attributes

> + *   specific operation
> + * @OVPN_A_KEYCONF: Peer specific cipher configuration
> + */
>   enum {
>   	OVPN_A_IFINDEX = 1,
>   	OVPN_A_PEER,
> diff --git a/tools/include/uapi/linux/netdev.h b/tools/include/uapi/linux/netdev.h
> index 48eb49aa03d4..4d5169fc798d 100644
> --- a/tools/include/uapi/linux/netdev.h
> +++ b/tools/include/uapi/linux/netdev.h
> @@ -82,6 +82,16 @@ enum netdev_napi_threaded {
>   	NETDEV_NAPI_THREADED_ENABLED,
>   };
>   
[clip]
> +/**
> + * enum netdev_qstats - Get device statistics, scoped to a device or a queue.
> + *   These statistics extend (and partially duplicate) statistics available in
> + *   struct rtnl_link_stats64. Value of the `scope` attribute determines how
> + *   statistics are aggregated. When aggregated for the entire device the
> + *   statistics represent the total number of events since last explicit reset
> + *   of the device (i.e. not a reconfiguration like changing queue count). When
> + *   reported per-queue, however, the statistics may not add up to the total
> + *   number of events, will only be reported for currently active objects, and
> + *   will likely report the number of events since last reconfiguration.
> + * @NETDEV_A_QSTATS_IFINDEX: ifindex of the netdevice to which stats belong.
> + * @NETDEV_A_QSTATS_QUEUE_TYPE: Queue type as rx, tx, for queue-id.
> + * @NETDEV_A_QSTATS_QUEUE_ID: Queue ID, if stats are scoped to a single queue
> + *   instance.
> + * @NETDEV_A_QSTATS_SCOPE: What object type should be used to iterate over the
> + *   stats.
> + * @NETDEV_A_QSTATS_RX_PACKETS: Number of wire packets successfully received
> + *   and passed to the stack. For drivers supporting XDP, XDP is considered the
> + *   first layer of the stack, so packets consumed by XDP are still counted
> + *   here.
> + * @NETDEV_A_QSTATS_RX_BYTES: Successfully received bytes, see `rx-packets`.
> + * @NETDEV_A_QSTATS_TX_PACKETS: Number of wire packets successfully sent.
> + *   Packet is considered to be successfully sent once it is in device memory
> + *   (usually this means the device has issued a DMA completion for the
> + *   packet).
> + * @NETDEV_A_QSTATS_TX_BYTES: Successfully sent bytes, see `tx-packets`.
> + * @NETDEV_A_QSTATS_RX_ALLOC_FAIL: Number of times skb or buffer allocation
> + *   failed on the Rx datapath. Allocation failure may, or may not result in a
> + *   packet drop, depending on driver implementation and whether system
> + *   recovers quickly.
> + * @NETDEV_A_QSTATS_RX_HW_DROPS: Number of all packets which entered the
> + *   device, but never left it, including but not limited to: packets dropped
> + *   due to lack of buffer space, processing errors, explicit or implicit
> + *   policies and packet filters.
> + * @NETDEV_A_QSTATS_RX_HW_DROP_OVERRUNS: Number of packets dropped due to
> + *   transient lack of resources, such as buffer space, host descriptors etc.
> + * @NETDEV_A_QSTATS_RX_CSUM_COMPLETE: Number of packets that were marked as
> + *   CHECKSUM_COMPLETE.
> + * @NETDEV_A_QSTATS_RX_CSUM_UNNECESSARY: Number of packets that were marked as
> + *   CHECKSUM_UNNECESSARY.
> + * @NETDEV_A_QSTATS_RX_CSUM_NONE: Number of packets that were not checksummed
> + *   by device.
> + * @NETDEV_A_QSTATS_RX_CSUM_BAD: Number of packets with bad checksum. The
> + *   packets are not discarded, but still delivered to the stack.
> + * @NETDEV_A_QSTATS_RX_HW_GRO_PACKETS: Number of packets that were coalesced
> + *   from smaller packets by the device. Counts only packets coalesced with the
> + *   HW-GRO netdevice feature, LRO-coalesced packets are not counted.
> + * @NETDEV_A_QSTATS_RX_HW_GRO_BYTES: See `rx-hw-gro-packets`.
> + * @NETDEV_A_QSTATS_RX_HW_GRO_WIRE_PACKETS: Number of packets that were
> + *   coalesced to bigger packetss with the HW-GRO netdevice feature.

packetss -> packets

> + *   LRO-coalesced packets are not counted.
> + * @NETDEV_A_QSTATS_RX_HW_GRO_WIRE_BYTES: See `rx-hw-gro-wire-packets`.
> + * @NETDEV_A_QSTATS_RX_HW_DROP_RATELIMITS: Number of the packets dropped by the
> + *   device due to the received packets bitrate exceeding the device rate

Thanks,
Alok