From owner-freebsd-doc@FreeBSD.ORG Fri Jul 9 00:58:41 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 97D6E16A4CE; Fri, 9 Jul 2004 00:58:41 +0000 (GMT) Received: from pittgoth.com (14.zlnp1.xdsl.nauticom.net [209.195.149.111]) by mx1.FreeBSD.org (Postfix) with ESMTP id E473A43D41; Fri, 9 Jul 2004 00:58:40 +0000 (GMT) (envelope-from trhodes@FreeBSD.org) Received: from localhost.pittgoth.com ([192.168.0.5]) (authenticated bits=0) by pittgoth.com (8.12.11/8.12.11) with ESMTP id i690weCh004110 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Thu, 8 Jul 2004 20:58:40 -0400 (EDT) (envelope-from trhodes@FreeBSD.org) Date: Thu, 8 Jul 2004 20:59:13 -0400 From: Tom Rhodes To: Giorgos Keramidas Message-Id: <20040708205913.502f6911@localhost.pittgoth.com> In-Reply-To: <20040708232534.GA85731@gothmog.gr> References: <20040708232534.GA85731@gothmog.gr> X-Mailer: Sylpheed version 0.9.11claws (GTK+ 1.2.10; i386-portbld-freebsd5.2) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit cc: Ruslan Ermilov cc: doc@FreeBSD.org Subject: Re: RFC: pciconf.8 options diff X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Jul 2004 00:58:41 -0000 On Fri, 9 Jul 2004 02:25:34 +0300 Giorgos Keramidas wrote: > I've tried to convert the description of options in pciconf.8 to the > usual .Bl ... .El style. The changes I made locally are: > > %% > Index: pciconf.8 > =================================================================== > RCS file: /home/ncvs/src/usr.sbin/pciconf/pciconf.8,v > retrieving revision 1.26 > diff -u -r1.26 pciconf.8 > --- pciconf.8 6 Jan 2004 20:23:20 -0000 1.26 > +++ pciconf.8 8 Jul 2004 23:19:51 -0000 > @@ -52,22 +52,16 @@ > .Pa /dev/pci , > normally only the super-user. > .Pp > -With the > -.Fl l > -option, it lists all devices found by the boot probe in the following format: > +The following options are available: > +.Bl -tag -width indent > +.It Fl l > +Lists all devices found by the boot probe in the following format: > .Bd -literal > foo0@pci0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00 > bar0@pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00 > none0@pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00 > .Ed > .Pp > -If the > -.Fl v > -option is supplied, > -.Nm > -will attempt to load the vendor/device information database, and print > -vendor, device, class and subclass identification strings for each device. > -.Pp > The first column gives the > device name, unit number, and > .Ar selector . > @@ -80,8 +74,10 @@ > The > .Ar selector > is in a form which may directly be used for the other forms of the command. > +.Pp > The second column is the class code, with the class byte printed as two > hex digits, followed by the sub-class and the interface bytes. > +.Pp > The third column gives the contents of the subvendorid register, introduced > in revision 2.1 of the > .Tn PCI > @@ -99,8 +95,11 @@ > this card is based on. > It consists of two fields, identifying the chip and > its vendor, as above. > +.Pp > The fifth column prints the chip's revision. > +.Pp > The sixth column describes the header type. > +.Pp > Currently assigned header types are 0 for all devices except > .Tn PCI > to In place of all these .Pp macros, how about making them a list? Perhaps: .Bl -bullet .It I describe column one. .It I describe column two. ... > @@ -115,36 +114,20 @@ > device, which contains several (similar or independent) functions on > one chip. > .Pp > -All invocations of > -.Nm > -except for > -.Fl l > -require a > -.Ar selector > -of the form > -.Li pci Ns Va bus Ns \&: Ns Va device > -(optionally followed by > -.Li \&: Ns Va function ) . > -A final colon may be appended and > -will be ignored; this is so that the first column in the output of > -.Nm > -.Fl l > -can be used without modification. > -All numbers are base 10. > -.Pp > -With the > -.Fl a > -flag, > +.It Fl v > +When used in combination with > +.Fl l , > .Nm > -determines whether any driver has been assigned to the device > +will attempt to load the vendor/device information database, and print > +vendor, device, class and subclass identification strings for each device. > +.It Fl a > +Determine whether any driver has been assigned to the device > identified by s/any/a here > .Ar selector . > An exit status of zero indicates that the device has a driver; > non-zero indicates that it does not. > -.Pp > -The > -.Fl r > -option reads a configuration space register at byte offset > +.It Fl r > +Reads a configuration space register at byte offset > .Ar addr > of device > .Ar selector > @@ -152,25 +135,47 @@ > The optional second address > .Ar addr2 > specifies a range to read. > -The > -.Fl w > -option writes the > +.It Fl w > +Write the > .Ar value > into a configuration space register at byte offset > .Ar addr > of device > .Ar selector . > -For both operations, the flags > -.Fl b > -and > -.Fl h > -select the width of the operation; > -.Fl b > -indicates a byte operation, and > -.Fl h > -indicates a halfword (two-byte) operation. > -The default is to read or > -write a longword (four bytes). > +.It Fl b > +When used in combination with > +.Fl r > +or > +.Fl w Perhaps a comma after w? > +indicate that the width of the operation is 1 byte. > +The default is to read or write a longword (four bytes). > +.It Fl h > +When used in combination with > +.Fl r > +or > +.Fl w Again here? > +indicate that the width of the operation is 1 half-word (two bytes). > +The default is to read or write a longword (four bytes). > +.El > +.Pp > +All invocations of > +.Nm > +except for > +.Fl l > +require a > +.Ar selector > +of the form > +.Li pci Ns Va bus Ns \&: Ns Va device > +(optionally followed by > +.Li \&: Ns Va function ) . I don't think we need '()' around this text. > +A final colon may be appended and > +will be ignored; this is so that the first column in the output of s/that // > +.Nm > +.Fl l > +can be used without modification. > +All numbers in the > +.Ar selector > +are base 10. > .Sh ENVIRONMENT > The PCI vendor/device information database is normally read from > .Pa /usr/share/misc/pci_vendors . > %% > > Any objections to committing this? Comments? Suggestions for > improvement? > > I know that the options are unsorted in the resulting manpage. > If it's ok to sort the options with a different commit, then > I'll do it separately. Otherwise I'll do it in only one commit. Remember, you are not required to take my advice. It's only when I demand you take my advice that you actually take my advice. :) -- Tom Rhodes