git: 8f25fac9ce23 - main - cxgbetool.8: Fix some minor mechanical issues

From: Alexander Ziaee <ziaee_at_FreeBSD.org>
Date: Mon, 19 May 2025 02:58:03 UTC
The branch main has been updated by ziaee:

URL: https://cgit.FreeBSD.org/src/commit/?id=8f25fac9ce2339ab5599e3af0ef7c6a1ea098aab

commit 8f25fac9ce2339ab5599e3af0ef7c6a1ea098aab
Author:     Alexander Ziaee <ziaee@FreeBSD.org>
AuthorDate: 2025-05-13 00:37:38 +0000
Commit:     Alexander Ziaee <ziaee@FreeBSD.org>
CommitDate: 2025-05-19 02:56:12 +0000

    cxgbetool.8: Fix some minor mechanical issues
    
    + Tag SPDX
    + Macros should not appear in titles, write a hopefully better title
    + Nm needs to be on it's own line in SYNOPSIS, fold it so this page
      does not appear in unrelated search results (test case `apropos fw`)
    + Remove Ns's that do nothing and generate linter errors
    + Move list initializers to where they render, correcting linter errors
    
    Unresolved:
    This page produces an error when rendered due to the macros table.
    I don't know how to fix that yet, but I'm interested in learning!
    
    Reviewed by:            mhorne
    Approved by:            mhorne (mentor)
    Differential Revision:  https://reviews.freebsd.org/D50320
---
 usr.sbin/cxgbetool/cxgbetool.8 | 177 ++++++++++++++++++++++++-----------------
 1 file changed, 103 insertions(+), 74 deletions(-)

diff --git a/usr.sbin/cxgbetool/cxgbetool.8 b/usr.sbin/cxgbetool/cxgbetool.8
index a5f345c6b781..f0dee1830a5a 100644
--- a/usr.sbin/cxgbetool/cxgbetool.8
+++ b/usr.sbin/cxgbetool/cxgbetool.8
@@ -1,3 +1,6 @@
+.\"
+.\" SPDX-License-Identifier: BSD-3-Clause
+.\"
 .\" Copyright (c) 2015, 2018 Chelsio Inc
 .\" All rights reserved.
 .\"
@@ -29,68 +32,93 @@
 .\"
 .\" * Other names and brands may be claimed as the property of others.
 .\"
-.Dd December 10, 2024
+.Dd May 11, 2025
 .Dt CXGBETOOL 8
 .Os
 .Sh NAME
 .Nm cxgbetool
-.Nd Userspace companion to
-.Xr cxgbe 4
+.Nd userspace companion to Chelsio cxgbe Ethernet driver
 .Sh SYNOPSIS
 .Bl -item -compact
 .It
-.Nm Ar nexus command Op Ar parameter ...
+.Nm
+.Ar nexus command Op Ar parameter ...
 .Pp
 .It
-.Nm Ar nexus Cm clearstats Ar port_id
+.Nm
+.Ar nexus Cm clearstats Ar port_id
 .It
-.Nm Ar nexus Cm clip Bro Cm hold | release Brc Ar ipv6-address
+.Nm
+.Ar nexus Cm clip Bro Cm hold | release Brc Ar ipv6-address
 .It
-.Nm Ar nexus Cm clip Cm list
+.Nm
+.Ar nexus Cm clip Cm list
 .It
-.Nm Ar nexus Cm context Bro Cm ingress | egress | fl | cong Brc Ar cntxt_id
+.Nm
+.Ar nexus Cm context Bro Cm ingress | egress | fl | cong Brc Ar cntxt_id
 .It
-.Nm Ar nexus Cm hashfilter mode
+.Nm
+.Ar nexus Cm hashfilter mode
 .It
-.Nm Ar nexus Cm hashfilter Ar filter-specification
+.Nm
+.Ar nexus Cm hashfilter Ar filter-specification
 .It
-.Nm Ar nexus Cm hashfilter Ar idx Cm delete
+.Nm
+.Ar nexus Cm hashfilter Ar idx Cm delete
 .It
-.Nm Ar nexus Cm hashfilter list
+.Nm
+.Ar nexus Cm hashfilter list
 .It
-.Nm Ar nexus Cm filter mode
+.Nm
+.Ar nexus Cm filter mode
 .It
-.Nm Ar nexus Cm filter Ar idx Ar filter-specification
+.Nm
+.Ar nexus Cm filter Ar idx Ar filter-specification
 .It
-.Nm Ar nexus Cm filter Ar idx Cm delete Op Cm prio Bro Cm 0 | 1 Brc
+.Nm
+.Ar nexus Cm filter Ar idx Cm delete Op Cm prio Bro Cm 0 | 1 Brc
 .It
-.Nm Ar nexus Cm filter list
+.Nm
+.Ar nexus Cm filter list
 .It
-.Nm Ar nexus Cm i2c Ar port_id devaddr addr Op Ar len
+.Nm
+.Ar nexus Cm i2c Ar port_id devaddr addr Op Ar len
 .It
-.Nm Ar nexus Cm loadcfg Ar fw-config.txt
+.Nm
+.Ar nexus Cm loadcfg Ar fw-config.txt
 .It
-.Nm Ar nexus Cm loadcfg clear
+.Nm
+.Ar nexus Cm loadcfg clear
 .It
-.Nm Ar nexus Cm loadfw Ar fw-image.bin
+.Nm
+.Ar nexus Cm loadfw Ar fw-image.bin
 .It
-.Nm Ar nexus Cm memdump Ar addr len
+.Nm
+.Ar nexus Cm memdump Ar addr len
 .It
-.Nm Ar nexus Cm policy Ar cop.txt
+.Nm
+.Ar nexus Cm policy Ar cop.txt
 .It
-.Nm Ar nexus Cm policy clear
+.Nm
+.Ar nexus Cm policy clear
 .It
-.Nm Ar nexus Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
+.Nm
+.Ar nexus Bro Cm reg | reg64 Brc Ar addr Ns Op Ar =val
 .It
-.Nm Ar nexus Cm regdump Op Ar register-block ...
+.Nm
+.Ar nexus Cm regdump Op Ar register-block ...
 .It
-.Nm Ar nexus Cm sched-class Ar sub-command Op Ar param Ar value
+.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
+.Nm
+.Ar nexus Cm sched-queue Ar port Ar queue Ar class
 .It
-.Nm Ar nexus Cm stdio
+.Nm
+.Ar nexus Cm stdio
 .It
-.Nm Ar nexus Cm tcb Ar tid
+.Nm
+.Ar nexus Cm tcb Ar tid
 .El
 .Sh DESCRIPTION
 .Nm
@@ -155,22 +183,22 @@ A reference on the address must have been acquired previously.
 .El
 Display hardware context for an ingress queue, congestion manager, egress
 queue, or freelist manager.
-.Bl -tag -width ingress_cntxt_id -compact
+.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 ,
+.Va dev.t4nex.%d.fwq.cntxt_id ,
+.Va dev.cxgbe.%d.rxq.%d.cntxt_id ,
 or
-.Va dev.cxgbe.%d.ofld_rxq.%d.cntxt_id Ns .
+.Va dev.cxgbe.%d.ofld_rxq.%d.cntxt_id .
 .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 ,
+.Va dev.t4nex.%d.mgmtq.cntxt_id ,
+.Va dev.cxgbe.%d.txq.%d.cntxt_id ,
+.Va dev.cxgbe.%d.ctrlq.%d.cntxt_id ,
+.Va dev.cxgbe.%d.ofld_txq.%d.cntxt_id ,
+.Va dev.cxgbe.%d.rxq.%d.fl.cntxt_id ,
 or
-.Va dev.cxgbe.%d.ofld_rxq.%d.fl.cntxt_id Ns .
+.Va dev.cxgbe.%d.ofld_rxq.%d.fl.cntxt_id .
 Note that freelists are egress queues too.
 .It Ar flm_cntxt_id
 context id of a freelist manager.
@@ -227,7 +255,7 @@ T}	T{
 bitwise and of the source address in an incoming IP datagram with
 .Ar mask
 equals
-.Ar addr Ns .
+.Ar addr .
 .Ar addr
 can be an IPv4 or IPv6 address.
 T}
@@ -238,7 +266,7 @@ T}	T{
 bitwise and of the destination address in an incoming IP datagram with
 .Ar mask
 equals
-.Ar addr Ns .
+.Ar addr .
 .Ar addr
 can be an IPv4 or IPv6 address.
 T}
@@ -249,7 +277,7 @@ T}	T{
 bitwise and of the source port in an incoming TCP or UDP datagram with
 .Ar mask
 equals
-.Ar port Ns .
+.Ar port .
 T}
 _
 dport	T{
@@ -258,7 +286,7 @@ T}	T{
 bitwise and of the destination port in an incoming TCP or UDP datagram with
 .Ar mask
 equals
-.Ar port Ns .
+.Ar port .
 T}
 _
 fcoe	T{
@@ -273,7 +301,7 @@ T}	T{
 bitwise and of the ingress port with
 .Ar mask
 equals
-.Ar val Ns .
+.Ar val .
 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
@@ -288,7 +316,7 @@ T}	T{
 bitwise and of the 16-bit outer VLAN tag of an incoming frame with
 .Ar mask
 equals
-.Ar tag Ns .
+.Ar tag .
 T}
 _
 vlan	T{
@@ -297,7 +325,7 @@ T}	T{
 bitwise and of the 16-bit VLAN tag of an incoming QinQ frame with
 .Ar mask
 equals
-.Ar tag Ns .
+.Ar tag .
 The inner VLAN tag is used if the incoming frame is QinQ.
 T}
 _
@@ -308,7 +336,7 @@ bitwise and of the 8-bit IP Type of Service/IPv6 Traffic Class in an
 incoming packet with
 .Ar mask
 equals
-.Ar val Ns .
+.Ar val .
 T}
 _
 proto	T{
@@ -317,7 +345,7 @@ T}	T{
 bitwise and of the 8-bit IP protocol in an incoming packet with
 .Ar mask
 equals
-.Ar ipproto Ns .
+.Ar ipproto .
 T}
 _
 ethtype	T{
@@ -326,7 +354,7 @@ T}	T{
 bitwise and of the 16-bit Ethernet type field of an incoming frame with
 .Ar mask
 equals
-.Ar type Ns .
+.Ar type .
 T}
 _
 macidx	T{
@@ -335,7 +363,7 @@ T}	T{
 bitwise and of the MAC Address Match Index of an incoming frame with
 .Ar mask
 equals
-.Ar idx Ns .
+.Ar idx .
 The MAC Address Match Index refers to an entry in the MPS TCAM or in the
 MPS hash.  See
 .Cm matchtype
@@ -348,7 +376,7 @@ T}	T{
 bitwise and of the Match Type of an incoming frame with
 .Ar mask
 equals
-.Ar idx Ns .
+.Ar idx .
 Match Type is one of the following:
 .Bl -tag -width "n" -compact
 .It 0
@@ -428,21 +456,21 @@ additional operational parameters.
 Hashfilters require an exact value for the 5-tuple (sip, dip, sport, dport,
 proto) and for any other match-criteria listed in "hashfilter mode".
 Possible filter actions are
-.Cm drop Ns ,
-.Cm pass Ns , or
-.Cm switch Ns .
+.Cm drop ,
+.Cm pass , or
+.Cm switch .
 .Pp
-.Bl -tag -width nat_dport -offset indent -compact
 Operational parameters that can be used with all filters:
+.Bl -tag -width "nat_dport" -offset indent -compact
 .It Cm hitcnts
 Count filter hits: 0 or 1 (default).
 .It Cm prio
 Filter has priority over active and server regions of TCAM: 0 (default) or 1.
 .El
 .Pp
-.Bl -tag -width nat_dport -offset indent -compact
 Operational parameters that can be used with filters with
-.Cm action pass Ns :
+.Cm action pass :
+.Bl -tag -width "nat_dport" -offset indent -compact
 .It Cm queue
 Context id of an ingress queue to which to deliver the packet.
 The context id is available in
@@ -458,9 +486,9 @@ Select TCB hash information in rx descriptor.
 0 (default) or 1
 .El
 .Pp
-.Bl -tag -width nat_dport -offset indent -compact
 Operational parameters that can be used with filters with
-.Cm action switch Ns :
+.Cm action switch :
+.Bl -tag -width "nat_dport" -offset indent -compact
 .It Cm eport
 Egress port number on which to send the packet matching the filter.
 0 to dev.<nexus>.<instance>.nports - 1.
@@ -483,8 +511,9 @@ replaces the existing tag with the one provided, and
 .Cm + Ns Ar tag
 inserts the given tag into the frame.
 .It Cm nat
-Specify the desired NAT mode. Valid NAT modes values are:
-.Bl -tag -width dip-dp-sip -compact
+Specify the desired NAT mode.
+Valid NAT modes values are:
+.Bl -tag -width "dip-dp-sip" -compact
 .It Cm dip
 Perform NAT on destination IP.
 .It Cm dip-dp
@@ -546,12 +575,12 @@ to the card.
 Display
 .Ar len
 bytes of data of the card's memory starting at
-.Ar addr Ns .
+.Ar addr .
 The card's memory map is available in
-.Va dev.t4nex.%d.misc.meminfo Ns .
+.Va dev.t4nex.%d.misc.meminfo .
 .It Cm policy Ar cop.txt
 Install the Connection Offload Policy (COP) in
-.Ar cop.txt Ns .
+.Ar cop.txt .
 A COP offers fine-grained control over which connections get offloaded and with
 what parameters.
 Set
@@ -645,7 +674,7 @@ Set ULP mode to ULP_MODE_TLS.
 Use the specified congestion control algorithm.
 .Ar algo
 must be one of
-.Cm reno Ns , Cm tahoe Ns , Cm newreno Ns , or Cm highspeed Ns .
+.Cm reno , Cm tahoe , Cm newreno , or Cm highspeed .
 .It Cm class Ar sc
 Bind the connection to the specified tx scheduling class.
 Valid range is 0 to 14 (for T4) and 0 to 15 (T5 onwards).
@@ -653,17 +682,17 @@ Valid range is 0 to 14 (for T4) and 0 to 15 (T5 onwards).
 Use the specified offload rx queue.
 .Ar qnum
 should be
-.Cm random Ns , Cm roundrobin Ns ,
+.Cm random , Cm roundrobin ,
 or a number between 0 and nofldrxq for the ifnet.
 .It Cm txq Ar qnum
 Use the specified offload tx queue.
 .Ar qnum
 should be
-.Cm random Ns , Cm roundrobin Ns ,
+.Cm random , Cm roundrobin ,
 or a number between 0 and nofldtxq for the ifnet.
 .It Cm bind Ar qnum
 Shorthand for
-.Cm rxq Ar qnum Cm txq Ar qnum Ns .
+.Cm rxq Ar qnum Cm txq Ar qnum .
 Use when nofldrxq is the same as nofldtxq.
 .It Cm mss Ar val
 Set the advertised TCP MSS in the SYN for this connection to
@@ -671,10 +700,10 @@ Set the advertised TCP MSS in the SYN for this connection to
 (in bytes).
 The hardware MTU table must already have an entry that is suitable for the MSS.
 .El
-.Pp
 .It Example of a COP.
 Note that hardware listener for port 22 will be IPv4 only because the rule
-before it will prevent any IPv6 servers other than the first two.  Also note
+before it will prevent any IPv6 servers other than the first two.
+Also note
 that outgoing connections to 192.168/16 are the only outgoing connections that
 will get offloaded.
 .Bd -literal
@@ -704,7 +733,7 @@ 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 .
+.Cm smb i2c mi uart pmu sf pl le ncsi xgmac .
 .It Cm sched-class config Op Ar param Ar value
 Configure optional feature capabilities for the TX scheduler.
 .Bl -ohang -offset indent
@@ -794,14 +823,14 @@ Consult the adapter documentation for specific information on any limitations.
 Bind the indicated port's NIC TX
 .Ar queue
 to the specified TX Scheduler
-.Ar class.
+.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.
+.Ar interface .
 If the class is
 .Cm unbind, clear
 or any negative value, the TX queue(s) will be unbound from
@@ -811,7 +840,7 @@ 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 .
+.Ar tid .
 .El
 .Sh FILES
 /sys/dev/cxgbe/t4_ioctl.h