1 .\" Copyright (c) 2015, 2018 Chelsio Inc
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions are met:
7 .\" 1. Redistributions of source code must retain the above copyright notice,
8 .\" this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the Chelsio Inc nor the names of its
15 .\" contributors may be used to endorse or promote products derived from
16 .\" this software without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
30 .\" * Other names and brands may be claimed as the property of others.
39 .Nd Userspace companion to
44 .Nm Ar nexus command Op Ar parameter ...
47 .Nm Ar nexus Cm clearstats Ar port_id
49 .Nm Ar nexus Cm context Bro Cm ingress | egress | fl | cong Brc Ar cntxt_id
51 .Nm Ar nexus Cm hashfilter mode
53 .Nm Ar nexus Cm hashfilter Ar filter-specification
55 .Nm Ar nexus Cm hashfilter Ar idx Cm delete
57 .Nm Ar nexus Cm hashfilter list
59 .Nm Ar nexus Cm filter mode
61 .Nm Ar nexus Cm filter Ar idx Ar filter-specification
63 .Nm Ar nexus Cm filter Ar idx Cm delete Op Cm prio Bro Cm 0 | 1 Brc
65 .Nm Ar nexus Cm filter list
67 .Nm Ar nexus Cm i2c Ar port_id devaddr addr Op Ar len
69 .Nm Ar nexus Cm loadcfg Ar fw-config.txt
71 .Nm Ar nexus Cm loadcfg clear
73 .Nm Ar nexus Cm loadfw Ar fw-image.bin
75 .Nm Ar nexus Cm memdump Ar addr len
77 .Nm Ar nexus Cm policy Ar cop.txt
79 .Nm Ar nexus Cm policy clear
81 .Nm Ar nexus Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
83 .Nm Ar nexus Cm regdump Op Ar register-block ...
85 .Nm Ar nexus Cm sched-class Ar sub-command Op Ar param Ar value
87 .Nm Ar nexus Cm sched-queue Ar port Ar queue Ar class
91 .Nm Ar nexus Cm tcb Ar tid
95 provides command-line access to features and debug facilities exported by
98 The target nexus device,
100 , is always the first argument.
101 (The parent nexus for an Ethernet port
104 .Va dev.cxgbe.%d.%parent
108 The rest consists of a command and any parameters required by that command.
111 .It Cm clearstats Ar port_id
112 Clear all transmit, receive, and error statistics of all queues associated
114 The total number of ports attached to a nexus is listed in
115 .Va dev.t4nex.%d.nports
118 identifies a port within this range.
122 .Cm context ingress Ar ingress_cntxt_id
124 .Cm context cong Ar ingress_cntxt_id
126 .Cm context egress Ar egress_cntxt_id
128 .Cm context fl Ar flm_cntxt_id
130 Display hardware context for an ingress queue, congestion manager, egress
131 queue, or freelist manager.
132 .Bl -tag -width ingress_cntxt_id -compact
133 .It Ar ingress_cntxt_id
134 context id of an ingress queue -- the value listed in one of
135 .Va dev.t4nex.%d.fwq.cntxt_id Ns ,
136 .Va dev.cxgbe.%d.rxq.%d.cntxt_id Ns ,
138 .Va dev.cxgbe.%d.ofld_rxq.%d.cntxt_id Ns .
139 .It Ar egress_cntxt_id
140 context id of an egress queue -- the value listed in one of
141 .Va dev.t4nex.%d.mgmtq.cntxt_id Ns ,
142 .Va dev.cxgbe.%d.txq.%d.cntxt_id Ns ,
143 .Va dev.cxgbe.%d.ctrlq.%d.cntxt_id Ns ,
144 .Va dev.cxgbe.%d.ofld_txq.%d.cntxt_id Ns ,
145 .Va dev.cxgbe.%d.rxq.%d.fl.cntxt_id Ns ,
147 .Va dev.cxgbe.%d.ofld_rxq.%d.fl.cntxt_id Ns .
148 Note that freelists are egress queues too.
150 context id of a freelist manager.
151 The FLM context id is displayed in the
152 egress context dump of a freelist as FLMcontextID.
161 Display a list of match-criteria available for use in filter rules.
162 A full list of match-criteria known to the chip is in the table below but not
163 all can be used together and the firmware sets up the available parameters based
164 on "filterMode" in the configuration file.
165 Every filter must conform to the filter mode -- multiple match criteria per
166 filter are allowed but only from among those in the current setting of the
168 The filter mode for hash filters is a subset of that for normal TCAM filters and
169 depends on the "filterMask" setting in the firmware configuration file.
170 Hash filters do not support masked matches and an exact value for every
171 parameter in the output of "hashfilter mode" (except ipv4/ipv6) must be provided
172 when creating a hash filter.
176 defaults to all 1s when not provided explicitly.
177 Hash filters do not support masked matches.
178 Also note that many of the items being matched are discrete numeric
179 values rather than bit fields and should be masked with caution.)
184 Criteria Usage Matches if ...
189 incoming packet is an IPv4 datagram.
195 incoming packet is an IPv6 datagram.
199 .Cm sip Ar addr Ns Op / Ns Ar mask
201 bitwise and of the source address in an incoming IP datagram with
206 can be an IPv4 or IPv6 address.
210 .Cm dip Ar addr Ns Op / Ns Ar mask
212 bitwise and of the destination address in an incoming IP datagram with
217 can be an IPv4 or IPv6 address.
221 .Cm sport Ar port Ns Op : Ns Ar mask
223 bitwise and of the source port in an incoming TCP or UDP datagram with
230 .Cm dport Ar port Ns Op : Ns Ar mask
232 bitwise and of the destination port in an incoming TCP or UDP datagram with
241 incoming frame is Fibre Channel over Ethernet(1) or not(0).
245 .Cm iport Ar val Ns Op : Ns Ar mask
247 bitwise and of the ingress port with
251 The ingress port is a 3 bit number that identifies the port on which a
253 Physical ports are numbered 0-3 and 4-7 are internal loopback paths
255 Note that ingress port is not a bit field so it is not always possible
256 to match an arbitrary subset of ingress ports with a single filter rule.
260 .Cm ovlan Ar tag Ns Op : Ns Ar mask
262 bitwise and of the 16-bit outer VLAN tag of an incoming frame with
269 .Cm vlan Ar tag Ns Op : Ns Ar mask
271 bitwise and of the 16-bit VLAN tag of an incoming QinQ frame with
275 The inner VLAN tag is used if the incoming frame is QinQ.
279 .Cm tos Ar val Ns Op : Ns Ar mask
281 bitwise and of the 8-bit IP Type of Service/IPv6 Traffic Class in an
289 .Cm proto Ar ipproto Ns Op : Ns Ar mask
291 bitwise and of the 8-bit IP protocol in an incoming packet with
298 .Cm ethtype Ar type Ns Op : Ns Ar mask
300 bitwise and of the 16-bit Ethernet type field of an incoming frame with
307 .Cm macidx Ar idx Ns Op : Ns Ar mask
309 bitwise and of the MAC Address Match Index of an incoming frame with
313 The MAC Address Match Index refers to an entry in the MPS TCAM or in the
316 for more information.
320 .Cm matchtype Ar type Ns Op : Ns Ar mask
322 bitwise and of the Match Type of an incoming frame with
326 Match Type is one of the following:
327 .Bl -tag -width "n" -compact
329 destination MAC in incoming frame is a unicast L2 address that is
330 programmed in the MPS TCAM.
332 can be used to match the index (and thus the MAC address) of the match
335 destination MAC in incoming frame is a unicast L2 address that "hit" a
336 hash entry in the MPS hash table.
338 can be used to match the index of the entry in the MPS hash table.
340 destination MAC in incoming frame is a multicast L2 address that is
341 programmed in the MPS TCAM.
343 can be used to match the index (and thus the MAC address) of the match
346 destination MAC in incoming frame is a multicast L2 address that "hit"
347 an entry in the MPS hash table.
349 interface on which incoming frame was received is in promiscuous mode
350 and the destination MAC in the frame is not a broadcast address, and
351 does not match in the MPS TCAM or the MPS hash either. (The frame would
352 have been discarded if the interface wasn't in promiscuous mode.)
354 interface on which incoming frame was received is in promiscuous mode
355 and the destination MAC in the frame is not a broadcast address; it
356 wasn't looked up in the MPS TCAM or the MPS hash because the chip is
357 configured to give precedence to promiscuous mode classification.
359 destination MAC in incoming frame is a broadcast address.
361 Not documented. Do not use.
368 incoming frame is part of a fragmented IP datagram(1) or not(0).
374 .Cm hashfilter Ar filter-specification
376 .Cm filter Ar idx Ar filter-specification
380 TCAM filters: The number of available filters is in
381 dev.<nexus>.<instance>.nfilters.
383 must be an unused index between 0 and nfilters - 1.
384 IPv6 filters consume 4 consecutive entries on T4/T5 and 2 on T6 and
386 must be aligned to 4 or 2 in this case.
388 Hash filters: These reside in the card's memory instead of its TCAM and are
389 enabled with a special configuration file that is selected with
390 .Cm hw.cxgbe.config_file="hashfilter"
392 There are at least half a million filters available with the sample config
393 shipped with the driver.
394 Note that the hardware selects the index for a hashfilter and this index is
395 displayed when the filter is created.
396 Hash and TCAM filters can be used together.
398 .Ar filter-specification
399 consists of one or more matches (see Usage in the table above) to try against an
400 incoming frame, an action to perform when all matches succeed, and some
401 additional operational parameters.
402 Hashfilters require an exact value for the 5-tuple (sip, dip, sport, dport,
403 proto) and for any other match-criteria listed in "hashfilter mode".
404 Possible filter actions are
409 .Bl -tag -width nat_dport -offset indent -compact
410 Operational parameters that can be used with all filters:
412 Count filter hits: 0 or 1 (default).
414 Filter has priority over active and server regions of TCAM: 0 (default) or 1.
417 .Bl -tag -width nat_dport -offset indent -compact
418 Operational parameters that can be used with filters with
421 Context id of an ingress queue to which to deliver the packet.
422 The context id is available in
423 .Va dev.cxgbe.%d.rxq.%d.cntxt_id .
424 By default, packets that hit a filter with action pass are delivered based on
425 their RSS hash as usual.
426 Use this to steer them to a particular queue.
428 Report the filter tid instead of the RSS hash in the rx descriptor.
431 Select TCB hash information in rx descriptor.
435 .Bl -tag -width nat_dport -offset indent -compact
436 Operational parameters that can be used with filters with
437 .Cm action switch Ns :
439 Egress port number on which to send the packet matching the filter.
440 0 to dev.<nexus>.<instance>.nports - 1.
442 Replace packet destination MAC address with the one provided before switching
445 Replace packet source MAC address with the one provided before switching it
448 Swap packet source and destination MAC addresses before switching it out of
451 Insert, remove, or rewrite the VLAN tag before switching the packet out of
456 replaces the existing tag with the one provided, and
458 inserts the given tag into the frame.
460 Specify the desired NAT mode. Valid NAT modes values are:
461 .Bl -tag -width dip-dp-sip -compact
463 Perform NAT on destination IP.
465 Perform NAT on destination IP, destination port.
467 Perform NAT on destination IP, destination port, source IP.
469 Perform NAT on destination IP, destination port, source port.
471 Perform NAT on source IP, source port.
473 Perform NAT on destination IP, source IP, source port.
475 Perform NAT on all 4-tuple fields.
478 Perform NAT only on segments which do not have TCP FIN or RST set.
480 Perform NAT only if incoming segment's sequence number + payload length is less
481 than this supplied value.
483 Perform NAT using this destination IP.
485 Perform NAT using this source IP.
487 Perform NAT using this destination port.
489 Perform NAT using this source port.
490 Perform NAT only if incoming segment's sequence number + payload length is less
491 than this supplied value.
496 .Cm hashfilter Ar idx Cm delete
498 .Cm filter Ar idx Cm delete
500 Delete filter that is at the given index.
501 .It Cm filter Cm list
502 List all filters programmed into the hardware.
503 .It Cm i2c Ar port_id devaddr addr Op Ar len
504 .It Cm loadcfg Ar fw-config.txt
505 Install the firmware configuration file contained in
508 Set hw.cxgbe.config_file="flash" in loader.conf to get
510 to use the on-flash configuration.
511 .It Cm loadcfg Cm clear
512 Erase configuration file from the card.
513 .It Cm loadfw Ar fw-image.bin
514 Install the firmware contained in
517 .It Cm memdump Ar addr len
520 bytes of data of the card's memory starting at
522 The card's memory map is available in
523 .Va dev.t4nex.%d.misc.meminfo Ns .
524 .It Cm policy Ar cop.txt
525 Install the Connection Offload Policy (COP) in
527 A COP offers fine-grained control over which connections get offloaded and with
530 .Cm hw.cxgbe.cop_managed_offloading="1"
531 in loader.conf to ensure that t4_tom will not offload any connection before a
533 Note that t4_tom must be loaded and operational (IFCAP_TOE enabled) as always
534 for any kind of offload based on the hardware TOE.
535 .Bl -column -offset indent "COP installed" "cop_managed_offloading" "Behavior"
536 .It Sy COP installed Ta Sy cop_managed_offloading Ta Sy Behavior
537 .It NO Ta 0 Ta offload all [Default]
538 .It NO Ta 1 Ta no offload
539 .It YES Ta Don't Care Ta Rule based offload
542 The policy file consists of empty lines, comments (lines begining with #) and
544 Rules are applied in the order they appear in the file and processing stops at
546 There is an implicit rule that disables offload for connections that do not
547 match anything in the policy.
549 Each rule consists of a filter part, which determines what connections the
550 rule applies to, and a settings part, which determines whether matching
551 connections will be offloaded and, if so, with what settings.
552 The general form of a rule is
553 .Bl -ohang -offset indent
554 .It Cm \&[ Ar socket-type Cm \&] Ar pcap-filter Cm => Ar settings
557 is one of the following.
558 .Bl -tag -width "X" -compact
561 Connection is being opened by this host.
564 Connection was requested by a peer.
566 Listen called on a socket.
567 Disabling offload in such a rule will prevent a hardware listener from being started.
570 Matches all of the above.
574 is an expression that follows the
576 syntax, or it is the keyword
578 that matches everything.
581 determine whether connections matching
585 are offloaded and optionally sets some per-connection properties if they are.
586 A combination of the following is allowed.
587 .Bl -tag -width "timestamp" -compact
589 Connection should be offloaded.
594 to disable offload instead.
596 Enable rx payload coalescing.
599 Enable TCP timestamp option.
602 Enable TCP Selective Acknowledgements (SACK).
605 Enable Nagle's algorithm.
608 Enable Explicit Congestion Notification (ECN).
611 Use Direct Data Placement (zero copy receive) and zero copy transmit on the
612 connection to service AIO requests on the socket.
615 Set ULP mode to ULP_MODE_TLS.
617 Use the specified congestion control algorithm.
620 .Cm reno Ns , Cm tahoe Ns , Cm newreno Ns , or Cm highspeed Ns .
622 Bind the connection to the specified tx scheduling class.
623 Valid range is 0 to 14 (for T4) and 0 to 15 (T5 onwards).
625 Use the specified offload rx queue.
627 should be between 0 and nofldrxq for the ifnet.
629 Use the specified offload tx queue.
631 should be between 0 and nofldtxq for the ifnet.
634 .Cm rxq Ar qnum Cm txq Ar qnum Ns .
635 Use only when nofldrxq is the same as nofldtxq.
637 Set the advertised TCP MSS in the SYN for this connection to
640 The hardware MTU table must already have an entry that is suitable for the MSS.
643 .It Example of a COP.
644 Note that hardware listener for port 22 will be IPv4 only because the rule
645 before it will prevent any IPv6 servers other than the first two. Also note
646 that outgoing connections to 192.168/16 are the only outgoing connections that
649 [L] port 80 => offload
650 [L] port 443 => offload
652 [L] port 22 => offload
653 [P] dst port 80 => offload cong highspeed !sack !ecn
654 [P] dst port 443 => offload tls
655 [A] dst net 192.168/16 => offload
657 [D] port 22 => offload !nagle
661 Remove the Connection Offload Policy (COP) if one is in use.
662 .It Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
663 .It Cm regdump Op Ar register-block ...
664 Display contents of device registers.
667 can be specified to limit the registers displayed.
668 The default is to display registers for all blocks.
669 Registers with read side effects are not read during a
674 .Cm sge pci dbg mc ma edc0 edc1 cim tp ulp_rx ulp_tx pmrx pmtx mps cplsw
675 .Cm smb i2c mi uart pmu sf pl le ncsi xgmac Ns .
676 .It Cm sched-class config Op Ar param Ar value
677 Configure optional feature capabilities for the TX scheduler.
678 .Bl -ohang -offset indent
679 .It Sy type Ar scheduler-type
680 Use packet for the packet scheduler.
681 .It Sy minmax Ar value
682 A non-zero value will enable "minmax" mode; a zero value will disable "minmax" mode.
684 NOTE: Many (most) of the parameters and constraints are adapter-specific
685 - for instance the number of channels and classes which are available
686 whether various modes are implemented, etc.
687 Consult the adapter documentation for specific information on any limitations.
689 .It Cm sched-class params Op Ar param Ar value
690 Configure parameters for a scheduling class.
691 .Bl -ohang -offset indent
692 .It Sy type Ar scheduler-type
693 Use packet for packet scheduler.
694 .It Sy level Ar scheduler-hierarchy-level
695 The "level" within the scheduling hierarchy which is being programed:
697 .Bl -tag -width "cl-wrr" -compact -offset indent
702 Class Weighted Round Robin.
705 Channel Rate Limiting.
707 .It Sy mode Ar scheduler-mode
708 The mode in which the scheduling class is going to operate:
710 .Bl -tag -width "class" -compact -offset indent
712 All of the "flows" bound to the scheduling class will be held to aggregate scheduling constraints.
715 Each of the "flows" bound to the scheduling class will be held to the scheduling constraints.
718 E.g. if the scheduling class has a TX bandwidth of 10Mb/s, in
720 mode, all of the "flows" bound to the class would be limited to an
721 aggregate bandwidth of 10Mb/s; but in
723 mode, each of the "flows" bound to the scheduling class would be limited to 10Mb/s.
724 .It Sy rate-unit Ar scheduler-rate-unit
725 The units of the scheduler rate constraints:
727 .Bl -tag -width "bits" -compact -offset indent
734 .It Sy rate-mode Ar scheduler-rate-mode
735 The mode of the scheduler rate constraints:
737 .Bl -tag -width "relative" -compact -offset indent
739 percent of port rate.
744 .It Sy channel Ar scheduler-channel-index
745 The scheduling channel to which the scheduling class will be bound.
746 .It Sy class Ar scheduler-class-index
747 The scheduling class being programmed.
748 .It Sy min-rate Ar minimum-rate
749 The minimum guaranteed rate to which a rate-limiting scheduling class hierarchy will have access.
750 .It Sy max-rate Ar maximum-rate
751 The maximum rate for a rate-limiting scheduling class hierarchy.
752 .It Sy weight Ar round-robin-weight
753 The weight to be used for a weighted-round-robin scheduling hierarchy.
754 .It Sy pkt-size Ar average-packet-size
755 The average packet size will be used to compute scheduler constraints for a rate-limited scheduler class hierarchy.
757 NOTE: Many (most) of the parameters and constraints are adapter-specific - for instance the number of channels and classes which are available,
758 whether various modes are implemented, etc.
759 Consult the adapter documentation for specific information on any limitations.
761 .It Cm sched-queue Ar port queue class
762 Bind the indicated port's NIC TX
764 to the specified TX Scheduler
770 or any negative value, the binding will apply to
771 all of the TX queues associated with the
775 or any negative value, the TX queue(s) will be unbound from
776 any current TX Scheduler Class binding.
778 Switch to interactive mode.
780 Display contents of the hardware TCB (TCP Control Block) for the
781 connection identfied by
785 /sys/dev/cxgbe/t4_ioctl.h
787 This manual page was written by
788 .An Navdeep Parhar Aq np@FreeBSD.org .