Documentation/netlink/specs/netdev.yaml

   1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
   2
   3 name: netdev
   4
   5 doc:
   6   netdev configuration over generic netlink.
   7
   8 definitions:
   9   -
  10     type: flags
  11     name: xdp-act
  12     render-max: true
  13     entries:
  14       -
  15         name: basic
  16         doc:
  17           XDP features set supported by all drivers
  18           (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX)
  19       -
  20         name: redirect
  21         doc:
  22           The netdev supports XDP_REDIRECT
  23       -
  24         name: ndo-xmit
  25         doc:
  26           This feature informs if netdev implements ndo_xdp_xmit callback.
  27       -
  28         name: xsk-zerocopy
  29         doc:
  30           This feature informs if netdev supports AF_XDP in zero copy mode.
  31       -
  32         name: hw-offload
  33         doc:
  34          This feature informs if netdev supports XDP hw offloading.
  35       -
  36         name: rx-sg
  37         doc:
  38           This feature informs if netdev implements non-linear XDP buffer
  39           support in the driver napi callback.
  40       -
  41         name: ndo-xmit-sg
  42         doc:
  43           This feature informs if netdev implements non-linear XDP buffer
  44           support in ndo_xdp_xmit callback.
  45   -
  46     type: flags
  47     name: xdp-rx-metadata
  48     entries:
  49       -
  50         name: timestamp
  51         doc:
  52           Device is capable of exposing receive HW timestamp via bpf_xdp_metadata_rx_timestamp().
  53       -
  54         name: hash
  55         doc:
  56           Device is capable of exposing receive packet hash via bpf_xdp_metadata_rx_hash().
  57       -
  58         name: vlan-tag
  59         doc:
  60           Device is capable of exposing receive packet VLAN tag via bpf_xdp_metadata_rx_vlan_tag().
  61   -
  62     type: flags
  63     name: xsk-flags
  64     entries:
  65       -
  66         name: tx-timestamp
  67         doc:
  68           HW timestamping egress packets is supported by the driver.
  69       -
  70         name: tx-checksum
  71         doc:
  72           L3 checksum HW offload is supported by the driver.
  73   -
  74     name: queue-type
  75     type: enum
  76     entries: [ rx, tx ]
  77   -
  78     name: qstats-scope
  79     type: flags
  80     entries: [ queue ]
  81
  82 attribute-sets:
  83   -
  84     name: dev
  85     attributes:
  86       -
  87         name: ifindex
  88         doc: netdev ifindex
  89         type: u32
  90         checks:
  91           min: 1
  92       -
  93         name: pad
  94         type: pad
  95       -
  96         name: xdp-features
  97         doc: Bitmask of enabled xdp-features.
  98         type: u64
  99         enum: xdp-act
 100       -
 101         name: xdp-zc-max-segs
 102         doc: max fragment count supported by ZC driver
 103         type: u32
 104         checks:
 105           min: 1
 106       -
 107         name: xdp-rx-metadata-features
 108         doc: Bitmask of supported XDP receive metadata features.
 109              See Documentation/networking/xdp-rx-metadata.rst for more details.
 110         type: u64
 111         enum: xdp-rx-metadata
 112       -
 113         name: xsk-features
 114         doc: Bitmask of enabled AF_XDP features.
 115         type: u64
 116         enum: xsk-flags
 117   -
 118     name: page-pool
 119     attributes:
 120       -
 121         name: id
 122         doc: Unique ID of a Page Pool instance.
 123         type: uint
 124         checks:
 125           min: 1
 126           max: u32-max
 127       -
 128         name: ifindex
 129         doc: |
 130           ifindex of the netdev to which the pool belongs.
 131           May be reported as 0 if the page pool was allocated for a netdev
 132           which got destroyed already (page pools may outlast their netdevs
 133           because they wait for all memory to be returned).
 134         type: u32
 135         checks:
 136           min: 1
 137           max: s32-max
 138       -
 139         name: napi-id
 140         doc: Id of NAPI using this Page Pool instance.
 141         type: uint
 142         checks:
 143           min: 1
 144           max: u32-max
 145       -
 146         name: inflight
 147         type: uint
 148         doc: |
 149           Number of outstanding references to this page pool (allocated
 150           but yet to be freed pages). Allocated pages may be held in
 151           socket receive queues, driver receive ring, page pool recycling
 152           ring, the page pool cache, etc.
 153       -
 154         name: inflight-mem
 155         type: uint
 156         doc: |
 157           Amount of memory held by inflight pages.
 158       -
 159         name: detach-time
 160         type: uint
 161         doc: |
 162           Seconds in CLOCK_BOOTTIME of when Page Pool was detached by
 163           the driver. Once detached Page Pool can no longer be used to
 164           allocate memory.
 165           Page Pools wait for all the memory allocated from them to be freed
 166           before truly disappearing. "Detached" Page Pools cannot be
 167           "re-attached", they are just waiting to disappear.
 168           Attribute is absent if Page Pool has not been detached, and
 169           can still be used to allocate new memory.
 170   -
 171     name: page-pool-info
 172     subset-of: page-pool
 173     attributes:
 174       -
 175         name: id
 176       -
 177         name: ifindex
 178   -
 179     name: page-pool-stats
 180     doc: |
 181       Page pool statistics, see docs for struct page_pool_stats
 182       for information about individual statistics.
 183     attributes:
 184       -
 185         name: info
 186         doc: Page pool identifying information.
 187         type: nest
 188         nested-attributes: page-pool-info
 189       -
 190         name: alloc-fast
 191         type: uint
 192         value: 8 # reserve some attr ids in case we need more metadata later
 193       -
 194         name: alloc-slow
 195         type: uint
 196       -
 197         name: alloc-slow-high-order
 198         type: uint
 199       -
 200         name: alloc-empty
 201         type: uint
 202       -
 203         name: alloc-refill
 204         type: uint
 205       -
 206         name: alloc-waive
 207         type: uint
 208       -
 209         name: recycle-cached
 210         type: uint
 211       -
 212         name: recycle-cache-full
 213         type: uint
 214       -
 215         name: recycle-ring
 216         type: uint
 217       -
 218         name: recycle-ring-full
 219         type: uint
 220       -
 221         name: recycle-released-refcnt
 222         type: uint
 223
 224   -
 225     name: napi
 226     attributes:
 227       -
 228         name: ifindex
 229         doc: ifindex of the netdevice to which NAPI instance belongs.
 230         type: u32
 231         checks:
 232           min: 1
 233       -
 234         name: id
 235         doc: ID of the NAPI instance.
 236         type: u32
 237       -
 238         name: irq
 239         doc: The associated interrupt vector number for the napi
 240         type: u32
 241       -
 242         name: pid
 243         doc: PID of the napi thread, if NAPI is configured to operate in
 244              threaded mode. If NAPI is not in threaded mode (i.e. uses normal
 245              softirq context), the attribute will be absent.
 246         type: u32
 247   -
 248     name: queue
 249     attributes:
 250       -
 251         name: id
 252         doc: Queue index; most queue types are indexed like a C array, with
 253              indexes starting at 0 and ending at queue count - 1. Queue indexes
 254              are scoped to an interface and queue type.
 255         type: u32
 256       -
 257         name: ifindex
 258         doc: ifindex of the netdevice to which the queue belongs.
 259         type: u32
 260         checks:
 261           min: 1
 262       -
 263         name: type
 264         doc: Queue type as rx, tx. Each queue type defines a separate ID space.
 265         type: u32
 266         enum: queue-type
 267       -
 268         name: napi-id
 269         doc: ID of the NAPI instance which services this queue.
 270         type: u32
 271
 272   -
 273     name: qstats
 274     doc: |
 275       Get device statistics, scoped to a device or a queue.
 276       These statistics extend (and partially duplicate) statistics available
 277       in struct rtnl_link_stats64.
 278       Value of the `scope` attribute determines how statistics are
 279       aggregated. When aggregated for the entire device the statistics
 280       represent the total number of events since last explicit reset of
 281       the device (i.e. not a reconfiguration like changing queue count).
 282       When reported per-queue, however, the statistics may not add
 283       up to the total number of events, will only be reported for currently
 284       active objects, and will likely report the number of events since last
 285       reconfiguration.
 286     attributes:
 287       -
 288         name: ifindex
 289         doc: ifindex of the netdevice to which stats belong.
 290         type: u32
 291         checks:
 292           min: 1
 293       -
 294         name: queue-type
 295         doc: Queue type as rx, tx, for queue-id.
 296         type: u32
 297         enum: queue-type
 298       -
 299         name: queue-id
 300         doc: Queue ID, if stats are scoped to a single queue instance.
 301         type: u32
 302       -
 303         name: scope
 304         doc: |
 305           What object type should be used to iterate over the stats.
 306         type: uint
 307         enum: qstats-scope
 308       -
 309         name: rx-packets
 310         doc: |
 311           Number of wire packets successfully received and passed to the stack.
 312           For drivers supporting XDP, XDP is considered the first layer
 313           of the stack, so packets consumed by XDP are still counted here.
 314         type: uint
 315         value: 8 # reserve some attr ids in case we need more metadata later
 316       -
 317         name: rx-bytes
 318         doc: Successfully received bytes, see `rx-packets`.
 319         type: uint
 320       -
 321         name: tx-packets
 322         doc: |
 323           Number of wire packets successfully sent. Packet is considered to be
 324           successfully sent once it is in device memory (usually this means
 325           the device has issued a DMA completion for the packet).
 326         type: uint
 327       -
 328         name: tx-bytes
 329         doc: Successfully sent bytes, see `tx-packets`.
 330         type: uint
 331       -
 332         name: rx-alloc-fail
 333         doc: |
 334           Number of times skb or buffer allocation failed on the Rx datapath.
 335           Allocation failure may, or may not result in a packet drop, depending
 336           on driver implementation and whether system recovers quickly.
 337         type: uint
 338
 339 operations:
 340   list:
 341     -
 342       name: dev-get
 343       doc: Get / dump information about a netdev.
 344       attribute-set: dev
 345       do:
 346         request:
 347           attributes:
 348             - ifindex
 349         reply: &dev-all
 350           attributes:
 351             - ifindex
 352             - xdp-features
 353             - xdp-zc-max-segs
 354             - xdp-rx-metadata-features
 355             - xsk-features
 356       dump:
 357         reply: *dev-all
 358     -
 359       name: dev-add-ntf
 360       doc: Notification about device appearing.
 361       notify: dev-get
 362       mcgrp: mgmt
 363     -
 364       name: dev-del-ntf
 365       doc: Notification about device disappearing.
 366       notify: dev-get
 367       mcgrp: mgmt
 368     -
 369       name: dev-change-ntf
 370       doc: Notification about device configuration being changed.
 371       notify: dev-get
 372       mcgrp: mgmt
 373     -
 374       name: page-pool-get
 375       doc: |
 376         Get / dump information about Page Pools.
 377         (Only Page Pools associated with a net_device can be listed.)
 378       attribute-set: page-pool
 379       do:
 380         request:
 381           attributes:
 382             - id
 383         reply: &pp-reply
 384           attributes:
 385             - id
 386             - ifindex
 387             - napi-id
 388             - inflight
 389             - inflight-mem
 390             - detach-time
 391       dump:
 392         reply: *pp-reply
 393       config-cond: page-pool
 394     -
 395       name: page-pool-add-ntf
 396       doc: Notification about page pool appearing.
 397       notify: page-pool-get
 398       mcgrp: page-pool
 399       config-cond: page-pool
 400     -
 401       name: page-pool-del-ntf
 402       doc: Notification about page pool disappearing.
 403       notify: page-pool-get
 404       mcgrp: page-pool
 405       config-cond: page-pool
 406     -
 407       name: page-pool-change-ntf
 408       doc: Notification about page pool configuration being changed.
 409       notify: page-pool-get
 410       mcgrp: page-pool
 411       config-cond: page-pool
 412     -
 413       name: page-pool-stats-get
 414       doc: Get page pool statistics.
 415       attribute-set: page-pool-stats
 416       do:
 417         request:
 418           attributes:
 419             - info
 420         reply: &pp-stats-reply
 421           attributes:
 422             - info
 423             - alloc-fast
 424             - alloc-slow
 425             - alloc-slow-high-order
 426             - alloc-empty
 427             - alloc-refill
 428             - alloc-waive
 429             - recycle-cached
 430             - recycle-cache-full
 431             - recycle-ring
 432             - recycle-ring-full
 433             - recycle-released-refcnt
 434       dump:
 435         reply: *pp-stats-reply
 436       config-cond: page-pool-stats
 437     -
 438       name: queue-get
 439       doc: Get queue information from the kernel.
 440            Only configured queues will be reported (as opposed to all available
 441            hardware queues).
 442       attribute-set: queue
 443       do:
 444         request:
 445           attributes:
 446             - ifindex
 447             - type
 448             - id
 449         reply: &queue-get-op
 450           attributes:
 451             - id
 452             - type
 453             - napi-id
 454             - ifindex
 455       dump:
 456         request:
 457           attributes:
 458             - ifindex
 459         reply: *queue-get-op
 460     -
 461       name: napi-get
 462       doc: Get information about NAPI instances configured on the system.
 463       attribute-set: napi
 464       do:
 465         request:
 466           attributes:
 467             - id
 468         reply: &napi-get-op
 469           attributes:
 470             - id
 471             - ifindex
 472             - irq
 473             - pid
 474       dump:
 475         request:
 476           attributes:
 477             - ifindex
 478         reply: *napi-get-op
 479     -
 480       name: qstats-get
 481       doc: |
 482         Get / dump fine grained statistics. Which statistics are reported
 483         depends on the device and the driver, and whether the driver stores
 484         software counters per-queue.
 485       attribute-set: qstats
 486       dump:
 487         request:
 488           attributes:
 489             - scope
 490         reply:
 491           attributes:
 492             - ifindex
 493             - queue-type
 494             - queue-id
 495             - rx-packets
 496             - rx-bytes
 497             - tx-packets
 498             - tx-bytes
 499
 500 mcast-groups:
 501   list:
 502     -
 503       name: mgmt
 504     -
 505       name: page-pool