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 attribute-sets:
  79   -
  80     name: dev
  81     attributes:
  82       -
  83         name: ifindex
  84         doc: netdev ifindex
  85         type: u32
  86         checks:
  87           min: 1
  88       -
  89         name: pad
  90         type: pad
  91       -
  92         name: xdp-features
  93         doc: Bitmask of enabled xdp-features.
  94         type: u64
  95         enum: xdp-act
  96       -
  97         name: xdp-zc-max-segs
  98         doc: max fragment count supported by ZC driver
  99         type: u32
 100         checks:
 101           min: 1
 102       -
 103         name: xdp-rx-metadata-features
 104         doc: Bitmask of supported XDP receive metadata features.
 105              See Documentation/networking/xdp-rx-metadata.rst for more details.
 106         type: u64
 107         enum: xdp-rx-metadata
 108       -
 109         name: xsk-features
 110         doc: Bitmask of enabled AF_XDP features.
 111         type: u64
 112         enum: xsk-flags
 113   -
 114     name: page-pool
 115     attributes:
 116       -
 117         name: id
 118         doc: Unique ID of a Page Pool instance.
 119         type: uint
 120         checks:
 121           min: 1
 122           max: u32-max
 123       -
 124         name: ifindex
 125         doc: |
 126           ifindex of the netdev to which the pool belongs.
 127           May be reported as 0 if the page pool was allocated for a netdev
 128           which got destroyed already (page pools may outlast their netdevs
 129           because they wait for all memory to be returned).
 130         type: u32
 131         checks:
 132           min: 1
 133           max: s32-max
 134       -
 135         name: napi-id
 136         doc: Id of NAPI using this Page Pool instance.
 137         type: uint
 138         checks:
 139           min: 1
 140           max: u32-max
 141       -
 142         name: inflight
 143         type: uint
 144         doc: |
 145           Number of outstanding references to this page pool (allocated
 146           but yet to be freed pages). Allocated pages may be held in
 147           socket receive queues, driver receive ring, page pool recycling
 148           ring, the page pool cache, etc.
 149       -
 150         name: inflight-mem
 151         type: uint
 152         doc: |
 153           Amount of memory held by inflight pages.
 154       -
 155         name: detach-time
 156         type: uint
 157         doc: |
 158           Seconds in CLOCK_BOOTTIME of when Page Pool was detached by
 159           the driver. Once detached Page Pool can no longer be used to
 160           allocate memory.
 161           Page Pools wait for all the memory allocated from them to be freed
 162           before truly disappearing. "Detached" Page Pools cannot be
 163           "re-attached", they are just waiting to disappear.
 164           Attribute is absent if Page Pool has not been detached, and
 165           can still be used to allocate new memory.
 166   -
 167     name: page-pool-info
 168     subset-of: page-pool
 169     attributes:
 170       -
 171         name: id
 172       -
 173         name: ifindex
 174   -
 175     name: page-pool-stats
 176     doc: |
 177       Page pool statistics, see docs for struct page_pool_stats
 178       for information about individual statistics.
 179     attributes:
 180       -
 181         name: info
 182         doc: Page pool identifying information.
 183         type: nest
 184         nested-attributes: page-pool-info
 185       -
 186         name: alloc-fast
 187         type: uint
 188         value: 8 # reserve some attr ids in case we need more metadata later
 189       -
 190         name: alloc-slow
 191         type: uint
 192       -
 193         name: alloc-slow-high-order
 194         type: uint
 195       -
 196         name: alloc-empty
 197         type: uint
 198       -
 199         name: alloc-refill
 200         type: uint
 201       -
 202         name: alloc-waive
 203         type: uint
 204       -
 205         name: recycle-cached
 206         type: uint
 207       -
 208         name: recycle-cache-full
 209         type: uint
 210       -
 211         name: recycle-ring
 212         type: uint
 213       -
 214         name: recycle-ring-full
 215         type: uint
 216       -
 217         name: recycle-released-refcnt
 218         type: uint
 219
 220   -
 221     name: napi
 222     attributes:
 223       -
 224         name: ifindex
 225         doc: ifindex of the netdevice to which NAPI instance belongs.
 226         type: u32
 227         checks:
 228           min: 1
 229       -
 230         name: id
 231         doc: ID of the NAPI instance.
 232         type: u32
 233       -
 234         name: irq
 235         doc: The associated interrupt vector number for the napi
 236         type: u32
 237       -
 238         name: pid
 239         doc: PID of the napi thread, if NAPI is configured to operate in
 240              threaded mode. If NAPI is not in threaded mode (i.e. uses normal
 241              softirq context), the attribute will be absent.
 242         type: u32
 243   -
 244     name: queue
 245     attributes:
 246       -
 247         name: id
 248         doc: Queue index; most queue types are indexed like a C array, with
 249              indexes starting at 0 and ending at queue count - 1. Queue indexes
 250              are scoped to an interface and queue type.
 251         type: u32
 252       -
 253         name: ifindex
 254         doc: ifindex of the netdevice to which the queue belongs.
 255         type: u32
 256         checks:
 257           min: 1
 258       -
 259         name: type
 260         doc: Queue type as rx, tx. Each queue type defines a separate ID space.
 261         type: u32
 262         enum: queue-type
 263       -
 264         name: napi-id
 265         doc: ID of the NAPI instance which services this queue.
 266         type: u32
 267
 268 operations:
 269   list:
 270     -
 271       name: dev-get
 272       doc: Get / dump information about a netdev.
 273       attribute-set: dev
 274       do:
 275         request:
 276           attributes:
 277             - ifindex
 278         reply: &dev-all
 279           attributes:
 280             - ifindex
 281             - xdp-features
 282             - xdp-zc-max-segs
 283             - xdp-rx-metadata-features
 284             - xsk-features
 285       dump:
 286         reply: *dev-all
 287     -
 288       name: dev-add-ntf
 289       doc: Notification about device appearing.
 290       notify: dev-get
 291       mcgrp: mgmt
 292     -
 293       name: dev-del-ntf
 294       doc: Notification about device disappearing.
 295       notify: dev-get
 296       mcgrp: mgmt
 297     -
 298       name: dev-change-ntf
 299       doc: Notification about device configuration being changed.
 300       notify: dev-get
 301       mcgrp: mgmt
 302     -
 303       name: page-pool-get
 304       doc: |
 305         Get / dump information about Page Pools.
 306         (Only Page Pools associated with a net_device can be listed.)
 307       attribute-set: page-pool
 308       do:
 309         request:
 310           attributes:
 311             - id
 312         reply: &pp-reply
 313           attributes:
 314             - id
 315             - ifindex
 316             - napi-id
 317             - inflight
 318             - inflight-mem
 319             - detach-time
 320       dump:
 321         reply: *pp-reply
 322       config-cond: page-pool
 323     -
 324       name: page-pool-add-ntf
 325       doc: Notification about page pool appearing.
 326       notify: page-pool-get
 327       mcgrp: page-pool
 328       config-cond: page-pool
 329     -
 330       name: page-pool-del-ntf
 331       doc: Notification about page pool disappearing.
 332       notify: page-pool-get
 333       mcgrp: page-pool
 334       config-cond: page-pool
 335     -
 336       name: page-pool-change-ntf
 337       doc: Notification about page pool configuration being changed.
 338       notify: page-pool-get
 339       mcgrp: page-pool
 340       config-cond: page-pool
 341     -
 342       name: page-pool-stats-get
 343       doc: Get page pool statistics.
 344       attribute-set: page-pool-stats
 345       do:
 346         request:
 347           attributes:
 348             - info
 349         reply: &pp-stats-reply
 350           attributes:
 351             - info
 352             - alloc-fast
 353             - alloc-slow
 354             - alloc-slow-high-order
 355             - alloc-empty
 356             - alloc-refill
 357             - alloc-waive
 358             - recycle-cached
 359             - recycle-cache-full
 360             - recycle-ring
 361             - recycle-ring-full
 362             - recycle-released-refcnt
 363       dump:
 364         reply: *pp-stats-reply
 365       config-cond: page-pool-stats
 366     -
 367       name: queue-get
 368       doc: Get queue information from the kernel.
 369            Only configured queues will be reported (as opposed to all available
 370            hardware queues).
 371       attribute-set: queue
 372       do:
 373         request:
 374           attributes:
 375             - ifindex
 376             - type
 377             - id
 378         reply: &queue-get-op
 379           attributes:
 380             - id
 381             - type
 382             - napi-id
 383             - ifindex
 384       dump:
 385         request:
 386           attributes:
 387             - ifindex
 388         reply: *queue-get-op
 389     -
 390       name: napi-get
 391       doc: Get information about NAPI instances configured on the system.
 392       attribute-set: napi
 393       do:
 394         request:
 395           attributes:
 396             - id
 397         reply: &napi-get-op
 398           attributes:
 399             - id
 400             - ifindex
 401             - irq
 402             - pid
 403       dump:
 404         request:
 405           attributes:
 406             - ifindex
 407         reply: *napi-get-op
 408
 409 mcast-groups:
 410   list:
 411     -
 412       name: mgmt
 413     -
 414       name: page-pool