projects/linux·blob master · refs

890 lines · 24.5 KiB

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 # Intentionally unprivileged (no admin-perm / uns-admin-perm); see
855 # comment above netdev_nl_bind_tx_doit().
856 do:
857 request:
858 attributes:
859 - ifindex
860 - fd
861 reply:
862 attributes:
863 - id
864 -
865 name: queue-create
866 doc: |
867 Create a new queue for the given netdevice. Whether this operation
868 is supported depends on the device and the driver.
869 attribute-set: queue
870 flags: [admin-perm]
871 do:
872 request:
873 attributes:
874 - ifindex
875 - type
876 - lease
877 reply: &queue-create-op
878 attributes:
879 - id
880
881kernel-family:
882 headers: ["net/netdev_netlink.h"]
883 sock-priv: struct netdev_nl_sock
884
885mcast-groups:
886 list:
887 -
888 name: mgmt
889 -
890 name: page-pool