pcictl(8): improve markup, edit for brevity

Author: nbuwe

usr.sbin/pcictl/pcictl.8

@@ -1,4 +1,4 @@
-.\"	$NetBSD: pcictl.8,v 1.20 2019/11/30 02:47:14 riastradh Exp $
+.\"	$NetBSD: pcictl.8,v 1.21 2026/01/25 00:59:36 uwe Exp $
 .\"
 .\" Copyright 2001 Wasabi Systems, Inc.
 .\" All rights reserved.
@@ -33,116 +33,162 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd September 23, 2016
+.Dd January 25, 2026
 .Dt PCICTL 8
 .Os
+.
 .Sh NAME
 .Nm pcictl
 .Nd a program to manipulate the PCI bus
+.
 .Sh SYNOPSIS
 .Nm
 .Ar pcibus
 .Ar command
-.Oo
-.Ar arg Oo ...
-.Oc
-.Oc
+.Op Ar arg \&...
+.
 .Sh DESCRIPTION
 .Nm
 allows a user or system administrator to access various resources
-on a PCI bus.
-.Pp
-The following commands are available:
+on a
+.Tn PCI
+bus.
+The
+.Ar pcibus
+argument names a special file for the
+.Tn PCI
+bus device.
+If the file name is relative, it's interpreted relative to the
+.Pa /dev
+directory, so e.g. plain
+.Ql pci0
+refers to
+.Pa /dev/pci0 .
+.
 .Pp
+The following
+.Ar command\^ Ns s
+are available:
+.
+.Bl -tag -width Cm
+.
+.It Xo
 .Cm list
 .Op Fl Nn
 .Op Fl b Ar bus
 .Op Fl d Ar device
 .Op Fl f Ar function
-.Pp
-List the devices in the PCI domain, either as names or, if
+.Xc
+List the devices in the
+.Tn PCI
+domain, either as names or, if
 .Fl n
 is given, as numbers.
-The bus, device, and function
-numbers may be specified by flags.
-Any locator not specified defaults
-to a wildcard, or may be explicitly wildcarded by specifying
-.Dq any .
+.Pp
 If
 .Fl N
-is given, the driver name for this PCI device will be listed
-if any driver is attached.
+is given, the driver name for this
+.Tn PCI
+device will be listed if any driver is attached.
 .Pp
-.Cm dump
-.Op Fl b Ar bus
-.Fl d Ar device
-.Op Fl f Ar function
+Any locator not specified defaults
+to a wildcard, or may be explicitly wildcarded by specifying
+.Sq Li all ,
+or
+.Sq Li any .
+.
+.El
+.\"
 .Pp
-Dump the PCI configuration space for the specified device located
-at the specified bus, device, and function.
+The remaining commands operate on a single
+.Tn PCI
+device, the
+.Fl d
+argument is mandatory.
 If the bus is not specified, it defaults to the bus number of the
-PCI bus specified on the command line.
+.Ar pcibus .
 If the function is not specified, it defaults to 0.
-.Pp
-.Cm read
+.
+.Bl -tag -width Cm
+.
+.It Xo
+.Cm dump
 .Op Fl b Ar bus
-.Fl d Ar device
+.   Fl d Ar device
 .Op Fl f Ar function
-.Ar reg
-.Pp
-Read the specified 32-bit aligned PCI configuration register and print
-it in hexadecimal to standard output.
-If the bus is not specified, it defaults to the bus number of the
-PCI bus specified on the command line.
-If the function is not specified, it defaults to 0.
-.Pp
-.Sy WARNING :
-.Nm
+.Xc
+Dump the
+.Tn PCI
+configuration space for the specified device.
+.
+.It Xo
 .Cm read
-is a dangerous command that can damage hardware and panic the operating
-system, even though it appears to be a harmless read-only operation.
-It is meant as a diagnostic tool for experiments or to debug device
-drivers.
-Do not use it as a substitute for a device driver!
-.Pp
+.Op Fl b Ar bus
+.   Fl d Ar device
+.Op Fl f Ar function
+.Ar register
+.Xc
+Read the specified 32-bit aligned
+.Tn PCI
+configuration
+.Ar register
+and print it in hexadecimal to standard output.
+.
+.It Xo
 .Cm write
 .Op Fl b Ar bus
-.Fl d Ar device
+.   Fl d Ar device
 .Op Fl f Ar function
-.Ar reg
+.Ar register
 .Ar value
-.Pp
-Write the specified value to the specified 32-bit aligned PCI
-configuration register.
-If the bus is not specified, it defaults to the bus number of the
-PCI bus specified on the command line.
-If the function is not specified, it defaults to 0.
-.Pp
-.Sy WARNING :
-.Nm
-.Cm write
-is a dangerous command that can damage hardware and panic the operating
-system.
-It is meant as a diagnostic tool for experiments or to debug device
-drivers.
-Do not use it as a substitute for a device driver!
+.Xc
+Write the specified
+.Ar value
+to the specified 32-bit aligned
+.Tn PCI
+configuration
+.Ar register .
+.
+.El
+.
 .Sh FILES
-.Pa /dev/pci*
-- PCI bus device nodes
+.Bl -tag -width Pa
+.It Pa /dev/pci*
+.Tn PCI
+bus device nodes
+.El
+.
 .Sh EXAMPLES
-This shows all PCI devices on the system:
+This shows all
+.Tn PCI
+devices on the system:
 .Pp
 .Dl pcictl pci0 list
 .Pp
-This shows all PCI devices on the system, including attached drivers:
+This shows all
+.Tn PCI
+devices on the system, including attached drivers:
 .Pp
 .Dl pcictl pci0 list -N
+.
 .Sh SEE ALSO
 .Xr pci 3 ,
 .Xr pci 4 ,
 .Xr drvctl 8
+.
 .Sh HISTORY
 The
 .Nm
 command first appeared in
 .Nx 1.6 .
+.
+.Sh CAVEATS
+.Nm
+.Cm read
+and
+.Cm write
+are dangerous commands that can damage hardware
+and panic the operating system.
+They are meant as a diagnostic tool for experiments or to debug device
+drivers.
+Do not use them as substitutes for a device driver!