tools/tools/cxgbetool/cxgbetool.8

   1 .\" Copyright (c) 2015, Chelsio Inc
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are met:
   6 .\"
   7 .\" 1. Redistributions of source code must retain the above copyright notice,
   8 .\"    this list of conditions and the following disclaimer.
   9 .\"
  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.
  13 .\"
  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.
  17 .\"
  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.
  29 .\"
  30 .\" * Other names and brands may be claimed as the property of others.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd February 1, 2013
  35 .Dt CXGBETOOL 8
  36 .Os
  37 .Sh NAME
  38 .Nm cxgbetool
  39 .Nd Userspace companion to
  40 .Xr cxgbe 4
  41 .Sh SYNOPSIS
  42 .Bl -item -compact
  43 .It
  44 .Nm Ar nexus command Op Ar parameter ...
  45 .Pp
  46 .It
  47 .Nm Ar nexus Cm clearstats Ar port_id
  48 .It
  49 .Nm Ar nexus Cm context Bro Cm ingress | egress | fl | cong Brc Ar cntxt_id
  50 .It
  51 .Nm Ar nexus Cm filter mode Op Ar match-criteria ...
  52 .It
  53 .Nm Ar nexus Cm filter Ar idx Bro Ar filter-specification | Cm delete Brc
  54 .It
  55 .Nm Ar nexus Cm filter list
  56 .It
  57 .Nm Ar nexus Cm i2c Ar port_id devaddr addr Op Ar len
  58 .It
  59 .Nm Ar nexus Cm loadcfg Ar fw-config.txt
  60 .It
  61 .Nm Ar nexus Cm loadcfg clear
  62 .It
  63 .Nm Ar nexus Cm loadfw Ar fw-image.bin
  64 .It
  65 .Nm Ar nexus Cm memdump Ar addr len
  66 .It
  67 .Nm Ar nexus Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
  68 .It
  69 .Nm Ar nexus Cm regdump Op Ar register-block ...
  70 .It
  71 .Nm Ar nexus Cm sched-class Ar sub-command Op Ar param Ar value
  72 .It
  73 .Nm Ar nexus Cm sched-queue Ar port Ar queue Ar class
  74 .It
  75 .Nm Ar nexus Cm stdio
  76 .It
  77 .Nm Ar nexus Cm tcb Ar tid
  78 .El
  79 .Sh DESCRIPTION
  80 .Nm
  81 provides command-line access to features and debug facilities exported by
  82 .Xr cxgbe 4
  83 via private ioctls.
  84 The target nexus device,
  85 .Va t4nex%d
  86 , is always the first argument.
  87 (The parent nexus for an Ethernet port
  88 .Va cxgbe%d
  89 is listed in
  90 .Va dev.cxgbe.%d.%parent
  91 in the
  92 .Xr sysctl 8
  93 MIB).
  94 The rest consists of a command and any parameters required by that command.
  95 .Ss Commands
  96 .Bl -ohang
  97 .It Cm clearstats Ar port_id
  98 Clear all transmit, receive, and error statistics of all queues associated
  99 with a port.
 100 The total number of ports attached to a nexus is listed in
 101 .Va dev.t4nex.%d.nports
 102 and the 0 based
 103 .Ar port_id
 104 identifies a port within this range.
 105 .Pp
 106 .Bl -item -compact
 107 .It
 108 .Cm context ingress Ar ingress_cntxt_id
 109 .It
 110 .Cm context cong Ar ingress_cntxt_id
 111 .It
 112 .Cm context egress Ar egress_cntxt_id
 113 .It
 114 .Cm context fl Ar flm_cntxt_id
 115 .El
 116 Display hardware context for an ingress queue, congestion manager, egress
 117 queue, or freelist manager.
 118 .Bl -tag -width ingress_cntxt_id -compact
 119 .It Ar ingress_cntxt_id
 120 context id of an ingress queue -- the value listed in one of
 121 .Va dev.t4nex.%d.fwq.cntxt_id Ns ,
 122 .Va dev.cxgbe.%d.rxq.%d.cntxt_id Ns ,
 123 or
 124 .Va dev.cxgbe.%d.ofld_rxq.%d.cntxt_id Ns .
 125 .It Ar egress_cntxt_id
 126 context id of an egress queue -- the value listed in one of
 127 .Va dev.t4nex.%d.mgmtq.cntxt_id Ns ,
 128 .Va dev.cxgbe.%d.txq.%d.cntxt_id Ns ,
 129 .Va dev.cxgbe.%d.ctrlq.%d.cntxt_id Ns ,
 130 .Va dev.cxgbe.%d.ofld_txq.%d.cntxt_id Ns ,
 131 .Va dev.cxgbe.%d.rxq.%d.fl.cntxt_id Ns ,
 132 or
 133 .Va dev.cxgbe.%d.ofld_rxq.%d.fl.cntxt_id Ns .
 134 Note that freelists are egress queues too.
 135 .It Ar flm_cntxt_id
 136 context id of a freelist manager.  The FLM context id is displayed in the
 137 egress context dump of a freelist as FLMcontextID.
 138 .El
 139 .It Cm filter mode Op Ar match-criteria ...
 140 Display or set the nexus's filter mode.
 141 .Ar match-criteria
 142 is a whitespace separated list of criteria from the table below.
 143 Each criteria has an associated budget which is also listed in the table.
 144 The total budget allowed is 36 and attempts to set a filter mode that
 145 exceeds this will be rejected.
 146 Every filter must conform to the filter mode -- multiple match criteria
 147 per filter are allowed but only from among those in the current setting
 148 of the filter mode.
 149 The filter mode can only be changed when there are no existing filters.
 150 Its default value is
 151 .Cm ipv4 ipv6 sip dip sport dport matchtype proto vlan iport fcoe
 152 .Pp
 153 (Note that
 154 .Ar mask
 155 defaults to all 1s when not provided explicitly.
 156 Also note that many of the items being matched are discrete numeric
 157 values rather than bit fields and should be masked with caution.)
 158 .TS
 159 center expand;
 160 cb cb cb cbw(40m)
 161 cb c l l.
 162 Criteria        Budget  Usage   Matches if ...
 163 _
 164 ipv4    0       T{
 165 .Cm type ipv4
 166 T}      T{
 167 incoming packet is an IPv4 datagram.
 168 T}
 169 _
 170 ipv6    0       T{
 171 .Cm type ipv6
 172 T}      T{
 173 incoming packet is an IPv6 datagram.
 174 T}
 175 _
 176 sip     0       T{
 177 .Cm sip Ar addr Ns Op / Ns Ar mask
 178 T}      T{
 179 bitwise and of the source address in an incoming IP datagram with
 180 .Ar mask
 181 equals
 182 .Ar addr Ns .
 183 .Ar addr
 184 can be an IPv4 or IPv6 address.
 185 T}
 186 _
 187 dip     0       T{
 188 .Cm dip Ar addr Ns Op / Ns Ar mask
 189 T}      T{
 190 bitwise and of the destination address in an incoming IP datagram with
 191 .Ar mask
 192 equals
 193 .Ar addr Ns .
 194 .Ar addr
 195 can be an IPv4 or IPv6 address.
 196 T}
 197 _
 198 sport   0       T{
 199 .Cm sport Ar port Ns Op : Ns Ar mask
 200 T}      T{
 201 bitwise and of the source port in an incoming TCP or UDP datagram with
 202 .Ar mask
 203 equals
 204 .Ar port Ns .
 205 T}
 206 _
 207 dport   0       T{
 208 .Cm dport Ar port Ns Op : Ns Ar mask
 209 T}      T{
 210 bitwise and of the destination port in an incoming TCP or UDP datagram with
 211 .Ar mask
 212 equals
 213 .Ar port Ns .
 214 T}
 215 _
 216 fcoe    1       T{
 217 .Cm fcoe Brq 0 | 1
 218 T}      T{
 219 incoming frame is Fibre Channel over Ethernet(1) or not(0).
 220 T}
 221 _
 222 iport   3       T{
 223 .Cm iport Ar val Ns Op : Ns Ar mask
 224 T}      T{
 225 bitwise and of the ingress port with
 226 .Ar mask
 227 equals
 228 .Ar val Ns .
 229 The ingress port is a 3 bit number that identifies the port on which a
 230 frame arrived.
 231 Physical ports are numbered 0-3 and 4-7 are internal loopback paths
 232 within the chip.
 233 Note that ingress port is not a bit field so it is not always possible
 234 to match an arbitrary subset of ingress ports with a single filter rule.
 235 T}
 236 _
 237 ovlan   17      T{
 238 .Cm ovlan Ar tag Ns Op : Ns Ar mask
 239 T}      T{
 240 bitwise and of the 16-bit outer VLAN tag of an incoming frame with
 241 .Ar mask
 242 equals
 243 .Ar tag Ns .
 244 T}
 245 _
 246 vlan    17      T{
 247 .Cm vlan Ar tag Ns Op : Ns Ar mask
 248 T}      T{
 249 bitwise and of the 16-bit VLAN tag of an incoming QinQ frame with
 250 .Ar mask
 251 equals
 252 .Ar tag Ns .
 253 The inner VLAN tag is used if the incoming frame is QinQ.
 254 T}
 255 _
 256 tos     8       T{
 257 .Cm tos Ar val Ns Op : Ns Ar mask
 258 T}      T{
 259 bitwise and of the 8-bit IP Type of Service/IPv6 Traffic Class in an
 260 incoming packet with
 261 .Ar mask
 262 equals
 263 .Ar val Ns .
 264 T}
 265 _
 266 proto   8       T{
 267 .Cm proto Ar ipproto Ns Op : Ns Ar mask
 268 T}      T{
 269 bitwise and of the 8-bit IP protocol in an incoming packet with
 270 .Ar mask
 271 equals
 272 .Ar ipproto Ns .
 273 T}
 274 _
 275 ethtype 16      T{
 276 .Cm ethtype Ar type Ns Op : Ns Ar mask
 277 T}      T{
 278 bitwise and of the 16-bit Ethernet type field of an incoming frame with
 279 .Ar mask
 280 equals
 281 .Ar type Ns .
 282 T}
 283 _
 284 macidx  9       T{
 285 .Cm macidx Ar idx Ns Op : Ns Ar mask
 286 T}      T{
 287 bitwise and of the MAC Address Match Index of an incoming frame with
 288 .Ar mask
 289 equals
 290 .Ar idx Ns .
 291 The MAC Address Match Index refers to an entry in the MPS TCAM or in the
 292 MPS hash.  See
 293 .Cm matchtype
 294 for more information.
 295 T}
 296 _
 297 matchtype       3       T{
 298 .Cm matchtype Ar type Ns Op : Ns Ar mask
 299 T}      T{
 300 bitwise and of the Match Type of an incoming frame with
 301 .Ar mask
 302 equals
 303 .Ar idx Ns .
 304 Match Type is one of the following:
 305 .Bl -tag -width "n" -compact
 306 .It 0
 307 destination MAC in incoming frame is a unicast L2 address that is
 308 programmed in the MPS TCAM.
 309 .Cm macidx
 310 can be used to match the index (and thus the MAC address) of the match
 311 in the TCAM.
 312 .It 1
 313 destination MAC in incoming frame is a unicast L2 address that "hit" a
 314 hash entry in the MPS hash table.
 315 .Cm macidx
 316 can be used to match the index of the entry in the MPS hash table.
 317 .It 2
 318 destination MAC in incoming frame is a multicast L2 address that is
 319 programmed in the MPS TCAM.
 320 .Cm macidx
 321 can be used to match the index (and thus the MAC address) of the match
 322 in the TCAM.
 323 .It 3
 324 destination MAC in incoming frame is a multicast L2 address that "hit"
 325 an entry in the MPS hash table.
 326 .It 4
 327 interface on which incoming frame was received is in promiscuous mode
 328 and the destination MAC in the frame is not a broadcast address, and
 329 does not match in the MPS TCAM or the MPS hash either.  (The frame would
 330 have been discarded if the interface wasn't in promiscuous mode.)
 331 .It 5
 332 interface on which incoming frame was received is in promiscuous mode
 333 and the destination MAC in the frame is not a broadcast address; it
 334 wasn't looked up in the MPS TCAM or the MPS hash because the chip is
 335 configured to give precedence to promiscuous mode classification.
 336 .It 6
 337 destination MAC in incoming frame is a broadcast address.
 338 .It 7
 339 Not documented.  Do not use.
 340 .El
 341 T}
 342 _
 343 frag    1       T{
 344 .Cm frag Brq 0 | 1
 345 T}      T{
 346 incoming frame is part of a fragmented IP datagram(1) or not(0).
 347 T}
 348 .TE
 349 .It Cm filter Ar idx Ar filter-specification
 350 Program a filter at the index specified by
 351 .Ar idx Ns .
 352 .Ar filter-specification
 353 consists of one or more matches to try against an incoming frame and an
 354 action to perform when all matches succeed.
 355 .It Cm filter Ar idx Cm delete
 356 Delete filter that is at the given index.
 357 .It Cm filter Cm list
 358 List all filters programmed into the hardware.
 359 .It Cm i2c Ar port_id devaddr addr Op Ar len
 360 .It Cm loadcfg Ar fw-config.txt
 361 Install the firmware configuration file contained in
 362 .Ar fw-config.txt
 363 to the card.
 364 Set hw.cxgbe.config_file="flash" in loader.conf to get
 365 .Xr cxgbe 4
 366 to use the on-flash configuration.
 367 .It Cm loadcfg Cm clear
 368 Erase configuration file from the card.
 369 .It Cm loadfw Ar fw-image.bin
 370 Install the firmware contained in
 371 .Ar fw-image.bin
 372 to the card.
 373 .It Cm memdump Ar addr len
 374 Display
 375 .Ar len
 376 bytes of data of the card's memory starting at
 377 .Ar addr Ns .
 378 The card's memory map is available in
 379 .Va dev.t4nex.%d.misc.meminfo Ns .
 380 .It Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
 381 .It Cm regdump Op Ar register-block ...
 382 Display contents of device registers.  One or more
 383 .Ar register-block
 384 can be specified to limit the registers displayed.
 385 The default is to display registers for all blocks.
 386 Registers with read side effects are not read during a
 387 .Cm regdump
 388 operation.
 389 .Ar register-block
 390 can be
 391 .Cm sge pci dbg mc ma edc0 edc1 cim tp ulp_rx ulp_tx pmrx pmtx mps cplsw
 392 .Cm smb i2c mi uart pmu sf pl le ncsi xgmac Ns .
 393 .It Cm sched-class config Op Ar param Ar value
 394 Configure optional feature capabilities for the TX scheduler.
 395 .Bl -ohang -offset indent
 396 .It Sy type Ar scheduler-type
 397 Use packet for the packet scheduler.
 398 .It Sy minmax Ar value
 399 A non-zero value will enable "minmax" mode; a zero value will disable "minmax" mode.
 400 .Pp
 401 NOTE:  Many (most) of the parameters and constraints are adapter-specific
 402 - for instance the number of channels and classes which are available
 403 whether various modes are implemented, etc.  Consult the adapter documentation for specific information on any limitations.
 404 .El
 405 .It Cm sched-class params Op Ar param Ar value
 406 Configure parameters for a scheduling class.
 407 .Bl -ohang -offset indent
 408 .It Sy type Ar scheduler-type
 409 Use packet for packet scheduler.
 410 .It Sy level Ar scheduler-hierarchy-level
 411 The "level" within the scheduling hierarchy which is being programed:
 412 .Pp
 413 .Bl -tag -width "cl-wrr" -compact -offset indent
 414 .It Sy cl-rl
 415 Class Rate Limiting.
 416 .Pp
 417 .It Sy cl-wrr
 418 Class Weighted Round Robin.
 419 .Pp
 420 .It Sy cl-wrr
 421 Channel Rate Limiting.
 422 .El
 423 .It Sy mode Ar scheduler-mode
 424 The mode in which the scheduling class is going to operate:
 425 .Pp
 426 .Bl -tag -width "class" -compact -offset indent
 427 .It Sy class
 428 All of the "flows" bound to the scheduling class will be held to aggregate scheduling constraints.
 429 .Pp
 430 .It Sy flow
 431 Each of the "flows" bound to the scheduling class will be held to the scheduling constraints.
 432 .El
 433 .Pp
 434 E.g. if the scheduling class has a TX bandwidth of 10Mb/s, in
 435 .Cm class
 436 mode, all of the "flows" bound to the class would be  limited  to  an
 437 aggregate bandwidth of 10Mb/s; but in
 438 .Cm flow
 439 mode, each of the "flows" bound to the scheduling class would be limited to 10Mb/s.
 440 .It Sy rate-unit Ar scheduler-rate-unit
 441 The units of the scheduler rate constraints:
 442 .Pp
 443 .Bl -tag -width "bits" -compact -offset indent
 444 .It Sy bits
 445 bit rate in Kb/s.
 446 .Pp
 447 .It Sy pkts
 448 packets/s.
 449 .El
 450 .It Sy rate-mode Ar scheduler-rate-mode
 451 The mode of the scheduler rate constraints:
 452 .Pp
 453 .Bl -tag -width "relative" -compact -offset indent
 454 .It Sy relative
 455 percent of port rate.
 456 .Pp
 457 .It Sy absolute
 458 Kb/s.
 459 .El
 460 .It Sy channel Ar scheduler-channel-index
 461 The scheduling channel to which the scheduling class will be bound.
 462 .It Sy class Ar scheduler-class-index
 463 The scheduling class being programmed.
 464 .It Sy min-rate Ar minimum-rate
 465 The minimum guaranteed rate to which a rate-limiting scheduling class hierarchy will have access.
 466 .It Sy max-rate Ar maximum-rate
 467 The maximum rate for a rate-limiting scheduling class hierarchy.
 468 .It Sy weight Ar round-robin-weight
 469 The weight to be used for a weighted-round-robin scheduling hierarchy.
 470 .It Sy pkt-size Ar average-packet-size
 471 The average packet size will be used to compute scheduler constraints for a rate-limited scheduler class hierarchy.
 472 .Pp
 473 NOTE:  Many (most) of the parameters and constraints are adapter-specific - for instance the number of channels and classes which are available,
 474 whether various modes are implemented, etc.  Consult the adapter documentation for specific information on any limitations.
 475 .El
 476 .It Cm sched-queue Ar port queue class
 477 Bind the indicated port's NIC TX
 478 .Ar queue
 479 to the specified TX Scheduler
 480 .Ar class.
 481 If the TX
 482 .Ar queue
 483 is
 484 .Cm all, *
 485 or any negative value, the binding will apply to
 486 all  of  the TX queues associated with the
 487 .Ar interface.
 488 If the class is
 489 .Cm unbind, clear
 490 or any negative value, the TX queue(s) will be unbound from
 491 any current TX Scheduler Class binding.
 492 .It Cm stdio
 493 Switch to interactive mode.
 494 .It Cm tcb Ar tid
 495 Display contents of the hardware TCB (TCP Control Block) for the
 496 connection identfied by
 497 .Ar tid Ns .
 498 .El
 499 .Sh FILES
 500 /sys/dev/cxgbe/t4_ioctl.h
 501 .Sh AUTHORS
 502 This manual page was written by
 503 .An Navdeep Parhar Aq np@FreeBSD.org .