File: //usr/share/doc/ynl/netdev.rst
.. LINENO 2
.. SPDX-License-Identifier: GPL-2.0
.. NOTE: This document was auto-generated.
.. _netlink-netdev:
=======================================
Family ``netdev`` netlink specification
=======================================
.. contents:: :depth: 3
-------
Summary
-------
netdev configuration over generic netlink.
----------
Operations
----------
.. LINENO 540
.. _netdev-operation-dev-get:
dev-get
=======
Get / dump information about a netdev.
:attribute-set: :ref:`netdev-attribute-set-dev`
:do:
.. LINENO 544
**request**
:attributes: [``ifindex``]
**reply**
:attributes: [``ifindex``, ``xdp-features``, ``xdp-zc-max-segs``, ``xdp-rx-metadata-features``, ``xsk-features``]
:dump:
.. LINENO 555
**reply**
:attributes: [``ifindex``, ``xdp-features``, ``xdp-zc-max-segs``, ``xdp-rx-metadata-features``, ``xsk-features``]
.. LINENO 557
.. _netdev-operation-dev-add-ntf:
dev-add-ntf
===========
Notification about device appearing.
:notify: dev-get
:mcgrp: mgmt
.. LINENO 562
.. _netdev-operation-dev-del-ntf:
dev-del-ntf
===========
Notification about device disappearing.
:notify: dev-get
:mcgrp: mgmt
.. LINENO 567
.. _netdev-operation-dev-change-ntf:
dev-change-ntf
==============
Notification about device configuration being changed.
:notify: dev-get
:mcgrp: mgmt
.. LINENO 572
.. _netdev-operation-page-pool-get:
page-pool-get
=============
Get / dump information about Page Pools.
(Only Page Pools associated with a net_device can be listed.)
:attribute-set: :ref:`netdev-attribute-set-page-pool`
:config-cond: page-pool
:do:
.. LINENO 578
**request**
:attributes: [``id``]
**reply**
:attributes: [``id``, ``ifindex``, ``napi-id``, ``inflight``, ``inflight-mem``, ``detach-time``, ``dmabuf``]
:dump:
.. LINENO 591
**reply**
:attributes: [``id``, ``ifindex``, ``napi-id``, ``inflight``, ``inflight-mem``, ``detach-time``, ``dmabuf``]
.. LINENO 594
.. _netdev-operation-page-pool-add-ntf:
page-pool-add-ntf
=================
Notification about page pool appearing.
:notify: page-pool-get
:mcgrp: page-pool
:config-cond: page-pool
.. LINENO 600
.. _netdev-operation-page-pool-del-ntf:
page-pool-del-ntf
=================
Notification about page pool disappearing.
:notify: page-pool-get
:mcgrp: page-pool
:config-cond: page-pool
.. LINENO 606
.. _netdev-operation-page-pool-change-ntf:
page-pool-change-ntf
====================
Notification about page pool configuration being changed.
:notify: page-pool-get
:mcgrp: page-pool
:config-cond: page-pool
.. LINENO 612
.. _netdev-operation-page-pool-stats-get:
page-pool-stats-get
===================
Get page pool statistics.
:attribute-set: :ref:`netdev-attribute-set-page-pool-stats`
:config-cond: page-pool-stats
:do:
.. LINENO 616
**request**
:attributes: [``info``]
**reply**
:attributes: [``info``, ``alloc-fast``, ``alloc-slow``, ``alloc-slow-high-order``, ``alloc-empty``, ``alloc-refill``, ``alloc-waive``, ``recycle-cached``, ``recycle-cache-full``, ``recycle-ring``, ``recycle-ring-full``, ``recycle-released-refcnt``]
:dump:
.. LINENO 634
**reply**
:attributes: [``info``, ``alloc-fast``, ``alloc-slow``, ``alloc-slow-high-order``, ``alloc-empty``, ``alloc-refill``, ``alloc-waive``, ``recycle-cached``, ``recycle-cache-full``, ``recycle-ring``, ``recycle-ring-full``, ``recycle-released-refcnt``]
.. LINENO 637
.. _netdev-operation-queue-get:
queue-get
=========
Get queue information from the kernel. Only configured queues will be reported (as opposed to all available hardware queues).
:attribute-set: :ref:`netdev-attribute-set-queue`
:do:
.. LINENO 643
**request**
:attributes: [``ifindex``, ``type``, ``id``]
**reply**
:attributes: [``id``, ``type``, ``napi-id``, ``ifindex``, ``dmabuf``]
:dump:
.. LINENO 656
**request**
:attributes: [``ifindex``]
**reply**
:attributes: [``id``, ``type``, ``napi-id``, ``ifindex``, ``dmabuf``]
.. LINENO 661
.. _netdev-operation-napi-get:
napi-get
========
Get information about NAPI instances configured on the system.
:attribute-set: :ref:`netdev-attribute-set-napi`
:do:
.. LINENO 665
**request**
:attributes: [``id``]
**reply**
:attributes: [``id``, ``ifindex``, ``irq``, ``pid``, ``defer-hard-irqs``, ``gro-flush-timeout``, ``irq-suspend-timeout``, ``threaded``]
:dump:
.. LINENO 679
**request**
:attributes: [``ifindex``]
**reply**
:attributes: [``id``, ``ifindex``, ``irq``, ``pid``, ``defer-hard-irqs``, ``gro-flush-timeout``, ``irq-suspend-timeout``, ``threaded``]
.. LINENO 684
.. _netdev-operation-qstats-get:
qstats-get
==========
Get / dump fine grained statistics. Which statistics are reported
depends on the device and the driver, and whether the driver stores
software counters per-queue.
:attribute-set: :ref:`netdev-attribute-set-qstats`
:dump:
.. LINENO 691
**request**
:attributes: [``ifindex``, ``scope``]
**reply**
:attributes: [``ifindex``, ``queue-type``, ``queue-id``, ``rx-packets``, ``rx-bytes``, ``tx-packets``, ``tx-bytes``]
.. LINENO 705
.. _netdev-operation-bind-rx:
bind-rx
=======
Bind dmabuf to netdev
:attribute-set: :ref:`netdev-attribute-set-dmabuf`
:flags: [``admin-perm``]
:do:
.. LINENO 710
**request**
:attributes: [``ifindex``, ``fd``, ``queues``]
**reply**
:attributes: [``id``]
.. LINENO 719
.. _netdev-operation-napi-set:
napi-set
========
Set configurable NAPI instance settings.
:attribute-set: :ref:`netdev-attribute-set-napi`
:flags: [``admin-perm``]
:do:
.. LINENO 724
**request**
:attributes: [``id``, ``defer-hard-irqs``, ``gro-flush-timeout``, ``irq-suspend-timeout``, ``threaded``]
----------------
Multicast groups
----------------
- mgmt
- page-pool
-----------
Definitions
-----------
.. LINENO 9
.. _netdev-definition-xdp-act:
xdp-act
=======
:type: flags
:entries:
:basic: XDP features set supported by all drivers (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX)
:redirect: The netdev supports XDP_REDIRECT
:ndo-xmit: This feature informs if netdev implements ndo_xdp_xmit callback.
:xsk-zerocopy: This feature informs if netdev supports AF_XDP in zero copy mode.
:hw-offload: This feature informs if netdev supports XDP hw offloading.
:rx-sg: This feature informs if netdev implements non-linear XDP buffer support in the driver napi callback.
:ndo-xmit-sg: This feature informs if netdev implements non-linear XDP buffer support in ndo_xdp_xmit callback.
.. LINENO 45
.. _netdev-definition-xdp-rx-metadata:
xdp-rx-metadata
===============
:type: flags
:entries:
:timestamp: Device is capable of exposing receive HW timestamp via bpf_xdp_metadata_rx_timestamp().
:hash: Device is capable of exposing receive packet hash via bpf_xdp_metadata_rx_hash().
:vlan-tag: Device is capable of exposing receive packet VLAN tag via bpf_xdp_metadata_rx_vlan_tag().
.. LINENO 61
.. _netdev-definition-xsk-flags:
xsk-flags
=========
:type: flags
:entries:
:tx-timestamp: HW timestamping egress packets is supported by the driver.
:tx-checksum: L3 checksum HW offload is supported by the driver.
:tx-launch-time-fifo: Launch time HW offload is supported by the driver.
.. LINENO 77
.. _netdev-definition-queue-type:
queue-type
==========
:type: enum
:entries:
- ``rx``
- ``tx``
.. LINENO 81
.. _netdev-definition-qstats-scope:
qstats-scope
============
:type: flags
:entries:
- ``queue``
.. LINENO 85
.. _netdev-definition-napi-threaded:
napi-threaded
=============
:type: enum
:entries:
- ``disabled``
- ``enabled``
- ``busy-poll``
--------------
Attribute sets
--------------
.. _netdev-attribute-set-dev:
dev
===
.. LINENO 94
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: netdev ifindex
.. LINENO 100
pad (``pad``)
~~~~~~~~~~~~~
.. LINENO 103
xdp-features (``u64``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Bitmask of enabled xdp-features.
:enum: :ref:`netdev-definition-xdp-act`
.. LINENO 108
xdp-zc-max-segs (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: max fragment count supported by ZC driver
.. LINENO 114
xdp-rx-metadata-features (``u64``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Bitmask of supported XDP receive metadata features. See Documentation/networking/xdp-rx-metadata.rst for more details.
:enum: :ref:`netdev-definition-xdp-rx-metadata`
.. LINENO 120
xsk-features (``u64``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Bitmask of enabled AF_XDP features.
:enum: :ref:`netdev-definition-xsk-flags`
.. _netdev-attribute-set-page-pool:
page-pool
=========
.. LINENO 128
id (``uint``)
~~~~~~~~~~~~~
:doc: Unique ID of a Page Pool instance.
.. LINENO 135
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: ifindex of the netdev to which the pool belongs. May be reported as 0 if the page pool was allocated for a netdev which got destroyed already (page pools may outlast their netdevs because they wait for all memory to be returned).
.. LINENO 146
napi-id (``uint``)
~~~~~~~~~~~~~~~~~~
:doc: Id of NAPI using this Page Pool instance.
.. LINENO 153
inflight (``uint``)
~~~~~~~~~~~~~~~~~~~
:doc: Number of outstanding references to this page pool (allocated but yet to be freed pages). Allocated pages may be held in socket receive queues, driver receive ring, page pool recycling ring, the page pool cache, etc.
.. LINENO 161
inflight-mem (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Amount of memory held by inflight pages.
.. LINENO 166
detach-time (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Seconds in CLOCK_BOOTTIME of when Page Pool was detached by the driver. Once detached Page Pool can no longer be used to allocate memory. Page Pools wait for all the memory allocated from them to be freed before truly disappearing. "Detached" Page Pools cannot be "re-attached", they are just waiting to disappear. Attribute is absent if Page Pool has not been detached, and can still be used to allocate new memory.
.. LINENO 178
dmabuf (``u32``)
~~~~~~~~~~~~~~~~
:doc: ID of the dmabuf this page-pool is attached to.
.. _netdev-attribute-set-page-pool-info:
page-pool-info
==============
.. LINENO 186
id
~~
.. LINENO 188
ifindex
~~~~~~~
.. _netdev-attribute-set-page-pool-stats:
page-pool-stats
===============
Page pool statistics, see docs for struct page_pool_stats
for information about individual statistics.
.. LINENO 196
info (``nest``)
~~~~~~~~~~~~~~~
:doc: Page pool identifying information.
:nested-attributes: :ref:`netdev-attribute-set-page-pool-info`
.. LINENO 201
alloc-fast (``uint``)
~~~~~~~~~~~~~~~~~~~~~
:value: 8
.. LINENO 205
alloc-slow (``uint``)
~~~~~~~~~~~~~~~~~~~~~
.. LINENO 208
alloc-slow-high-order (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 211
alloc-empty (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 214
alloc-refill (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 217
alloc-waive (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 220
recycle-cached (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 223
recycle-cache-full (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 226
recycle-ring (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 229
recycle-ring-full (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. LINENO 232
recycle-released-refcnt (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _netdev-attribute-set-napi:
napi
====
.. LINENO 239
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: ifindex of the netdevice to which NAPI instance belongs.
.. LINENO 245
id (``u32``)
~~~~~~~~~~~~
:doc: ID of the NAPI instance.
.. LINENO 249
irq (``u32``)
~~~~~~~~~~~~~
:doc: The associated interrupt vector number for the napi
.. LINENO 253
pid (``u32``)
~~~~~~~~~~~~~
:doc: PID of the napi thread, if NAPI is configured to operate in threaded mode. If NAPI is not in threaded mode (i.e. uses normal softirq context), the attribute will be absent.
.. LINENO 259
defer-hard-irqs (``u32``)
~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The number of consecutive empty polls before IRQ deferral ends and hardware IRQs are re-enabled.
.. LINENO 266
gro-flush-timeout (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The timeout, in nanoseconds, of when to trigger the NAPI watchdog timer which schedules NAPI processing. Additionally, a non-zero value will also prevent GRO from flushing recent super-frames at the end of a NAPI cycle. This may add receive latency in exchange for reducing the number of frames processed by the network stack.
.. LINENO 274
irq-suspend-timeout (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: The timeout, in nanoseconds, of how long to suspend irq processing, if event polling finds events
.. LINENO 279
threaded (``u32``)
~~~~~~~~~~~~~~~~~~
:doc: Whether the NAPI is configured to operate in threaded polling mode. If this is set to enabled then the NAPI context operates in threaded polling mode. If this is set to busy-poll, then the threaded polling mode also busy polls.
:enum: :ref:`netdev-definition-napi-threaded`
.. _netdev-attribute-set-queue:
queue
=====
.. LINENO 290
id (``u32``)
~~~~~~~~~~~~
:doc: Queue index; most queue types are indexed like a C array, with indexes starting at 0 and ending at queue count - 1. Queue indexes are scoped to an interface and queue type.
.. LINENO 296
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: ifindex of the netdevice to which the queue belongs.
.. LINENO 302
type (``u32``)
~~~~~~~~~~~~~~
:doc: Queue type as rx, tx. Each queue type defines a separate ID space.
:enum: :ref:`netdev-definition-queue-type`
.. LINENO 307
napi-id (``u32``)
~~~~~~~~~~~~~~~~~
:doc: ID of the NAPI instance which services this queue.
.. LINENO 311
dmabuf (``u32``)
~~~~~~~~~~~~~~~~
:doc: ID of the dmabuf attached to this queue, if any.
.. _netdev-attribute-set-qstats:
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.
.. LINENO 331
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: ifindex of the netdevice to which stats belong.
.. LINENO 337
queue-type (``u32``)
~~~~~~~~~~~~~~~~~~~~
:doc: Queue type as rx, tx, for queue-id.
:enum: :ref:`netdev-definition-queue-type`
.. LINENO 342
queue-id (``u32``)
~~~~~~~~~~~~~~~~~~
:doc: Queue ID, if stats are scoped to a single queue instance.
.. LINENO 346
scope (``uint``)
~~~~~~~~~~~~~~~~
:doc: What object type should be used to iterate over the stats.
:enum: :ref:`netdev-definition-qstats-scope`
.. LINENO 352
rx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~
:doc: 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.
:value: 8
.. LINENO 360
rx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~
:doc: Successfully received bytes, see `rx-packets`.
.. LINENO 364
tx-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~
:doc: 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).
.. LINENO 371
tx-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~
:doc: Successfully sent bytes, see `tx-packets`.
.. LINENO 375
rx-alloc-fail (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: 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.
.. LINENO 382
rx-hw-drops (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: 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.
.. LINENO 390
rx-hw-drop-overruns (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets dropped due to transient lack of resources, such as buffer space, host descriptors etc.
.. LINENO 396
rx-csum-complete (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that were marked as CHECKSUM_COMPLETE.
.. LINENO 400
rx-csum-unnecessary (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that were marked as CHECKSUM_UNNECESSARY.
.. LINENO 404
rx-csum-none (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that were not checksummed by device.
.. LINENO 408
rx-csum-bad (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets with bad checksum. The packets are not discarded, but still delivered to the stack.
.. LINENO 414
rx-hw-gro-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: 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.
.. LINENO 421
rx-hw-gro-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: See `rx-hw-gro-packets`.
.. LINENO 425
rx-hw-gro-wire-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that were coalesced to bigger packetss with the HW-GRO netdevice feature. LRO-coalesced packets are not counted.
.. LINENO 431
rx-hw-gro-wire-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: See `rx-hw-gro-wire-packets`.
.. LINENO 435
rx-hw-drop-ratelimits (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of the packets dropped by the device due to the received packets bitrate exceeding the device rate limit.
.. LINENO 441
tx-hw-drops (``uint``)
~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that arrived at the device but never left it, encompassing packets dropped for reasons such as processing errors, as well as those affected by explicitly defined policies and packet filtering criteria.
.. LINENO 449
tx-hw-drop-errors (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets dropped because they were invalid or malformed.
.. LINENO 453
tx-csum-none (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that did not require the device to calculate the checksum.
.. LINENO 459
tx-needs-csum (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that required the device to calculate the checksum.
.. LINENO 464
tx-hw-gso-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of packets that necessitated segmentation into smaller packets by the device.
.. LINENO 470
tx-hw-gso-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: See `tx-hw-gso-packets`.
.. LINENO 474
tx-hw-gso-wire-packets (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of wire-sized packets generated by processing `tx-hw-gso-packets`
.. LINENO 480
tx-hw-gso-wire-bytes (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: See `tx-hw-gso-wire-packets`.
.. LINENO 484
tx-hw-drop-ratelimits (``uint``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:doc: Number of the packets dropped by the device due to the transmit packets bitrate exceeding the device rate limit.
.. LINENO 490
tx-stop (``uint``)
~~~~~~~~~~~~~~~~~~
:doc: Number of times driver paused accepting new tx packets from the stack to this queue, because the queue was full. Note that if BQL is supported and enabled on the device the networking stack will avoid queuing a lot of data at once.
.. LINENO 498
tx-wake (``uint``)
~~~~~~~~~~~~~~~~~~
:doc: Number of times driver re-started accepting send requests to this queue from the stack.
.. _netdev-attribute-set-queue-id:
queue-id
========
.. LINENO 508
id
~~
.. LINENO 510
type
~~~~
.. _netdev-attribute-set-dmabuf:
dmabuf
======
.. LINENO 515
ifindex (``u32``)
~~~~~~~~~~~~~~~~~
:doc: netdev ifindex to bind the dmabuf to.
.. LINENO 521
queues (``nest``)
~~~~~~~~~~~~~~~~~
:doc: receive queues to bind the dmabuf to.
:nested-attributes: :ref:`netdev-attribute-set-queue-id`
:multi-attr: True
.. LINENO 527
fd (``u32``)
~~~~~~~~~~~~
:doc: dmabuf file descriptor to bind.
.. LINENO 531
id (``u32``)
~~~~~~~~~~~~
:doc: id of the dmabuf binding