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