Sweep formatting and assorted fixes.

svn path=/head/; revision=131736

share/man/man9/BUS_ADD_CHILD.9

@@ -33,34 +33,42 @@
 .Os
 .Sh NAME
 .Nm BUS_ADD_CHILD
-.Nd Adds a device node to the tree with a given priority
+.Nd "add a device node to the tree with a given priority"
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/bus.h
 .Ft int
 .Fn BUS_ADD_CHILD "device_t dev" "int order" "const char *name" "int unit"
 .Sh DESCRIPTION
-Used by the driver identify routine to add devices to the tree.
+The
+.Fn BUS_ADD_CHILD
+method
+is used by the driver identify routine to add devices to the tree.
 Please see
 .Xr device_add_child 9
 for more details.
 The interface is the same as
-.Fn device_add_child
+.Xr device_add_child 9
 however, the bus'
-.Ft BUS_ADD_CHILD
+.Fn BUS_ADD_CHILD
 is called.
 .Pp
 Busses implementing
-.Ft BUS_ADD_CHILD
+.Fn BUS_ADD_CHILD
 should insert the device into the tree using
-.Fn device_add_child
+.Xr device_add_child 9
 before adding things such as their own ivars and resource lists to the device.
 .Sh SEE ALSO
 .Xr device 9 ,
 .Xr device_add_child 9 ,
 .Xr driver 9
 .Sh RETURN VALUES
-The device_t added to the tree, or NULL.
+The
+.Fn BUS_ADD_CHILD
+method returns
+.Vt device_t
+added to the tree, or
+.Dv NULL .
 .Sh AUTHORS
 This manual page was written by
 .An M. Warner Losh .

share/man/man9/BUS_CONFIG_INTR.9

@@ -31,31 +31,33 @@
 .\"
 .Sh NAME
 .Nm BUS_CONFIG_INTR
-.Nd Configure interrupt polarity and trigger mode
+.Nd "configure interrupt polarity and trigger mode"
 .\"
 .Sh SYNOPSIS
 .In sys/param.h
 .In sys/bus.h
 .Ft int
-.Fn BUS_CONFIG_INTR "device_t dev" "int irq" "enum intr_trigger trig" "enum intr_polarity pol"
+.Fo BUS_CONFIG_INTR
+.Fa "device_t dev" "int irq" "enum intr_trigger trig" "enum intr_polarity pol"
+.Fc
 .\"
 .Sh DESCRIPTION
 The
-.Nm
+.Fn BUS_CONFIG_INTR
 method allows bus or device drivers to provide interrupt polarity and trigger
 mode to parent busses.
 This typically bubbles all the way up to the root bus (e.g.\& nexus) where the
 necessary actions are taken to actually program the hardware.
 Since the
-.Nm
+.Fn BUS_CONFIG_INTR
 method takes an interrupt number, it is assumed but not necessarily required
 that it is called prior to
 .Xr BUS_SETUP_INTR 9 .
 .Pp
 The
 .Fa trig
-argument can be one of
-.Bl -tag -width INTR_TRIGGER_CONFORM
+argument can be one of:
+.Bl -tag -width ".Dv INTR_TRIGGER_CONFORM"
 .It Dv INTR_TRIGGER_CONFORM
 The interrupt trigger mode is standard for the bus to which the device is
 attached.
@@ -63,7 +65,7 @@ attached.
 The interrupt is edge triggered.
 This means that the interrupt is raised by the rising edge of the signal on
 the interrupt line.
-The signal typically revert to the original state so as to cause a spike.
+The signal typically reverts to the original state so as to cause a spike.
 .Dv INTR_TRIGGER_LEVEL
 The interrupt is level triggered.
 This means that the interrupt is raised when the signal on the interrupt line
@@ -73,8 +75,8 @@ serviced, after which the signal transitions back.
 .Pp
 The
 .Fa pol
-argument can be any one of
-.Bl -tag -width INTR_POLARITY_CONFORM
+argument can be any one of:
+.Bl -tag -width ".Dv INTR_POLARITY_CONFORM"
 .It Dv INTR_POLARITY_CONFORM
 The interrupt polarity is standard for the bus to which the device is attached.
 .It Dv INTR_POLARITY_HIGH
@@ -94,11 +96,11 @@ Zero is returned on success, otherwise an appropriate error is returned.
 .\"
 .Sh HISTORY
 The
-.Nm
+.Fn BUS_CONFIG_INTR
 method first appeared in
 .Fx 5.2 .
 .\"
 .Sh AUTHORS
 This manual page was written by
 .An Marcel Moolenaar
-.Aq marcel@xcllnt.net
+.Aq marcel@xcllnt.net .

share/man/man9/VOP_LISTEXTATTR.9

@@ -1,7 +1,7 @@
 .\"-
 .\" Copyright (c) 2003 Network Associates Technology, Inc.
 .\" All rights reserved.
-
+.\"
 .\" This software was developed for the FreeBSD Project in part by Network
 .\" Associates Laboratories, the Security Research Division of Network
 .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"),
@@ -66,7 +66,10 @@ the location of the data to be read
 if not
 .Dv NULL ,
 on return it will contain the number of bytes required to read the list.
-The resulting data will be a ASCII nul-separated list of strings.
+The resulting data will be an
+.Tn ASCII
+.Dv NUL Ns
+-separated list of strings.
 In most cases
 .Fa uio
 will be
@@ -96,20 +99,24 @@ More information on extended attributes may be found in
 .Sh LOCKS
 The vnode will be locked on entry and should remain locked on return.
 .Sh RETURN VALUES
-On success, zero will be returned, and the uio structure will be updated to
+On success, zero will be returned, and the
+.Fa uio
+structure will be updated to
 reflect the list read.
 Otherwise, an appropriate error code is returned.
 .Sh ERRORS
 .Bl -tag -width Er
 .It Bq Er EACCES
-The the caller does not have the appropriate privilege.
+The caller does not have the appropriate privilege.
 .It Bq Er ENXIO
 The request was not valid in this file system for the specified vnode and
 attribute name.
 .It Bq Er ENOMEM
 Sufficient memory is not available to fulfill the request.
 .It Bq Er EFAULT
-The uio structure refers to an invalid userspace address.
+The
+.Fa uio
+structure refers to an invalid userspace address.
 .It Bq Er EINVAL
 The
 .Fa namespace

share/man/man9/alq.9

@@ -68,16 +68,16 @@ The logging facility runs in a separate kernel thread, which services
 all log entry requests.
 .Pp
 An
-.Dq asynchronous log entry ,
+.Dq asynchronous log entry
 is defined as
 .Vt "struct ale" ,
 which has the following members:
-.Bd -literal
-	struct ale {
-		struct ale	*ae_next;	/* Next Entry */
-		char		*ae_data;	/* Entry buffer */
-		int		ae_flags;	/* Entry flags */
-	};
+.Bd -literal -offset indent
+struct ale {
+	struct ale	*ae_next;	/* Next Entry */
+	char		*ae_data;	/* Entry buffer */
+	int		ae_flags;	/* Entry flags */
+};
 .Ed
 .Pp
 The
@@ -93,7 +93,7 @@ function creates a new logging queue.
 .Pp
 The
 .Fa file
-argument is the name of the file to open for logging,
+argument is the name of the file to open for logging.
 The size of each entry in the queue is determined by
 .Fa size .
 The
@@ -144,9 +144,9 @@ call is made.
 In the event that
 .Fn alq_get
 could not retrieve an entry immediately, it will
-.Xr tsleep 2
+.Xr tsleep 9
 with the
-.Dq alqget
+.Dq Li alqget
 wait message.
 .Pp
 The
@@ -205,7 +205,7 @@ was provided as a value to
 .Fa waitok
 and either the queue is full, or when the system is shutting down.
 .Pp
-NOTE, invalid arguments to non-void functions will result in
+NOTE: invalid arguments to non-void functions will result in
 undefined behaviour.
 .Sh SEE ALSO
 .Xr syslog 3 ,
@@ -216,7 +216,7 @@ undefined behaviour.
 .Sh HISTORY
 The
 Asynchronous Logging Queues (ALQ) facility first appeared in
-.Fx 5.0
+.Fx 5.0 .
 .Sh AUTHORS
 .An -nosplit
 The

share/man/man9/hexdump.9

@@ -33,45 +33,60 @@
 .Dt HEXDUMP 9
 .Sh NAME
 .Nm hexdump
-.Nd "Dump a block of bytes to the console in hexadecimal form"
+.Nd "dump a block of bytes to the console in hexadecimal form"
 .Sh SYNOPSIS
 .In sys/systm.h
 .Ft void
 .Fn hexdump "void *ptr" "int length" "const char *hdr" "int flags"
 .Sh DESCRIPTION
-Hexdump prints an array of bytes to the console in hexadecimal form, along with
-the ASCII representation of the bytes, if possible.
+The
+.Fn hexdump
+function prints an array of bytes to the console in hexadecimal form, along with
+the
+.Tn ASCII
+representation of the bytes, if possible.
 By default, each line of
 output will start with an offset count, followed by 16 hexadecimal values,
-followed by 16 ASCII characters.
-.Bl -tag -width 6n
+followed by 16
+.Tn ASCII
+characters.
+.Bl -tag -width indent
 .It Fa ptr
 Pointer to the array of bytes to print.
-It does not need to be NULL-terminated.
+It does not need to be
+.Dv NUL Ns
+-terminated.
 .It Fa length
-Number of bytes to print
+Number of bytes to print.
 .It Fa hdr
-Pointer to a NULL-terminated character string that will be prepended to each
+Pointer to a
+.Dv NUL Ns
+-terminated character string that will be prepended to each
 line of output.
-A value of NULL implies that no header will be printed.
+A value of
+.Dv NULL
+implies that no header will be printed.
 .It Fa flags
-Flags for controlling the formatting of the output
-.Bl -tag -width HD_OMIT_COUNT
-.It Fa Bits 0-7
+Flags for controlling the formatting of the output.
+.Bl -tag -width ".Dv HD_OMIT_COUNT"
+.It Bits 0-7
 Integer value of the number of bytes to display on each line.
 A value of 0 implies that the default value of 16 will be used.
-.It Fa Bits 8-15
-Character ASCII value to use as the separator for the hexadecimal output.
-A value of 0 implies that the default value of 32 (ASCII space) will be used.
-.It Fa HD_OMIT_COUNT
-Don't print the offset column at the beginning of each line
-.It Fa HD_OMIT_HEX
-Don't print the hexadecimal values on each line.
-.It Fa HD_OMIT_CHARS
-Don't print the character values on each line.
+.It Bits 8-15
+Character
+.Tn ASCII
+value to use as the separator for the hexadecimal output.
+A value of 0 implies that the default value of 32
+.Tn ( ASCII
+space) will be used.
+.It Dv HD_OMIT_COUNT
+Do not print the offset column at the beginning of each line.
+.It Dv HD_OMIT_HEX
+Do not print the hexadecimal values on each line.
+.It Dv HD_OMIT_CHARS
+Do not print the character values on each line.
 .El
 .El
-.Pp
 .Sh SEE ALSO
 .Xr ascii 7
 .Sh AUTHORS

share/man/man9/mbpool.9

@@ -23,25 +23,29 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" Author: Hartmut Brandt <harti@freebsd.org>
+.\" Author: Hartmut Brandt <harti@FreeBSD.org>
 .\"
 .\" $FreeBSD$
+.\"
 .Dd July 15, 2003
 .Dt MBPOOL 9
 .Os
 .Sh NAME
 .Nm mbpool
-.Nd Buffer pools for network interfaces
+.Nd "buffer pools for network interfaces"
 .Sh SYNOPSIS
 .In sys/types.h
 .In machine/bus.h
 .In sys/mbpool.h
-.Vt struct mbpool;
+.Vt struct mbpool ;
 .Ft int
-.Fn mbp_create "struct mbpool **mbp" "const char *name" "bus_dma_tag_t dmat" "u_int max_pages" "size_t page_size" "size_t chunk_size"
+.Fo mbp_create
+.Fa "struct mbpool **mbp" "const char *name" "bus_dma_tag_t dmat"
+.Fa "u_int max_pages" "size_t page_size" "size_t chunk_size"
+.Fc
 .Ft void
 .Fn mbp_destroy "struct mbpool *mbp"
-.Ft void *
+.Ft "void *"
 .Fn mbp_alloc "struct mbpool *mbp" "bus_addr_t *pa" "uint32_t *hp"
 .Ft void
 .Fn mbp_free "struct mbpool *mbp" "void *p"
@@ -51,19 +55,22 @@
 .Fn mbp_card_free "struct mbpool *mbp"
 .Ft void
 .Fn mbp_count "struct mbpool *mbp" "u_int *used" "u_int *card" "u_int *free"
-.Ft void *
+.Ft "void *"
 .Fn mbp_get "struct mbpool *mbp" "uint32_t h"
-.Ft void *
+.Ft "void *"
 .Fn mbp_get_keep "struct mbpool *mbp" "uint32_t h"
 .Ft void
-.Fn mbp_sync "struct mbpool *mbp" "uint32_t h" "bus_addr_t off" "bus_size_t len" "u_int op"
+.Fo mbp_sync
+.Fa "struct mbpool *mbp" "uint32_t h" "bus_addr_t off" "bus_size_t len"
+.Fa "u_int op"
+.Fc
 .Pp
 .Fn MODULE_DEPEND "your_module" "libmbpool" 1 1 1
 .Pp
-.Cd options LIBMBPOOL
+.Cd "options LIBMBPOOL"
 .Sh DESCRIPTION
 Mbuf pools are intended to help drivers for interface cards that need huge
-amounts of receive buffers and additionally provides a mapping between these
+amounts of receive buffers, and additionally provides a mapping between these
 buffers and 32-bit handles.
 .Pp
 An example of these cards are the Fore/Marconi ForeRunnerHE cards.
@@ -79,38 +86,41 @@ While for
 machines without an IOMMU and with lesser than 4GByte memory this is not
 a problem, for other machines this may quickly eat up all available IOMMU
 address space and/or bounce buffers.
-On the sparc64 the default IO page size
+On sparc64, the default I/O page size
 is 16k, so mapping a simple mbuf wastes 31/32 of the address space.
 .Pp
 Another problem with most of these cards is that they support putting a 32-bit
 handle into the buffer descriptor together with the physical address.
-This handle is reflected back to the driver when the buffer is filled and
+This handle is reflected back to the driver when the buffer is filled, and
 assists the driver in finding the buffer in host memory.
-For 32-bit machines
-usually the virtual address of the buffer is used as the handle.
+For 32-bit machines,
+the virtual address of the buffer is usually used as the handle.
 This does not
-work for 64-machines for obvious reasons so a mapping is needed between
+work for 64-bit machines for obvious reasons, so a mapping is needed between
 these handles and the buffers.
 This mapping should be possible without
 searching lists and the like.
 .Pp
 An mbuf pool overcomes both problems by allocating DMA-able memory page wise
 with a per-pool configurable page size.
-Each page is divided into a number
-equally-sized chunks the last
+Each page is divided into a number of
+equally-sized chunks, the last
 .Dv MBPOOL_TRAILER_SIZE
 of which are used by the pool code (4 bytes).
 The rest of each chunk is
-usable as buffer.
+usable as a buffer.
 There is a per-pool limit on pages that will be allocated.
 .Pp
-Additionally the code manages two flags for each buffer: on-card and used.
+Additionally, the code manages two flags for each buffer:
+.Dq on-card
+and
+.Dq used .
 A buffer may be in one of three states:
-.Bl -tag -width XXX
+.Bl -tag -width "on-card"
 .It free
-none of the flags is set.
+None of the flags is set.
 .It on-card
-both flags are set.
+Both flags are set.
 The buffer is assumed to be handed over to the card and
 waiting to be filled.
 .It used
@@ -122,26 +132,29 @@ A pool is created with
 This call specifies a DMA tag
 .Fa dmat
 to be used to create and map the memory pages via
-.Fn bus_dmamem_alloc .
+.Xr bus_dmamem_alloc 9 .
 The
 .Fa chunk_size
 includes the pool overhead.
-That means to get buffers for 5 ATM cells
-(240 bytes) a chunk size of 256 should be specified.
+It means that to get buffers for 5 ATM cells
+(240 bytes), a chunk size of 256 should be specified.
 This results in 12 unused
-bytes between the buffer and the pool overhead of four byte.
+bytes between the buffer, and the pool overhead of four byte.
 The total
 maximum number of buffers in a pool is
-.Fa max_pages *
-.Fa ( page_size /
+.Fa max_pages
+*
+.Fa ( page_size
+/
 .Fa chunk_size ) .
 The maximum value for
 .Fa max_pages
 is 2^14-1 (16383) and the maximum of
-.Fa page_size /
+.Fa page_size
+/
 .Fa chunk_size
 is 2^9 (512).
-If the call is successful a pointer to a newly allocated
+If the call is successful, a pointer to a newly allocated
 .Vt "struct mbpool"
 is set into the variable pointed to by
 .Fa mpb .
@@ -150,12 +163,12 @@ A pool is destroyed with
 .Fn mbp_destroy .
 This frees all pages and the pool structure itself.
 If compiled with
-.Dv DIAGNOSTICS
+.Dv DIAGNOSTICS ,
 the code checks that all buffers are free.
-If not a warning message is issued
+If not, a warning message is issued
 to the console.
 .Pp
-A buffer is allocate with
+A buffer is allocated with
 .Fn mbp_alloc .
 This returns the virtual address of the buffer and stores the physical
 address into the variable pointed to by
@@ -167,66 +180,85 @@ are unused by the pool code and may be used by the caller.
 These are
 automatically stripped when passing a handle to one of the other functions.
 If a buffer cannot be allocated (either because the maximum number of pages
-is reached, no memory is available or the memory cannot be mapped) NULL is
-returned.
-If a buffer could be allocated it is in the on-card state.
+is reached, no memory is available or the memory cannot be mapped),
+.Dv NULL
+is returned.
+If a buffer could be allocated, it is in the
+.Dq on-card
+state.
 .Pp
-When the buffer is returned by the card the driver calls
+When the buffer is returned by the card, the driver calls
 .Fn mbp_get
 with the handle.
 This function returns the virtual address of the buffer
-and clears the on-card bit.
-The buffer is now in the used state.
+and clears the
+.Dq on-card
+bit.
+The buffer is now in the
+.Dq used
+state.
 The function
 .Fn mbp_get_keep
 differs from
 .Fn mbp_get
-in that it does not clear the on-card bit.
+in that it does not clear the
+.Dq on-card
+bit.
 This can be used for buffers
 that are returned
-.Sq partially
+.Dq partially
 by the card.
 .Pp
 A buffer is freed by calling
 .Fn mbp_free
 with the virtual address of the buffer.
-This clears the used bit, and
+This clears the
+.Dq used
+bit, and
 puts the buffer on the free list of the pool.
-Note, that free buffers
+Note that free buffers
 are NOT returned to the system.
 The function
-.Fn mbp_ext_free can be given to
+.Fn mbp_ext_free
+can be given to
 .Fn m_extadd
 as the free function.
 The user argument must be the pointer to
 the pool.
 .Pp
-Before using the contents of a buffer returned by the card the driver
+Before using the contents of a buffer returned by the card, the driver
 must call
 .Fn mbp_sync
 with the appropriate parameters.
 This results in a call to
-.Fn bus_dmamap_sync
+.Xr bus_dmamap_sync 9
 for the buffer.
 .Pp
-All buffers in the pool that are currently in the on-card state can be freed
+All buffers in the pool that are currently in the
+.Dq on-card
+state can be freed
 with a call to
 .Fn mbp_card_free .
 This may be called by the driver when it stops the interface.
-Buffers in
-the used state are not freed by this call.
+Buffers in the
+.Dq used
+state are not freed by this call.
 .Pp
 For debugging it is possible to call
 .Fn mbp_count .
-This returns the number of buffers in the used and on-card states and
+This returns the number of buffers in the
+.Dq used
+and
+.Dq on-card
+states and
 the number of buffers on the free list.
 .Sh SEE ALSO
 .Xr mbuf 9
 .Sh CAVEATS
 The function
 .Fn mbp_sync
-is currently a NOP because
-.Fn bus_dmamap_sync
+is currently a no-op because
+.Xr bus_dmamap_sync 9
 is missing the offset and length parameters.
-.Sh AUTHOR
-.An Harti Brandt Aq harti@freebsd.org .
+.Sh AUTHORS
+.An Harti Brandt Aq harti@FreeBSD.org

share/man/man9/utopia.9

@@ -23,19 +23,24 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" Author: Hartmut Brandt <harti@freebsd.org>
+.\" Author: Hartmut Brandt <harti@FreeBSD.org>
 .\"
 .\" $FreeBSD$
+.\"
 .Dd May 8, 2003
 .Dt UTOPIA 9
 .Os
 .Sh NAME
 .Nm utopia
-.Nd Driver module for ATM PHY chips
+.Nd "driver module for ATM PHY chips"
 .Sh SYNOPSIS
 .In dev/utopia/utopia.h
 .Ft int
-.Fn utopia_attach "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media" "struct mtx *lock" "struct sysctl_ctx_list *ctx" "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab"
+.Fo utopia_attach
+.Fa "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media"
+.Fa "struct mtx *lock" "struct sysctl_ctx_list *ctx"
+.Fa "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab"
+.Fc
 .Ft void
 .Fn utopia_detach "struct utopia *utp"
 .Ft int
@@ -68,8 +73,8 @@ PHY chips to provide uniform functionality.
 The module implements status monitoring in either interrupt or polling mode,
 media option handling and application access to PHY registers.
 .Pp
-To use this interface a driver must implement two functions for reading and
-writing PHY registers and initialize the following structure with pointers
+To use this interface, a driver must implement two functions for reading and
+writing PHY registers, and initialize the following structure with pointers
 to these functions:
 .Bd -literal -offset indent
 struct utopia_methods {
@@ -87,10 +92,10 @@ function should read PHY registers starting at register
 The maximum number of registers to read is given by the integer pointed
 to by
 .Fa n .
-The function should either return 0 on success or an error code.
-In the first case
+The function should either return 0 on success, or an error code.
+In the first case,
 .Fa *n
-should be set to the actual number of registers red.
+should be set to the actual number of registers read.
 The
 .Fn writereg
 function should write one register.
@@ -98,9 +103,11 @@ It must change all bits for which the corresponding bit in
 .Fa mask
 is 1 to the value of the corresponding bit in
 .Fa val .
-It returns either 0 on success or an error code.
+It returns either 0 on success, or an error code.
 .Pp
-The ATM driver's private state block (softc) must begin with a
+The ATM driver's private state block
+.Pq Va softc
+must begin with a
 .Vt "struct ifatm" .
 .Pp
 The
@@ -122,12 +129,13 @@ struct utopia {
 };
 .Ed
 The public accessible fields have the following functions:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Va ifatm
-Pointer to the driver's private data (softc).
+Pointer to the driver's private data
+.Pq Va softc .
 .It Va media
 Pointer to the driver's media structure.
-.Ir Va lock
+.It Va lock
 Pointer to a mutex provided by the driver.
 This mutex is used to synchronize
 with the kernel thread that handles device polling.
@@ -139,12 +147,14 @@ In
 .Fn utopia_detach
 the mutex is locked to sleep and wait for the kernel thread to remove the
 .Vt "struct utopia"
-from the list of all utopia devices.
+from the list of all
+.Nm
+devices.
 Before returning to the caller the mutex is unlocked.
 .It
 In the
 .Nm
-kernel thread the mutex is locked and the
+kernel thread the mutex is locked, and the
 .Fn utopia_carrier_update
 function is called with this mutex locked.
 This will result in the driver's
@@ -158,26 +168,28 @@ or
 functions.
 .El
 .It Va flags
-Flags set by either the driver or the utopia module.
+Flags set by either the driver or the
+.Nm
+module.
 The following flags are
 defined:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Dv UTP_FL_NORESET
-If this flag is set the module will not try to write the
+If this flag is set, the module will not try to write the
 SUNI master reset register.
-(set by the driver)
+(Set by the driver.)
 .It Dv UTP_FL_POLL_CARRIER
-If this flag is set the module will periodically poll the carrier state
+If this flag is set, the module will periodically poll the carrier state
 (as opposed to interrupt driven carrier state changes).
-(set by the driver)
+(Set by the driver.)
 .El
 .It Va state
-Flags describing the current state of the phy chip.
+Flags describing the current state of the PHY chip.
 These are managed
 by the module:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Dv UTP_ST_ACTIVE
-The driver is active and the phy registers can be accessed.
+The driver is active and the PHY registers can be accessed.
 This is set by calling
 .Fn utopia_start ,
 which should be called either in the attach routine of the driver or
@@ -190,14 +202,15 @@ Interface is producing unassigned cells instead of idle cells.
 .It Dv UTP_ST_NOSCRAMB
 Cell scrambling is switched off.
 .It Dv UTP_ST_DETACH
-(internal use) interface is currently detaching.
+(Internal use.)
+Interface is currently detaching.
 .It Dv UTP_ST_ATTACHED
 The attach routine has been run successfully.
 .El
 .It Va carrier
 The carrier state of the interface.
 This field can have one of three values:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Dv UTP_CARR_UNKNOWN
 Carrier state is still unknown.
 .It Dv UTP_CARR_OK
@@ -207,12 +220,12 @@ Carrier has been lost.
 .El
 .It Va loopback
 This is the current loopback mode of the interface.
-Note, that not all
+Note that not all
 chips support all loopback modes.
 Refer to the chip documentation.
 The
 following modes may be supported:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Dv UTP_LOOP_NONE
 No loopback, normal operation.
 .It Dv UTP_LOOP_TIME
@@ -230,19 +243,20 @@ Twisted pair diagnostic loopback.
 Diagnostic path loopback.
 .El
 .It Va chip
-This points the a function vector for chip specific functions.
+This points to a function vector for chip specific functions.
 Two fields
 in this vector are publically available:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Va type
 This is the type of the detected PHY chip.
 One of:
-.Bl -tag -width XXX
-.It Dv UTP_TYPE_UNKNOWN (0)
-.It Dv UTP_TYPE_SUNI_LITE (1)
-.It Dv UTP_TYPE_SUNI_ULTRA (2)
-.It Dv UTP_TYPE_SUNI_622 (3)
-.It Dv UTP_TYPE_IDT77105 (4)
+.Pp
+.Bl -tag -width indent -compact
+.It Dv UTP_TYPE_UNKNOWN Pq No 0
+.It Dv UTP_TYPE_SUNI_LITE Pq No 1
+.It Dv UTP_TYPE_SUNI_ULTRA Pq No 2
+.It Dv UTP_TYPE_SUNI_622 Pq No 3
+.It Dv UTP_TYPE_IDT77105 Pq No 4
 .El
 .It Va name
 This is a string with the name of the PHY chip.
@@ -251,22 +265,27 @@ This is a string with the name of the PHY chip.
 .Pp
 The following functions are used by the driver during attach/detach and/or
 initialisation/stopping the interface:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Fn utopia_attach
 Attach the PHY chip.
 This is called with a preallocated
 .Vt "struct utopia"
-(which may be part of the driver's softc).
-The module initializes all fields of the utopia state and the media field.
+(which may be part of the driver's
+.Va softc ) .
+The module initializes all fields of the
+.Nm
+state and the media field.
 User settable flags should be set after the call to
 .Fn utopia_attach .
 This function may fail due to the inability to install the sysctl handlers.
-In this case it will return -1.
-On success 0 is returned and the
+In this case it will return \-1.
+On success, 0 is returned and the
 .Dv UTP_ST_ATTACHED
 flag is set.
 .It Fn utopia_detach
-Remove the utopia attachment from the system.
+Remove the
+.Nm
+attachment from the system.
 This cancels all outstanding polling
 timeouts.
 .It Fn utopia_start
@@ -290,45 +309,45 @@ This may be called to remove all media information from the ifmedia field.
 .Pp
 The following functions can be used to modify the PHY state while the interface
 is running:
-.Bl -tag -width XXX
+.Bl -tag -width indent
 .It Fn utopia_reset
 Reset the operational parameters to the default state (SONET, idle cells,
 scrambling enabled).
-Returns 0 on success, an error code otherwise leaving
+Returns 0 on success, an error code otherwise, leaving
 the state undefined.
 .It Fn utopia_set_sdh
 If the argument is zero the chip is switched to Sonet mode, if it is non-zero
 the chip is switched to SDH mode.
-Returns 0 on success, an error code otherwise
+Returns 0 on success, an error code otherwise,
 leaving the previous state.
 .It Fn utopia_set_unass
 If the argument is zero the chip is switched to produce idle cells, if it is
 non-zero the chip is switched to produce unassigned cells.
 Returns 0 on success,
-an error code otherwise leaving the previous state.
+an error code otherwise, leaving the previous state.
 .It Fn utopia_set_noscramb
 If the argument is zero enables scrambling, if it is
 non-zero disables scrambling.
 Returns 0 on success,
-an error code otherwise leaving the previous state.
+an error code otherwise, leaving the previous state.
 .It Fn utopia_update_carrier
 Check the carrier state and update the carrier field in the state structure.
-This will generate a message to the netgraph stack if the carrier state changes.
+This will generate a message to the Netgraph stack if the carrier state changes.
 For chips that are polled this is called automatically, for interrupt
 driven attachments this must be called on interrupts from the PHY chip.
 .It Fn utopia_set_loopback
 Set the loopback mode of the chip.
 Returns 0 on success, an error code
-otherwise leaving the previous state.
+otherwise, leaving the previous state.
 .It Fn utopia_intr
 Called when an interrupt from the PHY chip is detected.
 This resets the
 interrupt state by reading all registers and, if the interrupt was from the
 RSOP, checks the carrier state.
 .It Fn utopia_update_stats
-Update the statistics with counters red from the chip.
+Update the statistics with counters read from the chip.
 .El
 .Sh SEE ALSO
 .Xr utopia 4
-.Sh AUTHOR
-.An Harti Brandt Aq harti@freebsd.org .
+.Sh AUTHORS
+.An Harti Brandt Aq harti@FreeBSD.org