net: kernel-doc compliant documentation for net_device

Net_device is a vast and important structure, but it has no kernel-doc
compliant documentation. This patch extracts the comments from the structure
to clean it up, and let the scripts extract documentation from it. I know that
the patch is big, but it's just reordering of comments into the appropriate
form, and adding a few more, for the missing members.

Signed-off-by: Karoly Kemeny <karoly.kemeny@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

1 files changed, 250 insertions, 131 deletions

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 8e8fb3ed574b..38377392d082 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -1231,42 +1231,228 @@ enum netdev_priv_flags {
 #define IFF_LIVE_ADDR_CHANGE            IFF_LIVE_ADDR_CHANGE
 #define IFF_MACVLAN                     IFF_MACVLAN
 
-/*
- *      The DEVICE structure.
- *      Actually, this whole structure is a big mistake.  It mixes I/O
- *      data with strictly "high-level" data, and it has to know about
- *      almost every data structure used in the INET module.
+/**
+ *      struct net_device - The DEVICE structure.
+ *              Actually, this whole structure is a big mistake.  It mixes I/O
+ *              data with strictly "high-level" data, and it has to know about
+ *              almost every data structure used in the INET module.
+ *
+ *      @name:  This is the first field of the "visible" part of this structure
+ *              (i.e. as seen by users in the "Space.c" file).  It is the name
+ *              of the interface.
+ *
+ *      @name_hlist:    Device name hash chain, please keep it close to name[]
+ *      @ifalias:       SNMP alias
+ *      @mem_end:       Shared memory end
+ *      @mem_start:     Shared memory start
+ *      @base_addr:     Device I/O address
+ *      @irq:           Device IRQ number
+ *
+ *      @state:         Generic network queuing layer state, see netdev_state_t
+ *      @dev_list:      The global list of network devices
+ *      @napi_list:     List entry, that is used for polling napi devices
+ *      @unreg_list:    List entry, that is used, when we are unregistering the
+ *                      device, see the function unregister_netdev
+ *      @close_list:    List entry, that is used, when we are closing the device
+ *
+ *      @adj_list:      Directly linked devices, like slaves for bonding
+ *      @all_adj_list:  All linked devices, *including* neighbours
+ *      @features:      Currently active device features
+ *      @hw_features:   User-changeable features
+ *
+ *      @wanted_features:       User-requested features
+ *      @vlan_features:         Mask of features inheritable by VLAN devices
+ *
+ *      @hw_enc_features:       Mask of features inherited by encapsulating devices
+ *                              This field indicates what encapsulation
+ *                              offloads the hardware is capable of doing,
+ *                              and drivers will need to set them appropriately.
+ *
+ *      @mpls_features: Mask of features inheritable by MPLS
+ *
+ *      @ifindex:       interface index
+ *      @iflink:        unique device identifier
+ *
+ *      @stats:         Statistics struct, which was left as a legacy, use
+ *                      rtnl_link_stats64 instead
+ *
+ *      @rx_dropped:    Dropped packets by core network,
+ *                      do not use this in drivers
+ *      @tx_dropped:    Dropped packets by core network,
+ *                      do not use this in drivers
+ *
+ *      @carrier_changes:       Stats to monitor carrier on<->off transitions
+ *
+ *      @wireless_handlers:     List of functions to handle Wireless Extensions,
+ *                              instead of ioctl,
+ *                              see <net/iw_handler.h> for details.
+ *      @wireless_data: Instance data managed by the core of wireless extensions
+ *
+ *      @netdev_ops:    Includes several pointers to callbacks,
+ *                      if one wants to override the ndo_*() functions
+ *      @ethtool_ops:   Management operations
+ *      @fwd_ops:       Management operations
+ *      @header_ops:    Includes callbacks for creating,parsing,rebuilding,etc
+ *                      of Layer 2 headers.
+ *
+ *      @flags:         Interface flags (a la BSD)
+ *      @priv_flags:    Like 'flags' but invisible to userspace,
+ *                      see if.h for the definitions
+ *      @gflags:        Global flags ( kept as legacy )
+ *      @padded:        How much padding added by alloc_netdev()
+ *      @operstate:     RFC2863 operstate
+ *      @link_mode:     Mapping policy to operstate
+ *      @if_port:       Selectable AUI, TP, ...
+ *      @dma:           DMA channel
+ *      @mtu:           Interface MTU value
+ *      @type:          Interface hardware type
+ *      @hard_header_len: Hardware header length
+ *
+ *      @needed_headroom: Extra headroom the hardware may need, but not in all
+ *                        cases can this be guaranteed
+ *      @needed_tailroom: Extra tailroom the hardware may need, but not in all
+ *                        cases can this be guaranteed. Some cases also use
+ *                        LL_MAX_HEADER instead to allocate the skb
+ *
+ *      interface address info:
+ *
+ *      @perm_addr:             Permanent hw address
+ *      @addr_assign_type:      Hw address assignment type
+ *      @addr_len:              Hardware address length
+ *      @neigh_priv_len;        Used in neigh_alloc(),
+ *                              initialized only in atm/clip.c
+ *      @dev_id:                Used to differentiate devices that share
+ *                              the same link layer address
+ *      @dev_port:              Used to differentiate devices that share
+ *                              the same function
+ *      @addr_list_lock:        XXX: need comments on this one
+ *      @uc:                    unicast mac addresses
+ *      @mc:                    multicast mac addresses
+ *      @dev_addrs:             list of device hw addresses
+ *      @queues_kset:           Group of all Kobjects in the Tx and RX queues
+ *      @uc_promisc:            Counter, that indicates, that promiscuous mode
+ *                              has been enabled due to the need to listen to
+ *                              additional unicast addresses in a device that
+ *                              does not implement ndo_set_rx_mode()
+ *      @promiscuity:           Number of times, the NIC is told to work in
+ *                              Promiscuous mode, if it becomes 0 the NIC will
+ *                              exit from working in Promiscuous mode
+ *      @allmulti:              Counter, enables or disables allmulticast mode
+ *
+ *      @vlan_info:     VLAN info
+ *      @dsa_ptr:       dsa specific data
+ *      @tipc_ptr:      TIPC specific data
+ *      @atalk_ptr:     AppleTalk link
+ *      @ip_ptr:        IPv4 specific data
+ *      @dn_ptr:        DECnet specific data
+ *      @ip6_ptr:       IPv6 specific data
+ *      @ax25_ptr:      AX.25 specific data
+ *      @ieee80211_ptr: IEEE 802.11 specific data, assign before registering
+ *
+ *      @last_rx:       Time of last Rx
+ *      @dev_addr:      Hw address (before bcast,
+ *                      because most packets are unicast)
+ *
+ *      @_rx:                   Array of RX queues
+ *      @num_rx_queues:         Number of RX queues
+ *                              allocated at register_netdev() time
+ *      @real_num_rx_queues:    Number of RX queues currently active in device
+ *
+ *      @rx_handler:            handler for received packets
+ *      @rx_handler_data:       XXX: need comments on this one
+ *      @ingress_queue:         XXX: need comments on this one
+ *      @broadcast:             hw bcast address
+ *
+ *      @_tx:                   Array of TX queues
+ *      @num_tx_queues:         Number of TX queues allocated at alloc_netdev_mq() time
+ *      @real_num_tx_queues:    Number of TX queues currently active in device
+ *      @qdisc:                 Root qdisc from userspace point of view
+ *      @tx_queue_len:          Max frames per queue allowed
+ *      @tx_global_lock:        XXX: need comments on this one
+ *
+ *      @xps_maps:      XXX: need comments on this one
+ *
+ *      @rx_cpu_rmap:   CPU reverse-mapping for RX completion interrupts,
+ *                      indexed by RX queue number. Assigned by driver.
+ *                      This must only be set if the ndo_rx_flow_steer
+ *                      operation is defined
+ *
+ *      @trans_start:           Time (in jiffies) of last Tx
+ *      @watchdog_timeo:        Represents the timeout that is used by
+ *                              the watchdog ( see dev_watchdog() )
+ *      @watchdog_timer:        List of timers
+ *
+ *      @pcpu_refcnt:           Number of references to this device
+ *      @todo_list:             Delayed register/unregister
+ *      @index_hlist:           Device index hash chain
+ *      @link_watch_list:       XXX: need comments on this one
+ *
+ *      @reg_state:             Register/unregister state machine
+ *      @dismantle:             Device is going to be freed
+ *      @rtnl_link_state:       This enum represents the phases of creating
+ *                              a new link
+ *
+ *      @destructor:            Called from unregister,
+ *                              can be used to call free_netdev
+ *      @npinfo:                XXX: need comments on this one
+ *      @nd_net:                Network namespace this network device is inside
+ *
+ *      @ml_priv:       Mid-layer private
+ *      @lstats:        Loopback statistics
+ *      @tstats:        Tunnel statistics
+ *      @dstats:        Dummy statistics
+ *      @vstats:        Virtual ethernet statistics
+ *
+ *      @garp_port:     GARP
+ *      @mrp_port:      MRP
+ *
+ *      @dev:           Class/net/name entry
+ *      @sysfs_groups:  Space for optional device, statistics and wireless
+ *                      sysfs groups
+ *
+ *      @sysfs_rx_queue_group:  Space for optional per-rx queue attributes
+ *      @rtnl_link_ops: Rtnl_link_ops
+ *
+ *      @gso_max_size:  Maximum size of generic segmentation offload
+ *      @gso_max_segs:  Maximum number of segments that can be passed to the
+ *                      NIC for GSO
+ *
+ *      @dcbnl_ops:     Data Center Bridging netlink ops
+ *      @num_tc:        Number of traffic classes in the net device
+ *      @tc_to_txq:     XXX: need comments on this one
+ *      @prio_tc_map    XXX: need comments on this one
+ *
+ *      @fcoe_ddp_xid:  Max exchange id for FCoE LRO by ddp
+ *
+ *      @priomap:       XXX: need comments on this one
+ *      @phydev:        Physical device may attach itself
+ *                      for hardware timestamping
+ *
+ *      @qdisc_tx_busylock:     XXX: need comments on this one
+ *
+ *      @group:         The group, that the device belongs to
+ *      @pm_qos_req:    Power Management QoS object
  *
  *      FIXME: cleanup struct net_device such that network protocol info
  *      moves out.
  */
 
 struct net_device {
-
-        /*
-         * This is the first field of the "visible" part of this structure
-         * (i.e. as seen by users in the "Space.c" file).  It is the name
-         * of the interface.
-         */
         char                    name[IFNAMSIZ];
-
-        /* device name hash chain, please keep it close to name[] */
         struct hlist_node       name_hlist;
-
-        /* snmp alias */
         char                    *ifalias;
-
         /*
          *      I/O specific fields
          *      FIXME: Merge these and struct ifmap into one
          */
-        unsigned long           mem_end;        /* shared mem end       */
-        unsigned long           mem_start;      /* shared mem start     */
-        unsigned long           base_addr;      /* device I/O address   */
-        int                     irq;            /* device IRQ number    */
+        unsigned long           mem_end;
+        unsigned long           mem_start;
+        unsigned long           base_addr;
+        int                     irq;
 
         /*
-         *      Some hardware also needs these fields, but they are not
+         *      Some hardware also needs these fields (state,dev_list,
+         *      napi_list,unreg_list,close_list) but they are not
          *      part of the usual set specified in Space.c.
          */
 
@@ -1277,106 +1463,74 @@ struct net_device {
         struct list_head        unreg_list;
         struct list_head        close_list;
 
-        /* directly linked devices, like slaves for bonding */
         struct {
                 struct list_head upper;
                 struct list_head lower;
         } adj_list;
 
-        /* all linked devices, *including* neighbours */
         struct {
                 struct list_head upper;
                 struct list_head lower;
         } all_adj_list;
 
-
-        /* currently active device features */
         netdev_features_t       features;
-        /* user-changeable features */
         netdev_features_t       hw_features;
-        /* user-requested features */
         netdev_features_t       wanted_features;
-        /* mask of features inheritable by VLAN devices */
         netdev_features_t       vlan_features;
-        /* mask of features inherited by encapsulating devices
-         * This field indicates what encapsulation offloads
-         * the hardware is capable of doing, and drivers will
-         * need to set them appropriately.
-         */
         netdev_features_t       hw_enc_features;
-        /* mask of fetures inheritable by MPLS */
         netdev_features_t       mpls_features;
 
-        /* Interface index. Unique device identifier    */
         int                     ifindex;
         int                     iflink;
 
         struct net_device_stats stats;
 
-        /* dropped packets by core network, Do not use this in drivers */
         atomic_long_t           rx_dropped;
         atomic_long_t           tx_dropped;
 
-        /* Stats to monitor carrier on<->off transitions */
         atomic_t                carrier_changes;
 
 #ifdef CONFIG_WIRELESS_EXT
-        /* List of functions to handle Wireless Extensions (instead of ioctl).
-         * See <net/iw_handler.h> for details. Jean II */
         const struct iw_handler_def *   wireless_handlers;
-        /* Instance data managed by the core of Wireless Extensions. */
         struct iw_public_data * wireless_data;
 #endif
-        /* Management operations */
         const struct net_device_ops *netdev_ops;
         const struct ethtool_ops *ethtool_ops;
         const struct forwarding_accel_ops *fwd_ops;
 
-        /* Hardware header description */
         const struct header_ops *header_ops;
 
-        unsigned int            flags;  /* interface flags (a la BSD)   */
-        unsigned int            priv_flags; /* Like 'flags' but invisible to userspace.
-                                             * See if.h for definitions. */
+        unsigned int            flags;
+        unsigned int            priv_flags;
+
         unsigned short          gflags;
-        unsigned short          padded; /* How much padding added by alloc_netdev() */
+        unsigned short          padded;
 
-        unsigned char           operstate; /* RFC2863 operstate */
-        unsigned char           link_mode; /* mapping policy to operstate */
+        unsigned char           operstate;
+        unsigned char           link_mode;
 
-        unsigned char           if_port;        /* Selectable AUI, TP,..*/
-        unsigned char           dma;            /* DMA channel          */
+        unsigned char           if_port;
+        unsigned char           dma;
 
-        unsigned int            mtu;    /* interface MTU value          */
-        unsigned short          type;   /* interface hardware type      */
-        unsigned short          hard_header_len;        /* hardware hdr length  */
+        unsigned int            mtu;
+        unsigned short          type;
+        unsigned short          hard_header_len;
 
-        /* extra head- and tailroom the hardware may need, but not in all cases
-         * can this be guaranteed, especially tailroom. Some cases also use
-         * LL_MAX_HEADER instead to allocate the skb.
-         */
         unsigned short          needed_headroom;
         unsigned short          needed_tailroom;
 
         /* Interface address info. */
-        unsigned char           perm_addr[MAX_ADDR_LEN]; /* permanent hw address */
-        unsigned char           addr_assign_type; /* hw address assignment type */
-        unsigned char           addr_len;       /* hardware address length      */
+        unsigned char           perm_addr[MAX_ADDR_LEN];
+        unsigned char           addr_assign_type;
+        unsigned char           addr_len;
         unsigned short          neigh_priv_len;
-        unsigned short          dev_id;         /* Used to differentiate devices
-                                                 * that share the same link
-                                                 * layer address
-                                                 */
-        unsigned short          dev_port;       /* Used to differentiate
-                                                 * devices that share the same
-                                                 * function
-                                                 */
+        unsigned short          dev_id;
+        unsigned short          dev_port;
         spinlock_t              addr_list_lock;
-        struct netdev_hw_addr_list      uc;     /* Unicast mac addresses */
-        struct netdev_hw_addr_list      mc;     /* Multicast mac addresses */
-        struct netdev_hw_addr_list      dev_addrs; /* list of device
-                                                    * hw addresses
-                                                    */
+        struct netdev_hw_addr_list      uc;
+        struct netdev_hw_addr_list      mc;
+        struct netdev_hw_addr_list      dev_addrs;
+
 #ifdef CONFIG_SYSFS
         struct kset             *queues_kset;
 #endif
@@ -1391,40 +1545,34 @@ struct net_device {
         /* Protocol specific pointers */
 
 #if IS_ENABLED(CONFIG_VLAN_8021Q)
-        struct vlan_info __rcu  *vlan_info;     /* VLAN info */
+        struct vlan_info __rcu  *vlan_info;
 #endif
 #if IS_ENABLED(CONFIG_NET_DSA)
-        struct dsa_switch_tree  *dsa_ptr;       /* dsa specific data */
+        struct dsa_switch_tree  *dsa_ptr;
 #endif
 #if IS_ENABLED(CONFIG_TIPC)
-        struct tipc_bearer __rcu *tipc_ptr;     /* TIPC specific data */
+        struct tipc_bearer __rcu *tipc_ptr;
 #endif
-        void                    *atalk_ptr;     /* AppleTalk link       */
-        struct in_device __rcu  *ip_ptr;        /* IPv4 specific data   */
-        struct dn_dev __rcu     *dn_ptr;        /* DECnet specific data */
-        struct inet6_dev __rcu  *ip6_ptr;       /* IPv6 specific data */
-        void                    *ax25_ptr;      /* AX.25 specific data */
-        struct wireless_dev     *ieee80211_ptr; /* IEEE 802.11 specific data,
-                                                   assign before registering */
+        void                    *atalk_ptr;
+        struct in_device __rcu  *ip_ptr;
+        struct dn_dev __rcu     *dn_ptr;
+        struct inet6_dev __rcu  *ip6_ptr;
+        void                    *ax25_ptr;
+        struct wireless_dev     *ieee80211_ptr;
 
 /*
  * Cache lines mostly used on receive path (including eth_type_trans())
  */
-        unsigned long           last_rx;        /* Time of last Rx */
+        unsigned long           last_rx;
 
         /* Interface address info used in eth_type_trans() */
-        unsigned char           *dev_addr;      /* hw address, (before bcast
-                                                   because most packets are
-                                                   unicast) */
+        unsigned char           *dev_addr;
 
 
 #ifdef CONFIG_SYSFS
         struct netdev_rx_queue  *_rx;
 
-        /* Number of RX queues allocated at register_netdev() time */
         unsigned int            num_rx_queues;
-
-        /* Number of RX queues currently active in device */
         unsigned int            real_num_rx_queues;
 
 #endif
@@ -1433,33 +1581,23 @@ struct net_device {
         void __rcu              *rx_handler_data;
 
         struct netdev_queue __rcu *ingress_queue;
-        unsigned char           broadcast[MAX_ADDR_LEN];        /* hw bcast add */
+        unsigned char           broadcast[MAX_ADDR_LEN];
 
 
 /*
  * Cache lines mostly used on transmit path
  */
         struct netdev_queue     *_tx ____cacheline_aligned_in_smp;
-
-        /* Number of TX queues allocated at alloc_netdev_mq() time  */
         unsigned int            num_tx_queues;
-
-        /* Number of TX queues currently active in device  */
         unsigned int            real_num_tx_queues;
-
-        /* root qdisc from userspace point of view */
         struct Qdisc            *qdisc;
-
-        unsigned long           tx_queue_len;   /* Max frames per queue allowed */
+        unsigned long           tx_queue_len;
         spinlock_t              tx_global_lock;
 
 #ifdef CONFIG_XPS
         struct xps_dev_maps __rcu *xps_maps;
 #endif
 #ifdef CONFIG_RFS_ACCEL
-        /* CPU reverse-mapping for RX completion interrupts, indexed
-         * by RX queue number.  Assigned by driver.  This must only be
-         * set if the ndo_rx_flow_steer operation is defined. */
         struct cpu_rmap         *rx_cpu_rmap;
 #endif
 
@@ -1469,22 +1607,17 @@ struct net_device {
          * trans_start here is expensive for high speed devices on SMP,
          * please use netdev_queue->trans_start instead.
          */
-        unsigned long           trans_start;    /* Time (in jiffies) of last Tx */
+        unsigned long           trans_start;
 
-        int                     watchdog_timeo; /* used by dev_watchdog() */
+        int                     watchdog_timeo;
         struct timer_list       watchdog_timer;
 
-        /* Number of references to this device */
         int __percpu            *pcpu_refcnt;
-
-        /* delayed register/unregister */
         struct list_head        todo_list;
-        /* device index hash chain */
-        struct hlist_node       index_hlist;
 
+        struct hlist_node       index_hlist;
         struct list_head        link_watch_list;
 
-        /* register/unregister state machine */
         enum { NETREG_UNINITIALIZED=0,
                NETREG_REGISTERED,       /* completed register_netdevice */
                NETREG_UNREGISTERING,    /* called unregister_netdevice */
@@ -1493,14 +1626,13 @@ struct net_device {
                NETREG_DUMMY,            /* dummy device for NAPI poll */
         } reg_state:8;
 
-        bool dismantle; /* device is going do be freed */
+        bool dismantle;
 
         enum {
                 RTNL_LINK_INITIALIZED,
                 RTNL_LINK_INITIALIZING,
         } rtnl_link_state:16;
 
-        /* Called from unregister, can be used to call free_netdev */
         void (*destructor)(struct net_device *dev);
 
 #ifdef CONFIG_NETPOLL
@@ -1508,31 +1640,25 @@ struct net_device {
 #endif
 
 #ifdef CONFIG_NET_NS
-        /* Network namespace this network device is inside */
         struct net              *nd_net;
 #endif
 
         /* mid-layer private */
         union {
-                void                            *ml_priv;
-                struct pcpu_lstats __percpu     *lstats; /* loopback stats */
+                void                                    *ml_priv;
+                struct pcpu_lstats __percpu             *lstats;
                 struct pcpu_sw_netstats __percpu        *tstats;
-                struct pcpu_dstats __percpu     *dstats; /* dummy stats */
-                struct pcpu_vstats __percpu     *vstats; /* veth stats */
+                struct pcpu_dstats __percpu             *dstats;
+                struct pcpu_vstats __percpu             *vstats;
         };
-        /* GARP */
+
         struct garp_port __rcu  *garp_port;
-        /* MRP */
         struct mrp_port __rcu   *mrp_port;
 
-        /* class/net/name entry */
-        struct device           dev;
-        /* space for optional device, statistics, and wireless sysfs groups */
+        struct device   dev;
         const struct attribute_group *sysfs_groups[4];
-        /* space for optional per-rx queue attributes */
         const struct attribute_group *sysfs_rx_queue_group;
 
-        /* rtnetlink link ops */
         const struct rtnl_link_ops *rtnl_link_ops;
 
         /* for setting kernel sock attribute on TCP connection setup */
@@ -1542,7 +1668,6 @@ struct net_device {
         u16                     gso_max_segs;
 
 #ifdef CONFIG_DCB
-        /* Data Center Bridging netlink ops */
         const struct dcbnl_rtnl_ops *dcbnl_ops;
 #endif
         u8 num_tc;
@@ -1550,20 +1675,14 @@ struct net_device {
         u8 prio_tc_map[TC_BITMASK + 1];
 
 #if IS_ENABLED(CONFIG_FCOE)
-        /* max exchange id for FCoE LRO by ddp */
         unsigned int            fcoe_ddp_xid;
 #endif
 #if IS_ENABLED(CONFIG_CGROUP_NET_PRIO)
         struct netprio_map __rcu *priomap;
 #endif
-        /* phy device may attach itself for hardware timestamping */
         struct phy_device *phydev;
-
         struct lock_class_key *qdisc_tx_busylock;
-
-        /* group the device belongs to */
         int group;
-
         struct pm_qos_request   pm_qos_req;
 };
 #define to_net_dev(d) container_of(d, struct net_device, dev)