diff --git a/share/man/man9/BUS_ADD_CHILD.9 b/share/man/man9/BUS_ADD_CHILD.9 index c1bf9f7dfe0f..8a76d33ddafd 100644 --- a/share/man/man9/BUS_ADD_CHILD.9 +++ b/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 . diff --git a/share/man/man9/BUS_CONFIG_INTR.9 b/share/man/man9/BUS_CONFIG_INTR.9 index ccd90a04381d..90dc81f7be52 100644 --- a/share/man/man9/BUS_CONFIG_INTR.9 +++ b/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 . diff --git a/share/man/man9/VOP_LISTEXTATTR.9 b/share/man/man9/VOP_LISTEXTATTR.9 index b1fba71ef64f..cfb8e4e8ceb2 100644 --- a/share/man/man9/VOP_LISTEXTATTR.9 +++ b/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 diff --git a/share/man/man9/alq.9 b/share/man/man9/alq.9 index c42422f01ac0..bcea3ccb8cec 100644 --- a/share/man/man9/alq.9 +++ b/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 diff --git a/share/man/man9/hexdump.9 b/share/man/man9/hexdump.9 index 2d423095a2c8..2d044e6adeab 100644 --- a/share/man/man9/hexdump.9 +++ b/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 diff --git a/share/man/man9/mbpool.9 b/share/man/man9/mbpool.9 index 59746b72b584..b042973ac84d 100644 --- a/share/man/man9/mbpool.9 +++ b/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 +.\" Author: Hartmut Brandt .\" .\" $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 diff --git a/share/man/man9/utopia.9 b/share/man/man9/utopia.9 index 472699f8705e..61334ad20116 100644 --- a/share/man/man9/utopia.9 +++ b/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 +.\" Author: Hartmut Brandt .\" .\" $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