Sweep formatting and assorted fixes.
This commit is contained in:
Ruslan Ermilov
parent
ceba39a73b
commit
db79bbff16
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=131736
@ -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 .
|
||||
|
||||
@ -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 .
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user