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