1# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) 2--- 3name: netdev 4 5doc: >- 6 netdev configuration over generic netlink. 7 8definitions: 9 - 10 type: const 11 name: page-size 12 # Dummy value, codegen needs a number. The real value comes from 13 # the PAGE_SIZE macro in the header below. 14 value: 0 15 header: asm/page.h 16 scope: kernel 17 - 18 type: flags 19 name: xdp-act 20 render-max: true 21 entries: 22 - 23 name: basic 24 doc: >- 25 XDP features set supported by all drivers 26 (XDP_ABORTED, XDP_DROP, XDP_PASS, XDP_TX) 27 - 28 name: redirect 29 doc: >- 30 The netdev supports XDP_REDIRECT 31 - 32 name: ndo-xmit 33 doc: >- 34 This feature informs if netdev implements ndo_xdp_xmit callback. 35 - 36 name: xsk-zerocopy 37 doc: >- 38 This feature informs if netdev supports AF_XDP in zero copy mode. 39 - 40 name: hw-offload 41 doc: >- 42 This feature informs if netdev supports XDP hw offloading. 43 - 44 name: rx-sg 45 doc: >- 46 This feature informs if netdev implements non-linear XDP buffer 47 support in the driver napi callback. 48 - 49 name: ndo-xmit-sg 50 doc: >- 51 This feature informs if netdev implements non-linear XDP buffer 52 support in ndo_xdp_xmit callback. 53 - 54 type: flags 55 name: xdp-rx-metadata 56 entries: 57 - 58 name: timestamp 59 doc: | 60 Device is capable of exposing receive HW timestamp via 61 bpf_xdp_metadata_rx_timestamp(). 62 - 63 name: hash 64 doc: | 65 Device is capable of exposing receive packet hash via 66 bpf_xdp_metadata_rx_hash(). 67 - 68 name: vlan-tag 69 doc: | 70 Device is capable of exposing receive packet VLAN tag via 71 bpf_xdp_metadata_rx_vlan_tag(). 72 - 73 type: flags 74 name: xsk-flags 75 entries: 76 - 77 name: tx-timestamp 78 doc: >- 79 HW timestamping egress packets is supported by the driver. 80 - 81 name: tx-checksum 82 doc: >- 83 L3 checksum HW offload is supported by the driver. 84 - 85 name: tx-launch-time-fifo 86 doc: >- 87 Launch time HW offload is supported by the driver. 88 - 89 name: queue-type 90 type: enum 91 entries: [rx, tx] 92 - 93 name: qstats-scope 94 type: flags 95 entries: [queue] 96 - 97 name: napi-threaded 98 type: enum 99 entries: [disabled, enabled, busy-poll] 100 101attribute-sets: 102 - 103 name: dev 104 attributes: 105 - 106 name: ifindex 107 doc: netdev ifindex 108 type: u32 109 checks: 110 min: 1 111 - 112 name: pad 113 type: pad 114 - 115 name: xdp-features 116 doc: Bitmask of enabled xdp-features. 117 type: u64 118 enum: xdp-act 119 - 120 name: xdp-zc-max-segs 121 doc: max fragment count supported by ZC driver 122 type: u32 123 checks: 124 min: 1 125 - 126 name: xdp-rx-metadata-features 127 doc: Bitmask of supported XDP receive metadata features. 128 See Documentation/networking/xdp-rx-metadata.rst for more details. 129 type: u64 130 enum: xdp-rx-metadata 131 - 132 name: xsk-features 133 doc: Bitmask of enabled AF_XDP features. 134 type: u64 135 enum: xsk-flags 136 - 137 name: io-uring-provider-info 138 attributes: 139 - 140 name: rx-buf-len 141 type: uint 142 doc: | 143 RX buffer length in bytes for this io_uring memory provider. 144 Reflects the rx_buf_len passed at io_uring zerocopy rx 145 registration time. 146 - 147 name: page-pool 148 attributes: 149 - 150 name: id 151 doc: Unique ID of a Page Pool instance. 152 type: uint 153 checks: 154 min: 1 155 max: u32-max 156 - 157 name: ifindex 158 doc: | 159 ifindex of the netdev to which the pool belongs. 160 May not be reported if the page pool was allocated for a netdev 161 which got destroyed already (page pools may outlast their netdevs 162 because they wait for all memory to be returned). 163 type: u32 164 checks: 165 min: 1 166 max: s32-max 167 - 168 name: napi-id 169 doc: Id of NAPI using this Page Pool instance. 170 type: uint 171 checks: 172 min: 1 173 max: u32-max 174 - 175 name: inflight 176 type: uint 177 doc: | 178 Number of outstanding references to this page pool (allocated 179 but yet to be freed pages). Allocated pages may be held in 180 socket receive queues, driver receive ring, page pool recycling 181 ring, the page pool cache, etc. 182 - 183 name: inflight-mem 184 type: uint 185 doc: | 186 Amount of memory held by inflight pages. 187 - 188 name: detach-time 189 type: uint 190 doc: | 191 Seconds in CLOCK_BOOTTIME of when Page Pool was detached by 192 the driver. Once detached Page Pool can no longer be used to 193 allocate memory. 194 Page Pools wait for all the memory allocated from them to be freed 195 before truly disappearing. "Detached" Page Pools cannot be 196 "re-attached", they are just waiting to disappear. 197 Attribute is absent if Page Pool has not been detached, and 198 can still be used to allocate new memory. 199 - 200 name: dmabuf 201 doc: ID of the dmabuf this page-pool is attached to. 202 type: u32 203 - 204 name: io-uring 205 doc: io-uring memory provider information. 206 type: nest 207 nested-attributes: io-uring-provider-info 208 - 209 name: page-pool-info 210 subset-of: page-pool 211 attributes: 212 - 213 name: id 214 - 215 name: ifindex 216 - 217 name: page-pool-stats 218 doc: | 219 Page pool statistics, see docs for struct page_pool_stats 220 for information about individual statistics. 221 attributes: 222 - 223 name: info 224 doc: Page pool identifying information. 225 type: nest 226 nested-attributes: page-pool-info 227 - 228 name: alloc-fast 229 type: uint 230 value: 8 # reserve some attr ids in case we need more metadata later 231 - 232 name: alloc-slow 233 type: uint 234 - 235 name: alloc-slow-high-order 236 type: uint 237 - 238 name: alloc-empty 239 type: uint 240 - 241 name: alloc-refill 242 type: uint 243 - 244 name: alloc-waive 245 type: uint 246 - 247 name: recycle-cached 248 type: uint 249 - 250 name: recycle-cache-full 251 type: uint 252 - 253 name: recycle-ring 254 type: uint 255 - 256 name: recycle-ring-full 257 type: uint 258 - 259 name: recycle-released-refcnt 260 type: uint 261 262 - 263 name: napi 264 attributes: 265 - 266 name: ifindex 267 doc: ifindex of the netdevice to which NAPI instance belongs. 268 type: u32 269 checks: 270 min: 1 271 - 272 name: id 273 doc: ID of the NAPI instance. 274 type: u32 275 - 276 name: irq 277 doc: The associated interrupt vector number for the napi 278 type: u32 279 - 280 name: pid 281 doc: PID of the napi thread, if NAPI is configured to operate in 282 threaded mode. If NAPI is not in threaded mode (i.e. uses normal 283 softirq context), the attribute will be absent. 284 type: u32 285 - 286 name: defer-hard-irqs 287 doc: The number of consecutive empty polls before IRQ deferral ends 288 and hardware IRQs are re-enabled. 289 type: u32 290 checks: 291 max: s32-max 292 - 293 name: gro-flush-timeout 294 doc: The timeout, in nanoseconds, of when to trigger the NAPI watchdog 295 timer which schedules NAPI processing. Additionally, a non-zero 296 value will also prevent GRO from flushing recent super-frames at 297 the end of a NAPI cycle. This may add receive latency in exchange 298 for reducing the number of frames processed by the network stack. 299 type: uint 300 - 301 name: irq-suspend-timeout 302 doc: The timeout, in nanoseconds, of how long to suspend irq 303 processing, if event polling finds events 304 type: uint 305 - 306 name: threaded 307 doc: Whether the NAPI is configured to operate in threaded polling 308 mode. If this is set to enabled then the NAPI context operates 309 in threaded polling mode. If this is set to busy-poll, then the 310 threaded polling mode also busy polls. 311 type: u32 312 enum: napi-threaded 313 - 314 name: xsk-info 315 attributes: [] 316 - 317 name: queue 318 attributes: 319 - 320 name: id 321 doc: Queue index; most queue types are indexed like a C array, with 322 indexes starting at 0 and ending at queue count - 1. Queue indexes 323 are scoped to an interface and queue type. 324 type: u32 325 - 326 name: ifindex 327 doc: ifindex of the netdevice to which the queue belongs. 328 type: u32 329 checks: 330 min: 1 331 - 332 name: type 333 doc: Queue type as rx, tx. Each queue type defines a separate ID space. 334 XDP TX queues allocated in the kernel are not linked to NAPIs and 335 thus not listed. AF_XDP queues will have more information set in 336 the xsk attribute. 337 type: u32 338 enum: queue-type 339 - 340 name: napi-id 341 doc: ID of the NAPI instance which services this queue. 342 type: u32 343 - 344 name: dmabuf 345 doc: ID of the dmabuf attached to this queue, if any. 346 type: u32 347 - 348 name: io-uring 349 doc: io_uring memory provider information. 350 type: nest 351 nested-attributes: io-uring-provider-info 352 - 353 name: xsk 354 doc: XSK information for this queue, if any. 355 type: nest 356 nested-attributes: xsk-info 357 - 358 name: lease 359 doc: | 360 A queue from a virtual device can have a lease which refers to 361 another queue from a physical device. This is useful for memory 362 providers and AF_XDP operations which take an ifindex and queue id 363 to allow applications to bind against virtual devices in containers. 364 type: nest 365 nested-attributes: lease 366 - 367 name: qstats 368 doc: | 369 Get device statistics, scoped to a device or a queue. 370 These statistics extend (and partially duplicate) statistics available 371 in struct rtnl_link_stats64. 372 Value of the `scope` attribute determines how statistics are 373 aggregated. When aggregated for the entire device the statistics 374 represent the total number of events since last explicit reset of 375 the device (i.e. not a reconfiguration like changing queue count). 376 When reported per-queue, however, the statistics may not add 377 up to the total number of events, will only be reported for currently 378 active objects, and will likely report the number of events since last 379 reconfiguration. 380 attributes: 381 - 382 name: ifindex 383 doc: ifindex of the netdevice to which stats belong. 384 type: u32 385 checks: 386 min: 1 387 - 388 name: queue-type 389 doc: Queue type as rx, tx, for queue-id. 390 type: u32 391 enum: queue-type 392 - 393 name: queue-id 394 doc: Queue ID, if stats are scoped to a single queue instance. 395 type: u32 396 - 397 name: scope 398 doc: | 399 What object type should be used to iterate over the stats. 400 type: uint 401 enum: qstats-scope 402 - 403 name: rx-packets 404 doc: | 405 Number of wire packets successfully received and passed to the stack. 406 For drivers supporting XDP, XDP is considered the first layer 407 of the stack, so packets consumed by XDP are still counted here. 408 type: uint 409 value: 8 # reserve some attr ids in case we need more metadata later 410 - 411 name: rx-bytes 412 doc: Successfully received bytes, see `rx-packets`. 413 type: uint 414 - 415 name: tx-packets 416 doc: | 417 Number of wire packets successfully sent. Packet is considered to be 418 successfully sent once it is in device memory (usually this means 419 the device has issued a DMA completion for the packet). 420 type: uint 421 - 422 name: tx-bytes 423 doc: Successfully sent bytes, see `tx-packets`. 424 type: uint 425 - 426 name: rx-alloc-fail 427 doc: | 428 Number of times skb or buffer allocation failed on the Rx datapath. 429 Allocation failure may, or may not result in a packet drop, depending 430 on driver implementation and whether system recovers quickly. 431 type: uint 432 - 433 name: rx-hw-drops 434 doc: | 435 Number of all packets which entered the device, but never left it, 436 including but not limited to: packets dropped due to lack of buffer 437 space, processing errors, explicit or implicit policies and packet 438 filters. 439 type: uint 440 - 441 name: rx-hw-drop-overruns 442 doc: | 443 Number of packets dropped due to transient lack of resources, such as 444 buffer space, host descriptors etc. 445 type: uint 446 - 447 name: rx-csum-complete 448 doc: Number of packets that were marked as CHECKSUM_COMPLETE. 449 type: uint 450 - 451 name: rx-csum-unnecessary 452 doc: Number of packets that were marked as CHECKSUM_UNNECESSARY. 453 type: uint 454 - 455 name: rx-csum-none 456 doc: Number of packets that were not checksummed by device. 457 type: uint 458 - 459 name: rx-csum-bad 460 doc: | 461 Number of packets with bad checksum. The packets are not discarded, 462 but still delivered to the stack. 463 type: uint 464 - 465 name: rx-hw-gro-packets 466 doc: | 467 Number of packets that were coalesced from smaller packets by the 468 device. Counts only packets coalesced with the HW-GRO netdevice 469 feature, LRO-coalesced packets are not counted. 470 type: uint 471 - 472 name: rx-hw-gro-bytes 473 doc: See `rx-hw-gro-packets`. 474 type: uint 475 - 476 name: rx-hw-gro-wire-packets 477 doc: | 478 Number of packets that were coalesced to bigger packetss with the 479 HW-GRO netdevice feature. LRO-coalesced packets are not counted. 480 type: uint 481 - 482 name: rx-hw-gro-wire-bytes 483 doc: See `rx-hw-gro-wire-packets`. 484 type: uint 485 - 486 name: rx-hw-drop-ratelimits 487 doc: | 488 Number of the packets dropped by the device due to the received 489 packets bitrate exceeding the device rate limit. 490 type: uint 491 - 492 name: tx-hw-drops 493 doc: | 494 Number of packets that arrived at the device but never left it, 495 encompassing packets dropped for reasons such as processing errors, as 496 well as those affected by explicitly defined policies and packet 497 filtering criteria. 498 type: uint 499 - 500 name: tx-hw-drop-errors 501 doc: Number of packets dropped because they were invalid or malformed. 502 type: uint 503 - 504 name: tx-csum-none 505 doc: | 506 Number of packets that did not require the device to calculate the 507 checksum. 508 type: uint 509 - 510 name: tx-needs-csum 511 doc: | 512 Number of packets that required the device to calculate the checksum. 513 This counter includes the number of GSO wire packets for which device 514 calculated the L4 checksum. 515 type: uint 516 - 517 name: tx-hw-gso-packets 518 doc: | 519 Number of packets that necessitated segmentation into smaller packets 520 by the device. 521 type: uint 522 - 523 name: tx-hw-gso-bytes 524 doc: See `tx-hw-gso-packets`. 525 type: uint 526 - 527 name: tx-hw-gso-wire-packets 528 doc: | 529 Number of wire-sized packets generated by processing 530 `tx-hw-gso-packets` 531 type: uint 532 - 533 name: tx-hw-gso-wire-bytes 534 doc: See `tx-hw-gso-wire-packets`. 535 type: uint 536 - 537 name: tx-hw-drop-ratelimits 538 doc: | 539 Number of the packets dropped by the device due to the transmit 540 packets bitrate exceeding the device rate limit. 541 type: uint 542 - 543 name: tx-stop 544 doc: | 545 Number of times driver paused accepting new tx packets 546 from the stack to this queue, because the queue was full. 547 Note that if BQL is supported and enabled on the device 548 the networking stack will avoid queuing a lot of data at once. 549 type: uint 550 - 551 name: tx-wake 552 doc: | 553 Number of times driver re-started accepting send 554 requests to this queue from the stack. 555 type: uint 556 - 557 name: queue-id 558 subset-of: queue 559 attributes: 560 - 561 name: id 562 - 563 name: type 564 - 565 name: lease 566 attributes: 567 - 568 name: ifindex 569 doc: The netdev ifindex to lease the queue from. 570 type: u32 571 checks: 572 min: 1 573 - 574 name: queue 575 doc: The netdev queue to lease from. 576 type: nest 577 nested-attributes: queue-id 578 - 579 name: netns-id 580 doc: The network namespace id of the netdev. 581 type: s32 582 checks: 583 min: 0 584 - 585 name: dmabuf 586 attributes: 587 - 588 name: ifindex 589 doc: netdev ifindex to bind the dmabuf to. 590 type: u32 591 checks: 592 min: 1 593 - 594 name: queues 595 doc: receive queues to bind the dmabuf to. 596 type: nest 597 nested-attributes: queue-id 598 multi-attr: true 599 - 600 name: fd 601 doc: dmabuf file descriptor to bind. 602 type: u32 603 - 604 name: id 605 doc: id of the dmabuf binding 606 type: u32 607 checks: 608 min: 1 609 - 610 name: rx-page-size 611 doc: | 612 Size in bytes of each device page the NIC writes into from the bound 613 dmabuf. Must be a power of two and >= PAGE_SIZE; defaults to 614 PAGE_SIZE. 615 type: u32 616 checks: 617 min: page-size 618 max: u32-max 619 620operations: 621 list: 622 - 623 name: dev-get 624 doc: Get / dump information about a netdev. 625 attribute-set: dev 626 do: 627 request: 628 attributes: 629 - ifindex 630 reply: &dev-all 631 attributes: 632 - ifindex 633 - xdp-features 634 - xdp-zc-max-segs 635 - xdp-rx-metadata-features 636 - xsk-features 637 dump: 638 reply: *dev-all 639 - 640 name: dev-add-ntf 641 doc: Notification about device appearing. 642 notify: dev-get 643 mcgrp: mgmt 644 - 645 name: dev-del-ntf 646 doc: Notification about device disappearing. 647 notify: dev-get 648 mcgrp: mgmt 649 - 650 name: dev-change-ntf 651 doc: Notification about device configuration being changed. 652 notify: dev-get 653 mcgrp: mgmt 654 - 655 name: page-pool-get 656 doc: | 657 Get / dump information about Page Pools. 658 Only Page Pools associated by the driver with a net_device 659 can be listed. ifindex will not be reported if the net_device 660 no longer exists. 661 attribute-set: page-pool 662 do: 663 request: 664 attributes: 665 - id 666 reply: &pp-reply 667 attributes: 668 - id 669 - ifindex 670 - napi-id 671 - inflight 672 - inflight-mem 673 - detach-time 674 - dmabuf 675 - io-uring 676 dump: 677 request: 678 attributes: 679 - ifindex 680 reply: *pp-reply 681 config-cond: page-pool 682 - 683 name: page-pool-add-ntf 684 doc: Notification about page pool appearing. 685 notify: page-pool-get 686 mcgrp: page-pool 687 config-cond: page-pool 688 - 689 name: page-pool-del-ntf 690 doc: Notification about page pool disappearing. 691 notify: page-pool-get 692 mcgrp: page-pool 693 config-cond: page-pool 694 - 695 name: page-pool-change-ntf 696 doc: Notification about page pool configuration being changed. 697 notify: page-pool-get 698 mcgrp: page-pool 699 config-cond: page-pool 700 - 701 name: page-pool-stats-get 702 doc: Get page pool statistics. 703 attribute-set: page-pool-stats 704 do: 705 request: 706 attributes: 707 - info 708 reply: &pp-stats-reply 709 attributes: 710 - info 711 - alloc-fast 712 - alloc-slow 713 - alloc-slow-high-order 714 - alloc-empty 715 - alloc-refill 716 - alloc-waive 717 - recycle-cached 718 - recycle-cache-full 719 - recycle-ring 720 - recycle-ring-full 721 - recycle-released-refcnt 722 dump: 723 request: 724 attributes: 725 - info 726 reply: *pp-stats-reply 727 config-cond: page-pool-stats 728 - 729 name: queue-get 730 doc: Get queue information from the kernel. 731 Only configured queues will be reported (as opposed to all available 732 hardware queues). 733 attribute-set: queue 734 do: 735 request: 736 attributes: 737 - ifindex 738 - type 739 - id 740 reply: &queue-get-op 741 attributes: 742 - id 743 - type 744 - napi-id 745 - ifindex 746 - dmabuf 747 - io-uring 748 - xsk 749 - lease 750 dump: 751 request: 752 attributes: 753 - ifindex 754 reply: *queue-get-op 755 - 756 name: napi-get 757 doc: Get information about NAPI instances configured on the system. 758 attribute-set: napi 759 do: 760 request: 761 attributes: 762 - id 763 reply: &napi-get-op 764 attributes: 765 - id 766 - ifindex 767 - irq 768 - pid 769 - defer-hard-irqs 770 - gro-flush-timeout 771 - irq-suspend-timeout 772 - threaded 773 dump: 774 request: 775 attributes: 776 - ifindex 777 reply: *napi-get-op 778 - 779 name: qstats-get 780 doc: | 781 Get / dump fine grained statistics. Which statistics are reported 782 depends on the device and the driver, and whether the driver stores 783 software counters per-queue. 784 attribute-set: qstats 785 dump: 786 request: 787 attributes: 788 - ifindex 789 - scope 790 reply: 791 attributes: 792 - ifindex 793 - queue-type 794 - queue-id 795 - rx-packets 796 - rx-bytes 797 - tx-packets 798 - tx-bytes 799 - rx-alloc-fail 800 - rx-hw-drops 801 - rx-hw-drop-overruns 802 - rx-csum-complete 803 - rx-csum-unnecessary 804 - rx-csum-none 805 - rx-csum-bad 806 - rx-hw-gro-packets 807 - rx-hw-gro-bytes 808 - rx-hw-gro-wire-packets 809 - rx-hw-gro-wire-bytes 810 - rx-hw-drop-ratelimits 811 - tx-hw-drops 812 - tx-hw-drop-errors 813 - tx-csum-none 814 - tx-needs-csum 815 - tx-hw-gso-packets 816 - tx-hw-gso-bytes 817 - tx-hw-gso-wire-packets 818 - tx-hw-gso-wire-bytes 819 - tx-hw-drop-ratelimits 820 - tx-stop 821 - tx-wake 822 - 823 name: bind-rx 824 doc: Bind dmabuf to netdev 825 attribute-set: dmabuf 826 flags: [uns-admin-perm] 827 do: 828 request: 829 attributes: 830 - ifindex 831 - fd 832 - queues 833 - rx-page-size 834 reply: 835 attributes: 836 - id 837 - 838 name: napi-set 839 doc: Set configurable NAPI instance settings. 840 attribute-set: napi 841 flags: [admin-perm] 842 do: 843 request: 844 attributes: 845 - id 846 - defer-hard-irqs 847 - gro-flush-timeout 848 - irq-suspend-timeout 849 - threaded 850 - 851 name: bind-tx 852 doc: Bind dmabuf to netdev for TX 853 attribute-set: dmabuf 854 do: 855 request: 856 attributes: 857 - ifindex 858 - fd 859 reply: 860 attributes: 861 - id 862 - 863 name: queue-create 864 doc: | 865 Create a new queue for the given netdevice. Whether this operation 866 is supported depends on the device and the driver. 867 attribute-set: queue 868 flags: [admin-perm] 869 do: 870 request: 871 attributes: 872 - ifindex 873 - type 874 - lease 875 reply: &queue-create-op 876 attributes: 877 - id 878 879kernel-family: 880 headers: ["net/netdev_netlink.h"] 881 sock-priv: struct netdev_nl_sock 882 883mcast-groups: 884 list: 885 - 886 name: mgmt 887 - 888 name: page-pool 889