svn commit: r276598 - head/tools/tools/cxgbetool

[Navdeep Parhar]

Author: np
Date: Sat Jan  3 00:26:21 2015
New Revision: 276598
URL: https://svnweb.freebsd.org/changeset/base/276598

Log:
  Add a manual page for cxgbetool.  It is incomplete but definitely
  better than nothing.
  
  MFC after:	1 month

Added:
  head/tools/tools/cxgbetool/cxgbetool.8   (contents, props changed)
Modified:
  head/tools/tools/cxgbetool/Makefile

Modified: head/tools/tools/cxgbetool/Makefile
==============================================================================
--- head/tools/tools/cxgbetool/Makefile	Sat Jan  3 00:09:21 2015	(r276597)
+++ head/tools/tools/cxgbetool/Makefile	Sat Jan  3 00:26:21 2015	(r276598)
@@ -2,7 +2,7 @@
 
 PROG=	cxgbetool
 SRCS=	cxgbetool.c
-MAN=
+MAN=	cxgbetool.8
 CFLAGS+= -I${.CURDIR}/../../../sys/dev/cxgbe -I${.CURDIR}/../../../sys -I.
 BINDIR?= /usr/sbin
 

Added: head/tools/tools/cxgbetool/cxgbetool.8
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/tools/tools/cxgbetool/cxgbetool.8	Sat Jan  3 00:26:21 2015	(r276598)
@@ -0,0 +1,497 @@
+." Copyright (c) 2015, Chelsio Inc
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright notice,
+.\"    this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" 3. Neither the name of the Chelsio Inc nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" * Other names and brands may be claimed as the property of others.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 1, 2013
+.Dt CXGBETOOL 8
+.Os
+.Sh NAME
+.Nm cxgbetool
+.Nd Userspace companion to
+.Xr cxgbe 4
+.Sh SYNOPSIS
+.Bl -item -compact
+.It
+.Nm Ar nexus command Op Ar parameter ...
+.Pp
+.It
+.Nm Ar nexus Cm clearstats Ar port_id
+.It
+.Nm Ar nexus Cm context Bro Cm ingress | egress | fl | cong Brc Ar cntxt_id
+.It
+.Nm Ar nexus Cm filter mode Op Ar match-criteria ...
+.It
+.Nm Ar nexus Cm filter Ar idx Bro Ar filter-specification | Cm delete Brc
+.It
+.Nm Ar nexus Cm filter list
+.It
+.Nm Ar nexus Cm i2c Ar port_id devaddr addr Op Ar len
+.It
+.Nm Ar nexus Cm loadfw Ar fw-image.bin
+.It
+.Nm Ar nexus Cm memdump Ar addr len
+.It
+.Nm Ar nexus Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
+.It
+.Nm Ar nexus Cm regdump Op Ar register-block ...
+.It
+.Nm Ar nexus Cm sched-class Ar sub-command Op Ar param Ar value
+.It
+.Nm Ar nexus Cm sched-queue Ar port Ar queue Ar class
+.It
+.Nm Ar nexus Cm stdio
+.It
+.Nm Ar nexus Cm tcb Ar tid
+.El
+.Sh DESCRIPTION
+.Nm
+provides command-line access to features and debug facilities exported by
+.Xr cxgbe 4
+via private ioctls.
+The target nexus device,
+.Va t4nex%d
+, is always the first argument.
+(The parent nexus for an Ethernet port
+.Va cxgbe%d
+is listed in
+.Va dev.cxgbe.%d.%parent
+in the
+.Xr sysctl 8
+MIB).
+The rest consists of a command and any parameters required by that command.
+.Ss Commands
+.Bl -ohang
+.It Cm clearstats Ar port_id
+Clear all transmit, receive, and error statistics of all queues associated
+with a port.
+The total number of ports attached to a nexus is listed in 
+.Va dev.t4nex.%d.nports
+and the 0 based
+.Ar port_id
+identifies a port within this range.
+.Pp
+.Bl -item -compact
+.It
+.Cm context ingress Ar ingress_cntxt_id
+.It
+.Cm context cong Ar ingress_cntxt_id
+.It
+.Cm context egress Ar egress_cntxt_id
+.It
+.Cm context fl Ar flm_cntxt_id
+.El
+Display hardware context for an ingress queue, congestion manager, egress
+queue, or freelist manager.
+.Bl -tag -width ingress_cntxt_id -compact
+.It Ar ingress_cntxt_id
+context id of an ingress queue -- the value listed in one of
+.Va dev.t4nex.%d.fwq.cntxt_id Ns ,
+.Va dev.cxgbe.%d.rxq.%d.cntxt_id Ns ,
+or
+.Va dev.cxgbe.%d.ofld_rxq.%d.cntxt_id Ns .
+.It Ar egress_cntxt_id
+context id of an egress queue -- the value listed in one of
+.Va dev.t4nex.%d.mgmtq.cntxt_id Ns ,
+.Va dev.cxgbe.%d.txq.%d.cntxt_id Ns ,
+.Va dev.cxgbe.%d.ctrlq.%d.cntxt_id Ns ,
+.Va dev.cxgbe.%d.ofld_txq.%d.cntxt_id Ns ,
+.Va dev.cxgbe.%d.rxq.%d.fl.cntxt_id Ns ,
+or
+.Va dev.cxgbe.%d.ofld_rxq.%d.fl.cntxt_id Ns .
+Note that freelists are egress queues too.
+.It Ar flm_cntxt_id
+context id of a freelist manager.  The FLM context id is displayed in the
+egress context dump of a freelist as FLMcontextID.
+.El
+.It Cm filter mode Op Ar match-criteria ...
+Display or set the nexus's filter mode.
+.Ar match-criteria
+is a whitespace separated list of criteria from the table below.
+Each criteria has an associated budget which is also listed in the table.
+The total budget allowed is 36 and attempts to set a filter mode that
+exceeds this will be rejected.
+Every filter must conform to the filter mode -- multiple match criteria
+per filter are allowed but only from among those in the current setting
+of the filter mode.
+The filter mode can only be changed when there are no existing filters.
+Its default value is
+.Cm ipv4 ipv6 sip dip sport dport matchtype proto vlan iport fcoe
+.Pp
+(Note that
+.Ar mask
+defaults to all 1s when not provided explicitly.
+Also note that many of the items being matched are discrete numeric
+values rather than bit fields and should be masked with caution.)
+.TS
+center expand;
+cb cb cb cbw(40m)
+cb c l l.
+Criteria	Budget	Usage	Matches if ...
+_
+ipv4	0	T{
+.Cm type ipv4
+T}	T{
+incoming packet is an IPv4 datagram.
+T}
+_
+ipv6	0	T{
+.Cm type ipv6
+T}	T{
+incoming packet is an IPv6 datagram.
+T}
+_
+sip	0	T{
+.Cm sip Ar addr Ns Op / Ns Ar mask
+T}	T{
+bitwise and of the source address in an incoming IP datagram with
+.Ar mask
+equals
+.Ar addr Ns .
+.Ar addr
+can be an IPv4 or IPv6 address.
+T}
+_
+dip	0	T{
+.Cm dip Ar addr Ns Op / Ns Ar mask
+T}	T{
+bitwise and of the destination address in an incoming IP datagram with
+.Ar mask
+equals
+.Ar addr Ns .
+.Ar addr
+can be an IPv4 or IPv6 address.
+T}
+_
+sport	0	T{
+.Cm sport Ar port Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the source port in an incoming TCP or UDP datagram with
+.Ar mask
+equals
+.Ar port Ns .
+T}
+_
+dport	0	T{
+.Cm dport Ar port Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the destination port in an incoming TCP or UDP datagram with
+.Ar mask
+equals
+.Ar port Ns .
+T}
+_
+fcoe	1	T{
+.Cm fcoe Brq 0 | 1
+T}	T{
+incoming frame is Fibre Channel over Ethernet(1) or not(0).
+T}
+_
+iport	3	T{
+.Cm iport Ar val Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the ingress port with
+.Ar mask
+equals
+.Ar val Ns .
+The ingress port is a 3 bit number that identifies the port on which a
+frame arrived.
+Physical ports are numbered 0-3 and 4-7 are internal loopback paths
+within the chip.
+Note that ingress port is not a bit field so it is not always possible
+to match an arbitrary subset of ingress ports with a single filter rule.
+T}
+_
+ovlan	17	T{
+.Cm ovlan Ar tag Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the 16-bit outer VLAN tag of an incoming frame with
+.Ar mask
+equals
+.Ar tag Ns .
+T}
+_
+vlan	17	T{
+.Cm vlan Ar tag Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the 16-bit VLAN tag of an incoming QinQ frame with
+.Ar mask
+equals
+.Ar tag Ns .
+The inner VLAN tag is used if the incoming frame is QinQ.
+T}
+_
+tos	8	T{
+.Cm tos Ar val Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the 8-bit IP Type of Service/IPv6 Traffic Class in an
+incoming packet with
+.Ar mask
+equals
+.Ar val Ns .
+T}
+_
+proto	8	T{
+.Cm proto Ar ipproto Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the 8-bit IP protocol in an incoming packet with
+.Ar mask
+equals
+.Ar ipproto Ns .
+T}
+_
+ethtype	16	T{
+.Cm ethtype Ar type Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the 16-bit Ethernet type field of an incoming frame with
+.Ar mask
+equals
+.Ar type Ns .
+T}
+_
+macidx	9	T{
+.Cm macidx Ar idx Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the MAC Address Match Index of an incoming frame with
+.Ar mask
+equals
+.Ar idx Ns .
+The MAC Address Match Index refers to an entry in the MPS TCAM or in the
+MPS hash.  See
+.Cm matchtype
+for more information.
+T}
+_
+matchtype	3	T{
+.Cm matchtype Ar type Ns Op : Ns Ar mask
+T}	T{
+bitwise and of the Match Type of an incoming frame with
+.Ar mask
+equals
+.Ar idx Ns .
+Match Type is one of the following:
+.Bl -tag -width "n" -compact
+.It 0
+destination MAC in incoming frame is a unicast L2 address that is
+programmed in the MPS TCAM.
+.Cm macidx
+can be used to match the index (and thus the MAC address) of the match
+in the TCAM.
+.It 1
+destination MAC in incoming frame is a unicast L2 address that "hit" a
+hash entry in the MPS hash table.
+.Cm macidx
+can be used to match the index of the entry in the MPS hash table.
+.It 2
+destination MAC in incoming frame is a multicast L2 address that is
+programmed in the MPS TCAM.
+.Cm macidx
+can be used to match the index (and thus the MAC address) of the match
+in the TCAM.
+.It 3
+destination MAC in incoming frame is a multicast L2 address that "hit"
+an entry in the MPS hash table.
+.It 4
+interface on which incoming frame was received is in promiscuous mode
+and the destination MAC in the frame is not a broadcast address, and
+does not match in the MPS TCAM or the MPS hash either.  (The frame would
+have been discarded if the interface wasn't in promiscuous mode.)
+.It 5
+interface on which incoming frame was received is in promiscuous mode
+and the destination MAC in the frame is not a broadcast address; it
+wasn't looked up in the MPS TCAM or the MPS hash because the chip is
+configured to give precedence to promiscuous mode classification.
+.It 6
+destination MAC in incoming frame is a broadcast address.
+.It 7
+Not documented.  Do not use.
+.El
+T}
+_
+frag	1	T{
+.Cm frag Brq 0 | 1
+T}	T{
+incoming frame is part of a fragmented IP datagram(1) or not(0).
+T}
+.TE
+.It Cm filter Ar idx Ar filter-specification
+Program a filter at the index specified by
+.Ar idx Ns .
+.Ar filter-specification
+consists of one or more matches to try against an incoming frame and an
+action to perform when all matches succeed.
+.It Cm filter Ar idx Cm delete
+Delete filter that is at the given index.
+.It Cm filter Cm list
+List all filters programmed into the hardware.
+.It Cm i2c Ar port_id devaddr addr Op Ar len
+.It Cm loadfw Ar fw-image.bin
+Install the firmware contained in
+.Ar fw-image.bin
+to the card.
+.It Cm memdump Ar addr len
+Display
+.Ar len
+bytes of data of the card's memory starting at
+.Ar addr Ns .
+The card's memory map is available in
+.Va dev.t4nex.%d.misc.meminfo Ns .
+.It Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
+.It Cm regdump Op Ar register-block ...
+Display contents of device registers.  One or more
+.Ar register-block
+can be specified to limit the registers displayed.
+The default is to display registers for all blocks.
+Registers with read side effects are not read during a
+.Cm regdump
+operation.
+.Ar register-block
+can be
+.Cm sge pci dbg mc ma edc0 edc1 cim tp ulp_rx ulp_tx pmrx pmtx mps cplsw
+.Cm smb i2c mi uart pmu sf pl le ncsi xgmac Ns .
+.It Cm sched-class config Op Ar param Ar value
+Configure optional feature capabilities for the TX scheduler.
+.Bl -ohang -offset indent
+.It Sy type Ar scheduler-type
+Use packet for the packet scheduler.
+.It Sy minmax Ar value
+A non-zero value will enable "minmax" mode; a zero value will disable "minmax" mode.
+.Pp
+NOTE:  Many (most) of the parameters and constraints are adapter-specific
+- for instance the number of channels and classes which are available
+whether various modes are implemented, etc.  Consult the adapter documentation for specific information on any limitations.
+.El
+.It Cm sched-class params Op Ar param Ar value
+Configure parameters for a scheduling class.
+.Bl -ohang -offset indent
+.It Sy type Ar scheduler-type
+Use packet for packet scheduler.
+.It Sy level Ar scheduler-hierarchy-level
+The "level" within the scheduling hierarchy which is being programed:
+.Pp
+.Bl -tag -width "cl-wrr" -compact -offset indent
+.It Sy cl-rl
+Class Rate Limiting.
+.Pp
+.It Sy cl-wrr
+Class Weighted Round Robin.
+.Pp
+.It Sy cl-wrr
+Channel Rate Limiting.
+.El
+.Pp
+.It Sy mode Ar scheduler-mode
+The mode in which the scheduling class is going to operate:
+.Pp
+.Bl -tag -width "class" -compact -offset indent
+.It Sy class
+All of the "flows" bound to the scheduling class will be held to aggregate scheduling constraints.
+.Pp
+.It Sy flow
+Each of the "flows" bound to the scheduling class will be held to the scheduling constraints.
+.El
+.Pp
+E.g. if the scheduling class has a TX bandwidth of 10Mb/s, in
+.Cm class
+mode, all of the "flows" bound to the class would be  limited  to  an
+aggregate bandwidth of 10Mb/s; but in
+.Cm flow
+mode, each of the "flows" bound to the scheduling class would be limited to 10Mb/s.
+.Pp
+.It Sy rate-unit Ar scheduler-rate-unit
+The units of the scheduler rate constraints:
+.Pp
+.Bl -tag -width "bits" -compact -offset indent
+.It Sy bits
+bit rate in Kb/s.
+.Pp
+.It Sy pkts
+packets/s.
+.El
+.It Sy rate-mode Ar scheduler-rate-mode
+The mode of the scheduler rate constraints:
+.Pp
+.Bl -tag -width "relative" -compact -offset indent
+.It Sy relative
+percent of port rate.
+.Pp
+.It Sy absolute
+Kb/s.
+.El
+.Pp
+.It Sy channel Ar scheduler-channel-index
+The scheduling channel to which the scheduling class will be bound.
+.Pp
+.It Sy class Ar scheduler-class-index
+The scheduling class being programmed.
+.Pp
+.It Sy min-rate Ar minimum-rate
+The minimum guaranteed rate to which a rate-limiting scheduling class hierarchy will have access.
+.Pp
+.It Sy max-rate Ar maximum-rate
+The maximum rate for a rate-limiting scheduling class hierarchy.
+.Pp
+.It Sy weight Ar round-robin-weight
+The weight to be used for a weighted-round-robin scheduling hierarchy.
+.It Sy pkt-size Ar average-packet-size
+The average packet size will be used to compute scheduler constraints for a rate-limited scheduler class hierarchy.
+.Pp
+NOTE:  Many (most) of the parameters and constraints are adapter-specific - for instance the number of channels and classes which are available,
+whether various modes are implemented, etc.  Consult the adapter documentation for specific information on any limitations.
+.El
+.It Cm sched-queue Ar port queue class
+Bind the indicated port's NIC TX
+.Ar queue
+to the specified TX Scheduler
+.Ar class.
+If the TX
+.Ar queue
+is
+.Cm all, *
+or any negative value, the binding will apply to
+all  of  the TX queues associated with the
+.Ar interface.
+If the class is
+.Cm unbind, clear
+or any negative value, the TX queue(s) will be unbound from
+any current TX Scheduler Class binding.
+.It Cm stdio
+Switch to interactive mode.
+.It Cm tcb Ar tid
+Display contents of the hardware TCB (TCP Control Block) for the
+connection identfied by
+.Ar tid Ns .
+.El
+.Sh FILES
+/sys/dev/cxgbe/t4_ioctl.h
+.Sh AUTHORS
+This manual page was written by
+.An Navdeep Parhar Aq np at FreeBSD.org .