Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

New sentence, new line.

Browse Source
This commit is contained in:
wiz 2002-10-14 13:43:14 +00:00
parent bb63fa7b1b
commit 770eef2122
85 changed files with 2997 additions and 2287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
share/man/man9/audio.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: audio.9,v 1.22 2002/06/04 14:09:34 isaki Exp $
.\" $NetBSD: audio.9,v 1.23 2002/10/14 13:43:14 wiz Exp $
.\"
.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -43,8 +43,8 @@
.Sh DESCRIPTION
The audio device driver is divided into a high level,
hardware independent layer, and a low level hardware
dependent layer. The interface between these is
the
dependent layer.
The interface between these is the
.Va audio_hw_if
structure.
.Bd -literal
@ -133,7 +133,8 @@ This call should be
.Pp
The
.Va audio_hw_if
struct is as shown above. The
struct is as shown above.
The
.Va hdl
argument is a handle to some low level data structure.
It is sent as the first argument to all the functions
@ -144,13 +145,13 @@ when the high level driver calls them.
is the device struct for the hardware device.
.Pp
The upper layer of the audio driver allocates one buffer for playing
and one for recording. It handles the buffering of data from the
user processes in these. The data is presented to the lower level
in smaller chunks, called blocks. If there, during playback, is
no data available from the user process when the hardware request
another block a block of silence will be used instead. Furthermore,
if the user process does not read data quickly enough during recording
data will be thrown away.
and one for recording.
It handles the buffering of data from the user processes in these.
The data is presented to the lower level in smaller chunks, called blocks.
If there, during playback, is no data available from the user process when
the hardware request another block a block of silence will be used instead.
Furthermore, if the user process does not read data quickly enough during
recording data will be thrown away.
.Pp
The fields of
.Va audio_hw_if
@ -158,8 +159,9 @@ are described in some more detail below.
Some fields are optional and can be set to 0 if not needed.
.Bl -tag -width indent
.It Dv int open(void *hdl, int flags)
is called when the audio device is opened. It should initialize
the hardware for I/O. Every successful call to
is called when the audio device is opened.
It should initialize the hardware for I/O.
Every successful call to
.Va open
is matched by a call to
.Va close .
@ -169,15 +171,17 @@ is called when the audio device is closed.
.It Dv int drain(void *hdl)
optional, is called before the device is closed or when
.Dv AUDIO_DRAIN
is called. It should make sure that no samples remain
in to be played that could be lost when
is called.
It should make sure that no samples remain in to be played that could
be lost when
.Va close
is called.
Return 0 on success, otherwise an error code.
.It Dv int query_encoding(void *hdl, struct audio_encoding *ae)
is used when
.Dv AUDIO_GETENC
is called. It should fill the
is called.
It should fill the
.Va audio_encoding
structure and return 0 or, if there is no encoding with the
given number, return EINVAL.
@ -193,7 +197,7 @@ and
flags to indicate which mode(s) are to be set.
.Va usemode
is also a combination of these flags, but indicates the current
mode of the device (i.e. the value of
mode of the device (i.e., the value of
.Va mode
in the
.Va audio_info
@ -229,11 +233,12 @@ to
and 16 to
.Va hw_precision .
The values of the structures may also be modified if the hardware
cannot be set to exactly the requested mode (e.g. if the requested
cannot be set to exactly the requested mode (e.g., if the requested
sampling rate is not supported, but one close enough is).
.Pp
The hardware driver can also request sampling rate conversion
and mono-stereo conversion. If
and mono-stereo conversion.
If
.Va set_params
sets to
.Va hw_sampling_rate
@ -248,7 +253,8 @@ and set
to
.Va hw_encoding ,
the hardware independent driver performs sampling rate and/or mono-stereo
conversion. If such conversion is not needed,
conversion.
If such conversion is not needed,
.Va set_params
must keep
.Va sampling_rate
@ -283,33 +289,34 @@ Return 0 on success, otherwise an error code.
.It Dv int round_blocksize(void *hdl, int bs)
optional, is called with the block size,
.Va bs ,
that has been computed by the upper layer. It should return
a block size, possibly changed according to the needs of the
hardware driver.
that has been computed by the upper layer.
It should return a block size, possibly changed according to the needs
of the hardware driver.
.It Dv int commit_settings(void *hdl)
optional, is called after all calls to
.Va set_params ,
and
.Va set_port ,
are done. A hardware driver that needs to get the hardware in
and out of command mode for each change can save all the changes
during previous calls and do them all here.
are done.
A hardware driver that needs to get the hardware in and out of command
mode for each change can save all the changes during previous calls and
do them all here.
Return 0 on success, otherwise an error code.
.It Dv int init_output(void *hdl, void *buffer, int size)
optional, is called before any output starts, but when the total
.Va size
of the output
.Va buffer
has been determined. It can be used to initialize looping DMA
for hardware that needs that.
has been determined.
It can be used to initialize looping DMA for hardware that needs that.
Return 0 on success, otherwise an error code.
.It Dv int init_input(void *hdl, void *buffer, int size)
optional, is called before any input starts, but when the total
.Va size
of the input
.Va buffer
has been determined. It can be used to initialize looping DMA
for hardware that needs that.
has been determined.
It can be used to initialize looping DMA for hardware that needs that.
Return 0 on success, otherwise an error code.
.It Dv int start_output(void *hdl, void *block, int blksize,
.Dv "void (*intr)(void*), void *intrarg)"
@ -318,9 +325,10 @@ is called to start the transfer of
.Va blksize
bytes from
.Va block
to the audio hardware. The call should return when the data
transfer has been initiated (normally with DMA). When the
hardware is ready to accept more samples the function
to the audio hardware.
The call should return when the data transfer has been initiated
(normally with DMA).
When the hardware is ready to accept more samples the function
.Va intr
should be called with the argument
.Va intrarg .
@ -336,9 +344,10 @@ is called to start the transfer of
.Va blksize
bytes to
.Va block
from the audio hardware. The call should return when the data
transfer has been initiated (normally with DMA). When the
hardware is ready to deliver more samples the function
from the audio hardware.
The call should return when the data transfer has been initiated
(normally with DMA).
When the hardware is ready to deliver more samples the function
.Va intr
should be called with the argument
.Va intrarg .
@ -359,7 +368,8 @@ in progress.
Return 0 on success, otherwise an error code.
.It Dv int speaker_ctl(void *hdl, int on)
optional, is called when a half duplex device changes between
playing and recording. It can, e.g., be used to turn on
playing and recording.
It can, e.g., be used to turn on
and off the speaker.
Return 0 on success, otherwise an error code.
.It Dv int getdev(void *hdl, struct audio_device *ret)
@ -375,27 +385,31 @@ Return 0 on success, otherwise an error code.
.It Dv int set_port(void *hdl, mixer_ctl_t *mc)
is called in when
.Dv AUDIO_MIXER_WRITE
is used. It should take data from the
is used.
It should take data from the
.Va mixer_ctl_t
struct at set the corresponding mixer values.
Return 0 on success, otherwise an error code.
.It Dv int get_port(void *hdl, mixer_ctl_t *mc)
is called in when
.Dv AUDIO_MIXER_READ
is used. It should fill the
is used.
It should fill the
.Va mixer_ctl_t
struct.
Return 0 on success, otherwise an error code.
.It Dv int query_devinfo(void *hdl, mixer_devinfo_t *di)
is called in when
.Dv AUDIO_MIXER_DEVINFO
is used. It should fill the
is used.
It should fill the
.Va mixer_devinfo_t
struct.
Return 0 on success, otherwise an error code.
.It Dv "void *allocm(void *hdl, int direction, size_t size, int type, int flags)"
.br
optional, is called to allocate the device buffers. If not present
optional, is called to allocate the device buffers.
If not present
.Xr malloc 9
is used instead (with the same arguments but the first two).
The reason for using a device dependent routine instead of
@ -410,8 +424,8 @@ If not supplied
is used.
.It Dv size_t round_buffersize(void *hdl, int direction, size_t bufsize)
optional, is called at startup to determine the audio
buffer size. The upper layer supplies the suggested
size in
buffer size.
The upper layer supplies the suggested size in
.Va bufsize ,
which the hardware driver can then change if needed.
E.g., DMA on the ISA bus cannot exceed 65536 bytes.
@ -428,7 +442,7 @@ mapped with protection
Returns -1 on failure, or a machine dependent opaque value
on success.
.It Dv int get_props(void *hdl)
Should return the device properties; i.e. a combination of
Should return the device properties; i.e., a combination of
AUDIO_PROP_xxx.
.It Dv int trigger_output(void *hdl, void *start, void *end,
.Dv "int blksize, void (*intr)(void*), void *intrarg,"
@ -443,8 +457,8 @@ and
to the audio hardware, parameterized as in
.Va param .
The call should return when the data transfer has been initiated
(normally with DMA). When the hardware is finished transferring
each
(normally with DMA).
When the hardware is finished transferring each
.Va blksize
sized block, the function
.Va intr
@ -467,8 +481,8 @@ to the circular buffer delimited by
and
.Va end .
The call should return when the data transfer has been initiated
(normally with DMA). When the hardware is finished transferring
each
(normally with DMA).
When the hardware is finished transferring each
.Va blksize
sized block, the function
.Va intr
@ -510,7 +524,7 @@ a control in the
class of type
.Dv AUDIO_MIXER_VALUE
if recording level of the source can be set.
If the overall recording level can be changed (i.e. regardless
If the overall recording level can be changed (i.e., regardless
of the input source) then this control should be named
.Dv AudioNrecord
and be of class
@ -532,7 +546,7 @@ a control in the
class of type
.Dv AUDIO_MIXER_VALUE
if output level of the destination can be set.
If the overall output level can be changed (i.e. regardless
If the overall output level can be changed (i.e., regardless
of the destination) then this control should be named
.Dv AudioNmaster
and be of class

6
share/man/man9/autoconf.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: autoconf.9,v 1.12 2002/10/13 00:52:50 wiz Exp $
.\" $NetBSD: autoconf.9,v 1.13 2002/10/14 13:43:15 wiz Exp $
.\"
.\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -205,11 +205,11 @@ function must return an integer value.
.Pp
Two special strings,
.Do
not configured
not configured
.Dc
and
.Do
unsupported
unsupported
.Dc
will be appended automatically to non-driver reports if the return
value is UNCONF or UNSUPP respectively; otherwise the function should

5
share/man/man9/bcopy.9
View File

@ -33,7 +33,7 @@
.\" SUCH DAMAGE.
.\"
.\" from: @(#)bcopy.3 8.1 (Berkeley) 6/4/93
.\" $NetBSD: bcopy.9,v 1.6 2002/02/13 08:18:36 ross Exp $
.\" $NetBSD: bcopy.9,v 1.7 2002/10/14 13:43:15 wiz Exp $
.\"
.Dd July 7, 2001
.Dt BCOPY 9
@ -80,7 +80,8 @@ In the traditional
.Bx
kernel, overlapping copies were handled by the now-purged
.Fn ovbcopy
function. If you need to copy overlapping data, see
function.
If you need to copy overlapping data, see
.Xr memmove 9 .
.Pp
If

5
share/man/man9/bufq.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: bufq.9,v 1.3 2002/07/23 14:00:17 hannken Exp $
.\" $NetBSD: bufq.9,v 1.4 2002/10/14 13:43:15 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -102,7 +102,8 @@ for reads with read priority
.It Fn bufq_alloc "bufq" "flags"
Initialize a
.Em bufq_state
descriptor. The argument
descriptor.
The argument
.Fa flags
controls the strategy and sort order.
.It Fn bufq_free "bufq"

191
share/man/man9/bus_dma.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: bus_dma.9,v 1.24 2002/06/12 15:27:55 wiz Exp $
.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $
.\"
.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -138,12 +138,13 @@ A pointer to a structure with at least the following members:
The structure may have machine-dependent members and arbitrary layout.
The
.Fa dm_mapsize
member indicates the size of the mapping. A value of 0 indicates the
mapping is invalid.
member indicates the size of the mapping.
A value of 0 indicates the mapping is invalid.
The
.Fa dm_segs
member may be an array of segments or a pointer to an
array of segments. The
array of segments.
The
.Fa dm_nsegs
member indicates the number of segments in
.Fa dm_segs .
@ -169,11 +170,14 @@ The maximum number of bytes that may be transferred by any given DMA
segment.
.It Fa boundary
Some DMA controllers are not able to transfer data that crosses a
particular boundary. This argument allows this boundary to be
specified. The boundary lines begin at 0, and occur every
particular boundary.
This argument allows this boundary to be specified.
The boundary lines begin at 0, and occur every
.Fa boundary
bytes. Mappings may begin on a boundary line but may not end on or
cross a boundary line. If no boundary condition needs to be observed, a
bytes.
Mappings may begin on a boundary line but may not end on or
cross a boundary line.
If no boundary condition needs to be observed, a
.Fa boundary
argument of 0 should be used.
.It Fa flags
@ -184,8 +188,8 @@ It is safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_NOWAIT
It is not safe to wait (sleep) for resources during this call.
.It Dv BUS_DMA_ALLOCNOW
Perform any resource allocation this handle may need now. If this is
not specified, the allocation may be deferred to
Perform any resource allocation this handle may need now.
If this is not specified, the allocation may be deferred to
.Fn bus_dmamap_load .
If this flag is specified,
.Fn bus_dmamap_load
@ -196,8 +200,8 @@ These flags are placeholders, and may be used by busses to provide
bus-dependent functionality.
.El
.It Fa dmamp
This is a pointer to a bus_dmamap_t. A DMA map will be allocated and
pointed to by
This is a pointer to a bus_dmamap_t.
A DMA map will be allocated and pointed to by
.Fa dmamp
upon successful completion of this routine.
.El
@ -207,8 +211,8 @@ Behavior is not defined if invalid arguments are passed to
.Pp
Returns 0 on success, or an error code to indicate mode of failure.
.It Fn bus_dmamap_destroy "tag" "dmam"
Frees all resources associated with a given DMA handle. Arguments are
as follows:
Frees all resources associated with a given DMA handle.
Arguments are as follows:
.Bl -tag -width dmam -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -228,8 +232,8 @@ If given valid arguments,
.Fn bus_dmamap_destroy
always succeeds.
.It Fn bus_dmamap_load "tag" "dmam" "buf" "buflen" "p" "flags"
Loads a DMA handle with mappings for a DMA transfer. It assumes that
all pages involved in a DMA transfer are wired.
Loads a DMA handle with mappings for a DMA transfer.
It assumes that all pages involved in a DMA transfer are wired.
Arguments are as follows:
.Bl -tag -width buflen -compact
.It Fa tag
@ -242,10 +246,11 @@ The buffer to be used for the DMA transfer.
.It Fa buflen
The size of the buffer.
.It Fa p
Used to indicate the address space in which the buffer is located. If
Used to indicate the address space in which the buffer is located.
If
.Dv NULL ,
the buffer is assumed to be in kernel space. Otherwise, the
buffer is assumed to be in process
the buffer is assumed to be in kernel space.
Otherwise, the buffer is assumed to be in process
.Fa p Ns 's
address space.
.It Fa flags
@ -259,8 +264,8 @@ It is not safe to wait (sleep) for resources during this call.
By default, the
.Nm
API assumes that there is coherency between memory and the device
performing the DMA transaction. Some platforms, however, have
special hardware, such as an
performing the DMA transaction.
Some platforms, however, have special hardware, such as an
.Dq I/O cache ,
which may improve performance
of some types of DMA transactions, but which break the assumption
@ -269,24 +274,25 @@ the DMA transaction.
This flag allows the use of this special hardware, provided that
the device is doing sequential, unidirectional transfers which
conform to certain alignment and size constraints defined by the
platform. If the platform does not support the feature, or if
the buffer being loaded into the DMA map does not conform to the
constraints required for use of the feature, then this flag will
be silently ignored. Also refer to the use of this flag with the
platform.
If the platform does not support the feature, or if the buffer being
loaded into the DMA map does not conform to the constraints required
for use of the feature, then this flag will be silently ignored.
Also refer to the use of this flag with the
.Fn bus_dmamem_alloc
function.
.It Dv BUS_DMA_READ
This is a hint to the machine-dependent back-end that indicates the
mapping will be used only for a
.Em "device -\*[Gt] memory"
transaction. The back-end may perform optimizations based on this
information.
transaction.
The back-end may perform optimizations based on this information.
.It Dv BUS_DMA_WRITE
This is a hint to the machine-dependent back-end that indicates the
mapping will be used only for a
.Em "memory -\*[Gt] device"
transaction. The back-end may perform optimizations based on this
information.
transaction.
The back-end may perform optimizations based on this information.
.It Dv BUS_DMA_BUS[1-4]
These flags are placeholders, and may be used by busses to
provide bus-dependent functionality.
@ -301,9 +307,9 @@ will never block.
If a call to
.Fn bus_dmamap_load
fails, the mapping in
the DMA handle will be invalid. It is the responsibility
of the caller to clean up any inconsistent device state
resulting from incomplete iteration through the uio.
the DMA handle will be invalid.
It is the responsibility of the caller to clean up any inconsistent
device state resulting from incomplete iteration through the uio.
.Pp
Behavior is not defined if invalid arguments are passed to
.Fn bus_dmamap_load .
@ -313,14 +319,15 @@ Returns 0 on success, or an error code to indicate mode of failure.
This is a variation of
.Fn bus_dmamap_load
which maps mbuf chains
for DMA transfers. Mbuf chains are assumed to be in kernel
virtual address space.
for DMA transfers.
Mbuf chains are assumed to be in kernel virtual address space.
.It Fn bus_dmamap_load_uio "tag" "dmam" "uio" "flags"
This is a variation of
.Fn bus_dmamap_load
which maps buffers pointed to by
.Fa uio
for DMA transfers. The value of
for DMA transfers.
The value of
.Fa "uio-\*[Gt]uio_segflg"
will
determine if the buffers are in user or kernel virtual address space.
@ -334,18 +341,21 @@ This is a variation of
which maps buffers
allocated by
.Fn bus_dmamem_alloc
(see below). The
(see below).
The
.Fa segs
argument is an array of bus_dma_segment_t's filled in
by
.Fn bus_dmamem_alloc .
The
.Fa nsegs
argument is the number of segments in the array. The
argument is the number of segments in the array.
The
.Fa size
argument is the size of the DMA transfer.
.It Fn bus_dmamap_unload "tag" "dmam"
Deletes the mappings for a given DMA handle. Arguments are as follows:
Deletes the mappings for a given DMA handle.
Arguments are as follows:
.Bl -tag -width dmam -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -367,8 +377,8 @@ on resources if the handle was created with
.Dv BUS_DMA_ALLOCNOW .
.Pp
.Fn bus_dmamap_unload
will not perform any implicit synchronization of DMA buffers. This
must be done explicitly by
will not perform any implicit synchronization of DMA buffers.
This must be done explicitly by
.Fn bus_dmamap_sync .
.Pp
Behavior is not defined if invalid arguments are passed to
@ -393,8 +403,8 @@ The length of the mapping from
.Fa offset
to synchronize.
.It Fa ops
One or more synchronization operation to perform. The following DMA
synchronization operations are defined:
One or more synchronization operation to perform.
The following DMA synchronization operations are defined:
.Bl -tag -width BUS_DMASYNC_POSTWRITE -compact
.It Dv BUS_DMASYNC_PREREAD
Perform any pre-read DMA cache and/or bounce operations.
@ -415,7 +425,7 @@ operations is not allowed, and behavior is undefined if this is attempted.
.El
.Pp
Synchronization operations are expressed from the perspective of
the host RAM, e.g. a
the host RAM, e.g., a
.Em "device -\*[Gt] memory"
operation is a
.Em READ
@ -426,10 +436,12 @@ operation is a
.Pp
.Fn bus_dmamap_sync
may consult state kept within the DMA map to determine if the memory
is mapped in a DMA coherent fashion. If so,
is mapped in a DMA coherent fashion.
If so,
.Fn bus_dmamap_sync
may elect to skip certain expensive operations, such as flushing
of the data cache. See
of the data cache.
See
.Fn bus_dmamem_map
for more information on this subject.
.Pp
@ -500,18 +512,18 @@ given tag.
The mapping of this memory is machine-dependent (or
"opaque"); machine-independent code is not to assume that the
addresses returned are valid in kernel virtual address space, or that
the addresses returned are system physical addresses. The address value
returned as part of
the addresses returned are system physical addresses.
The address value returned as part of
.Fa segs
can thus not be used to program DMA controller address registers. Only
the values in the
can thus not be used to program DMA controller address registers.
Only the values in the
.Fa dm_segs
array of a successfully loaded DMA map (using
.Fn bus_dmamap_load
) can be used for this purpose.
.Fn bus_dmamap_load )
can be used for this purpose.
.Pp
Allocations will always be rounded to the hardware page size. Callers
may wish to take advantage of this, and cluster allocation of small
Allocations will always be rounded to the hardware page size.
Callers may wish to take advantage of this, and cluster allocation of small
data structures.
Arguments are as follows:
.Bl -tag -width alignment -compact
@ -521,13 +533,15 @@ The is the bus_dma_tag_t passed down from the parent driver via
.It Fa size
The amount of memory to allocate.
.It Fa alignment
Each segment in the allocated memory will be aligned to this value. If
the alignment is less than a hardware page size, it will be rounded up
to the hardware page size. This value must be a power of two.
Each segment in the allocated memory will be aligned to this value.
If the alignment is less than a hardware page size, it will be rounded up
to the hardware page size.
This value must be a power of two.
.It Fa boundary
Each segment in the allocated memory must not cross this boundary
(relative to zero). This value must be a power of two. A boundary
value less than the size of the allocation is invalid.
(relative to zero).
This value must be a power of two.
A boundary value less than the size of the allocation is invalid.
.It Fa segs
An array of bus_dma_segment_t's, filled in as memory is allocated,
representing the opaque addresses of the memory chunks.
@ -551,11 +565,13 @@ to conform to the platform-dependent requirements for the use of the
.Dv BUS_DMA_STREAMING
flag with the
.Fn bus_dmamap_load
function. If the platform does not support the
function.
If the platform does not support the
.Dv BUS_DMA_STREAMING
feature, or if the size, alignment, and boundary constraints
would already satisfy the platform's requirements, this flag
is silently ignored. The
is silently ignored.
The
.Dv BUS_DMA_STREAMING
flag will never relax the constraints specified in the call.
.It Dv BUS_DMA_BUS[1-4]
@ -578,7 +594,8 @@ Returns 0 on success, or an error code indicating mode of failure.
Frees memory previously allocated by
.Fn bus_dmamem_alloc .
Any mappings
will be invalidated. Arguments are as follows:
will be invalidated.
Arguments are as follows:
.Bl -tag -width nsegs -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -600,7 +617,8 @@ always succeeds.
.It Fn bus_dmamem_map "tag" "segs" "nsegs" "size" "kvap" "flags"
Maps memory allocated with
.Fn bus_dmamem_alloc
into kernel virtual address space. Arguments are as follows:
into kernel virtual address space.
Arguments are as follows:
.Bl -tag -width flags -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -629,31 +647,34 @@ bus-dependent functionality.
.It Dv BUS_DMA_COHERENT
This flag is a
.Em hint
to machine-dependent code. If possible, map the memory in such a way
as it will be DMA coherent. This may include mapping the pages into
uncached address space or setting the cache-inhibit bits in page table
entries. If DMA coherent mappings are impossible, this flag is
silently ignored.
to machine-dependent code.
If possible, map the memory in such a way as it will be DMA coherent.
This may include mapping the pages into uncached address space or
setting the cache-inhibit bits in page table entries.
If DMA coherent mappings are impossible, this flag is silently ignored.
.Pp
Later, when this memory is loaded into a DMA map, machine-dependent code
will take whatever steps are necessary to determine if the memory was
mapped in a DMA coherent fashion. This may include checking if the
kernel virtual address lies within uncached address space or if the
cache-inhibit bits are set in page table entries. If it is determined
that the mapping is DMA coherent, state may be placed into the DMA map
for use by later calls to
mapped in a DMA coherent fashion.
This may include checking if the kernel virtual address lies within
uncached address space or if the cache-inhibit bits are set in page
table entries.
If it is determined that the mapping is DMA coherent, state may be
placed into the DMA map for use by later calls to
.Fn bus_dmamap_sync .
.Pp
Note that a device driver must not rely on
.Dv BUS_DMA_COHERENT
for correct operation. All calls to
for correct operation.
All calls to
.Fn bus_dmamap_sync
must still be made. This flag is provided only as an optimization
hint to machine-dependent code.
must still be made.
This flag is provided only as an optimization hint to machine-dependent code.
.Pp
Also note that this flag only applies to coherency between the CPU
and memory. Coherency between memory and the device is controlled
with a different flag. See the description of the
and memory.
Coherency between memory and the device is controlled with a different flag.
See the description of the
.Fn bus_dmamap_load
function.
.El
@ -667,8 +688,8 @@ Returns 0 on success, or an error code indicating mode of failure.
Unmaps memory previously mapped with
.Fn bus_dmamem_map ,
freeing the
kernel virtual address space used by the mapping. The arguments are as
follows:
kernel virtual address space used by the mapping.
The arguments are as follows:
.Bl -tag -width size -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -688,10 +709,10 @@ always succeeds.
.It Fn bus_dmamem_mmap "tag" "segs" "nsegs" "off" "prot" "flags"
Provides support for user
.Xr mmap 2 Ns 'ing
of DMA-safe memory. This function is to be called by a device
driver's (*d_mmap)() entry point, which is called by the
device pager for each page to be mapped. The arguments are
as follows:
of DMA-safe memory.
This function is to be called by a device driver's (*d_mmap)() entry
point, which is called by the device pager for each page to be mapped.
The arguments are as follows:
.Bl -tag -width nsegs -compact
.It Fa tag
This is the bus_dma_tag_t passed down from the parent driver via
@ -730,8 +751,8 @@ Behavior is undefined if invalid arguments are passed
to
.Fn bus_dmamem_mmap .
.Pp
Returns -1 to indicate failure. Otherwise, returns an opaque
value to be interpreted by the device pager.
Returns -1 to indicate failure.
Otherwise, returns an opaque value to be interpreted by the device pager.
.El
.Sh SEE ALSO
.Xr bus_space 9

585
share/man/man9/bus_space.9
View File

File diff suppressed because it is too large Load Diff

32
share/man/man9/callout.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: callout.9,v 1.6 2002/02/13 08:18:38 ross Exp $
.\" $NetBSD: callout.9,v 1.7 2002/10/14 13:43:16 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -65,7 +65,8 @@ The
facility provides a mechanism to execute a function at a given time.
The timer is based on the hardclock timer which ticks
.Dv hz
times per second. The function is called at softclock interrupt level.
times per second.
The function is called at softclock interrupt level.
.Pp
Clients of the
.Nm callout
@ -85,7 +86,8 @@ The
.Fn callout_init
function initializes the callout handle
.Fa c
for use. If it is inconvenient to call
for use.
If it is inconvenient to call
.Fn callout_init ,
statically-allocated callout handles may be initialized by assigning
the value
@ -110,7 +112,8 @@ and
.Em PENDING .
Once the timer expires,
.Em PENDING
status is cleared. Expiration of the timer does not affect
status is cleared.
Expiration of the timer does not affect
.Em ACTIVE
status.
.Pp
@ -122,7 +125,8 @@ The
.Em ACTIVE
and
.Em PENDING
status for the callout handle is cleared. It is safe to call
status for the callout handle is cleared.
It is safe to call
.Fn callout_stop
on a callout handle that is not active, so long as it is initialized.
.Pp
@ -137,10 +141,11 @@ An
callout is one that has been started but not explicitly stopped.
Testing
.Em ACTIVE
status is a way to determine if a callout has been started. Once the
callout fires, the executed function may clear
status is a way to determine if a callout has been started.
Once the callout fires, the executed function may clear
.Em ACTIVE
status. See
status.
See
.Fn callout_deactivate
below.
.Pp
@ -153,10 +158,11 @@ status of the callout handle
A
.Em PENDING
callout is one that has been started and whose function has not yet
been called. Note that it is possible for a callout's timer to have
expired without its function being called if interrupt level has not
dropped low enough to let softclock interrupts through. Note that it
is only safe to test
been called.
Note that it is possible for a callout's timer to have expired without
its function being called if interrupt level has not dropped low enough
to let softclock interrupts through.
Note that it is only safe to test
.Em PENDING
status when at softclock interrupt level or higher.
.Pp
@ -176,7 +182,7 @@ status of the callout handle
.Fa c .
Note that is only safe to call
.Fn callout_deactivate
if the callout function has already been executed, i.e. the callout
if the callout function has already been executed, i.e., the callout
is no longer
.Em PENDING .
.Sh SEE ALSO

65
share/man/man9/cardbus.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cardbus.9,v 1.5 2002/02/13 08:18:38 ross Exp $
.\" $NetBSD: cardbus.9,v 1.6 2002/10/14 13:43:17 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -147,12 +147,13 @@ It introduces several new capabilities such as 32-bit addressing,
It remains compatible with all features of the PC-Card standard.
.Pp
The Cardbus interface signaling protocol is derived from the PCI
signaling protocol. There are some differences between PCI and
Cardbus, however operations are identical for most functions
implemented. Since a 32-bit Cardbus interface is also defined for
16-bit PC-Cards, the same Card Services client to be used to manage
both Cardbus and PCMCIA PC-Cards. By interrogating the card upon
detection of an insertion event,
signaling protocol.
There are some differences between PCI and Cardbus, however operations
are identical for most functions implemented.
Since a 32-bit Cardbus interface is also defined for 16-bit PC-Cards,
the same Card Services client to be used to manage both Cardbus and
PCMCIA PC-Cards.
By interrogating the card upon detection of an insertion event,
.Nx
determines whether the card requires
.Nm
@ -163,8 +164,8 @@ Drivers attached to the Cardbus bus will make use of the following
data types:
.Bl -tag -width compact
.It struct cardbus_attach_args
Devices have their identity recorded in this structure. It contains
the following members:
Devices have their identity recorded in this structure.
It contains the following members:
.Bd -literal
cardbus_devfunc_t ca_ct;
bus_space_tag_t ca_iot; /* Cardbus I/O space tag */
@ -182,21 +183,23 @@ the following members:
.Bl -tag -width compact
.It Fn cardbus_attach_card "csc"
Attaches the card on the slot by turning on the power, read and
analyse the tuple and sets configuration index. This function returns
the number of recognised device functions. If no device functions are
recognised it returns zero.
analyse the tuple and sets configuration index.
This function returns the number of recognised device functions.
If no device functions are recognised it returns zero.
.It Fn cardbus_detach_card "csc"
Detaches the card on the slot by release resources and turning off the
power. This function must not be called under interrupt context.
power.
This function must not be called under interrupt context.
.It Fn cardbus_function_enable "csc" "function"
Enables device function
.Fa function
on the card. Power will be applied if it hasn't already.
on the card.
Power will be applied if it hasn't already.
.It Fn cardbus_function_disable "csc" "function"
Disables device function
.Fa function
on the card. When no device functions are enabled, the turn is turned
off.
on the card.
When no device functions are enabled, the turn is turned off.
.It Fo cardbus_mapreg_map
.Fa "csc" "cf" "reg" "type" "busflags"
.Fa "tagp" "handlep" "basep" "sizep"
@ -231,18 +234,20 @@ Returns the capability in
and
.Fa valuep .
.It Fn cardbus_make_tag "cc" "cf" "bus" "device" "function"
Make a tag to access config space of a Cardbus card. It works the
same as
Make a tag to access config space of a Cardbus card.
It works the same as
.Fn pci_make_tag .
.It Fn cardbus_free_tag "cc" "cf" "tag"
Release a tag used to access the config space of a Cardbus card. It
works the same as
Release a tag used to access the config space of a Cardbus card.
It works the same as
.Fn pci_free_tag .
.It Fn cardbus_conf_read "cc" "cf" "tag" "offs"
Read the config space of a Cardbus card. It works the same as
Read the config space of a Cardbus card.
It works the same as
.Fn pci_conf_read .
.It Fn cardbus_conf_write "cc" "cf" "tag" "offs" "val"
Write to the config space of a Cardbus card. It works same as
Write to the config space of a Cardbus card.
It works same as
.Fn pci_conf_write .
.It Fn cardbus_intr_establish "cc" "cf" "irq" "level" "handler" "arg"
Establish an interrupt handler for device function
@ -283,8 +288,8 @@ During autoconfiguration, a
.Nm
driver will receive a pointer to
.Fa struct isapnp_attach_args
describing the device attaches to the Cardbus bus. Drivers match the
device using the
describing the device attaches to the Cardbus bus.
Drivers match the device using the
.Fa ca_id
member using
.Fn CARDBUS_VENDOR
@ -301,8 +306,8 @@ applied to the device with
.Fn cardbus_function_enable
or
.Fn Cardbus_function_enable .
so that device-specific interrogation can be performed. Finally,
power should be removed from the device using
so that device-specific interrogation can be performed.
Finally, power should be removed from the device using
.Fn cardbus_function_disable
or
.Fn Cardbus_function_disable .
@ -321,8 +326,8 @@ interface.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent Cardbus subsystem can be found. All pathnames are
relative to
machine-independent Cardbus subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The Cardbus subsystem itself is implemented within the files
@ -334,8 +339,8 @@ The database of known devices exists within the file
.Pa sys/dev/cardbus/cardbus_data.h
and is generated automatically from the file
.Pa sys/dev/cardbus/cardbusdevs .
New vendor and product identifiers should be added to this
file. The database can be regenerated using the Makefile
New vendor and product identifiers should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/cardbus/Makefile.cardbusdevs .
.Sh SEE ALSO
.Xr cardbus 4 ,

40
share/man/man9/cnmagic.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cnmagic.9,v 1.8 2002/02/13 08:18:38 ross Exp $
.\" $NetBSD: cnmagic.9,v 1.9 2002/10/14 13:43:17 wiz Exp $
.\"
.\" Copyright (c) 2000 Eduardo Horvath
.\" All rights reserved.
@ -69,11 +69,12 @@ flexible methods to set, change, and detect magic key sequences on console
devices and break into the debugger or ROM monitor with a minimum of interrupt
latency.
.Pp
Drivers that generate console input should make use of these routines. A
different
Drivers that generate console input should make use of these routines.
A different
.Va cnm_state_t
should be used for each separate input stream. Multiple devices that share
the same input stream, such as USB keyboards can share the same
should be used for each separate input stream.
Multiple devices that share the same input stream, such as USB
keyboards can share the same
.Va cnm_state_t .
Once a
.Va cnm_state_t
@ -84,8 +85,8 @@ so it can be used by
If a driver thinks it might be the console input device it can set the
magic sequence with
.Fn cn_set_magic
to any arbitrary string. Whenever the driver receives input,
it should call
to any arbitrary string.
Whenever the driver receives input, it should call
.Fn cn_check_magic
to process the data and determine whether the magic sequence has
been hit.
@ -93,7 +94,8 @@ been hit.
The magic key sequence can be accessed through the
.Va hw.cnmagic
.Ic sysctl
variable. This is the raw data and may be keycodes rather than
variable.
This is the raw data and may be keycodes rather than
processed characters, depending on the console device.
.Pp
Here is a description of the console magic interface:
@ -105,15 +107,16 @@ Initialize the console magic state pointed to by
to a usable state.
.It Fn "void cnm_trap"
.Pp
Trap into the kernel debugger or ROM monitor. By default this
routine is defined to be
Trap into the kernel debugger or ROM monitor.
By default this routine is defined to be
.Fn console_debugger
but can be overridden in MI header files.
.It Fn "int cn_isconsole" "dev_t dev"
.Pp
Determine whether a given
.Fa dev
is the system console. This macro tests to see if
is the system console.
This macro tests to see if
.Fa dev
is the same as
.Va cn_tab-\*[Gt]cn_dev
@ -128,13 +131,14 @@ calls
.Fn cn_isconsole
with
.Fa dev
to determine if this is the console. If that returns true then
it runs the input value
to determine if this is the console.
If that returns true then it runs the input value
.Fa k
through the state machine. If the state machine completes a match
of the current console magic sequence
through the state machine.
If the state machine completes a match of the current console magic sequence
.Fn cn_trap
is called. Some input may need to be translated to state machine
is called.
Some input may need to be translated to state machine
values such as the serial line
.Li BREAK
sequence.
@ -148,8 +152,8 @@ points to is no longer needed.
encodes a
.Li nul
terminated string arbitrary string into values that can be used by
the state machine and installs it as the global magic sequence. The
escape sequence is character value
the state machine and installs it as the global magic sequence.
The escape sequence is character value
.Li 0x27
and can be used to encode special values:
.Pp

137
share/man/man9/config.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: config.9,v 1.8 2002/09/06 15:44:45 wiz Exp $
.\" $NetBSD: config.9,v 1.9 2002/10/14 13:43:17 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -50,7 +50,8 @@ In
the
.Xr config 8
program reads and verifies a machine description file specifying the
devices to include in the kernel. A table is produced by
devices to include in the kernel.
A table is produced by
.Xr config 8
which is used by the kernel during autoconfiguration (see
.Xr autoconf 9 )
@ -61,34 +62,39 @@ Each device in the machine description file has:
.Bl -tag -width xxxxxx
.It A Name
The name is simply an alphanumeric string that ends in a unit number
(eg. "sd0", "sd1", and so forth). These unit numbers identify
particular instances of a base device name; the base name in turn maps
directly to a device driver. Device unit numbers are independent of
hardware features.
(e.g., "sd0", "sd1", and so forth).
These unit numbers identify particular instances of a base device name;
the base name in turn maps directly to a device driver.
Device unit numbers are independent of hardware features.
.It A Parent
Every device must have a parent. The pairing is denoted by "child at
parent". These pairings form the links in a directed graph. The root
device is the only exception, as it does not have a parent.
Every device must have a parent.
The pairing is denoted by "child at parent".
These pairings form the links in a directed graph.
The root device is the only exception, as it does not have a parent.
.It Locators
Locators are used to augment the parent/child pairings the locate
specific devices. Each locator value is simply an integer that
represents some sort of device address on the parent bus or
controller. This can be a memory address, and I/O port, a driver
number, or any other value. Locators can sometimes be wildcarded on
devices that support direct connection.
specific devices.
Each locator value is simply an integer that represents some sort of
device address on the parent bus or controller.
This can be a memory address, and I/O port, a driver number, or any
other value.
Locators can sometimes be wildcarded on devices that support direct
connection.
.It Attributes
An attribute describes the device's relationship with the code; it
then serves to constrain the device graph. A
then serves to constrain the device graph.
A
.Em plain attribute
describes some attribute of a device. An
describes some attribute of a device.
An
.Em interface attribute
describes a kind of
.Do
software interface
.Dc
and declares the devices's ability to support other devices that use
that interface. In addition, an interface attribute usually identifies
additional locators.
that interface.
In addition, an interface attribute usually identifies additional locators.
.El
.Pp
During autoconfiguration, the directed graph is turned into a tree by
@ -97,11 +103,13 @@ devices by doing a depth-first traversal through the graph starting at
this root node.
.Pp
However, there must be constraints on the parent/child pairings that
are possible. These constraints are embedded in the
are possible.
These constraints are embedded in the
.Do
device definition
.Dc
files. The remainder of this page describes the
files.
The remainder of this page describes the
.Do
device definition
.Dc
@ -110,29 +118,33 @@ language and how to use this language to add new functionality to the
kernel.
.Sh DEVICE DEFINITION FILES
The device definition files are separated into machine-dependent and
machine-independent files. The machine-dependent file is located in
machine-independent files.
The machine-dependent file is located in
.Pa sys/arch/\*[Lt]arch\*[Gt]/conf/files.\*[Lt]arch\*[Gt] ,
where \*[Lt]arch\*[Gt] is the name of
.Nx
architecture. The machine-independent file is located in
architecture.
The machine-independent file is located in
.Pa sys/conf/files .
It in turn includes files for the machine-independent drivers located
in
.Pa sys/dev/\*[Lt]bus\*[Gt]/files.\*[Lt]bus\*[Gt] ,
where \*[Lt]bus\*[Gt] is the name of the machine-independent bus.
.Pp
These files define all legal devices and pseudo-devices. They also
define all attributes and interfaces, establishing the rules that
These files define all legal devices and pseudo-devices.
They also define all attributes and interfaces, establishing the rules that
determine allowable machine descriptions, and list the source files
that make up the kernel.
.Pp
Each device definition file consists of a list of statements,
typically one per line. Comments may be inserted anywhere using the
typically one per line.
Comments may be inserted anywhere using the
.Do
#
.Dc
character, and any line that begins with white space continues the
previous line. Valid statements are:
previous line.
Valid statements are:
.Bl -tag -width xxxxxx
.It defflag [filename] {options}
The space-separated list of pre-processor macros
@ -142,9 +154,9 @@ are defined in file
This statement permits ``options FOO'' for FOO (i.e, without a value)
in the machine description file.
.Xr config 8
will generate an error if a value is given. If the filename field is
not specified, the options are defined on the commandline invocation
of
will generate an error if a value is given.
If the filename field is not specified, the options are defined on
the commandline invocation of
.Xr make 1 .
The
.Em option
@ -157,9 +169,9 @@ are defined in file
This statement permits ``options FOO=bar'' or ``option FOO="\\"com\\""''
in the machine description file.
.Xr config 8
will generate an error if a value is not given. If the filename field
is not specified, the options are defined on the commandline
invocation of
will generate an error if a value is not given.
If the filename field is not specified, the options are defined on
the commandline invocation of
.Xr make 1 .
The
.Em option
@ -173,10 +185,11 @@ This statement permits the syntax of either the defflag and defparam
statements and
.Xr config 8
does not perform any checking of whether ``options FOO'' takes a
value. Therefore, the use of the defopt statement is deprecated in
favour of the defflag and defparam statements. If the filename field
is not specified, the options are defined on the commandline
invocation of
value.
Therefore, the use of the defopt statement is deprecated in
favour of the defflag and defparam statements.
If the filename field is not specified, the options are defined on
the commandline invocation of
.Xr make 1 .
The
.Em option
@ -191,8 +204,8 @@ A device class is similar to an attribute.
.It define name [{locators}]
The attribute
.Em name
is defined and device definitions can then refer to it. If the
attribute is an interface attribute and defines optional
is defined and device definitions can then refer to it.
If the attribute is an interface attribute and defines optional
.Em locators ,
device attributes that refer to
.Em name
@ -224,31 +237,33 @@ define attribute dependencies.
.It defpseudo name: [{locators}]
The pseudo-device
.Em name
is defined. The optional
is defined.
The optional
.Em locators
may be defined, but are largely pointless since no device can attach
to a pseudo-device.
.It file pathname [attributes [flags]] [rule]
The file
.Em pathname
is added to the list of files used to build the kernel. If no
attributes are specified, the file is always added to the kernel
compilation. If any of the attributes are specified by other devices
in the machine descripton file, then the file is included in
compilation, otherwise it is omitted. Valid values for the optional
flags are:
is added to the list of files used to build the kernel.
If no attributes are specified, the file is always added to the kernel
compilation.
If any of the attributes are specified by other devices in the machine
descripton file, then the file is included in compilation, otherwise it
is omitted.
Valid values for the optional flags are:
.Bl -tag -width xxxxxx
.It needs-count
Specify that config should generate a file for each of the attributes
notifying the driver how many of some particular device or set of
devices are configured in the kernel. This flag
allows drivers to make calculations of driver used at compile time.
devices are configured in the kernel.
This flag allows drivers to make calculations of driver used at compile time.
This option prevents autoconfiguration cloning.
.It needs-flag
This flag performs the same operation as
.Em needs-count
but only records if the number is nonzero. Since the count is not
exact,
but only records if the number is nonzero.
Since the count is not exact,
.Em needs-flag
does not prevent autoconfiguration cloning.
.El
@ -256,26 +271,28 @@ does not prevent autoconfiguration cloning.
The character device switch
.Em name
associated with a character major device number is added to the list of
device switches used to build the kernel. If
device switches used to build the kernel.
If
.Em block
is specified, the block device switch associated with a block major device
number is also added. If all of attributes are specified by devices in the
machine description files, then device switches are added into the device
switches' table of the kernel in compilation, otherwise they are omitted.
number is also added.
If all of attributes are specified by devices in the machine description
files, then device switches are added into the device switches' table of
the kernel in compilation, otherwise they are omitted.
.El
.Pp
To allow locators to be wildcarded in the machine description file,
their default value must be defined in the attribute definition. To
allow locators to be omitted entirely in the machine description file,
enclose the locator in square brackets. This can be used when some
locators do not make sense for some devices, but the software
interface requires them.
their default value must be defined in the attribute definition.
To allow locators to be omitted entirely in the machine description file,
enclose the locator in square brackets.
This can be used when some locators do not make sense for some devices,
but the software interface requires them.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
autoconfiguration framework can be found. All pathnames are relative
to
autoconfiguration framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The device definition files are in

25
share/man/man9/cons.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cons.9,v 1.7 2002/09/20 03:35:33 uebayasi Exp $
.\" $NetBSD: cons.9,v 1.8 2002/10/14 13:43:18 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -54,8 +54,8 @@
.Ft void
.Fn cnputc "int c"
.Sh DESCRIPTION
These functions operate over current console device. The console has
to be initialized first, before these functions could be used.
These functions operate over current console device.
The console has to be initialized first, before these functions could be used.
.Pp
Console input polling functions
.Fn cngetc ,
@ -63,9 +63,9 @@ Console input polling functions
and
.Fn cnpollc
are only to be used during initial system
boot, e.g. when asking for root and dump device or to get
necessary user input within mountroothooks. Once the system
boots, user input is read via standard
boot, e.g., when asking for root and dump device or to get
necessary user input within mountroothooks.
Once the system boots, user input is read via standard
.Xr tty 4
facilities.
.Pp
@ -92,16 +92,18 @@ could be used.
should be used during kernel startup only.
.It Fn cngetsn
Read one line of user input, stop reading once the newline
key is input. Input is echoed back. This
uses
key is input.
Input is echoed back.
This uses
.Fn cnpollc
and
.Fn cngetc .
Number of read characters is
.Fa size
at maximum, user is notified by console bell when the end
of input buffer is reached. \*[Lt]Backspace\*[Gt] key
works as expected. \*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make
of input buffer is reached.
\*[Lt]Backspace\*[Gt] key works as expected.
\*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make
.Fn cngetsn
discard input read so far, print newline and
wait for next input.
@ -123,7 +125,8 @@ is zero.
.Fn cnpollc
should be used during kernel startup only.
.It Fn cnputc
Console kernel output character routine. Commonly, kernel code uses
Console kernel output character routine.
Commonly, kernel code uses
.Xr printf 9
rather than using this low-level interface.
.El

8
share/man/man9/copy.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: copy.9,v 1.12 2002/07/20 03:58:26 thorpej Exp $
.\" $NetBSD: copy.9,v 1.13 2002/10/14 13:43:18 wiz Exp $
.\"
.\" Copyright (c) 1996, 2002 Jason R. Thorpe.
.\" All rights reserved.
@ -64,7 +64,8 @@
The
.Nm
functions are designed to copy contiguous data from one address
to another. All but
to another.
All but
.Fn copystr
copy data from user-space to kernel-space or vice-versa.
.Pp
@ -120,7 +121,8 @@ bytes long, from kernel-space address
.Fa kaddr
to user-space address
.Fa uaddr
in the current process. If the
in the current process.
If the
.Fa done
argument is non-NULL,
the number of bytes actually copied, including the terminating

9
share/man/man9/cpu_configure.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_configure.9,v 1.2 2002/05/25 11:08:21 wiz Exp $
.\" $NetBSD: cpu_configure.9,v 1.3 2002/10/14 13:43:18 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -47,9 +47,10 @@
.Sh DESCRIPTION
.Fn cpu_configure
is called during system bootstrap to perform the machine-dependent
portion of device autoconfiguration. It sets the configuration
machinery in motion by finding the root bus ("mainbus"). When this
function returns, interrupts must be enabled.
portion of device autoconfiguration.
It sets the configuration machinery in motion by finding the root
bus ("mainbus").
When this function returns, interrupts must be enabled.
.Pp
.Fn cpu_configure
performs the following tasks:

9
share/man/man9/cpu_coredump.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_coredump.9,v 1.3 2002/05/25 11:08:21 wiz Exp $
.\" $NetBSD: cpu_coredump.9,v 1.4 2002/10/14 13:43:18 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -49,7 +49,8 @@
.Fn cpu_coredump
is the machine-dependent interface invoked by machine-independent code
to dump the machine-dependent header information at the start of a
process core dump. The header information primarily consists of the
process core dump.
The header information primarily consists of the
CPU and floating-point registers.
.Fa p
is the process structure of the processing being dumped.
@ -66,8 +67,8 @@ returns 0 on success and an appropriate error code on failure.
This section describes places within the
.Nx
source tree where actual code implementing or utilizing the
machine-dependent coredump interface can be found. All pathnames are
relative to
machine-dependent coredump interface can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
Process core dumps are initiated within the file

5
share/man/man9/cpu_dumpconf.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_dumpconf.9,v 1.2 2002/05/25 11:08:21 wiz Exp $
.\" $NetBSD: cpu_dumpconf.9,v 1.3 2002/10/14 13:43:19 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -58,7 +58,8 @@
.Fn cpu_dumpconf
is the machine-dependent interface invoked during system bootstrap to
determine the dump device and initialize machine-dependent kernel core
dump state. Internally,
dump state.
Internally,
.Fn cpu_dumpconf
will invoke
.Fn cpu_dumpsize

6
share/man/man9/cpu_exit.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_exit.9,v 1.3 2002/05/25 11:08:21 wiz Exp $
.\" $NetBSD: cpu_exit.9,v 1.4 2002/10/14 13:43:19 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -69,8 +69,8 @@ This section describes places within the
.Nx
source tree where actual code utilizing
.Fn cpu_exit
be found. All pathnames are
relative to
be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
.Fn exit1

11
share/man/man9/cpu_fork.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_fork.9,v 1.2 2002/05/25 11:40:02 wiz Exp $
.\" $NetBSD: cpu_fork.9,v 1.3 2002/10/14 13:43:19 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -55,8 +55,8 @@ is the machine-dependent portion of
.Fn fork1
which finishes a fork operation, with child process
.Fa p2
nearly set up. It copies and updates the PCB and trap frame from the
parent
nearly set up.
It copies and updates the PCB and trap frame from the parent
.Fa p1 ,
making the child ready to run.
.Pp
@ -98,8 +98,9 @@ as
.Fa func
and
.Fa arg
respectively. This causes the newly-created child process to go
directly to user level with an apparent return value of 0 from
respectively.
This causes the newly-created child process to go directly to user
level with an apparent return value of 0 from
.Xr fork 2 ,
while the parent process returns normally.
.Sh SEE ALSO

6
share/man/man9/cpu_initclocks.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_initclocks.9,v 1.3 2002/05/25 11:08:21 wiz Exp $
.\" $NetBSD: cpu_initclocks.9,v 1.4 2002/10/14 13:43:20 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -55,8 +55,8 @@ start the real-time and statistic clocks running.
This section describes places within the
.Nx
source tree where actual code implementing or utilizing the
machine-dependent clocks initialization interface can be found. All
pathnames are relative to
machine-dependent clocks initialization interface can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
Machine-independent clock interface operations are performed within

8
share/man/man9/cpu_reboot.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_reboot.9,v 1.12 2002/05/25 10:44:22 wiz Exp $
.\" $NetBSD: cpu_reboot.9,v 1.13 2002/10/14 13:43:20 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -46,8 +46,8 @@
The
.Fn cpu_reboot
function handles final system shutdown, and either halts or reboots
the system. The exact action to be taken is determined by the
flags passed in
the system.
The exact action to be taken is determined by the flags passed in
.Fa howto
and by whether or not the system has finished autoconfiguration.
.Pp
@ -75,7 +75,7 @@ and sets the time of day clock by calling
.It
Disables interrupts.
.It
If rebooting after a crash (i.e. if
If rebooting after a crash (i.e., if
.Dv RB_DUMP
is set in
.Fa howto ,

8
share/man/man9/cpu_swapout.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_swapout.9,v 1.1 2002/05/25 02:16:37 gmcgarry Exp $
.\" $NetBSD: cpu_swapout.9,v 1.2 2002/10/14 13:43:20 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -53,8 +53,10 @@
and
.Fn cpu_swapin
are the machine-dependent interface for swapping processes in and out
of the system. They perform any machine-specific operations such as
saving and restoring floating point state. They are invoked by
of the system.
They perform any machine-specific operations such as
saving and restoring floating point state.
They are invoked by
.Fn uvm_swapout
and
.Fn uvm_swapin

6
share/man/man9/cpu_sysctl.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: cpu_sysctl.9,v 1.1 2002/05/25 02:16:37 gmcgarry Exp $
.\" $NetBSD: cpu_sysctl.9,v 1.2 2002/10/14 13:43:20 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -50,7 +50,7 @@
.Fn sysctl
retrieves machine-dependent system information for the
.Xr sysctl 3
function. All variables are prefixed with
"hw".
function.
All variables are prefixed with "hw".
.Sh SEE ALSO
.Xr sysctl 3

86
share/man/man9/disk.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: disk.9,v 1.17 2002/02/13 08:18:40 ross Exp $
.\" $NetBSD: disk.9,v 1.18 2002/10/14 13:43:21 wiz Exp $
.\"
.\" Copyright (c) 1995, 1996 Jason R. Thorpe.
.\" All rights reserved.
@ -106,10 +106,12 @@ struct disk {
.Ed
.Pp
The system maintains a global linked-list of all disks attached to the
system. This list, called
system.
This list, called
.Nm disklist ,
may grow or shrink over time as disks are dynamically added and removed
from the system. Drivers which currently make use of the detachment
from the system.
Drivers which currently make use of the detachment
capability of the framework are the
.Nm ccd
and
@ -130,20 +132,21 @@ timestamp, insert the disk into the disklist, and increment the
system disk count.
.It Fn disk_detach
Detach a disk; free storage for the disklabel, remove the disk
from the disklist, and decrement the system disk count. If the count
drops below zero, panic.
from the disklist, and decrement the system disk count.
If the count drops below zero, panic.
.It Fn disk_busy
Increment the disk's
.Dq busy counter .
If this counter goes from 0 to 1, set the timestamp corresponding to
this transfer.
.It Fn disk_unbusy
Decrement a disk's busy counter. If the count drops below zero, panic.
Decrement a disk's busy counter.
If the count drops below zero, panic.
Get the current time, subtract it from the disk's timestamp, and add
the difference to the disk's running total. Set the disk's timestamp
to the current time. If the provided byte count is greater than 0,
add it to the disk's running total and increment the number of transfers
performed by the disk.
the difference to the disk's running total.
Set the disk's timestamp to the current time.
If the provided byte count is greater than 0, add it to the disk's
running total and increment the number of transfers performed by the disk.
.It Fn disk_resetstat
Reset the running byte, transfer, and time totals.
.It Fn disk_find
@ -163,20 +166,23 @@ The function
is provided as a utility function.
.Sh USING THE FRAMEWORK
This section includes a description on basic use of the framework
and example usage of its functions. Actual implementation of
a device driver which utilizes the framework may vary.
and example usage of its functions.
Actual implementation of a device driver which utilizes the framework
may vary.
.Pp
A special routine,
.Fn disk_init ,
is provided to perform basic initialization of data structures used by
the framework. It is called exactly once by the system, in
the framework.
It is called exactly once by the system, in
.Fn main ,
before device autoconfiguration.
.Pp
Each device in the system uses a
.Dq softc
structure which contains autoconfiguration and state information for that
device. In the case of disks, the softc should also contain one instance
device.
In the case of disks, the softc should also contain one instance
of the disk structure, e.g.:
.Bd -literal
struct foo_softc {
@ -187,17 +193,21 @@ struct foo_softc {
.Ed
.Pp
In order for the system to gather metrics data about a disk, the disk must
be registered with the system. The
be registered with the system.
The
.Fn disk_attach
routine performs all of the functions currently required to register a disk
with the system including allocation of disklabel storage space,
recording of the time since boot that the disk was attached, and insertion
into the disklist. Note that since this function allocates storage space
for the disklabel, it must be called before the disklabel is read from the
media or used in any other way. Before
into the disklist.
Note that since this function allocates storage space for the disklabel,
it must be called before the disklabel is read from the media or used in
any other way.
Before
.Fn disk_attach
is called, a portions of the disk structure must be initialized with
data specific to that disk. For example, in the
data specific to that disk.
For example, in the
.Dq foo
disk driver, the following would be performed in the autoconfiguration
.Dq attach
@ -225,22 +235,25 @@ The
.Nm foodkdriver
above is the disk's
.Dq driver
switch. This switch currently includes a pointer to the disk's
switch.
This switch currently includes a pointer to the disk's
.Dq strategy
routine. This switch needs to have global scope and should be initialized
as follows:
routine.
This switch needs to have global scope and should be initialized as follows:
.Bd -literal
void foostrategy(struct buf *);
struct dkdriver foodkdriver = { foostrategy };
.Ed
.Pp
Once the disk is attached, metrics may be gathered on that disk. In order
to gather metrics data, the driver must tell the framework when the disk
starts and stops operations. This functionality is provided by the
Once the disk is attached, metrics may be gathered on that disk.
In order to gather metrics data, the driver must tell the framework when
the disk starts and stops operations.
This functionality is provided by the
.Fn disk_busy
and
.Fn disk_unbusy
routines. The
routines.
The
.Fn disk_busy
routine should be called immediately before a command to the disk is
sent, e.g.:
@ -275,16 +288,19 @@ must be called at
.Fn splbio .
At the end of a transaction, the
.Fn disk_unbusy
routine should be called. This routine performs some consistency checks,
routine should be called.
This routine performs some consistency checks,
such as ensuring that the calls to
.Fn disk_busy
and
.Fn disk_unbusy
are balanced. This routine also performs the actual metrics calculation.
are balanced.
This routine also performs the actual metrics calculation.
A timestamp is taken, and the difference from the timestamp taken in
.Fn disk_busy
is added to the disk's total running time. The disk's timestamp is then
updated in case there is more than one pending transfer on the disk.
is added to the disk's total running time.
The disk's timestamp is then updated in case there is more than one
pending transfer on the disk.
A byte count is also added to the disk's running total, and if greater than
zero, the number of transfers the disk has performed is incremented.
.Bd -literal
@ -323,15 +339,16 @@ must be called at
.Fn splbio .
.Pp
At some point a driver may wish to reset the metrics data gathered on a
particular disk. For this function, the
particular disk.
For this function, the
.Fn disk_resetstat
routine is provided.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual
code implementing or utilizing the disk framework can be found. All
pathnames are relative to
code implementing or utilizing the disk framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The disk framework itself is implemented within the file
@ -342,7 +359,8 @@ Data structures and function prototypes for the framework are located in
The
.Nx
machine-independent SCSI disk and CD-ROM drivers utilize the
disk framework. They are located in
disk framework.
They are located in
.Pa sys/scsi/sd.c
and
.Pa sys/scsi/cd.c .

160
share/man/man9/dmover.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: dmover.9,v 1.5 2002/08/04 04:54:19 thorpej Exp $
.\" $NetBSD: dmover.9,v 1.6 2002/10/14 13:43:21 wiz Exp $
.\"
.\" Copyright (c) 2002 Wasabi Systems, Inc.
.\" All rights reserved.
@ -73,26 +73,29 @@ Back-end interface routines:
.Sh DESCRIPTION
The
.Nm dmover
facility provides an interface to hardware-assisted data movers. This
can be used to copy data from one location in memory to another, clear
facility provides an interface to hardware-assisted data movers.
This can be used to copy data from one location in memory to another, clear
a region of memory, fill a region of memory with a pattern, and perform
simple operations on multiple regions of memory, such as an XOR, without
intervention by the CPU.
.Pp
The drivers for hardware-assisted data movers present themselves to
.Nm dmover
by registering their capabilities. When a client wishes to use a
by registering their capabilities.
When a client wishes to use a
.Nm dmover
function, it creates a session for that function, which identifies back-ends
capable of performing that function. The client then enqueues requests
on that session, which the back-ends process asynchronously. The client
may choose to block until the request is completed, or may have a call-back
invoked once the request has been completed.
capable of performing that function.
The client then enqueues requests on that session, which the back-ends
process asynchronously.
The client may choose to block until the request is completed, or may
have a call-back invoked once the request has been completed.
.Pp
When a client creates a session, the
.Nm dmover
facility identifies back-ends which are capable of handling the requested
function. When a request is scheduled for processing, the
function.
When a request is scheduled for processing, the
.Nm dmover
scheduler will identify the best back-end to process the request from
the list of candidate back-ends, in an effort to provide load balancing,
@ -100,10 +103,12 @@ while considering the relative performance of each back-end.
.Pp
A
.Nm dmover
function always has one output region. A function may have zero or more
input regions, or may use an immediate value as an input. For functions
which use input regions, the lengths of each input region and the output
region must be the same. All
function always has one output region.
A function may have zero or more input regions, or may use an immediate
value as an input.
For functions which use input regions, the lengths of each input region
and the output region must be the same.
All
.Nm dmover
functions with the same name will have the same number of and type inputs.
If a back-end attempts to register a function which violates this invariant,
@ -111,10 +116,10 @@ behavior is undefined.
.Pp
The
.Nm dmover
facility supports several types of buffer descriptors. For functions
which use input regions, each input buffer descriptor and the output buffer
descriptor must be of the same type. This restriction may be removed in
a future revision of the interface.
facility supports several types of buffer descriptors.
For functions which use input regions, each input buffer descriptor and
the output buffer descriptor must be of the same type.
This restriction may be removed in a future revision of the interface.
.Pp
The
.Nm dmover
@ -149,15 +154,16 @@ typedef union {
Together, these data types are used to describe buffer data structures
which the
.Nm dmover
facility understands. Additional buffer types may be added in future
revisions of the
facility understands.
Additional buffer types may be added in future revisions of the
.Nm dmover
interface.
.Pp
The
.Fa dmover_assignment
structure contains the information about the back-end to which a
request is currently assigned. It contains the following public members:
request is currently assigned.
It contains the following public members:
.Bl -tag -width "XXXX"
.It struct dmover_backend *das_backend
This is a pointer to the back-end.
@ -183,19 +189,20 @@ structure contains the following public members:
.It TAILQ_ENTRY(dmover_request) dreq_dmbq
Linkage on the back-end's queue of pending requests.
.It struct dmover_session *dreq_session
Pointer to the session with which this request is associated. This
is intended for use by the back-end.
Pointer to the session with which this request is associated.
This is intended for use by the back-end.
.It struct dmover_assignment *dreq_assignment
Pointer to the
.Fa dmover_assignment
structure which describes the back-end to which the request is
currently assigned. The back-end is assigned when the request
is scheduled with
currently assigned.
The back-end is assigned when the request is scheduled with
.Fn dmover_process .
.It void (*dreq_callback)(struct dmover_request *)
This is a pointer to an optional call-back function provided by the
client. If provided, the call-back is invoked when the request is
complete. This field must be
client.
If provided, the call-back is invoked when the request is complete.
This field must be
.Dv NULL
if
.Em DMOVER_REQ_WAIT
@ -210,13 +217,14 @@ is actively processing a request.
The following flags are defined:
.Bl -tag -width "DMOVER_REQ_RUNNINGXX"
.It DMOVER_REQ_DONE
The request has been completed. If not using a call-back, the client
may poll this bit to determine if a request has been processed.
The request has been completed.
If not using a call-back, the client may poll this bit to determine
if a request has been processed.
.It DMOVER_REQ_ERROR
An error has occurred while processing the request.
.It DMOVER_REQ_RUNNING
The request is currently being executed by the back-end. Once a
command is running, it cannot be cancelled, and must run to completion.
The request is currently being executed by the back-end.
Once a command is running, it cannot be cancelled, and must run to completion.
.It DMOVER_REQ_WAIT
If set by the client,
.Fn dmover_process
@ -236,19 +244,21 @@ The type of the output buffer.
.It dmover_buffer dreq_outbuf
The output buffer.
.It uint8_t dreq_immediate[8]
This is the input for algorithms which use an immediate value. Values
smaller than 8 bytes should use the least-significant bytes first. For
example, a 32-bit integer would occupy bytes 0, 1, 2, and 3.
This is the input for algorithms which use an immediate value.
Values smaller than 8 bytes should use the least-significant bytes first.
For example, a 32-bit integer would occupy bytes 0, 1, 2, and 3.
.It dmover_buffer_type dreq_inbuf_type
The type of the input buffer. This is only used if the
The type of the input buffer.
This is only used if the
.Nm dmover
function has one or more inputs.
.It dmover_buffer *dreq_inbuf
A pointer to an array of input buffers. This is only used if the
A pointer to an array of input buffers.
This is only used if the
.Nm dmover
function has one or more inputs. The number of inputs, and thus the
number of valid elements in the array, is specified by the algorithm
description for the session.
function has one or more inputs.
The number of inputs, and thus the number of valid elements in the
array, is specified by the algorithm description for the session.
.El
.Ss CLIENT INTERFACE
The following functions are provided to the client:
@ -267,38 +277,40 @@ A handle to the new session is returned in
The following are valid data movement function names:
.Bl -tag -width "fill8xx"
.It Dq zero
Fill a memory region with zeros. This algorithm has an input count of 0.
Fill a memory region with zeros.
This algorithm has an input count of 0.
.It Dq fill8
Fill a memory region with an 8-bit pattern. This algorithm has an input
count of 0. The pattern is provided in the
Fill a memory region with an 8-bit pattern.
This algorithm has an input count of 0.
The pattern is provided in the
.Em dreq_imm8
member of the
.Fa dmover_request
structure.
.It Dq copy
Copy a memory region from one location to another. This algorithm has an
input count of 1.
Copy a memory region from one location to another.
This algorithm has an input count of 1.
.It Dq xor2
Perform an XOR operation on 2 inputs. This algorithm has an input count
of 2.
Perform an XOR operation on 2 inputs.
This algorithm has an input count of 2.
.It Dq xor3
Perform an XOR operation on 3 inputs. This algorithm has an input count
of 3.
Perform an XOR operation on 3 inputs.
This algorithm has an input count of 3.
.It Dq xor4
Perform an XOR operation on 4 inputs. This algorithm has an input count
of 4.
Perform an XOR operation on 4 inputs.
This algorithm has an input count of 4.
.It Dq xor5
Perform an XOR operation on 5 inputs. This algorithm has an input count
of 5.
Perform an XOR operation on 5 inputs.
This algorithm has an input count of 5.
.It Dq xor6
Perform an XOR operation on 6 inputs. This algorithm has an input count
of 6.
Perform an XOR operation on 6 inputs.
This algorithm has an input count of 6.
.It Dq xor7
Perform an XOR operation on 7 inputs. This algorithm has an input count
of 7.
Perform an XOR operation on 7 inputs.
This algorithm has an input count of 7.
.It Dq xor8
Perform an XOR operation on 8 inputs. This algorithm has an input count
of 8.
Perform an XOR operation on 8 inputs.
This algorithm has an input count of 8.
.El
.Pp
Users of the
@ -379,7 +391,8 @@ The
.Fn dmover_request_free
function frees a
.Nm dmover
request structure. If the
request structure.
If the
.Nm dmover
function requires input buffers, and the input buffer descriptors
associated with
@ -395,8 +408,9 @@ function submits the
.Nm dmover
request
.Fa req
for processing. The call-back specified by the request is
invoked when processing is complete.
for processing.
The call-back specified by the request is invoked when processing is
complete.
.El
.Pp
The
@ -438,7 +452,8 @@ The
.Em dad_name
member points to a valid
.Nm dmover
function name which the client may specify. The
function name which the client may specify.
The
.Em dad_data
member points to a back-end-specific description of the algorithm.
.Pp
@ -446,8 +461,8 @@ A back-end presents itself to the
.Nm dmover
facility using the
.Fa dmover_backend
structure. The back-end must initialize the following members
of the structure:
structure.
The back-end must initialize the following members of the structure:
.Bl -tag -width "XXXX"
.It const char *dmb_name
This is the name of the back-end.
@ -497,8 +512,8 @@ value to indicate the error.
When the back-end has finished processing the request, it must call
the
.Fn dmover_done
function. This function eventually invokes the client's call-back
routine.
function.
This function eventually invokes the client's call-back routine.
.Pp
If a hardware-assisted data mover uses interrupts, the interrupt handlers
should be registered at IPL_BIO.
@ -522,7 +537,8 @@ function removes the back-end
.Fa backend
from the
.Nm dmover
facility. The back-end must already be registered.
facility.
The back-end must already be registered.
.It void Fn dmover_done "struct dmover_request *req"
.Pp
The
@ -547,9 +563,10 @@ or in non-interrupt context.
.Sh EXAMPLES
The following is an example of a client using
.Nm dmover
to zero-fill a region of memory. In this example, the CPU will be
able to context switch to another thread and perform work while the
hardware-assisted data mover clears the specified block of memory.
to zero-fill a region of memory.
In this example, the CPU will be able to context switch to another
thread and perform work while the hardware-assisted data mover clears
the specified block of memory.
.Bd -literal
int
hw_bzero(void *buf, size_t len)
@ -602,5 +619,6 @@ facility was designed and implemented by
and contributed by Wasabi Systems, Inc.
.Sh BUGS
The mechanism by which a back-end should advertise its performance to
the request scheduler is not well-defined. Therefore, the load-balancing
mechanism within the request scheduler is also not well-defined.
the request scheduler is not well-defined.
Therefore, the load-balancing mechanism within the request scheduler is
also not well-defined.

5
share/man/man9/doshutdownhooks.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: doshutdownhooks.9,v 1.8 2002/07/31 00:47:55 soren Exp $
.\" $NetBSD: doshutdownhooks.9,v 1.9 2002/10/14 13:43:21 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -46,7 +46,8 @@ The
.Fn doshutdownhooks
function invokes all shutdown hooks established using the
.Xr shutdownhook_establish 9
function. Shutdown hooks are called in reverse order, i.e.
function.
Shutdown hooks are called in reverse order, i.e.,
the shutdown hook established last will be called first.
.Pp
This function is called from

185
share/man/man9/driver.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: driver.9,v 1.8 2002/09/14 14:19:38 jonb Exp $
.\" $NetBSD: driver.9,v 1.9 2002/10/14 13:43:22 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -55,15 +55,18 @@
.Sh DESCRIPTION
This page briefly describes the basic
.Nx
autoconfiguration interface utilised by device drivers. For a detailed
overview of the autoconfiguration framework see
autoconfiguration interface utilised by device drivers.
For a detailed overview of the autoconfiguration framework see
.Xr autoconf 9 .
.Pp
Each device driver must present to the system a standard
autoconfiguration interface. This interface is provided by the
autoconfiguration interface.
This interface is provided by the
.Em cfattach
structure. The interface to the driver is constant and is defined
statically inside the driver. For example, the interface to driver
structure.
The interface to the driver is constant and is defined
statically inside the driver.
For example, the interface to driver
.Dq foo
is defined with:
.Pp
@ -81,24 +84,28 @@ The structure variable must be named
.Va foo_ca
by appending the letters
.Dq _ca
to the driver's base name. This convention is mandated by the
autoconfiguration framework.
to the driver's base name.
This convention is mandated by the autoconfiguration framework.
.Pp
For each device instance controlled by the driver, the
autoconfiguration framework allocates a block of memory to record
device-instance-specific driver variables. The size of this memory
block is specified by the first field in the
device-instance-specific driver variables.
The size of this memory block is specified by the first field in the
.Em cfattach
structure. The memory block is referred to as the driver's
structure.
The memory block is referred to as the driver's
.Em softc
structure. The
structure.
The
.Em softc
structure is only accessed within the driver, so its definition is
local to the driver. Nevertheless, the
local to the driver.
Nevertheless, the
.Em softc
structure should adopt the standard
.Nx
configuration and naming conventions. For example, the
configuration and naming conventions.
For example, the
.Em softc
structure for driver
.Dq foo
@ -122,8 +129,9 @@ device-instance name
If a driver has character device interfaces accessed from userland, the driver
must define the
.Em cdevsw
structure. The structure is constant and is defined inside the driver. For
example, the
structure.
The structure is constant and is defined inside the driver.
For example, the
.Em cdevsw
structure for driver
.Dq foo
@ -145,15 +153,16 @@ const struct cdevsw foo_cdevsw {
.Pp
The structure variable must be named foo_cdevsw by appending the letters
.Dq _cdevsw
to the driver's base name. This convention is mandated by the
autoconfiguration framework.
to the driver's base name.
This convention is mandated by the autoconfiguration framework.
.Pp
If the driver
.Dq foo
has also block device interfaces, the driver must define the
.Em bdevsw
structure. The structure is constant and is defined inside the driver. For
example, the
structure.
The structure is constant and is defined inside the driver.
For example, the
.Em bdevsw
structure for driver
.Dq foo
@ -173,41 +182,47 @@ const struct bdevsw foo_bdevsw {
.Pp
The structure variable must be named foo_bdevsw by appending the letters
.Dq _bdevsw
to the driver's base name. This convention is mandated by the
autoconfiguration framework.
to the driver's base name.
This convention is mandated by the autoconfiguration framework.
.Pp
During system bootstrap, the autoconfiguration framework searches the
system for devices. For each device driver, its match function
is called
system for devices.
For each device driver, its match function is called
.Po
via its
.Em cfattach
structure
.Pc
to match the driver with a device instance. The match function is
called with three arguments. This first argument
to match the driver with a device instance.
The match function is called with three arguments.
This first argument
.Fa parent
is a pointer to the driver's parent device structure. The second
argument
is a pointer to the driver's parent device structure.
The second argument
.Fa match
is a pointer to a data structure describing the autoconfiguration
framework's understanding of the driver. Both the
framework's understanding of the driver.
Both the
.Fa parent
and
.Fa match
arguments are ignored by most drivers. The third argument
arguments are ignored by most drivers.
The third argument
.Fa aux
contains a pointer to a structure describing a potential
device-instance. It is passed to the driver from the parent.
device-instance.
It is passed to the driver from the parent.
The match function would type-cast the
.Fa aux
argument to its appropriate attachment structure and use its contents
to determine whether it supports the device. Depending on the device
hardware, the contents of the attachment structure may contain
to determine whether it supports the device.
Depending on the device hardware, the contents of the attachment
structure may contain
.Dq locators
to locate the device instance so that the driver can probe it for its
identity. If the probe process identifies additional device
properties, it may modify the members of the attachment structure.
identity.
If the probe process identifies additional device properties, it may
modify the members of the attachment structure.
For these devices, the
.Nx
convention is to
@ -215,9 +230,10 @@ call the match routine
.Fn foo_probe
instead of
.Fn foo_match
to make this distinction clear. Either way, the match function
returns a nonzero integer indicating the confidence of supporting this
device and a value of 0 if the driver doesn't support the device.
to make this distinction clear.
Either way, the match function returns a nonzero integer indicating the
confidence of supporting this device and a value of 0 if the driver
doesn't support the device.
Generally, only a single driver exists for a device, so the match
function returns 1 for a positive match.
.Pp
@ -228,28 +244,31 @@ via its
structure
.Pc
of the driver which returns the highest value from its match function.
The attach function is called with three arguments. The attach
function performs the necessary process to initialise the device for
operation. The first argument
The attach function is called with three arguments.
The attach function performs the necessary process to initialise the
device for operation.
The first argument
.Fa parent
is a pointer to the driver's parent device structure. The second
argument
is a pointer to the driver's parent device structure.
The second argument
.Fa self
is a pointer to the driver's device structure. It is also a pointer
to our
is a pointer to the driver's device structure.
It is also a pointer to our
.Em softc
structure since the device structure is its first member. The third
argument
structure since the device structure is its first member.
The third argument
.Fa aux
is a pointer to the attachment structure. The
is a pointer to the attachment structure.
The
.Fa parent
and
.Fa aux
arguments are the same as passed to the match function.
.Pp
The driver's attach function is called before system interrupts are
enabled. If interrupts are required during initialisation, then
the attach function should make use of
enabled.
If interrupts are required during initialisation, then the attach
function should make use of
.Fn config_interrupts
.Po
see
@ -257,22 +276,26 @@ see
.Pc .
.Pp
Some devices can be removed from the system without requiring a system
reboot. The autoconfiguration framework calls the driver's detach
function
reboot.
The autoconfiguration framework calls the driver's detach function
.Po
via its
.Em cfattach
structure
.Pc
during device detachment. If the device does not support detachment,
then the driver does not have to provide a detach function. The
detach function is used to relinquish resources allocated to the
driver which are no longer needed. The first argument
during device detachment.
If the device does not support detachment, then the driver does not
have to provide a detach function.
The detach function is used to relinquish resources allocated to the
driver which are no longer needed.
The first argument
.Fa self
is a pointer to the driver's device structure. It is the same
structure as passed to the attach function. The second argument
is a pointer to the driver's device structure.
It is the same structure as passed to the attach function.
The second argument
.Fa flags
contains detachment flags. Valid values are DETACH_FORCE
contains detachment flags.
Valid values are DETACH_FORCE
.Po
force detachment; hardware gone
.Pc and DETACH_QUIET
@ -282,14 +305,17 @@ do not print a notice
.Pp
The autoconfiguration framework calls the driver's activate function
to notify the driver of a change in the resources that have been
allocated to it. For example, an Ethernet driver has to be notified
if the network stack is being added or removed from the kernel. The
first argument to the activate function
allocated to it.
For example, an Ethernet driver has to be notified if the network stack
is being added or removed from the kernel.
The first argument to the activate function
.Fa self
is a pointer to the driver's device structure. It is the same
argument as passed to the attach function. The second argument
is a pointer to the driver's device structure.
It is the same argument as passed to the attach function.
The second argument
.Fa act
describes the action. Valid actions are DVACT_ACTIVATE
describes the action.
Valid actions are DVACT_ACTIVATE
.Po
activate the device
.Pc and DVACT_DEACTIVATE
@ -300,14 +326,17 @@ If the action is not supported the activate function should return
EOPNOTSUPP.
The activate function is called in interrupt context.
.Pp
Most drivers will want to make use of interrupt facilities. Interrupt
locators provided through the attachment structure should be used to
establish interrupts within the system. Generally, an interrupt
interface is provided by the parent. The interface will require a
handler and a driver-specific argument to be specified. This argument
is usually a pointer to the device-instance-specific softc structure.
Most drivers will want to make use of interrupt facilities.
Interrupt locators provided through the attachment structure should be
used to establish interrupts within the system.
Generally, an interrupt interface is provided by the parent.
The interface will require a handler and a driver-specific argument
to be specified.
This argument is usually a pointer to the device-instance-specific
softc structure.
When a hardware interrupt for the device occurs the handler is called
with the argument. Interrupt handlers should return 0 for
with the argument.
Interrupt handlers should return 0 for
.Dq interrupt not for me ,
1 for
.Dq I took care of it ,
@ -318,9 +347,10 @@ I guess it was mine, but I wasn't expecting it
.Pp
For a driver to be compiled into the kernel,
.Xr config 8
must be aware of its existence. This is done by including an entry in
files.\*[Lt]bus\*[Gt] in the directory containing the driver. For example, the
driver
must be aware of its existence.
This is done by including an entry in files.\*[Lt]bus\*[Gt] in the
directory containing the driver.
For example, the driver
.Dq foo
attaching to bus
.Dq bar
@ -340,8 +370,9 @@ foo* at bar?
.Pp
For device interfaces of a driver to be compiled into the kernel,
.Xr config 8
must be aware of its existence. This is done by including an entry in
majors.<arch>. For example, the driver
must be aware of its existence.
his is done by including an entry in majors.<arch>.
For example, the driver
.Dq foo
with character device interfaces, a character major device number
.Dq cmaj ,

5
share/man/man9/ethersubr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ethersubr.9,v 1.13 2002/02/13 08:18:40 ross Exp $
.\" $NetBSD: ethersubr.9,v 1.14 2002/10/14 13:43:22 wiz Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -163,7 +163,8 @@ which the caller must provide.
.It Fn ETHER_FIRST_MULTI
must be called to initialize
.Fa step
and get the first record. Both macros return a
and get the first record.
Both macros return a
.Dv NULL
.Fa enm
when there are no remaining records.

66
share/man/man9/evcnt.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: evcnt.9,v 1.6 2002/02/13 08:18:40 ross Exp $
.\" $NetBSD: evcnt.9,v 1.7 2002/10/14 13:43:22 wiz Exp $
.\"
.\" Copyright (c) 2000 Christopher G. Demetriou
.\" All rights reserved.
@ -58,7 +58,8 @@ system events (including device interrupts).
.Pp
The fundamental component of this framework is the
.Nm evcnt
structure. Its user-accessible fields are:
structure.
Its user-accessible fields are:
.Bd -literal
struct evcnt {
u_int64_t ev_count; /* how many have occurred */
@ -95,10 +96,10 @@ Each event counter also has a group name
and
an event name
.Pq Fa ev_name
which are used to identify the counter. The group name
may be shared by a set of counters. For example, device
interrupt counters would use the name of the device whose
interrupts are being counted as the group name.
which are used to identify the counter.
The group name may be shared by a set of counters.
For example, device interrupt counters would use the name of the
device whose interrupts are being counted as the group name.
The counter
name is meant to distinguish the counter from others in its group
(and need not be unique across groups).
@ -115,10 +116,11 @@ In the current implementation it is 256.
To support hierarchical tracking of events, each event counter can
name a
.Dq parent
event counter. For instance, interrupt dispatch code could have an
event counter per interrupt line, and devices could each have
counters for the number of interrupts that they were responsible for
causing. In that case, the counter for a device on a given interrupt line
event counter.
For instance, interrupt dispatch code could have an event counter per
interrupt line, and devices could each have counters for the number
of interrupts that they were responsible for causing.
In that case, the counter for a device on a given interrupt line
would have the line's counter as its parent.
The value
.Dv NULL
@ -129,10 +131,12 @@ and detached after the counter is detached.
The
.Fn EVCNT_INITIALIZER
macro can be used to provide a static initializer for an event
counter structure. It is be invoked as
counter structure.
It is be invoked as
.Fn EVCNT_INITIALIZER "type" "parent" "group" "name" ,
and its arguments will be placed into the corresponding fields of
the event counter structure it is initializing. The
the event counter structure it is initializing.
The
.Fa group
and
.Fa name
@ -144,8 +148,9 @@ The following is a brief description of each function in the framework:
.Pp
Attach the event counter structure pointed to by
.Fa ev
to the system event list. The event counter is cleared and its fields
initialized using the arguments to the function call.
to the system event list.
The event counter is cleared and its fields initialized using the
arguments to the function call.
The contents of the remaining elements in the structure (e.g., the
name lengths) are calculated, and the counter is added to the
system event list.
@ -159,12 +164,12 @@ not copied into, the counter.
Attach the statically-initialized event counter structure
pointed to by
.Fa ev
to the system event list. The event counter is assumed to be
statically initialized using the
to the system event list.
The event counter is assumed to be statically initialized using the
.Fn EVCNT_INITIALIZER
macro. This function simply calculates structure elements'
values as appropriate (e.g., the string lengths), and adds
the counter to the system event list.
macro.
This function simply calculates structure elements' values as appropriate
(e.g., the string lengths), and adds the counter to the system event list.
.It Fn "void evcnt_detach" "struct evcnt *ev"
.Pp
Detach the event counter structure pointed to by
@ -173,12 +178,12 @@ from the system event list.
.El
.Pp
Note that no method is provided to increment the value of an
event counter. Code incrementing an event counter should
do so by directly accessing its
event counter.
Code incrementing an event counter should do so by directly accessing its
.Fa ev_count
field in a manner that is known to be safe. For instance,
additions to a device's event counters in the interrupt handler
for that device will often be safe without additional protection
field in a manner that is known to be safe.
For instance, additions to a device's event counters in the interrupt
handler for that device will often be safe without additional protection
(because interrupt handler entries for a given device have to be
serialized).
However, for other uses of event counters, additional locking
@ -186,8 +191,8 @@ or use of machine-dependent atomic operation may be appropriate.
(The overhead of using a mechanism that is guaranteed to
be safe to increment every counter, regardless of actual need
for such a mechanism where the counter is being incremented,
would be too great. On some systems, it might involve a global
lock and several function calls.)
would be too great.
On some systems, it might involve a global lock and several function calls.)
.Sh USING THE FRAMEWORK
This section includes a description on basic use of the framework
and example usage of its functions.
@ -199,8 +204,8 @@ and
functions to manage device-specific event counters.
Statically configured system modules can use
.Fn evcnt_attach_static
to configure global event counters. Similarly, loadable
modules can use
to configure global event counters.
Similarly, loadable modules can use
.Fn evcnt_attach_static
to configure their global event counters,
.Fn evcnt_attach_dynamic
@ -212,8 +217,9 @@ to detach all counters when being unloaded.
Device drivers that wish to use the generic event counter
framework should place event counter structures in their
.Dq softc
structures. For example, to keep track of the number of interrupts
for a given device (broken down further into
structures.
For example, to keep track of the number of interrupts for a given
device (broken down further into
.Dq device readable
and
.Dq device writable

80
share/man/man9/extent.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: extent.9,v 1.22 2002/02/13 08:18:41 ross Exp $
.\" $NetBSD: extent.9,v 1.23 2002/10/14 13:43:22 wiz Exp $
.\"
.\" Copyright (c) 1996, 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -83,8 +83,8 @@
The
.Nx
extent manager provides management of areas of memory or
other number spaces (such as I/O ports). An opaque structure
called an
other number spaces (such as I/O ports).
An opaque structure called an
.Nm extent map
keeps track of allocated regions within the number space.
.Pp
@ -93,7 +93,8 @@ creates an extent map managing the space from
.Fa start
to
.Fa end
inclusive. All memory allocation will use the memory type
inclusive.
All memory allocation will use the memory type
.Fa mtype
.Po
see
@ -101,13 +102,15 @@ see
.Pc .
The extent map will have the name
.Fa name ,
used for identification in case of an error. If the flag
used for identification in case of an error.
If the flag
.Dv EX_NOCOALESCE
is specified, only entire regions may be freed within the extent map,
but internal coalescing of regions is disabled so that
.Fn extent_free
will never have to allocate a region descriptor and therefore will
never fail. The caller must specify one of the flags
never fail.
The caller must specify one of the flags
.Dv EX_NOWAIT
or
.Dv EX_WAITOK ,
@ -144,8 +147,9 @@ map may be extended using a call to
.Fn extent_destroy
destroys the extent map
.Fa ex ,
freeing all allocated regions. If the extent is not a fixed extent,
the region and internal extent descriptors themselves are freed.
freeing all allocated regions.
If the extent is not a fixed extent, the region and internal extent
descriptors themselves are freed.
This function always succeeds.
.Pp
.Fn extent_alloc
@ -153,8 +157,8 @@ allocates a region in extent
.Fa ex
of size
.Fa size
that fits the provided parameters. There are two distinct allocation
policies, which are selected by the
that fits the provided parameters.
There are two distinct allocation policies, which are selected by the
.Fa flags
argument:
.Bl -tag -offset indent -width "XXXXXXXXX"
@ -180,19 +184,22 @@ or
flags, if waiting for overhead allocation is allowed.
The request will be aligned to
.Fa alignment
boundaries. Alignment values must be a power of 2. If no alignment
is necessary, the value 1 should be specified. If
boundaries.
Alignment values must be a power of 2.
If no alignment is necessary, the value 1 should be specified.
If
.Fa boundary
is nonzero, the allocated region will not cross any of the numbers
which are a multiple of
.Fa boundary .
If the caller specifies the
.Dv EX_BOUNDZERO
flag, the boundary lines begin at zero. Otherwise, the boundary lines
begin at the beginning of the extent. The allocated region may begin on a
boundary address, but the end of the region will not touch nor cross
it. A boundary argument smaller than the size of the request is
invalid. Upon successful completion,
flag, the boundary lines begin at zero.
Otherwise, the boundary lines begin at the beginning of the extent.
The allocated region may begin on a boundary address, but the end of
the region will not touch nor cross it.
A boundary argument smaller than the size of the request is invalid.
Upon successful completion,
.Fa *result
will contain the start of the allocated region.
.Pp
@ -204,7 +211,8 @@ fall within the subregion from
.Fa substart
to
.Fa subend
inclusive. The other arguments and the return values of
inclusive.
The other arguments and the return values of
.Fn extent_alloc_subregion
are otherwise the same as those of
.Fn extent_alloc .
@ -259,24 +267,27 @@ starting at
.Fa start .
If the extent has the
.Dv EX_NOCOALESCE
property, only entire regions may be freed. If the extent has the
property, only entire regions may be freed.
If the extent has the
.Dv EX_NOCOALESCE
property and the caller attempts to free a partial region, behavior is
undefined. The caller must specify one of the flags
undefined.
The caller must specify one of the flags
.Dv EX_NOWAIT
or
.Dv EX_WAITOK
to specify whether waiting for memory is okay; these flags have
meaning in the event that allocation of a region descriptor is
required during the freeing process. This situation occurs only when
a partial region that begins and ends in the middle of another region
is freed. Behavior is undefined if invalid arguments are provided.
required during the freeing process.
This situation occurs only when a partial region that begins and ends
in the middle of another region is freed.
Behavior is undefined if invalid arguments are provided.
.Pp
.Fn extent_print
Print out information about extent
.Fa ex .
This function always succeeds. Behavior is undefined if invalid
arguments are provided.
This function always succeeds.
Behavior is undefined if invalid arguments are provided.
.Sh LOCKING
The extent manager performs all necessary locking on the extent map
itself, and any other data structures internal to the extent manager.
@ -293,8 +304,8 @@ invalid arguments.
.Fn extent_create
returns the extent map on success, or
.Dv NULL
if it fails to allocate storage for the extent map. It always
succeeds when creating a fixed extent or when given the flag
if it fails to allocate storage for the extent map.
It always succeeds when creating a fixed extent or when given the flag
.Dv EX_WAITOK .
.Fn extent_alloc ,
.Fn extent_alloc_region ,
@ -317,7 +328,8 @@ Requested region is not available and
was not specified.
.It Dv EINTR
Process received a signal while waiting for the requested region to
become available in the extent. Does not apply to
become available in the extent.
Does not apply to
.Fn extent_free .
.El
.Sh EXAMPLES
@ -369,7 +381,8 @@ Function prototypes for the framework are located in
.Pa sys/sys/extent.h .
.Pp
The i386 bus management code uses the extent manager for managing I/O
ports and I/O memory. This code is in the file
ports and I/O memory.
This code is in the file
.Pa sys/arch/i386/i386/machdep.c .
.Sh SEE ALSO
.Xr malloc 9
@ -382,7 +395,8 @@ extent manager appeared in
The
.Nx
extent manager was architected and implemented by Jason
R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt]. Matthias Drochner
\*[Lt]drochner@zelux6.zel.kfa-juelich.de\*[Gt] contributed to the initial
testing and optimization of the implementation. Chris Demetriou
\*[Lt]cgd@NetBSD.ORG\*[Gt] contributed many architectural suggestions.
R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt].
Matthias Drochner \*[Lt]drochner@zelux6.zel.kfa-juelich.de\*[Gt]
contributed to the initial testing and optimization of the implementation.
Chris Demetriou \*[Lt]cgd@NetBSD.ORG\*[Gt] contributed many
architectural suggestions.

8
share/man/man9/fetch.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: fetch.9,v 1.14 2002/02/13 08:18:41 ross Exp $
.\" $NetBSD: fetch.9,v 1.15 2002/10/14 13:43:23 wiz Exp $
.\"
.\" Copyright (c) 1996 Jason R. Thorpe.
.\" All rights reserved.
@ -95,6 +95,6 @@ The function
.Fn fuword
has no way to unambiguously signal an error, because the
data it reads might legitimately be the same as the -1
used to indicate an error. The other functions do not
have this problem because the unsigned values returned
by those can never match the -1 error return value.
used to indicate an error.
The other functions do not have this problem because the unsigned
values returned by those can never match the -1 error return value.

22
share/man/man9/fork1.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: fork1.9,v 1.7 2002/08/06 14:00:03 pooka Exp $
.\" $NetBSD: fork1.9,v 1.8 2002/10/14 13:43:23 wiz Exp $
.\"
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -50,8 +50,8 @@
.Fn fork1
creates a new process out of
.Ar p1 ,
which is assumed to be the current process. This function is used primarily
to implement the
which is assumed to be the current process.
This function is used primarily to implement the
.Xr fork 2
and
.Xr vfork 2
@ -69,9 +69,9 @@ or exits (either by a call to
.Xr _exit 2
or abnormally).
.It FORK_SHAREVM
The child process will share the parent's virtual address space. If this
flag is not specified, the child will get a copy-on-write snapshot of the
parent's address space.
The child process will share the parent's virtual address space.
If this flag is not specified, the child will get a copy-on-write
snapshot of the parent's address space.
.It FORK_SHARECWD
The child process will share the parent's current directory, root directory,
and file creation mask.
@ -92,7 +92,8 @@ value of 0 indicates a standard fork operation.
.Pp
The
.Ar retval
argument is provided for the use of system call stubs. If
argument is provided for the use of system call stubs.
If
.Ar retval
is not NULL, it will hold the following values after successful completion
of the fork operation:
@ -100,8 +101,8 @@ of the fork operation:
.It Ar retval[0]
This will contain the pid of the child process.
.It Ar retval[1]
In the parent process, this will contain the value 0. In the child process,
this will contain 1.
In the parent process, this will contain the value 0.
In the child process, this will contain 1.
.El
.Pp
User level system call stubs typically subtract 1 from
@ -119,7 +120,8 @@ the fork operation.
.Sh RETURN VALUES
Upon successful completion of the fork operation,
.Fn fork1
returns 0. Otherwise, the following error values are returned:
returns 0.
Otherwise, the following error values are returned:
.Bl -tag -width [EAGAIN]
.It Bq Er EAGAIN
The limit on the total number of system processes would be exceeded.

10
share/man/man9/inittodr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: inittodr.9,v 1.7 2001/09/04 02:51:16 wiz Exp $
.\" $NetBSD: inittodr.9,v 1.8 2002/10/14 13:43:23 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -75,8 +75,8 @@ variable.
The
.Fn inittodr
function prints diagnostic messages if it has trouble figuring
out the system time. Conditions that can cause diagnostic
messages to be printed include:
out the system time.
Conditions that can cause diagnostic messages to be printed include:
.Bl -bullet
.It
The battery-backed clock's time appears nonsensical.
@ -99,8 +99,8 @@ has to convert from
a time expressed in terms of year, month, day, hours, minutes,
and seconds to
.Va time ,
expressed in seconds. Many of the implementations could share code,
but do not.
expressed in seconds.
Many of the implementations could share code, but do not.
.Pp
Each system's heuristics for picking the correct time are slightly
different.

33
share/man/man9/ioctl.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ioctl.9,v 1.16 2002/06/11 23:31:01 wiz Exp $
.\" $NetBSD: ioctl.9,v 1.17 2002/10/14 13:43:24 wiz Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -63,8 +63,8 @@ system call as second argument, e.g.
a macro which can be one of
.Bl -tag -width _IOWR
.It _IO
the call is a simple message to the kernel by itself. It does not copy
anything into the kernel, nor does it want anything back.
the call is a simple message to the kernel by itself.
It does not copy anything into the kernel, nor does it want anything back.
.It _IOR
the call only reads parameters from the kernel and does not
pass any to it
@ -228,16 +228,17 @@ ite devices (amiga, atari, x68k)
passthrough ioctls
.El
.It Ar n
This numbers the ioctl within the group. There may be only one
This numbers the ioctl within the group.
There may be only one
.Ar n
for a given
.Ar t .
This is a unsigned 8 bit number.
.It Ar pt
This specifies the type of the passed parameter. This one gets internally
transformed to the size of the parameter, so if you e.g. want to pass
a structure, then you have to specify that structure and not a pointer
to it or sizeof(struct foo)
This specifies the type of the passed parameter.
This one gets internally transformed to the size of the parameter, so
if you e.g. want to pass a structure, then you have to specify that
structure and not a pointer to it or sizeof(struct foo)
.El
.Pp
In order for the new ioctl to be known to the system it is installed
@ -268,14 +269,14 @@ driver_ioctl(..., u_long cmd, caddr_t data)
.Sh NOTES
Note that if you e.g. try to read information from e.g. a ethernet
driver where the name of the card is included in the third argument
(e.g. ioctl(s, READFROMETH, struct ifreq *)), then you have to use
(e.g., ioctl(s, READFROMETH, struct ifreq *)), then you have to use
the _IOWR() form not the _IOR(), as passing the name of the card to the
kernel already consists of writing data.
.Sh RETURN VALUES
All ioctl() routines should return either 0 or a defined error code.
The use of magic numbers such as -1, to indicate that a given ioctl
code was not handled is strongly discouraged. The value -1 coincides
with the historic value for
code was not handled is strongly discouraged.
The value -1 coincides with the historic value for
.Cm ERESTART
which was shown to produce user space code that never returned from
a call to
@ -287,16 +288,16 @@ are not handled by a given routine, the pseudo error value
is provided.
.Cm EPASSTHROUGH
indicates that no error occurred during processing (it did not fail),
but neither was anything processed (it did not succeed). This
supercedes the use of either
but neither was anything processed (it did not succeed).
This supercedes the use of either
.Cm ENOTTY
(which is an explicit failure) or -1 (which has no contextual meaning)
as a return value.
.Cm ENOTTY
will get passed directly back to user space and bypass any further
processing by other ioctl layers. Only code that wishes to suppress
possible further processing of an ioctl code (eg, the tty line discipline
code) should return
processing by other ioctl layers.
Only code that wishes to suppress possible further processing of an
ioctl code (e.g., the tty line discipline code) should return
.Cm ENOTTY .
All other code should return
.Cm EPASSTHROUGH ,

32
share/man/man9/ipkdb.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ipkdb.9,v 1.4 2002/06/02 11:21:53 wiz Exp $
.\" $NetBSD: ipkdb.9,v 1.5 2002/10/14 13:43:24 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -79,10 +79,10 @@ argument to 0.
.Fn ipkdbcmds
is invoked by machine-dependent code when the trap mechanism
determines that the debugger should be entered, i.e., on a single step
or breakpoint interrupt from kernel code. The trapping mechanism
should already have stored the registers into the global area
ipkdbregs. The layout of this area must be the same as that expected
by
or breakpoint interrupt from kernel code.
The trapping mechanism should already have stored the registers into
the global area ipkdbregs.
The layout of this area must be the same as that expected by
.Xr gdb 1 .
Valid return values are:
.Pp
@ -102,8 +102,8 @@ the machine-independent code.
This routine gets called when the debugger should be entered for the
first time.
.It Fn ipkdb_trap ""
This routine is part of the trap handler. Whenever a trap happens
(e.g., when hitting a breakpoint during debugging),
This routine is part of the trap handler.
Whenever a trap happens (e.g., when hitting a breakpoint during debugging),
.Fn ipkdb_trap
decides if the Debugger needs to be called.
If there are other ways to decide that, it's not necessary to provide an
@ -111,10 +111,11 @@ If there are other ways to decide that, it's not necessary to provide an
implementation.
.It Fn ipkdb_poll ""
This routine gets called after a panic to check for a key press by the
user. If implemented it allows the user to press any key on the
console to do the automatic reboot after a panic. Otherwise the
debugging interface will wait forever for some remote debugger to
attach in case of a panic.
user.
If implemented it allows the user to press any key on the
console to do the automatic reboot after a panic.
Otherwise the debugging interface will wait forever for some remote
debugger to attach in case of a panic.
.It Fn ipkdbif_init "kip"
In order to be able to find the debugging interface, the network
driver must invoke
@ -126,7 +127,8 @@ specifying a
plus some additional parameters that allow it to access the devices
registers, hopefully using
.Xr bus_space 9
methods. In the
methods.
In the
.Fa ipkdb_if
structure, the attach routine must initialize the following fields:
.Pp
@ -173,9 +175,9 @@ This routine should set the byte pointed to by
.Fa c
to the value given as
.Fa i .
The routine must not enter any trap handling code. Furthermore it should
reset the modification bit in the relevant page table entry to the value
before the store.
The routine must not enter any trap handling code.
Furthermore it should reset the modification bit in the relevant page
table entry to the value before the store.
.El
.Sh SEE ALSO
.Xr ipkdb 4

99
share/man/man9/isa.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: isa.9,v 1.6 2002/02/13 08:18:42 ross Exp $
.\" $NetBSD: isa.9,v 1.7 2002/10/14 13:43:24 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -120,22 +120,22 @@ The machine-independent
.Nm
subsystem provides support for the ISA bus.
.Pp
The ISA bus was introduced on the IBM PC/AT. It is an extension to
the original bus found on the original IBM PC. The ISA bus is
essentially the host bus of the Intel 80286 processor, however the
widespread acceptance of the bus as a defacto standard has seen it
appear on systems without Intel processors.
The ISA bus was introduced on the IBM PC/AT.
It is an extension to the original bus found on the original IBM PC.
The ISA bus is essentially the host bus of the Intel 80286 processor,
however the widespread acceptance of the bus as a defacto standard has
seen it appear on systems without Intel processors.
.Pp
The ISA bus has a 16-bit data bus, a 24-bit memory address bus, a
16-bit I/O address bus, and operates at 8MHz. It provides 15
interrupt lines and 8 DMA channels supporting DMA transfers of 64KB or
128KB transfers depending on the width of the channel being
used. Historically, some devices only decoded the 10 lowest bits of
16-bit I/O address bus, and operates at 8MHz.
It provides 15 interrupt lines and 8 DMA channels supporting DMA transfers
of 64KB or 128KB transfers depending on the width of the channel being used.
Historically, some devices only decoded the 10 lowest bits of
the I/O address bus, preventing use of the full 16-bit address space.
.Pp
On newer machines, the ISA bus is no longer connected directly to the
host bus, and is usually connected via a PCI-ISA bridge. Either way,
the bus looks the same to the device driver.
host bus, and is usually connected via a PCI-ISA bridge.
Either way, the bus looks the same to the device driver.
.Sh DATA TYPES
Drivers for devices attached to the
.Nm
@ -144,8 +144,8 @@ bus will make use of the following data types:
.It Fa isa_chipset_tag_t
Chipset tag for the ISA bus.
.It Fa struct isa_attach_args
Location hints for devices are recorded in this structure. It
contains the following members:
Location hints for devices are recorded in this structure.
It contains the following members:
.Bd -literal
bus_space_tag_t ia_iot; /* isa i/o space tag */
bus_space_tag_t ia_memt; /* isa mem space tag */
@ -164,8 +164,8 @@ contains the following members:
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn isa_intr_alloc "ic" "mask" "type" "irq"
This function is generally not required by device drivers. It is used
by bridges attaching other busses to the ISA bus.
This function is generally not required by device drivers.
It is used by bridges attaching other busses to the ISA bus.
.It Fn isa_intr_evcnt "ic" "irq"
Returns the event counter associated with interrupt line
.Fa irq .
@ -272,17 +272,19 @@ for channel
The kernel virtual address space used by the mapping is freed.
.It Fn isa_malloc "ic" "chan" "size" "pool" "flags"
This function is a shortcut for allocating and mapping DMA-safe memory
in a single step. The arguments correspond with the arguments to
in a single step.
The arguments correspond with the arguments to
.Fn isa_dmamem_alloc
and
.Fn isa_dmamem_map .
The argument
.Fa pool
is a pool to record the memory allocation. This function returns
a pointer to the DMA-safe memory.
is a pool to record the memory allocation.
This function returns a pointer to the DMA-safe memory.
.It Fn isa_free "addrp" "pool"
This function is a shortcut for unmapping and deallocating DMA-safe
memory in a single step. It replaces
memory in a single step.
It replaces
.Fn isa_dmamem_unmap
and
.Fn isa_dmamem_free .
@ -305,13 +307,14 @@ and set it in motion.
The argument
.Fa proc
is used to indicate the address space in which the buffer is located.
If NULL, the buffer is assumed to be in kernel space. Otherwise, the
buffer is assumed to be in process
If NULL, the buffer is assumed to be in kernel space.
Otherwise, the buffer is assumed to be in process
.Fa proc 's
address space.
The argument
.Fa flags
describes the type of ISA DMA. Valid values are:
describes the type of ISA DMA.
Valid values are:
.Bl -tag -width compact
.It DMAMODE_WRITE
DMA transfer from host to device.
@ -329,7 +332,8 @@ Transfer buffer continuously in loop and demand mode.
.sp
The argument
.Fa bf
is the bus-space flags. Valid values are the same as for
is the bus-space flags.
Valid values are the same as for
.Fn bus_dmamap_load
(see
.Xr bus_dma 9 ) .
@ -356,8 +360,9 @@ or
members of
.Fa struct isa_attach_args
are wildcarded, then the driver is expected to probe the hardware for
valid DMA channels. In this case, the driver can check to see if the
hardware-supported DMA channel
valid DMA channels.
In this case, the driver can check to see if the hardware-supported
DMA channel
.Fa chan
is available for use.
.It Fn isa_dmacascade "ic" "chan"
@ -370,8 +375,9 @@ Provides support for user
of DMA-safe memory.
.El
.Sh AUTOCONFIGURATION
The ISA bus is an indirect-connection bus. During autoconfiguration
each driver is required to probe the bus for the presence of a device.
The ISA bus is an indirect-connection bus.
During autoconfiguration each driver is required to probe the bus
for the presence of a device.
An ISA driver will receive a pointer to
.Fa struct isa_attach_args
hinting at "locations" on the ISA bus where the device may be located.
@ -381,13 +387,15 @@ They should use the
.Em ia_maddr ,
and
.Em ia_msize
members. Not all of these hints will be necessary; locators may
be wildcarded with IOBASEUNK and MADDRUNK for
members.
Not all of these hints will be necessary; locators may be wildcarded
with IOBASEUNK and MADDRUNK for
.Em ia_iobase
and
.Em ia_maddr
respectively. If a driver can probe the device for configuration
information at default locations, it may update the members of
respectively.
If a driver can probe the device for configuration information at default
locations, it may update the members of
.Fa struct isa_attach_args .
The IRQ and DMA locators can also be wildcarded with IRQUNK and DRQUNK
respectively.
@ -396,10 +404,10 @@ During the driver attach step, the I/O and memory address spaces
should be mapped (see
.Xr bus_space 9 ) .
.Sh DMA SUPPORT
Extensive DMA facilities are provided for the ISA bus. A driver can
use up to two DMA channels simultaneously. The DMA channels allocated
during autoconfiguration are passed to the driver during the driver
attach using the
Extensive DMA facilities are provided for the ISA bus.
A driver can use up to two DMA channels simultaneously.
The DMA channels allocated during autoconfiguration are passed to the
driver during the driver attach using the
.Fa ia_drq
and
.Fa ia_drq2
@ -414,8 +422,8 @@ channel using
A DMA map should be created first using
.Fn isa_dmamap_create .
A DMA map describes how DMA memory is loaded into the DMA controllers.
Only DMA-safe memory can be used for DMA transfers. DMA-safe memory
is allocated using
Only DMA-safe memory can be used for DMA transfers.
DMA-safe memory is allocated using
.Fn isa_dmamem_alloc .
The memory allocated by
.Fn isa_dmamem_alloc
@ -424,8 +432,8 @@ must now be mapped into kernel virtual address space by
so that it can be accessed by the driver.
.Pp
For a DMA transfer from the host to the device, the driver will fill
the DMA memory with the data to be transferred. The DMA-transfer of
the memory is started using
the DMA memory with the data to be transferred.
The DMA-transfer of the memory is started using
.Fn isa_dmastart
with
.Fa flags
@ -444,7 +452,8 @@ containing DMAMODE_READ.
When the DMA transfer is completed, a call to
.Fn isa_dmadone
cleans up the DMA transfer by unloading the memory from the
controller. The memory can now be access by the driver.
controller.
The memory can now be access by the driver.
.Pp
When the DMA resources are no longer required they should be released
using
@ -456,8 +465,8 @@ and
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent ISA subsystem can be found. All pathnames are
relative to
machine-independent ISA subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The ISA subsystem itself is implemented within the files
@ -483,5 +492,5 @@ was to invoke
.Fn panic
on failure.
.Fn isa_intr_establish
now returns NULL on failure. Some old drivers written for the former
behaviour discard the return value.
now returns NULL on failure.
Some old drivers written for the former behaviour discard the return value.

49
share/man/man9/isapnp.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: isapnp.9,v 1.5 2002/02/13 08:18:43 ross Exp $
.\" $NetBSD: isapnp.9,v 1.6 2002/10/14 13:43:24 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -62,15 +62,17 @@
.Sh DESCRIPTION
The machine-independent
.Nm
subsystem provides support for ISAPNP devices. ISAPNP devices were
developed to support "plug and play" connection on the ISA bus. In
all other aspects, the ISAPNP bus is same as the ISA bus (see
subsystem provides support for ISAPNP devices.
ISAPNP devices were developed to support "plug and play" connection
on the ISA bus.
In all other aspects, the ISAPNP bus is same as the ISA bus (see
.Xr isa 9 ) .
.Pp
Devices on the ISAPNP bus are uniquely identified by a 7-character
string. Resources, such as I/O address space and interrupts, should
be allocated to the devices by the machine firmware. On some machine
the firmware seems doesn't work correctly and
string.
Resources, such as I/O address space and interrupts, should
be allocated to the devices by the machine firmware.
On some machine the firmware seems doesn't work correctly and
.Nx
will attempt to allocate resources as necessary.
.Sh DATA TYPES
@ -79,8 +81,8 @@ types:
.Bl -tag -width compact
.It Fa struct isapnp_matchinfo
.Nx
kernel contains a database of known ISAPNP devices. Each entry in the
database has a
kernel contains a database of known ISAPNP devices.
Each entry in the database has a
.Em struct isapnp_matchinfo .
It contains the following members:
.Bd -literal
@ -88,8 +90,8 @@ It contains the following members:
int variant; /* variant flag */
.Ed
.It Fa struct isapnp_devinfo
Defines the devices supported by a driver. It contains pointer to an
array of supported
Defines the devices supported by a driver.
It contains pointer to an array of supported
.Em struct isapnp_matchinfo
structures and a pointer to another array of compatibility devices.
It contains the following members:
@ -100,8 +102,8 @@ It contains the following members:
int ncompat;
.Ed
.It Fa struct isapnp_region
Describes ISAPNP bus-space regions. It contains the following
members:
Describes ISAPNP bus-space regions.
It contains the following members:
.Bd -literal
bus_space_handle_t h;
u_int32_t base;
@ -109,7 +111,8 @@ members:
.Ed
.It Fa struct isapnp_pin
Describes the wiring of interrupts and DMA pins from the ISAPNP bus
onto the host processor. It contains the following members:
onto the host processor.
It contains the following members:
.Bd -literal
u_int8_t num;
u_int8_t flags:4;
@ -117,8 +120,8 @@ onto the host processor. It contains the following members:
u_int16_t bits;
.Ed
.It Fa struct isapnp_attach_args
A structure used to inform the driver of the device properties. It
contains the following members:
A structure used to inform the driver of the device properties.
It contains the following members:
.Bd -literal
bus_space_tag_t ipa_iot; /* isa i/o space tag */
bus_space_tag_t ipa_memt; /* isa mem space tag */
@ -152,7 +155,8 @@ bus-space tags
.Fa iot
and
.Fa memt
respectively. The
respectively.
The
.Fa ipa_io ,
.Fa ipa_mem ,
.Fa ipa_mem32 ,
@ -171,8 +175,8 @@ Free the resources allocated by
.Sh AUTOCONFIGURATION
During autoconfiguration, an ISAPNP driver will receive a pointer to
.Fa struct isapnp_attach_args
describing the device attached to the ISAPNP bus. Drivers match the
device using
describing the device attached to the ISAPNP bus.
Drivers match the device using
.Fn ispnp_devmatch .
.Pp
During the driver attach step, driver should initially allocate and
@ -218,7 +222,8 @@ This section describes places within the
source tree where actual code implementing or utilising the
machine-independent
.Nm
subsystem can be found. All pathnames are relative to
subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The
@ -229,8 +234,8 @@ The database of the known devices exists within the file
.Pa sys/dev/isapnp/isapnpdevs.c
and is generated automatically from the file
.Pa sys/dev/isapnp/isapnpdevs .
New devices should be added to this file. The database can be
regenerated using the Makefile
New devices should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/isapnp/Makefile.isapnpdevs .
.Sh SEE ALSO
.Xr isa 4 ,

26
share/man/man9/kprintf.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: kprintf.9,v 1.12 2002/02/13 08:18:43 ross Exp $
.\" $NetBSD: kprintf.9,v 1.13 2002/10/14 13:43:25 wiz Exp $
.\"
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -75,8 +75,9 @@ The functions
.Fn snprintf
and
.Fn vsnprintf
write output to a string buffer. These four functions work similarly
to their user space counterparts, and are not described in detail here.
write output to a string buffer.
These four functions work similarly to their user space counterparts,
and are not described in detail here.
.Pp
The functions
.Fn uprintf
@ -90,10 +91,11 @@ The
function sends formatted strings to a process's controlling tty,
via a handle of type tpr_t.
This allows multiple write operations to the tty with a guarantee that the
tty will be valid across calls. A handle is acquired by calling
tty will be valid across calls.
A handle is acquired by calling
.Fn tprintf_open
with the target process as an argument. This handle must be closed with
a matching call to
with the target process as an argument.
This handle must be closed with a matching call to
.Fn tprintf_close .
.Sh RETURN VALUES
The
@ -114,7 +116,8 @@ The
and
.Fn vsprintf
unsized string formatting functions are supported for compatibility only,
and are not documented here. New code should use the size-limited
and are not documented here.
New code should use the size-limited
.Fn snprintf
and
.Fn vsnprintf
@ -126,8 +129,8 @@ and earlier,
.Fn printf
supported more format strings than the user space
.Fn printf .
These nonstandard format strings are no longer supported. For the
functionality provided by the former
These nonstandard format strings are no longer supported.
For the functionality provided by the former
.Li %b
format string, see
.Xr bitmask_snprintf 9 .
@ -136,7 +139,8 @@ The
.Fn uprintf
and
.Fn ttyprintf
functions should be used sparingly, if at all. Where multiple lines of
output are required to reach a process's controlling terminal,
functions should be used sparingly, if at all.
Where multiple lines of output are required to reach a process's
controlling terminal,
.Fn tprintf
is preferred.

21
share/man/man9/kthread.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: kthread.9,v 1.8 2002/10/09 15:27:23 itojun Exp $
.\" $NetBSD: kthread.9,v 1.9 2002/10/14 13:43:25 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -53,9 +53,10 @@
"const char *fmt" "..."
.Sh DESCRIPTION
Kernel threads are light-weight processes which execute entirely
within the kernel. Any process can request the creation of a new
kernel thread. Kernel threads are not swapped out during memory
congestion. The VM space and limits are shared with proc0 (usually swapper).
within the kernel.
Any process can request the creation of a new kernel thread.
Kernel threads are not swapped out during memory congestion.
The VM space and limits are shared with proc0 (usually swapper).
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn kthread_create1 "void (*func)(void *)" "void *arg" "struct proc **newpp" "const char *fmt" "..."
@ -73,16 +74,17 @@ thread name.
.It Fn kthread_create "void (*func)(void *)" "void *arg"
Register function
.Fa func
to defer creation of the kernel thread. Deferral of kernel thread
creation is required during system startup when kernel thread resources
are not available.
to defer creation of the kernel thread.
Deferral of kernel thread creation is required during system startup
when kernel thread resources are not available.
.It Fn kthread_exit "int ecode"
Exit from a kernel thread.
.El
.Sh RETURN VALUES
Upon successful completion,
.Fn kthread_create1
returns 0. Otherwise, the following error values are returned:
returns 0.
Otherwise, the following error values are returned:
.Bl -tag -width [EAGAIN]
.It Bq Er EAGAIN
The limit on the total number of system processes would be exceeded.
@ -96,7 +98,8 @@ user id would be exceeded.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the kthread
framework can be found. All pathnames are relative to
framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The kthread framework itself is implemented within the file

13
share/man/man9/linedisc.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: linedisc.9,v 1.6 2002/02/13 08:18:44 ross Exp $
.\" $NetBSD: linedisc.9,v 1.7 2002/10/14 13:43:25 wiz Exp $
.\"
.\" Copyright (c) 2000 Christopher G. Demetriou.
.\" All rights reserved.
@ -66,13 +66,14 @@ and calling
The following is a brief description of each function in the framework:
.Bl -tag -width "ttyldisc_remove()"
.It Fn ttyldisc_add
Register a line discipline. The
Register a line discipline.
The
.Fa l_name
field of the
.Fa struct linesw
should point to a string which is to be the symbolic
name of that line discipline. For compatibility
purposes, a line discipline number can be passed in
name of that line discipline.
For compatibility purposes, a line discipline number can be passed in
.Fa no ,
but for new disciplines this should be set to
.Dv -1 .
@ -84,8 +85,8 @@ is returned if it can not be found.
.It Fn ttyldisc_remove
Remove a line discipline called
.Fa name
and return a pointer to it. If the discipline cannot
be found or removed
and return a pointer to it.
If the discipline cannot be found or removed
.Fn ttyldisc_remove
will return
.Dv NULL .

174
share/man/man9/lock.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: lock.9,v 1.14 2002/07/14 04:08:44 gmcgarry Exp $
.\" $NetBSD: lock.9,v 1.15 2002/10/14 13:43:26 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -81,34 +81,37 @@ The
.Nm
functions provide synchronisation in the kernel by preventing multiple
threads from simultaneously executing critical sections of code
accessing shared data. A number of different locks are available:
accessing shared data.
A number of different locks are available:
.Pp
.Bl -tag -width compact
.It struct simplelock
Provides a simple spinning mutex. A processor will busy-wait while
trying to acquire a simplelock. The simplelock operations are
implemented with machine-dependent locking primitives.
Provides a simple spinning mutex.
A processor will busy-wait while trying to acquire a simplelock.
The simplelock operations are implemented with machine-dependent
locking primitives.
.Pp
Simplelocks are usually used only by the high-level lock manager and
to protect short, critical sections of code. Simplelocks are the only
locks that can be be used inside an interrupt handler. For a
simplelock to be used in an interrupt handler, care must be taken to
to protect short, critical sections of code.
Simplelocks are the only locks that can be be used inside an interrupt
handler.
For a simplelock to be used in an interrupt handler, care must be taken to
disable the interrupt, acquire the lock, do any processing, release
the simplelock and re-enable the interrupt. This procedure is
necessary to avoid deadlock between the interrupt handler and other
threads executing on the same processor.
the simplelock and re-enable the interrupt.
This procedure is necessary to avoid deadlock between the interrupt handler
and other threads executing on the same processor.
.It struct lock
Provides a high-level lock supporting sleeping/spinning until the lock
can be acquired. The lock manager supplies both exclusive-access and
shared-access locks, with recursive exclusive-access locks within a
single thread. It also allows upgrading a shared-access lock to an
exclusive-access lock, as well as downgrading an exclusive-access lock
to a shared-access lock.
can be acquired.
The lock manager supplies both exclusive-access and shared-access locks,
with recursive exclusive-access locks within a single thread.
It also allows upgrading a shared-access lock to an exclusive-access
lock, as well as downgrading an exclusive-access lock to a shared-access lock.
.El
.Pp
If the kernel option LOCKDEBUG is enabled, additional facilities
are provided to record additional lock information. These facilities are
provided to assist in determining deadlock occurrences.
are provided to record additional lock information.
These facilities are provided to assist in determining deadlock occurrences.
.Sh FUNCTIONS
The functions which operate on simplelocks are:
.Pp
@ -116,45 +119,51 @@ The functions which operate on simplelocks are:
.It Fn simple_lock_init "slock"
The simplelock
.Fa slock
is initialised to the unlocked state. A statically allocated simplelock
also can be initialised with the macro SIMPLELOCK_INITIALIZER. The
effect is the same as the dynamic initialisation by a call to
simple_lock_init. For example,
is initialised to the unlocked state.
A statically allocated simplelock also can be initialised with the
macro SIMPLELOCK_INITIALIZER.
The effect is the same as the dynamic initialisation by a call to
simple_lock_init.
For example,
.Pp
struct simplelock slock = SIMPLELOCK_INITIALIZER;
.It Fn simple_lock "slock"
The simplelock
.Fa slock
is locked. If the simplelock is held then execution will
spin until the simplelock is acquired. Care must be taken that the
calling thread does not already hold the simplelock. In this case, the
simplelock can never be acquired. If kernel option LOCKDEBUG is enabled,
a "locking against myself" panic will occur.
is locked.
If the simplelock is held then execution will spin until the simplelock
is acquired.
Care must be taken that the calling thread does not already hold
the simplelock.
In this case, the simplelock can never be acquired.
If kernel option LOCKDEBUG is enabled, a "locking against myself" panic
will occur.
.It Fn simple_lock_try "slock"
Try to acquire the simplelock
.Fa slock
without spinning. If the simplelock is held by another thread
then the return value is 0. If the simplelock was acquired
successfully then the return value is 1.
without spinning.
If the simplelock is held by another thread then the return value is 0.
If the simplelock was acquired successfully then the return value is 1.
.It Fn simple_unlock "slock"
The simplelock
.Fa slock
is unlocked. The simplelock must be locked and the calling thread must
be the one that last acquired the simplelock. If the calling
thread does not hold the simplelock, the simplelock will be released
but the kernel behaviour is undefined.
is unlocked.
The simplelock must be locked and the calling thread must be the one
that last acquired the simplelock.
If the calling thread does not hold the simplelock, the simplelock will
be released but the kernel behaviour is undefined.
.It Fn simple_lock_freecheck "start" "end"
Check that all simplelocks in the address range
.Fa start
to
.Fa end
are not held. If a simplelock within the range is found, the kernel
enters the debugger. This function is available only with kernel
option LOCKDEBUG. It provides a mechanism for basic simplelock
consistency checks.
are not held.
If a simplelock within the range is found, the kernel enters the debugger.
This function is available only with kernel option LOCKDEBUG.
It provides a mechanism for basic simplelock consistency checks.
.It Fn simple_lock_dump "void"
Dump the state of all simplelocks in the kernel. This function is
available only with kernel option LOCKDEBUG.
Dump the state of all simplelocks in the kernel.
This function is available only with kernel option LOCKDEBUG.
.El
.Pp
The functions which operate on locks are:
@ -163,8 +172,8 @@ The functions which operate on locks are:
.It Fn lockinit "lock" "prio" "wmesg" "timo" "flags"
The lock
.Fa lock
is initialised according to the parameters provided. Arguments are as
follows:
is initialised according to the parameters provided.
Arguments are as follows:
.Bl -tag -width compact
.It Fa lock
The lock.
@ -174,11 +183,13 @@ The thread priority when it is woken up after sleeping on the lock.
A sleep message used when a thread goes to sleep waiting for the lock, so
that the exact reason it is sleeping can easily be identified.
.It Fa timo
The maximum sleep time. Used by
The maximum sleep time.
Used by
.Xr tsleep 9 .
.It Fa flags
Flags to specify the lock behaviour permanently over the lifetime of
the lock. Valid lock flags are:
the lock.
Valid lock flags are:
.Bl -tag -width compact
.It LK_NOWAIT
Threads should not sleep when attempting to acquire the lock.
@ -195,23 +206,25 @@ Arguments are as follows:
.It Fa lock
The lock.
.It Fa slock
Simplelock interlock. If the flag LK_INTERLOCK is set in
Simplelock interlock.
If the flag LK_INTERLOCK is set in
.Fa flags ,
.Fa slock
is a simplelock held by the caller. When the lock
is a simplelock held by the caller.
When the lock
.Fa lock
is acquired, the simplelock is released. If the flag LK_INTERLOCK is
not set,
is acquired, the simplelock is released.
If the flag LK_INTERLOCK is not set,
.Fa slock
is ignored.
.It Fa flags
Flags to specify the lock request type. In addition to the flags
specified above, the following flags are valid:
Flags to specify the lock request type.
In addition to the flags specified above, the following flags are valid:
.Bl -tag -width compact
.It LK_SHARED
Get one of many possible shared-access locks. If a thread holding an
exclusive-access lock requests a shared-access lock, the
exclusive-access lock is downgraded to a shared-access lock.
Get one of many possible shared-access locks.
If a thread holding an exclusive-access lock requests a shared-access
lock, the exclusive-access lock is downgraded to a shared-access lock.
.It LK_EXCLUSIVE
Stop further shared-access locks, when they are cleared, grant a
pending upgrade if it exists, then grant an exclusive-access lock.
@ -222,21 +235,22 @@ the lock request, or if the LK_CANRECURSE flag was set when the lock
was initialised.
.It LK_UPGRADE
The thread must hold a shared-access lock that it wants to have
upgraded to an exclusive-access lock. Other threads may get exclusive
access to the protected resource between the time that the upgrade is
requested and the time that it is granted.
upgraded to an exclusive-access lock.
Other threads may get exclusive access to the protected resource between
the time that the upgrade is requested and the time that it is granted.
.It LK_EXCLUPGRADE
The thread must hold a shared-access lock that it wants to have
upgraded to an exclusive-access lock. If the request succeeds, no
other threads will have acquired exclusive access to the protected
resource between the time that the upgrade is requested and the time
that it is granted. However, if another thread has already requested
an upgrade, the request will fail.
upgraded to an exclusive-access lock.
If the request succeeds, no other threads will have acquired exclusive
access to the protected resource between the time that the upgrade is
requested and the time that it is granted.
However, if another thread has already requested an upgrade, the request
will fail.
.It LK_DOWNGRADE
The thread must hold an exclusive-access lock that it wants to have
downgraded to a shared-access lock. If the thread holds multiple
(recursive) exclusive-access locks, they will all be downgraded to
shared-access locks.
downgraded to a shared-access lock.
If the thread holds multiple (recursive) exclusive-access locks, they
will all be downgraded to shared-access locks.
.It LK_RELEASE
Release one instance of a lock.
.It LK_DRAIN
@ -244,8 +258,9 @@ Wait for all activity on the lock to end, then mark it decommissioned.
This feature is used before freeing a lock that is part of a piece of
memory that is about to be freed.
.It LK_REENABLE
Lock is to be re-enabled after drain. The LK_REENABLE flag may be set
only at the release of a lock obtained by a drain.
Lock is to be re-enabled after drain.
The LK_REENABLE flag may be set only at the release of a lock obtained
by a drain.
.It LK_SETRECURSE
Other locks while we have it OK.
.It LK_RECURSEFAIL
@ -277,8 +292,8 @@ The lock.
.It Fa wmesg
This is a simple name for lock.
.It Fa flags
Flags to specify the lock behaviour. Valid lock flags are the same as
outlined above.
Flags to specify the lock behaviour.
Valid lock flags are the same as outlined above.
.El
.It Fn spinlockmgr "lock" "flags" "slock"
Set, change or release a lock according to the parameters provided.
@ -287,22 +302,24 @@ Arguments are as follows:
.It Fa lock
The spin lock.
.It Fa flags
Flags to specify the lock request type. Valid lock flags are the same
as outlined above.
Flags to specify the lock request type.
Valid lock flags are the same as outlined above.
.It Fa slock
Simplelock interlock. The simplelock
Simplelock interlock.
The simplelock
.Fa slock
is set by the caller. When the lock
is set by the caller.
When the lock
.Fa lock
is acquired, the simplelock is released.
.El
.El
.Sh RETURN VALUES
Successfully acquired locks return 0. A failed lock attempt always
returns a non-zero error value. No lock is held after an error
return (in particular, a failed LK_UPGRADE or LK_FORCEUPGRADE will
have released its shared-access lock). Locks will always succeed
unless one of the following is true:
Successfully acquired locks return 0.
A failed lock attempt always returns a non-zero error value.
No lock is held after an error return (in particular, a failed
LK_UPGRADE or LK_FORCEUPGRADE will have released its shared-access lock).
Locks will always succeed unless one of the following is true:
.Bl -tag -width Er
.It Bq Er EBUSY
LK_FORCEUPGRADE is requested and some other thread has already
@ -323,7 +340,8 @@ Non-null lock timeout and timeout expires.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the locking
framework can be found. All pathnames are relative to
framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The locking framework itself is implemented within the file

13
share/man/man9/ltsleep.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ltsleep.9,v 1.1 2002/09/29 17:36:17 wiz Exp $
.\" $NetBSD: ltsleep.9,v 1.2 2002/10/14 13:43:26 wiz Exp $
.\"
.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -132,13 +132,14 @@ will return
.It Fa slock
If not NULL, the
.Fa slock
interlock is unlocked once the scheduler lock is acquired. Unless
interlock is unlocked once the scheduler lock is acquired.
Unless
.Dv PNORELOCK
was set,
.Fa slock
is locked again once
the process is resumed from sleep. This provides wakeup-before-sleep
condition protection facility.
the process is resumed from sleep.
This provides wakeup-before-sleep condition protection facility.
.El
.Pp
The
@ -191,8 +192,8 @@ returns because of a timeout it returns
.Xr hz 9 ,
.Xr lock 9
.Sh HISTORY
The sleep/wakeup process synchronization mechanism is very old. It
appeared in a very early version of Unix.
The sleep/wakeup process synchronization mechanism is very old.
It appeared in a very early version of Unix.
.Fn tsleep
appeared in
.Bx 4.4 .

6
share/man/man9/malloc.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: malloc.9,v 1.25 2002/06/27 17:31:25 yamt Exp $
.\" $NetBSD: malloc.9,v 1.26 2002/10/14 13:43:26 wiz Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -132,8 +132,8 @@ the call can still wait for resources.
.Pp
Rather than depending on
.Dv M_CANFAIL ,
kernel code should do proper bound checking itself. This
flag should only be used in cases where this is not feasible.
kernel code should do proper bound checking itself.
This flag should only be used in cases where this is not feasible.
Since it can hide real kernel bugs, it's usage is
.Em strongly discouraged .
.El

8
share/man/man9/mbuf.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: mbuf.9,v 1.22 2002/05/12 15:48:38 wiz Exp $
.\" $NetBSD: mbuf.9,v 1.23 2002/10/14 13:43:26 wiz Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -293,7 +293,8 @@ Creates a copy of an mbuf chain starting
.Fa off0
bytes from the beginning, continuing for
.Fa len
bytes. If the
bytes.
If the
.Fa len
requested is
.Dv M_COPYALL ,
@ -422,7 +423,8 @@ must be smaller or equal than
Partitions an mbuf chain in two pieces, returning the tail,
which is all but the first
.Fa len0
bytes. In case of failure, it returns
bytes.
In case of failure, it returns
.Dv NULL
and attempts to
restore the chain to its original state.

69
share/man/man9/mca.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: mca.9,v 1.4 2002/02/13 08:18:45 ross Exp $
.\" $NetBSD: mca.9,v 1.5 2002/10/14 13:43:27 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -65,24 +65,28 @@
The
.Nm
device provides support for IBM's MicroChannel Architecture bus found
on IBM PS/2 systems and selected workstations. It was designed as a
replacement bus for the ISA bus found on IBM's older machines.
on IBM PS/2 systems and selected workstations.
It was designed as a replacement bus for the ISA bus found on IBM's
older machines.
However, the bus specifications were only available under license, so
MCA did not achieve widespread acceptance in the industry.
.Pp
Being a replacement for the ISA bus, the MCA bus does share some
similar aspects with the ISA bus. Some MCA devices can be detected
via the usual ISA-style probing. However, most device detection is
done through the Programmable Option Select (POS) registers. These
registers provide a window into a device to determine device-specific
properties and configuration. The configuration of devices and their
POS registers is performed using IBM's system configuration software.
similar aspects with the ISA bus.
Some MCA devices can be detected via the usual ISA-style probing.
However, most device detection is done through the Programmable Option
Select (POS) registers.
These registers provide a window into a device to determine device-specific
properties and configuration.
The configuration of devices and their POS registers is performed using
IBM's system configuration software.
.Pp
The MCA bus uses level-triggered interrupts while the ISA bus uses
edge-triggered interrupts. Level triggered interrupts have the
advantage that they can be shared among multiple device. Therefore,
most MCA-specific devices should be coded with shared interrupts in
mind.
edge-triggered interrupts.
Level triggered interrupts have the advantage that they can be shared
among multiple device.
Therefore, most MCA-specific devices should be coded with shared
interrupts in mind.
.Sh DATA TYPES
Drivers for devices attached to the MCA bus will make use of the
following data types:
@ -144,28 +148,31 @@ on the MCA bus specified by
.Fa mc .
.El
.Sh AUTOCONFIGURATION
The MCA bus is a direct-connection bus. During autoconfiguration, the
parent specifies the MCA device ID for the found device in the
The MCA bus is a direct-connection bus.
During autoconfiguration, the parent specifies the MCA device ID for the
found device in the
.Fa ma_id
member of the
.Em mca_attach_args
structure. Drivers should match on the device ID. Device
capabilities and configuration information should be read from device
POS registers using
structure.
Drivers should match on the device ID.
Device capabilities and configuration information should be read from
device POS registers using
.Fn mca_conf_read .
Some important configuration information found in the POS registers
include the I/O base address, memory base address and interrupt
number. The location of these configurable options with the POS
registers are device specific.
number.
The location of these configurable options with the POS registers are
device specific.
.Sh DMA SUPPORT
The MCA bus supports 32-bit, bidirectional DMA transfers. Currently,
no machine-independent support for MCA DMA is available.
The MCA bus supports 32-bit, bidirectional DMA transfers.
Currently, no machine-independent support for MCA DMA is available.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent MCA subsystem can be found. All pathnames are
relative to
machine-independent MCA subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The MCA subsystem itself is implemented within the file
@ -176,13 +183,14 @@ The database of known devices exists within the file
.Fa sys/dev/mca/mcadevs_data.h
and is generated automatically from the file
.Pa sys/dev/mca/mcadevs .
New vendor and product identifiers should be added to this
file. The database can be regenerated using the Makefile
New vendor and product identifiers should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/mca/Makefile.mcadevs .
.Pp
A good source of information about MCA devices is IBM's system
configuration disk. The disk contains .adf files which describe the
location of device configuration options in the POS registers.
configuration disk.
The disk contains .adf files which describe the location of device
configuration options in the POS registers.
.Sh SEE ALSO
.Xr mca 4 ,
.Xr autoconf 9 ,
@ -193,5 +201,6 @@ location of device configuration options in the POS registers.
.Sh BUGS
The machine-independent
.Nm
driver does not currently support DMA. MCA devices which require DMA
operation currently access the DMA capabilities directly.
driver does not currently support DMA.
MCA devices which require DMA operation currently access the DMA
capabilities directly.

5
share/man/man9/memcpy.9
View File

@ -34,7 +34,7 @@
.\" SUCH DAMAGE.
.\"
.\" from: @(#)memcpy.3 8.1 (Berkeley) 6/4/93
.\" $NetBSD: memcpy.9,v 1.3 2002/02/13 08:18:45 ross Exp $
.\" $NetBSD: memcpy.9,v 1.4 2002/10/14 13:43:27 wiz Exp $
.\"
.Dd July 7, 2001
.Dt MEMCPY 9
@ -57,7 +57,8 @@ bytes from string
to string
.Fa dst .
The arguments must not overlap -- behavior if the arguments overlap is
undefined. To copy byte strings that overlap, use
undefined.
To copy byte strings that overlap, use
.Xr memmove 9 .
.Sh RETURN VALUES
The

89
share/man/man9/namei.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: namei.9,v 1.3 2002/02/13 08:18:47 ross Exp $
.\" $NetBSD: namei.9,v 1.4 2002/10/14 13:43:27 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -61,7 +61,8 @@
.Sh DESCRIPTION
The
.Nm
interface is used to convert pathnames to file system vnodes. The
interface is used to convert pathnames to file system vnodes.
The
name of the interface is actually a contraction of the words
.Em name
and
@ -72,7 +73,8 @@ interface was implemented.
.Pp
The arguments passed to the functions are uncapsulated in the
.Em nameidata
structure. It has the following structure:
structure.
It has the following structure:
.Bd -literal
struct nameidata {
/*
@ -111,11 +113,12 @@ partially initialised
structure
.Em ni_cnd .
This structure describes the subset of information from the nameidata
structure that is passed through to the vnode operations. See
structure that is passed through to the vnode operations.
See
.Xr vnodeops 9
for more information. The details of the componentname structure are
not absolutely necessary since the members are initialised by the
helper macro
for more information.
The details of the componentname structure are not absolutely necessary
since the members are initialised by the helper macro
.Fn NDINIT .
It is useful to know the operations and flags as specified in
.Xr vnodeops 9 .
@ -124,10 +127,11 @@ The
.Nm
interface overloads
.Em ni_cnd.cn_flags
with some additional flags. These flags should be specific to the
with some additional flags.
These flags should be specific to the
.Nm
interface and ignored by vnode operations. However, due to the
historic close relationship between the
interface and ignored by vnode operations.
However, due to the historic close relationship between the
.Nm
interface and the vnode operations, these flags are sometimes used
(and set) by vnode operations, particularly
@ -168,33 +172,35 @@ mask of parameter descriptors
.Pp
If the caller of
.Fn namei
sets the SAVENAME flag, then it must free the buffer. If
sets the SAVENAME flag, then it must free the buffer.
If
.Fn VOP_LOOKUP
sets the flag, then the buffer must be freed by either the commit
routine or the
.Fn VOP_ABORT
routine. The SAVESTART flag is set only by the callers of
routine.
The SAVESTART flag is set only by the callers of
.Fn namei .
It implies SAVENAME plus the addition of saving the parent directory
that contains the name in
.Em ni_startdir .
It allows repeated calls to
.Fn lookup
for the name being sought. The caller is responsible for releasing
the buffer and for invoking
for the name being sought.
The caller is responsible for releasing the buffer and for invoking
.Fn vrele
on
.Em ni_startdir .
.Pp
All access to the
.Nm
interface must be in process context. Pathname lookups cannot be done
in interrupt context.
interface must be in process context.
Pathname lookups cannot be done in interrupt context.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn namei "ndp"
Convert a pathname into a pointer to a locked inode. The pathname is
specified by
Convert a pathname into a pointer to a locked inode.
The pathname is specified by
.Em ndp-\*[Gt]ni_dirp
and is of length
.Em ndp-\*[Gt]ni_pathlen .
@ -203,18 +209,19 @@ The
flags defines whether the name in
.Em ndp-\*[Gt]ni_dirp
is an address in kernel space (UIO_SYSSPACE) or an address in user
space (UIO_USERSPACE). The locked vnode for the pathname is returned
in
space (UIO_USERSPACE).
The locked vnode for the pathname is returned in
.Em ndp-\*[Gt]ni_vp .
.Pp
If
.Em ndp-\*[Gt]ni_cnd.cn_flags
has the FOLLOW flag set then symbolic links are followed when they
occur at the end of the name translation process. Symbolic links are
always followed for all other pathname components other than the last.
occur at the end of the name translation process.
Symbolic links are always followed for all other pathname components
other than the last.
.It Fn lookup "ndp"
Search for a pathname. This is a very central and rather complicated
routine.
Search for a pathname.
This is a very central and rather complicated routine.
.Pp
The pathname is specified by
.Em ndp-\*[Gt]ni_dirp
@ -237,13 +244,15 @@ If
has LOCKPARENT set, the parent directory is returned locked in
.Em ndp-\*[Gt]ni_dvp .
If WANTPARENT is set, the parent directory is returned unlocked.
Otherwise the parent directory is not returned. If the target of the
pathname exists and LOCKLEAF is set, the target is returned locked in
Otherwise the parent directory is not returned.
If the target of the pathname exists and LOCKLEAF is set, the target
is returned locked in
.Em ndp-\*[Gt]ni_vp ,
otherwise it is returned unlocked.
.It Fn relookup "dvp" "vpp" "cnp"
Reacquire a path name component is a directory. This is a quicker way
to lookup a pathname component when the parent directory is known.
Reacquire a path name component is a directory.
This is a quicker way to lookup a pathname component when the parent
directory is known.
The unlocked parent directory vnode is specified by
.Fa dvp
and the pathname component by
@ -255,20 +264,21 @@ Initialise a nameidata structure pointed to by
.Fa ndp
for use by the
.Nm
interface. It saves having to deal with the componentname structure
inside
interface.
It saves having to deal with the componentname structure inside
.Fa ndp .
The operation and flags are specified by
.Fa op
and
.Fa flags
respectively. These are the values
respectively.
These are the values
.Em ndp-\*[Gt]ni_cnd.cn_nameiop
and
.Em ndp-\*[Gt]ni_cnd.cn_flags
are respectively set to. The segment flags which defines whether the
pathname is in kernel address space or user address space is specified
by
are respectively set to.
The segment flags which defines whether the pathname is in kernel
address space or user address space is specified by
.Fa segflag .
The argument
.Fa namep
@ -282,7 +292,8 @@ is the calling process.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the name
lookup subsystem can be found. All pathnames are relative to
lookup subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The name lookup subsystem is implemented within the file
@ -296,7 +307,7 @@ The name lookup subsystem is implemented within the file
.Sh BUGS
It is unfortunate that much of the
.Nm
interface makes assumptions on the underlying vnode operations. These
assumptions are an artefact of the introduction of the vfs interface
to split a file system interface which was historically designed as a
tightly coupled module.
interface makes assumptions on the underlying vnode operations.
These assumptions are an artefact of the introduction of the vfs
interface to split a file system interface which was historically
designed as a tightly coupled module.

140
share/man/man9/pci.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pci.9,v 1.7 2002/08/04 01:03:12 gmcgarry Exp $
.\" $NetBSD: pci.9,v 1.8 2002/10/14 13:43:27 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -128,31 +128,36 @@ The machine-independent
subsystem provides support for PCI devices.
.Pp
The PCI bus was initially developed by Intel in the early 1990's to
replace the ISA bus for interfacing with their Pentium processor. The
PCI specification is widely regarded as well designed, and the PCI bus
has found widespread acceptance in machines ranging from Apple's
PowerPC-based systems to Sun's UltraSPARC-based machines.
replace the ISA bus for interfacing with their Pentium processor.
The PCI specification is widely regarded as well designed, and the
PCI bus has found widespread acceptance in machines ranging from
Apple's PowerPC-based systems to Sun's UltraSPARC-based machines.
.Pp
The PCI bus is a multiplexed bus, allowing addresses and data on the same
pins for a reduced number of pins. Data transfers can be 8-bit,
16-bit or 32-bit. A 64-bit extended PCI bus is also defined.
Multi-byte transfers are little-endian. The PCI bus operates up to
33MHz and any device on the bus can be the bus master.
pins for a reduced number of pins.
Data transfers can be 8-bit, 16-bit or 32-bit.
A 64-bit extended PCI bus is also defined.
Multi-byte transfers are little-endian.
The PCI bus operates up to 33MHz and any device on the bus can be
the bus master.
.Pp
AGP is a version of PCI optimised for high-throughput data rates,
particularly for accelerated frame buffers.
.Pp
The PCI bus is a "plug and play" bus, in the sense that devices can be
configured dynamically by software. The PCI interface chip on a PCI
device bus presents a small window of registers into the PCI
configuration space. These registers contain information about the
device such as the vendor and a product ID. The configuration
registers can also be written to by software to alter how the device
interfaces to the PCI bus. An important register in the configuration
space is the Base Address Register (BAR). The BAR is written to by
software to map the device registers into a window of processor
address space. Once this mapping is done, the device registers can be
accessed relative to the base address.
configured dynamically by software.
The PCI interface chip on a PCI device bus presents a small window
of registers into the PCI configuration space.
These registers contain information about the device such as the vendor
and a product ID.
The configuration registers can also be written to by software to alter
how the device interfaces to the PCI bus.
An important register in the configuration space is the Base Address
Register (BAR).
The BAR is written to by software to map the device registers into a
window of processor address space.
Once this mapping is done, the device registers can be accessed relative
to the base address.
.Sh DATA TYPES
Drivers for devices attached to the
.Nm
@ -164,15 +169,16 @@ Configuration space register.
Chipset tag for the PCI bus.
.It Fa pcitag_t
Configuration tag describing the location and function of the PCI
device. It contains the tuple
device.
It contains the tuple
.Ao
bus, device, function
.Ac .
.It Fa pci_intr_handle_t
The opaque handle describing an established interrupt handler.
.It Fa struct pci_attach_args
Devices have their identity recorded in this structure. It contains
the following members:
Devices have their identity recorded in this structure.
It contains the following members:
.Bd -literal
bus_space_tag_t pa_iot; /* pci i/o space tag */
bus_space_tag_t pa_memt; /* pci mem space tag */
@ -189,20 +195,23 @@ the following members:
.It Fn pci_conf_read "pc" "tag" "reg"
Read from register
.Fa reg
in PCI configuration space. The argument
in PCI configuration space.
The argument
.Fa tag
is the PCI tag for the current device attached to PCI chipset
.Fa pc .
.It Fn pci_conf_write "pc" "tag" "reg" "val"
Write to register
.Fa reg
in PCI configuration space. The argument
in PCI configuration space.
The argument
.Fa tag
is the PCI tag for the current device attached to PCI chipset
.Fa pc .
.It Fn pci_conf_print "pc" "tag" "func"
Print out most of the registers in the PCI configuration for the
device. The argument
device.
The argument
.Fa tag
is the PCI tag for the current device attached to PCI chipset
.Fa pc .
@ -210,21 +219,22 @@ The argument
.Fa func
is a function called by
.Fn pci_conf_print
to print the device-dependent registers. This function is only useful
for driver development and is usually wrapped in pre-processor
declarations.
to print the device-dependent registers.
This function is only useful for driver development and is usually
wrapped in pre-processor declarations.
.It Fn pci_find_device "pa" "func"
Find a device using a match function on all probed busses. The
argument
Find a device using a match function on all probed busses.
The argument
.Fa func
is called by
.Fn pci_find_device
to match a device. The argument
to match a device.
The argument
.Fa pa
is filled in if the device is matched.
.Fn pci_find_device
returns 1 if the device is matched, and zero otherwise. This function
is specifically for use by LKMs (see
returns 1 if the device is matched, and zero otherwise.
This function is specifically for use by LKMs (see
.Xr lkm 4 )
and its use otherwise is strongly discouraged.
.It Fn pci_get_capability "pc" "tag" "capid" "offsetp" "valuep"
@ -243,8 +253,8 @@ The argument
.Fa tag
is the PCI tag for the current device attached to PCI chipset
.Fa pc .
This function returns 1 if the capability was found. If the
capability was not found, it returns zero, and
This function returns 1 if the capability was found.
If the capability was not found, it returns zero, and
.Fa offsetp
and
.Fa valuep
@ -253,8 +263,8 @@ remain unchanged.
Interrogates the Base Address Register (BAR) in configuration space
specified by
.Fa reg
and returns the default (or current) mapping type. Valid returns
values are:
and returns the default (or current) mapping type.
Valid returns values are:
.Bl -tag -width compact
.It PCI_MAPREG_TYPE_IO
The mapping is to I/O address space.
@ -275,8 +285,9 @@ is the PCI tag for the current device attached to PCI chipset
.Fa "basep" "sizep"
.Fc
Maps the register windows for the device into kernel virtual address
space. This function is generally only called during the driver
attach step and takes a pointer to the
space.
This function is generally only called during the driver attach step
and takes a pointer to the
.Em struct pci_attach_args
in
.Fa pa .
@ -306,11 +317,13 @@ returned in
.Fa tagp
and
.Fa handlep
respectively. The bus-address and size of the mapping are returned in
respectively.
The bus-address and size of the mapping are returned in
.Fa basep
and
.Fa sizep
respectively. If any of
respectively.
If any of
.Fa tagp ,
.Fa handlep ,
.Fa basep ,
@ -318,18 +331,20 @@ or
.Fa sizep
are NULL then
.Fn pci_mapreg_map
does not define their return value. This function returns zero on
success and non-zero on error.
does not define their return value.
This function returns zero on success and non-zero on error.
.It Fn pci_mapreg_info "pc" "tag" "reg" "type" "basep" "sizep" "flagsp"
Performs the same operations as
.Fn pci_mapreg_map
but doesn't actually map the register window into kernel virtual
address space. Returns the bus-address, size and bus flags in
address space.
Returns the bus-address, size and bus flags in
.Fa basep ,
.Fa sizep
and
.Fa flagsp
respectively. These return values can be used by
respectively.
These return values can be used by
.Fn bus_space_map
to actually map the register window into kernel virtual address space.
This function is useful for setting up the registers in configuration
@ -353,7 +368,8 @@ See
See
.Xr pci_intr 9 .
.It Fn pci_set_powerstate "pc" "tag" "newstate"
Set power state of the device to newstate. Valid values for
Set power state of the device to newstate.
Valid values for
.Fa newstate
are:
.Pp
@ -370,9 +386,9 @@ Create a new PCI tag for the PCI device specified by the tuple
.Ao
bus, device, function
.Ac .
This function is not useful to the usual PCI device driver. It is
generally used by drivers of multi-function devices when attaching
other PCI device drivers to each function.
This function is not useful to the usual PCI device driver.
It is generally used by drivers of multi-function devices when
attaching other PCI device drivers to each function.
.It Fn pci_decompose_tag "pc" "tag" "busp" "devicep" "fnp"
Decompose the PCI tag
.Fa tag
@ -413,8 +429,8 @@ During autoconfiguration, a
.Nm
driver will receive a pointer to
.Fa struct pci_attach_args
describing the device attaches to the PCI bus. Drivers match the
device using the
describing the device attaches to the PCI bus.
Drivers match the device using the
.Fa pa_id
member using
.Fn PCI_VENDOR .
@ -427,8 +443,8 @@ configuration space using
.Fn pci_conf_read .
The meaning attached to registers in the PCI configuration space are
device-dependent, but will usually contain physical addresses of the
device register windows. Device options can also be stored into the
PCI configuration space using
device register windows.
Device options can also be stored into the PCI configuration space using
.Fn pci_conf_write .
For example, the driver can request support for bus-mastering DMA by
writing the option to the PCI configuration space.
@ -449,12 +465,12 @@ Device registers can now be accessed using the standard bus-space API
Details of using PCI interrupts is described in
.Xr pci_intr 9 .
.Sh DMA SUPPORT
The PCI bus supports bus-mastering operations from any device on the
bus. The DMA facilities are accessed through the standard
The PCI bus supports bus-mastering operations from any device on the bus.
The DMA facilities are accessed through the standard
.Xr bus_dma 9
interface. To support DMA transfers from the device to the host, it
is necessary to enable bus-mastering in the PCI configuration space
for the device.
interface.
To support DMA transfers from the device to the host, it is necessary
to enable bus-mastering in the PCI configuration space for the device.
.Pp
During system shutdown, it is necessary to abort any DMA transfers in
progress by registering a shutdown hook (see
@ -463,8 +479,8 @@ progress by registering a shutdown hook (see
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent PCI subsystem can be found. All pathnames are
relative to
machine-independent PCI subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The PCI subsystem itself is implemented within the files
@ -481,8 +497,8 @@ The database of known devices exists within the file
.Pa sys/dev/pci/pcidevs_data.h
and is generated automatically from the file
.Pa sys/dev/pci/pcidevs .
New vendor and product identifiers should be added to this
file. The database can be regenerated using the Makefile
New vendor and product identifiers should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/pci/Makefile.pcidevs .
.Sh SEE ALSO
.Xr pci 4 ,

59
share/man/man9/pci_configure_bus.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pci_configure_bus.9,v 1.8 2002/02/25 00:40:19 kleink Exp $
.\" $NetBSD: pci_configure_bus.9,v 1.9 2002/10/14 13:43:28 wiz Exp $
.\"
.\" Copyright 2001 Wasabi Systems, Inc.
.\" All rights reserved.
@ -55,7 +55,8 @@
.Sh DESCRIPTION
The
.Fn pci_configure_bus
function configures a PCI bus for use. This involves:
function configures a PCI bus for use.
This involves:
.Bl -bullet
.It
Defining bus numbers for all busses on the system,
@ -77,28 +78,37 @@ should be called prior to the auto-configuration of the bus.
The
.Fa pc
argument is a machine-dependent tag used to specify the PCI chipset to the
system. This should be the same value used with
system.
This should be the same value used with
.Fn pci_make_tag .
The extent arguments
define memory extents from which the address space for the cards will be
taken. These addresses should be in the PCI address space. The
taken.
These addresses should be in the PCI address space.
The
.Fa ioext
extent is for PCI I/O accesses. The
extent is for PCI I/O accesses.
The
.Fa memext
extent is for PCI memory accesses that might have side effects. I.e.,
that can not be cached. The
extent is for PCI memory accesses that might have side effects.
I.e., that can not be cached.
The
.Fa pmemext
extent is for PCI memory accesses that can be cached. The
extent is for PCI memory accesses that can be cached.
The
.Fa pmemext
extent will be used for any ROMs and any memory regions that are marked as
.Dq prefetchable
in their BAR. If an implementation does not distinguish between
in their BAR.
If an implementation does not distinguish between
prefetchable and non-prefetchable memory, it may pass NULL for
.Fa pmemext .
In this case, prefetchable memory allocations will be made from the
non-prefetchable region. The
non-prefetchable region.
The
.Fa firstbus
argument indicates the number of the first bus to be configured. The
argument indicates the number of the first bus to be configured.
The
.Fa cacheline_size
argument is used to configure the PCI Cache Line Size Register; it
should be the size, in bytes, of the largest D-cache line on the system.
@ -107,15 +117,16 @@ An implementation may choose to not have full configuration performed
by
.Fn pci_configure_bus
on certain PCI devices, such as PCI host bridges or PCI bus analyzers
which are instantiated as devices on the bus. In order for this to
take place, the header
which are instantiated as devices on the bus.
In order for this to take place, the header
.Aq Pa machine/pci_machdep.h
must define the
.Dv __HAVE_PCI_CONF_HOOK
symbol (without a value), and a machine-dependent function
.Fn pci_conf_hook
(declared in the same header)
must be defined. The prototype for this function is
must be defined.
The prototype for this function is
.Pp
.Fn "int pci_conf_hook" "pci_chipset_tag_t pc" "int bus" \
"int device" "int function" "pcireg_t id"
@ -156,10 +167,12 @@ One of the functions of
.Fn pci_configure_bus
is to configure interrupt
.Dq line
information. This must be done on a machine-dependent basis, so a
information.
This must be done on a machine-dependent basis, so a
machine-dependent function
.Fn pci_conf_interrupt
must be defined. The prototype for this function is
must be defined.
The prototype for this function is
.Pp
.Fn "void pci_conf_interrupt" "pci_chipset_tag_t pc" "int bus" \
"int device" "int function" "int swiz" "int *iline"
@ -169,13 +182,14 @@ In this function,
.Fa device ,
and
.Fa function ,
uniquely identify the item being configured. The
uniquely identify the item being configured.
The
.Fa swiz
argument is a
.Dq swizzle ,
a sum of the device numbers of the primary interface of the bridges between
the host bridge and the current device. The function is responsible for
setting the value of
the host bridge and the current device.
The function is responsible for setting the value of
.Fa iline .
See chapter 9 of the
.Dq PCI-to-PCI Bridge Architecture Specification
@ -183,9 +197,10 @@ for more information on swizzling (also known as interrupt routing).
.Sh RETURN VALUES
If successful
.Fn pci_configure_bus
returns 0. A non-zero return value means that the bus was not completely
configured for some reason. A description of the failure will be displayed
on the console.
returns 0.
A non-zero return value means that the bus was not completely
configured for some reason.
A description of the failure will be displayed on the console.
.Sh ENVIRONMENT
The
.Fn pci_configure_bus

16
share/man/man9/pci_intr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pci_intr.9,v 1.9 2002/05/19 15:24:35 wiz Exp $
.\" $NetBSD: pci_intr.9,v 1.10 2002/10/14 13:43:28 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -59,8 +59,8 @@
The
.Nm
functions exist to allow device drivers machine-independent access to
PCI bus interrupts. The functions described in this page are
typically declared in a port's
PCI bus interrupts.
The functions described in this page are typically declared in a port's
.Pa Aq machine/pci_machdep.h
header file; however, drivers should generally include
.Pa Aq dev/pci/pcivar.h
@ -82,8 +82,8 @@ it should pass the
.Ft struct pci_attach_args *
to the
.Fn pci_intr_map
function, which returns zero on success, and nonzero on failure. The function
sets the
function, which returns zero on success, and nonzero on failure.
The function sets the
.Ft pci_intr_handle_t
pointed at by its second argument to a machine-dependent value which
identifies a particular interrupt source.
@ -124,9 +124,9 @@ to determine how the device's interrupts are routed.
.Ed
.Pp
PCI-PCI
bridges swizzle (permute) interrupt wiring. Depending on
implementation details, it may be more convenient to use either
original or the swizzled interrupt parameters.
bridges swizzle (permute) interrupt wiring.
Depending on implementation details, it may be more convenient to use
either original or the swizzled interrupt parameters.
The original device tag and interrupt pin can be found in
.Ft pa_tag
and

92
share/man/man9/pcmcia.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pcmcia.9,v 1.8 2002/02/13 08:18:48 ross Exp $
.\" $NetBSD: pcmcia.9,v 1.9 2002/10/14 13:43:28 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -117,29 +117,32 @@
The machine-independent
.Nm
subsystem provides support for PC-Card devices defined by the Personal
Computer Memory Card International Assocation (PCMCIA). The
Computer Memory Card International Assocation (PCMCIA).
The
.Nm
bus supports insertion and removal of cards while a system is
powered-on (ie, dynamic reconfiguration). The socket must be
powered-off when a card is not present. To the user, this appears as
though the socket is "hot" during insertion and removal events.
powered-on (ie, dynamic reconfiguration).
The socket must be powered-off when a card is not present.
To the user, this appears as though the socket is "hot" during
insertion and removal events.
.Pp
A PCMCIA controller interfaces the PCMCIA bus with the ISA or PCI
busses on the host system. The controller is responsible for
detecting and enabling devices and for allocating and mapping
resources such as memory and interrupts to devices on the
PCMCIA bus.
busses on the host system.
The controller is responsible for detecting and enabling devices and
for allocating and mapping resources such as memory and interrupts
to devices on the PCMCIA bus.
.Pp
Each device has a table called the Card Information Structure (CIS)
which contains configuration information. The tuples in the CIS are
used by the controller to uniquely identify the device. Additional
information may be present in the CIS, such as the ethernet MAC
address, that can be accessed and utilised within a device driver.
which contains configuration information.
The tuples in the CIS are used by the controller to uniquely identify
the device.
Additional information may be present in the CIS, such as the ethernet
MAC address, that can be accessed and utilised within a device driver.
.Pp
Devices on the PCMCIA bus are uniquely identified by a 32-bit
manufacturer ID and a 32-bit product ID. Additionally, devices can
perform multiple functions (such a ethernet and modem) and these
functions are identified by a function ID.
manufacturer ID and a 32-bit product ID.
Additionally, devices can perform multiple functions (such a ethernet
and modem) and these functions are identified by a function ID.
.Pp
PCMCIA devices do not support DMA, however memory on the device can be
mapped into the address space of the host.
@ -149,8 +152,8 @@ Drivers attached to the
bus will make use of the following data types:
.Bl -tag -width compact
.It Fa struct pcmcia_card
Devices (cards) have their identity recorded in this structure. It
contains the following members:
Devices (cards) have their identity recorded in this structure.
It contains the following members:
.Bd -literal
char *cis1_info[4];
int32_t manufacturer;
@ -159,9 +162,10 @@ contains the following members:
SIMPLEQ_HEAD(, pcmcia_function) pf_head;
.Ed
.It Fa struct pcmcia_function
Identifies the function of the devices. A device can have multiple
functions. Consider it an opaque type for identifying a particular
function of a device.
Identifies the function of the devices.
A device can have multiple functions.
Consider it an opaque type for identifying a particular function
of a device.
.It struct pcmcia_config_entry
Contains information about the resources requested by the device.
It contains the following members:
@ -188,14 +192,15 @@ It contains the following members:
.It Fa struct pcmcia_tuple
A handle for identifying an entry in the CIS.
.It Fa struct pcmcia_io_handle
A handle for mapping and allocating I/O address spaces. It contains
the tag and handle for accessing the bus-space.
A handle for mapping and allocating I/O address spaces.
It contains the tag and handle for accessing the bus-space.
.It Fa struct pcmcia_mem_handle
A handle for mapping and allocating memory address spaces. It contains
the tag and handle for accessing the bus-space.
A handle for mapping and allocating memory address spaces.
It contains the tag and handle for accessing the bus-space.
.It Fa struct pcmcia_attach_args
A structure used to inform the driver of the
device properties. It contains the following members:
device properties.
It contains the following members:
.Bd -literal
int32_t manufacturer;
int32_t product;
@ -243,7 +248,8 @@ An I/O window of size
.Fa size
is mapped at offset
.Fa offset
in the chipset I/O window. The width of data access is specified by
in the chipset I/O window.
The width of data access is specified by
.Fa width .
Valid values for the width are:
.Bl -tag -width PCMCIA_WIDTH_AUTO
@ -371,8 +377,8 @@ During autoconfiguration, a
.Nm
driver will receive a pointer to
.Fa struct pcmcia_attach_args
describing the device attached to the PCMCIA bus. Drivers match the
device using the
describing the device attached to the PCMCIA bus.
Drivers match the device using the
.Em manufacturer
and
.Em product
@ -381,23 +387,25 @@ members.
During the driver attach step, drivers will use the pcmcia function
.Em pf .
The driver should traverse the list of config entries searching for a
useful configuration. This config entry is passed to
useful configuration.
This config entry is passed to
.Fn pcmcia_function_init
to initialise the machine-independent interface. I/O and memory
resources should be initialised using
to initialise the machine-independent interface.
I/O and memory resources should be initialised using
.Fn pcmcia_io_alloc
and
.Fn pcmcia_mem_alloc
using the specified resources in the config entry. These resources
can then be mapped into processor bus space using
using the specified resources in the config entry.
These resources can then be mapped into processor bus space using
.Fn pcmcia_io_map
and
.Fn pcmcia_mem_map
respectively. Upon successful allocation of resources, power can be
applied to the device with
respectively.
Upon successful allocation of resources, power can be applied to the
device with
.Fn pcmcia_function_enable
so that device-specific interrogation can be performed. Finally,
power should be removed from the device using
so that device-specific interrogation can be performed.
Finally, power should be removed from the device using
.Fn pcmcia_function_disable .
.Pp
Since PCMCIA devices support dynamic configuration, drivers should
@ -411,8 +419,8 @@ PCMCIA devices do not support DMA.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent PCMCIA subsystem can be found. All pathnames are
relative to
machine-independent PCMCIA subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The PCMCIA subsystem itself is implemented within the file
@ -421,8 +429,8 @@ The database of known devices exists within the file
.Pa sys/dev/pcmcia/pcmciadevs_data.h
and is generated automatically from the file
.Pa sys/dev/pcmcia/pcmciadevs .
New manufacturer and product identifiers should be added to this
file. The database can be regenerated using the Makefile
New manufacturer and product identifiers should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/pcmcia/Makefile.pcmciadevs .
.Sh SEE ALSO
.Xr pcic 4 ,

53
share/man/man9/pfil.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pfil.9,v 1.18 2002/07/16 00:36:45 lha Exp $
.\" $NetBSD: pfil.9,v 1.19 2002/10/14 13:43:29 wiz Exp $
.\"
.\" Copyright (c) 1996 Matthew R. Green
.\" All rights reserved.
@ -64,17 +64,20 @@
The
.Nm
framework allows for a specified function to be invoked for every
incoming or outgoing packet for a particular network I/O stream. These
hooks may be used to implement a firewall or perform packet transformations.
incoming or outgoing packet for a particular network I/O stream.
These hooks may be used to implement a firewall or perform packet
transformations.
.Nm
Packet filtering points are registered with
.Fn pfil_head_register .
Filtering points are identified by a key (void *) and a data link type
(int) in the
.Em pfil_head
structure. Packet filters use the key and data link type to look up
the filtering point with which they register themselves. The key is
unique to the filtering point. The data link type is a
structure.
Packet filters use the key and data link type to look up the filtering
point with which they register themselves.
The key is unique to the filtering point.
The data link type is a
.Xr bpf 4
DLT constant indicating what kind of header is present on the packet
at the filtering point.
@ -87,22 +90,26 @@ with the
.Fn pfil_add_hook
and
.Fn pfil_remove_hook
functions, respectively. The head is looked up using the
functions, respectively.
The head is looked up using the
.Fn pfil_head_get
function, which takes the key and data link type that the packet filter
expects. Filters may provide an argument to be passed to the filter
when invoked on a packet.
expects.
Filters may provide an argument to be passed to the filter when
invoked on a packet.
.Pp
When a filter is invoked, the packet appears just as if it
.Dq came off the wire .
That is, all protocol fields are in network byte order. The filter is
called with its specified argument, the pointer to the pointer to the
mbuf containing the packet, the pointer to the network interface that
the packet is traversing, and the direction (PFIL_IN or PFIL_OUT) that
the packet is traveling. The filter may change which mbuf the mbuf **
argument references. The filter returns an errno if the packet processing
is to stop, or 0 if the processing is to continue. If the packet processing
is to stop, it is the responsibility of the filter to free the packet.
That is, all protocol fields are in network byte order.
The filter is called with its specified argument, the pointer to the
pointer to the mbuf containing the packet, the pointer to the network
interface that the packet is traversing, and the direction (PFIL_IN
or PFIL_OUT) that the packet is traveling.
The filter may change which mbuf the mbuf ** argument references.
The filter returns an errno if the packet processing is to stop, or 0
if the processing is to continue.
If the packet processing is to stop, it is the responsibility of the
filter to free the packet.
.Pp
The
.Nm
@ -126,18 +133,18 @@ however this was changed in
.Nx 1.4
to
.Dv TAILQ
structures. This change was to allow the input and output filters to be
processed in reverse order, to allow the same path to be taken, in or out
of the kernel.
structures.
This change was to allow the input and output filters to be processed in
reverse order, to allow the same path to be taken, in or out of the kernel.
.Pp
The
.Nm
interface was changed in 1.4T to accept a 3rd parameter to both
.Fn pfil_add_hook
and
.Fn pfil_remove_hook
, introducing the capability of per-protocol filtering. This was done
primarily in order to support filtering of IPv6.
.Fn pfil_remove_hook ,
introducing the capability of per-protocol filtering.
This was done primarily in order to support filtering of IPv6.
.Pp
In
.Nx 1.5K ,

48
share/man/man9/pmc.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pmc.9,v 1.1 2002/08/07 04:48:56 briggs Exp $
.\" $NetBSD: pmc.9,v 1.2 2002/10/14 13:43:29 wiz Exp $
.\"
.\" Copyright (c) 2002 Wasabi Systems, Inc.
.\" All rights reserved.
@ -93,19 +93,19 @@
.Fn PMC_ENABLED "struct proc *p"
.Sh DESCRIPTION
Provides a machine-independent interface to the hardware performance counters
which are available on several CPU families. The capabilities of these
counters vary from CPU to CPU, but they basically count hardware events
such as data cache hits or misses, branches taken, branched mispredicted,
and so forth. Some can interrupt the processor when a certain threshold
has been reached. Some can count events in user space and kernel space
independently.
which are available on several CPU families.
The capabilities of these counters vary from CPU to CPU, but they
basically count hardware events such as data cache hits or misses,
branches taken, branched mispredicted, and so forth.
Some can interrupt the processor when a certain threshold has been reached.
Some can count events in user space and kernel space independently.
.Pp
The
.Nm
interface is intended to allow monitoring from within the kernel as well
as monitoring of userland applications. If the hardware can interrupt the
CPU in a specific implementation, then it may also be used as a profiling
source instead of the clock.
as monitoring of userland applications.
If the hardware can interrupt the CPU in a specific implementation,
then it may also be used as a profiling source instead of the clock.
.Sh NOTES
All function calls in this interface may be defined as
.Xr cpp 1
@ -150,7 +150,8 @@ are currently unused.
.Sh FUNCTIONS
.Bl -tag -width width -compact
.It Fn pmc_get_num_counters "void"
Returns the number of counters present on the current system. Valid values for
Returns the number of counters present on the current system.
Valid values for
.Fa ctr
in the interface entry points below are from zero to one less than the
return value from this function.
@ -158,26 +159,28 @@ return value from this function.
.It Fn pmc_get_counter_type "int ctr"
Returns an implementation-dependent type describing the specified counter.
If ctr is specified as -1, returns a machine-dependent type describing the
CPU or counter configuration. For example, on an ia32 architecture, it may
distinguish between 586-, 686-, and K7-style counters.
CPU or counter configuration.
For example, on an ia32 architecture, it may distinguish between
586-, 686-, and K7-style counters.
.sp
.It Fn pmc_save_context "struct proc *p"
Saves the PMC context for the current process. This is called just before
Saves the PMC context for the current process.
This is called just before
.Xr cpu_switch 9 .
If there is kernel PMC state, it must be maintained across this call.
.sp
.It Fn pmc_restore_context "struct proc *p"
Restores the PMC context for the current process. This is called just
after
Restores the PMC context for the current process.
This is called just after
.Xr cpu_switch 9
returns. If there is kernel PMC state, it must be maintained across
this call.
returns.
If there is kernel PMC state, it must be maintained across this call.
.sp
.It Fn pmc_enable_counter "struct proc *p" "int ctr"
Enables counter
.Fa ctr
for the specified process. The counter should have already been configured
with a call to
for the specified process.
The counter should have already been configured with a call to
.Fn pmc_configure_counter .
This starts the counter running if it is not already started and enables
any interrupts, as appropriate.
@ -185,8 +188,9 @@ any interrupts, as appropriate.
.It Fn pmc_disable_counter "struct proc *p" "int ctr"
Disables counter
.Fa ctr
for the specified process. This stops the counter from running, and
disables any interrupts, as appropriate.
for the specified process.
This stops the counter from running, and disables any interrupts,
as appropriate.
.sp
.It Fn pmc_counter_isrunning "struct proc *p" "int ctr"
Returns non-zero if the specified counter in the specified process is

5
share/man/man9/pool.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: pool.9,v 1.24 2002/08/20 16:25:51 wiz Exp $
.\" $NetBSD: pool.9,v 1.25 2002/10/14 13:43:29 wiz Exp $
.\"
.\" Copyright (c) 1997, 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -128,7 +128,8 @@ when the pool will never be accessed from interrupt context.
.Ss DESTROYING A POOL
The function
.Fn pool_destroy
destroys a resource pool. It takes a single argument
destroys a resource pool.
It takes a single argument
.Fa pp
identifying the pool resource instance.
.Ss ALLOCATING ITEMS FROM A POOL

18
share/man/man9/powerhook_establish.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: powerhook_establish.9,v 1.3 2001/06/21 11:59:01 wiz Exp $
.\" $NetBSD: powerhook_establish.9,v 1.4 2002/10/14 13:43:30 wiz Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -53,7 +53,8 @@ function adds
.Fa fn
of the list of hooks invoked by
.Xr dopowerhooks 9
at power change. When invoked, the hook function
at power change.
When invoked, the hook function
.Fa fn
will be passed the new power state as the first argument and
.Fa arg
@ -63,21 +64,23 @@ The
.Fn powerhook_disestablish
function removes the hook described by the opaque pointer
.Fa cookie
from the list of hooks to be invoked at power change. If
from the list of hooks to be invoked at power change.
If
.Fa cookie
is invalid, the result of
.Fn powerhook_disestablish
is undefined.
.Pp
Power hooks should be used to perform activities
that must happen when the power situation to the computer changes. Because
of the environment in which they are run, shutdown hooks cannot
that must happen when the power situation to the computer changes.
Because of the environment in which they are run, shutdown hooks cannot
rely on many system services (including file systems, and timeouts
and other interrupt-driven services).
The power hooks are typically executed from an interrupt context.
.Pp
The different reasons for calling the power hooks are: suspend, standby, and
resume. The reason is reflected in the
resume.
The reason is reflected in the
.Fa why
argument and the values
.Dv PWR_SOFTSUSPEND ,
@ -97,6 +100,7 @@ back to normal.
If successful,
.Fn powerhook_establish
returns an opaque pointer describing the newly-established
shutdown hook. Otherwise, it returns NULL.
shutdown hook.
Otherwise, it returns NULL.
.Sh SEE ALSO
.Xr dopowerhooks 9

82
share/man/man9/properties.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: properties.9,v 1.3 2002/02/13 08:18:49 ross Exp $
.\" $NetBSD: properties.9,v 1.4 2002/10/14 13:43:30 wiz Exp $
.\"
.\" Copyright (c) 2001 Eduardo Horvath
.\" All rights reserved.
@ -75,7 +75,8 @@ property management routines allow kernel subsystems to associate
.Po name , value Pc
pairs with arbitrary keys in a generalized manner.
.Pp
A database is a container for a set of properties. It is created with
A database is a container for a set of properties.
It is created with
.Fn propdb_create
and discarded with
.Fn propdb_destroy .
@ -85,8 +86,8 @@ namespace conflicts.
A property is a tuple that consists of an opaque identifier
.Po often a pointer to a kernel data structure
.Pc ,
string, and an arbitrary amount of data. This
association is established by
string, and an arbitrary amount of data.
This association is established by
.Fn prop_set ,
retrieved by
.Fn prop_get ,
@ -117,9 +118,10 @@ type is a 64-bit scalar type used to store arbitrary object identifiers.
The
.Nm
makes no type distinctions, but it does associate a type datum with each
property. Users of the interface can use that field to help determine what
information is stored in the value field of the property. There are three
base types:
property.
Users of the interface can use that field to help determine what
information is stored in the value field of the property.
There are three base types:
.El
.Pp
.Bl -tag -width "PROP_ELSZ(type) " -compact -offset indent
@ -139,8 +141,9 @@ Property is an array of values.
.It PROP_CONST
Property value has static storage and is maintained outside the database.
.It PROP_ELSZ Pq Fa size
Encode element size into the type field. This is primarily used to describe
the size of individual elements of an array.
Encode element size into the type field.
This is primarily used to describe the size of individual elements
of an array.
.El
.Sh FUNCTIONS
.Bl -tag -width indent
@ -151,14 +154,15 @@ Allocate and initialize a kernel database object, and associate
with the database.
.Fa name
may later be used to access this database from userland throught the
userland database query interface. This operation may block.
userland database query interface.
This operation may block.
Returns
.Li NULL
on failure.
.Pp
.It Fn "void propdb_destroy" "propdb_t db"
Destroy and deallocate a kernel database and all data within. This
routine deallocates all properties contained within the database.
Destroy and deallocate a kernel database and all data within.
This routine deallocates all properties contained within the database.
.Pp
.It Fn "int prop_set" "propdb_t db" "opaque_t object" "const char *name" \
"void *val" "size_t len" "int type" "int wait"
@ -175,16 +179,20 @@ byte value copied from location
The database must already have been initialized with
.Fn propdb_create .
.Fa object
is treated as an opaque value. If
is treated as an opaque value.
If
.Fa len
is
.Li 0
then no data is copied. This can be used to create properties which
convey information by their presence or absence. The
then no data is copied.
This can be used to create properties which convey information by
their presence or absence.
The
.Fa type
field is used to identify what the format of the object is. This value
is usually only used to help programs dump property values into human
readable formats. However, if
field is used to identify what the format of the object is.
This value is usually only used to help programs dump property values
into human readable formats.
However, if
.Li PROP_CONST
is specified in the
.Fa type
@ -193,11 +201,13 @@ queried it will copy
.Fa len
bytes directly from the location specified by
.Fa val ,
so that data cannot be freed or the kernel may panic. If
so that data cannot be freed or the kernel may panic.
If
.Fa wait
is zero then
.Fn prop_set
will not sleep for resource shortage. Returns
will not sleep for resource shortage.
Returns
.Li 0
on success, or an error value.
.Pp
@ -208,7 +218,8 @@ Retrieve a property called
associated with
.Fa object .
.Fa name
is a pointer to a string. The property that matches both
is a pointer to a string.
The property that matches both
.Fa object
and
.Fa name
@ -234,7 +245,8 @@ the type information associated with that property is stored in the location
it points to.
.Pp
.It Fn "int prop_delete" "propdb_t db" "opaque_t object" "const char *name"
Remove a property from a database. If a
Remove a property from a database.
If a
.Li NULL
is supplied for
.Fa name ,
@ -249,26 +261,30 @@ Copy all properties associated with
.Fa source
to
.Fa dest
structure. If
structure.
If
.Fa wait
is zero then
.Fn prop_copy
will not sleep for resource shortage. Returns
will not sleep for resource shortage.
Returns
.Li 0
on success or an error value. The state of properties is undefined if the
operation fails.
on success or an error value.
The state of properties is undefined if the operation fails.
.It Fn "size_t prop_objs" "propdb_t db" "opaque_t *objects" "size_t len"
Get a list of objects identifiers from a database. An array of object
idientifiers will be copied into the buffer pointed to by
Get a list of objects identifiers from a database.
An array of object idientifiers will be copied into the buffer pointed
to by
.Fa objects
up to
.Fa len
bytes. It returns the amount of memory needed to store the entire list.
bytes.
It returns the amount of memory needed to store the entire list.
.Pp
.It Fn "size_t prop_list" "propdb_t db" "opaque_t object" "char *names" \
"size_t len"
Get a list of an object's properties from the database. It queries the
database to locate all properties associated with
Get a list of an object's properties from the database.
It queries the database to locate all properties associated with
.Pa object
objedt identifier, and copies up to
.Pa len
@ -277,8 +293,8 @@ bytes of
terminated property names into the buffer pointed to by
.Pa names .
Partial strings are not copied, and another NUL character to indicate the
termination of the list. It returns the size needed to hold the
entire list.
termination of the list.
It returns the size needed to hold the entire list.
.El
.Sh HISTORY
The

20
share/man/man9/ras.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ras.9,v 1.2 2002/08/29 11:27:03 wiz Exp $
.\" $NetBSD: ras.9,v 1.3 2002/10/14 13:43:30 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -54,9 +54,9 @@
.Fn ras_purgeall "struct proc *p"
.Sh DESCRIPTION
Restartable atomic sequences are user code sequences which are
guaranteed to execute without preemption. This property is assured by
checking the set of restartable atomic sequences registered for a
process during
guaranteed to execute without preemption.
This property is assured by checking the set of restartable atomic
sequences registered for a process during
.Xr cpu_switch 9 .
If a process is found to have been preempted during a restartable
sequence, then its execution is rolled-back to the start of the
@ -75,10 +75,11 @@ for machine-independent code to conditionally provide RAS support.
A complicated side-effect of restartable atomic sequences is their
interaction with the machine-dependent
.Xr ptrace 2
support. Specifically, single-step traps and/or the emulation of
single-stepping must carefully consider the effect on restartable
atomic sequences. A general solution is to ignore these traps or
disable them within restartable atomic sequences.
support.
Specifically, single-step traps and/or the emulation of single-stepping
must carefully consider the effect on restartable atomic sequences.
A general solution is to ignore these traps or disable them within
restartable atomic sequences.
.Sh FUNCTIONS
The functions which operate on restartable atomic sequences are:
.Pp
@ -116,7 +117,8 @@ and by
This section describes places within the
.Nx
source tree where actual code implementing or utilising the RAS
functionality can be found. All pathnames are relative to
functionality can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The RAS framework itself is implemented within the file

20
share/man/man9/rasops.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: rasops.9,v 1.4 2002/02/13 08:18:50 ross Exp $
.\" $NetBSD: rasops.9,v 1.5 2002/10/14 13:43:31 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -153,21 +153,24 @@ completed successfully
.It Fn rasops_init "ri" "wantrows" "wantcols"
Initialise a
.Em rasops_info
desriptor. The arguments
desriptor.
The arguments
.Fa wantrows
and
.Fa wantcols
are the number of rows and columns we'd like. In terms of
optimization, fonts that are a multiple of 8 pixels wide work the
best.
are the number of rows and columns we'd like.
In terms of optimization, fonts that are a multiple of 8 pixels wide
work the best.
.It Fn rasops_reconfig "ri" "wantrows" "wantcols"
Reconfigure a
.Em rasops_info
descriptor because parameters have changed in some way. The arguments
descriptor because parameters have changed in some way.
The arguments
.Fa wantrows
and
.Fa wantcols
are the number of rows and columns we'd like. If calling
are the number of rows and columns we'd like.
If calling
.Fn rasops_reconfig
to change the font and ri_wsfcookie \*[Ge] 0, you must call
.Fn wsfont_unlock
@ -177,7 +180,8 @@ on it, and reset it to -1 (or a new, valid cookie).
This section describes places within the
.Nx
source tree where actual code implementing or utilising the rasops
subsystem can be found. All pathnames are relative to
subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The rasops subsystem is implemented within the directory

21
share/man/man9/ratecheck.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ratecheck.9,v 1.7 2002/02/13 08:18:50 ross Exp $
.\" $NetBSD: ratecheck.9,v 1.8 2002/10/14 13:43:31 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -56,23 +56,26 @@ and
.Fa lasttime
is less than the value given by the
.Fa mininterval
argument, zero is returned. Otherwise,
argument, zero is returned.
Otherwise,
.Fa lasttime
is set to the current time and a non-zero value is returned.
.Pp
The motivation for implementing
.Fn ratecheck
was to provide a mechanism that could be used to add rate limiting to
diagnostic message output. If printed too often, diagnostic messages can
keep the system from doing useful work. If the repeated messages can
be caused by deliberate user action or network events, they can be
exploited to cause denial of system service.
diagnostic message output.
If printed too often, diagnostic messages can keep the system from
doing useful work.
If the repeated messages can be caused by deliberate user action
or network events, they can be exploited to cause denial of system service.
.Pp
Note that using a very short time interval (less than a second)
for
.Fa mininterval
defeats the purpose of this function. (It doesn't
take much to flood a 9600 baud serial console with output, for instance.)
defeats the purpose of this function.
(It doesn't take much to flood a 9600 baud serial console with
output, for instance.)
.Sh EXAMPLES
Here is a simple example of use of the
.Fn ratecheck
@ -88,7 +91,7 @@ struct timeval drv_lasterr2time; /* time of last err2 message */
long drv_err2count; /* # of err2 errs since last msg */
/*
* the following variable will often be global or shared by all
* The following variable will often be global or shared by all
* instances of a driver. It should be initialized, so it can be
* patched. Allowing it to be set via an option might be nice,
* but could lead to an insane proliferation of options.

5
share/man/man9/resettodr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: resettodr.9,v 1.6 2001/09/04 02:51:16 wiz Exp $
.\" $NetBSD: resettodr.9,v 1.7 2002/10/14 13:43:31 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -57,4 +57,5 @@ On many systems,
has to convert from
.Va time
to a time expressed in terms of year, month, day, hours, minutes,
and seconds. Many of the implementations could share code, but do not.
and seconds.
Many of the implementations could share code, but do not.

42
share/man/man9/rnd.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: rnd.9,v 1.12 2002/08/19 17:41:46 wiz Exp $
.\" $NetBSD: rnd.9,v 1.13 2002/10/14 13:43:31 wiz Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -64,7 +64,8 @@ Ideally the first argument
.Fa rnd_source
of these functions gets included in the devices' entity struct,
but any means to permanently (static) attach one such argument
to one incarnation of the device is ok. Do not share
to one incarnation of the device is ok.
Do not share
.Fa rnd_source
structures between two devices.
.Pp
@ -76,9 +77,9 @@ It must be called before the source struct pointed to by
is used in any of the following functions.
.Pp
.Fa devname
is the name of the device. It is used to print a message (if the kernel is
compiled with ``options RND_VERBOSE'') and also for status information printed
with
is the name of the device.
It is used to print a message (if the kernel is compiled with
``options RND_VERBOSE'') and also for status information printed with
.Xr rndctl 8 .
.Pp
.Fa source_type
@ -92,7 +93,8 @@ for a tape drive, and
.Dv RND_TYPE_TTY
for a tty.
.Dv RND_TYPE_UNKNOWN
is not to be used as a type. It is used internally to the rnd system.
is not to be used as a type.
It is used internally to the rnd system.
.Pp
.Fa flags
are the logical OR of
@ -100,8 +102,8 @@ are the logical OR of
(don't collect or estimate)
.Dv RND_FLAG_NO_ESTIMATE
(don't estimate)
to control the default setting for collection and estimation. Note that
devices of type
to control the default setting for collection and estimation.
Note that devices of type
.Dv RND_TYPE_NET
default to
.Dv RND_FLAG_NO_ESTIMATE .
@ -111,25 +113,27 @@ This function disconnects the device from entropy collection.
.It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "u_int32_t datum"
This function adds the value of
.Va datum
to the entropy pool. No entropy is assumed to be collected from this value,
it merely helps stir the entropy pool. All entropy is gathered from
jitter between the timing of events.
to the entropy pool.
No entropy is assumed to be collected from this value, it merely helps
stir the entropy pool.
All entropy is gathered from jitter between the timing of events.
.Pp
Note that using a constant for
.Va datum
does not weaken security, but it does
not help. Try to use something that can change, such as an interrupt status
register which might have a bit set for receive ready or transmit ready,
or other device status information.
not help.
Try to use something that can change, such as an interrupt status register
which might have a bit set for receive ready or transmit ready, or other
device status information.
.Pp
To allow the system to gather the timing information accurately, this call
should be placed within the actual hardware interrupt service routine. Care
must be taken to ensure that the interrupt was actually serviced by the
interrupt handler, since on some systems interrupts can be shared.
should be placed within the actual hardware interrupt service routine.
Care must be taken to ensure that the interrupt was actually serviced by
the interrupt handler, since on some systems interrupts can be shared.
.Pp
This function loses nearly all usefulness if it is called from a scheduled
software interrupt. If that is the only way to add the device as an entropy
source, don't.
software interrupt.
If that is the only way to add the device as an entropy source, don't.
.Pp
If it is desired to mix in the
.Va datum

36
share/man/man9/rt_timer.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: rt_timer.9,v 1.8 2002/02/13 08:18:50 ross Exp $
.\" $NetBSD: rt_timer.9,v 1.9 2002/10/14 13:43:32 wiz Exp $
.\"
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -68,11 +68,13 @@ This was originally intended to be used to remove routes added
by path MTU discovery code.
.Pp
For maximum efficiency, a separate queue should be defined for each
timeout period. For example, one queue should be created for the
10 minute path MTU discovery timeouts, another for 20 minute ARP
timeouts after 20 minutes, and so on. This permits extremely fast
queue manipulations so that the timeout functions remain scalable,
even in the face of thousands of route manipulations per minute.
timeout period.
For example, one queue should be created for the 10 minute path MTU
discovery timeouts, another for 20 minute ARP timeouts after 20
minutes, and so on.
This permits extremely fast queue manipulations so that the timeout
functions remain scalable, even in the face of thousands of route
manipulations per minute.
.Pp
It is possible to create only a single timeout queue for all possible
timeout values, but doing so is not scalable as queue manipulations
@ -88,13 +90,13 @@ This function creates a new timer queue with the specified timeout period
expressed in seconds.
.It Fn rt_timer_queue_change "rttimer_queue *q" "time_t timeout"
This function modifies the timeout period for a timer queue.
Any value, including 0, is valid. The next time the timer queue's
timeout expires (based on the previous timeout value), all entries
which are valid to execute based on the new timeout will be executed,
and the new timeout period scheduled.
Any value, including 0, is valid.
The next time the timer queue's timeout expires (based on the previous
timeout value), all entries which are valid to execute based on the new
timeout will be executed, and the new timeout period scheduled.
.It Fn rt_timer_queue_destroy "rttimer_queue *q" "int destroy"
This function destroys a timeout queue. All entries are removed,
and if the
This function destroys a timeout queue.
All entries are removed, and if the
.Fa destroy
argument is non-zero, the timeout action is performed for each entry.
.It Fn rt_timer_add "struct rtentry *rt" \
@ -112,16 +114,18 @@ the route will be deleted when the timeout expires.
.It Fn rt_timer_remove_all "struct rtentry *rt"
This function removes all references to the given route from the
.Nm
subsystem. This is used when a route is deleted to ensure that no
dangling references remain.
subsystem.
This is used when a route is deleted to ensure that no dangling
references remain.
.El
.Sh SEE ALSO
.Xr netstat 1 ,
.Xr arp 9
.Sh AUTHORS
This interface is roughly based on (but, alas, not compatible with) one
designed by David Borman of BSDI. This implementation is by Kevin Lahey
of the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
designed by David Borman of BSDI.
This implementation is by Kevin Lahey of the Numerical Aerospace
Simulation Facility, NASA Ames Research Center.
.Sh CODE REFERENCES
The
.Nm

124
share/man/man9/scsipi.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: scsipi.9,v 1.10 2002/05/15 11:17:32 bouyer Exp $
.\" $NetBSD: scsipi.9,v 1.11 2002/10/14 13:43:32 wiz Exp $
.\"
.\"
.\" Copyright (c) 2001 Manuel Bouyer.
@ -66,10 +66,11 @@
The
.Nm
system is the middle layer interface between SCSI/ATAPI host bus
adapters (HBA) and high-level SCSI/ATAPI drivers. This document
describes the interfaces provided by the
adapters (HBA) and high-level SCSI/ATAPI drivers.
This document describes the interfaces provided by the
.Nm
layer towards the HBA layer. An HBA has to provide a pointer to a
layer towards the HBA layer.
An HBA has to provide a pointer to a
.Va struct scsipi_adapter
and one pointer per channel to a
.Va struct scsipi_channel .
@ -77,13 +78,15 @@ Once the SCSI or ATAPI bus is attached, the
.Nm
system will scan the bus and allocate a
.Va struct scsipi_periph
for each device found on the bus. A high-level command (command sent from
the high-level SCSI/ATAPI layer to the low-level HBA layer) is described by a
for each device found on the bus.
A high-level command (command sent from the high-level SCSI/ATAPI
layer to the low-level HBA layer) is described by a
.Va struct scsipi_xfer .
.Pp
A request is sent to the HBA driver though the
.Fn adapt_request
callback. The HBA driver signals completion (with or without errors) of the
callback.
The HBA driver signals completion (with or without errors) of the
request though
.Fn scsipi_done .
.Nm
@ -191,10 +194,12 @@ number of LUNs per target
.It Va int chan_id
adapter's ID on this channel
.It Va int chan_defquirks
default device quirks. Quirks are defined in
default device quirks.
Quirks are defined in
.Pa \*[Lt]dev/scsipi/scsipiconf.h\*[Gt]
and are usually set in the middle layer based on the device's inquiry
data. For some kinds of adapters it may be convenient to have a set of
data.
For some kinds of adapters it may be convenient to have a set of
quirks applied to all devices, regardless of the inquiry data.
.El
.Pp
@ -204,7 +209,8 @@ by passing a pointer to the
.Va struct scsipi_channel
to the
.Xr autoconf 4
machinery. The print function shall be either
machinery.
The print function shall be either
.Fn scsiprint
or
.Fn atapiprint .
@ -213,7 +219,8 @@ When scanning the bus, the
.Nm
system allocates a
.Va struct scsipi_periph
for each device probed. The interesting fields are:
for each device probed.
The interesting fields are:
.Bl -tag -width int_periph_openings -compact -offset indent
.It Va struct device *periph_dev
pointer to the device's
@ -270,9 +277,10 @@ mask of flags reserved for HBA's use (0xf0000000)
.It Va struct scsipi_periph *xs_periph
periph doing the xfer
.It Va int timeout
command timeout, in milliseconds. The HBA should start the timeout at the time
the command is accepted by the device. If the timeout happens, the HBA shall
terminate the command through
command timeout, in milliseconds.
The HBA should start the timeout at the time the command is accepted
by the device.
If the timeout happens, the HBA shall terminate the command through
.Fn scsipi_done
with a XS_TIMEOUT error
.It Va struct scsipi_generic *cmd
@ -288,7 +296,8 @@ difference between
.Fa datalen
and how much data was really transferred
.It Va scsipi_xfer_result_t error
error value returned by the HBA driver to mid-layer. See description of
error value returned by the HBA driver to mid-layer.
See description of
.Fn scsipi_done
for valid values
.It Va union {struct scsipi_sense_data scsi_sense; u_int32_t atapi_sense;} sense
@ -331,13 +340,14 @@ ask the adapter to increase resources of the channel (grow
.Va adapt_openings
or
.Va chan_openings )
if possible. Support of this feature is optional. This request is called from
the kernel completion thread.
if possible.
Support of this feature is optional.
This request is called from the kernel completion thread.
.Fa arg
must be ignored.
.It Dv ADAPTER_REQ_SET_XFER_MODE
set the xfer mode for a for I_T Nexus. This will be called once all
LUNs of a target have been probed.
set the xfer mode for a for I_T Nexus.
This will be called once all LUNs of a target have been probed.
.Fa arg
points to a
.Va struct scsipi_xfer_mode
@ -380,34 +390,37 @@ to notify the mid-layer.
.Fn adapt_request
may be called from interrupt context.
.It Fn adapt_minphys
pointer to the driver's minphys function. If the driver can handle
transfers of size
pointer to the driver's minphys function.
If the driver can handle transfers of size
.Dv MAXPHYS ,
this can point to
.Fn minphys .
.It Fn adapt_ioctl
ioctl function for the channel. The only ioctl supported at this level is
ioctl function for the channel.
The only ioctl supported at this level is
.Dv SCBUSIORESET
for which the HBA driver shall issue a SCSI reset on the channel.
.It int Fn adapt_enable "struct device *dev" "int enable"
Disable the adapter if
.Va enable
is zero, or enable it if non-zero. Returns 0 if operation is successful,
or error from
is zero, or enable it if non-zero.
Returns 0 if operation is successful, or error from
.Pa \*[Lt]sys/errno.h\*[Gt] .
This callback is optional, and is useful mostly for hot-plug devices.
For example, this callback would power on or off
the relevant PCMCIA socket for a PCMCIA controller.
.It int Fn adapt_getgeom "struct scsipi_periph *periph" "struct disk_parms *params" "u_long sectors"
Optional callback, used by high-level drivers to get the fictitious geometry
used by the controller's firmware for the specified periph. Returns 0 if
successful. See adaptec drivers for details.
used by the controller's firmware for the specified periph.
Returns 0 if successful.
See adaptec drivers for details.
.It int Fn adapt_accesschk "struct scsipi_periph *periph" "struct scsipi_inquiry_pattern *inqbuf"
Optional callback; if present the mid-layer uses it to check if it can
attach a driver to the specified periph. If the callback returns a non-zero
value, the periph is ignored by the
attach a driver to the specified periph.
If the callback returns a non-zero value, the periph is ignored by the
.Nm
code. This callback is used by adapters which want to drive some devices
code.
This callback is used by adapters which want to drive some devices
themselves, for example hardware RAID controllers.
.It Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg"
Asynchronous event notification for the mid-layer.
@ -415,7 +428,8 @@ Asynchronous event notification for the mid-layer.
can be one of:
.Bl -tag -width xxxxxxxx -compact
.It Dv ASYNC_EVENT_MAX_OPENINGS
set max openings for a periph. Argument is a
set max openings for a periph.
Argument is a
.Va struct scsipi_max_openings
with at least the following members:
.Bl -tag -width xxxxxxxx -compact
@ -427,9 +441,11 @@ with at least the following members:
Not all periphs may allow openings to increase; if not allowed the request is
silently ignored.
.It Dv ASYNC_EVENT_XFER_MODE
update the xfer mode for an I_T nexus. Argument is a
update the xfer mode for an I_T nexus.
Argument is a
.Va struct scsipi_xfer_mode
properly filled in. An
properly filled in.
An
.Fa Dv ASYNC_EVENT_XFER_MODE
call with
.Fa Dv PERIPH_CAP_TQING
@ -437,7 +453,8 @@ set in
.Va xm_mode
is mandatory to activate tagged queuing.
.It Dv ASYNC_EVENT_RESET
channel has been reset. No argument.
channel has been reset.
No argument.
HBA drivers have to issue
.Dv ASYNC_EVENT_RESET events if they rely on the
mid-layer for SCSI CHECK CONDITION handling.
@ -458,8 +475,8 @@ Check the ATAPI sense for the error.
.It Dv XS_DRIVER_STUFFUP
Driver failed to perform operation.
.It Dv XS_RESOURCE_SHORTAGE
Adapter resource shortage. The mid-layer will retry the command after some
delay.
Adapter resource shortage.
The mid-layer will retry the command after some delay.
.It Dv XS_SELTIMEOUT
The device timed out while trying to send the command
.It Dv XS_TIMEOUT
@ -470,10 +487,11 @@ The mid-layer will check
for additional details:
.Bl -tag -width SCSI_QUEUE_FULL -compact
.It Dv SCSI_CHECK
SCSI check condition. The mid-layer will freeze the periph queue and issue
a REQUEST SENSE command. If the HBA supports tagged queuing, it shall remove
and requeue any command not yet accepted by the HBA (or at last make sure no
more commands will be sent to the device before the REQUEST SENSE is complete).
SCSI check condition.
The mid-layer will freeze the periph queue and issue a REQUEST SENSE command.
If the HBA supports tagged queuing, it shall remove and requeue any command
not yet accepted by the HBA (or at last make sure no more commands will
be sent to the device before the REQUEST SENSE is complete).
.It Dv SCSI_QUEUE_FULL
The mid layer will adjust the periph's openings and requeue the command.
.It Dv SCSI_BUSY
@ -506,20 +524,21 @@ and
.Fa xfer
doesn't have
.Dv XS_CTL_POLL
set. All other error conditions are handled by a kernel thread
set.
All other error conditions are handled by a kernel thread
(once the HBA's interrupt handler has returned).
.It Fn scsipi_printaddr "struct scsipi_periph *periph"
print a kernel message with the periph's name, in the form
device(controller:channel:target:lun).
.It Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count"
Freeze the specified channel (requests are queued but not sent to HBA). The
channel's freeze counter is increased by
Freeze the specified channel (requests are queued but not sent to HBA).
The channel's freeze counter is increased by
.Fa count .
.It Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count"
Decrement the channel's freeze counter by
.Fa count
and process the queue if the counter goes to 0. In order to preserve command
ordering, HBA drivers should not call
and process the queue if the counter goes to 0.
In order to preserve command ordering, HBA drivers should not call
.Fn scsipi_channel_thaw
before calling
.Fn scsipi_done
@ -535,7 +554,8 @@ callback.
.It Fn scsipi_periph_timed_thaw "void *arg"
Same as the channel counterparts, but only for one specific peripheral.
.It Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags"
detach the periph associated with this I_T_L nexus. Both
detach the periph associated with this I_T_L nexus.
Both
.Fa target
and
.Fa lun
@ -551,11 +571,12 @@ will be called with
.Fa chan
and
.Fa arg
as arguments, from the channel completion thread. The callback is run at
splbio.
as arguments, from the channel completion thread.
The callback is run at splbio.
.Fn scsipi_thread_call_callback
will freeze the channel by one, it's up to the caller to thaw it when
appropriate. Returns 0 if the callback was properly recorded, or EBUSY if the
appropriate.
Returns 0 if the callback was properly recorded, or EBUSY if the
channel has already a callback pending.
.El
.Sh FILES
@ -570,7 +591,8 @@ Both header files include
.Pa sys/dev/scsipiconf.h
which contains most structure definitions, function prototypes and macros.
.Sh EXAMPLES
The best examples are existing HBA drivers. Most of them sit in the
The best examples are existing HBA drivers.
Most of them sit in the
.Pa sys/dev/ic
directory.
.Sh HISTORY
@ -581,5 +603,5 @@ interface appeared in
.Sh AUTHORS
The
.Nm
interface was designed and implemented by Jason R. Thorpe. Manuel Bouyer
converted most drivers to the new interface.
interface was designed and implemented by Jason R. Thorpe.
Manuel Bouyer converted most drivers to the new interface.

5
share/man/man9/setjmp.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: setjmp.9,v 1.1 2002/05/25 02:16:38 gmcgarry Exp $
.\" $NetBSD: setjmp.9,v 1.2 2002/10/14 13:43:32 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -53,7 +53,8 @@ The
.Fn setjmp
function saves its calling environment in
.Fa label .
It returns zero on success. The
It returns zero on success.
The
.Fn longjmp
function restores the environment saved by the most recent
invocation of

15
share/man/man9/shutdownhook_establish.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: shutdownhook_establish.9,v 1.6 2001/09/04 02:51:16 wiz Exp $
.\" $NetBSD: shutdownhook_establish.9,v 1.7 2002/10/14 13:43:32 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -51,7 +51,8 @@ function adds
.Fa fn
to the list of hooks invoked by
.Xr doshutdownhooks 9
at shutdown. When invoked, the hook function
at shutdown.
When invoked, the hook function
.Fa fn
will be passed
.Fa arg
@ -61,15 +62,16 @@ The
.Fn shutdownhook_disestablish
function removes the hook described by the opaque pointer
.Fa cookie
from the list of hooks to be invoked at shutdown. If
from the list of hooks to be invoked at shutdown.
If
.Fa cookie
is invalid, the result of
.Fn shutdownhook_disestablish
is undefined.
.Pp
Shutdown hooks should be used to perform one-time activities
that must happen immediately before the kernel exits. Because
of the environment in which they are run, shutdown hooks cannot
that must happen immediately before the kernel exits.
Because of the environment in which they are run, shutdown hooks cannot
rely on many system services (including file systems, and timeouts
and other interrupt-driven services), or even basic system
integrity (because the system could be rebooting after a crash).
@ -77,7 +79,8 @@ integrity (because the system could be rebooting after a crash).
If successful,
.Fn shutdownhook_establish
returns an opaque pointer describing the newly-established
shutdown hook. Otherwise, it returns NULL.
shutdown hook.
Otherwise, it returns NULL.
.Sh EXAMPLES
It may be appropriate to use a shutdown hook to
disable a device that does direct memory access, so that

106
share/man/man9/signal.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: signal.9,v 1.3 2002/07/28 22:18:52 manu Exp $
.\" $NetBSD: signal.9,v 1.4 2002/10/14 13:43:33 wiz Exp $
.\"
.\" Copyright (c) 1996, 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -120,11 +120,11 @@ always be within the range of
.Bq 1- Ns NSIG .
.Pp
Most of the kernel's signal infrastructure is implemented in
machine-independent code. Machine-dependent code provides
support for invoking a process's signal handler, restoring
context when the signal handler returns, generating signals
when hardware traps occur, triggering the delivery of signals
when a process is about to return from the kernel to userspace.
machine-independent code.
Machine-dependent code provides support for invoking a process's
signal handler, restoring context when the signal handler returns,
generating signals when hardware traps occur, triggering the delivery
of signals when a process is about to return from the kernel to userspace.
.Pp
The signal state for a process is contained in
.Fa struct sigctx .
@ -143,7 +143,8 @@ functions:
.Pp
This function initializes the signal state of
.Va proc0
to the system default. This signal state is then inherited by
to the system default.
This signal state is then inherited by
.Xr init 8
when it is started by the kernel.
.It void Fn sigactsinit "struct proc *np" "struct proc *pp" "int share"
@ -194,7 +195,8 @@ to the system defaults when the process execs a new program image.
.Pp
This function implements the
.Xr sigaction 2
system call. The
system call.
The
.Fa tramp
and
.Fa vers
@ -202,7 +204,8 @@ arguments provide support for userspace signal trampolines.
Trampoline version 0 is reserved for the legacy kernel-provided
signal trampoline;
.Fa tramp
must be NULL in this case. Otherwise,
must be NULL in this case.
Otherwise,
.Fa vers
specifies the ABI of the trampoline specified by
.Fa tramp .
@ -250,7 +253,8 @@ to be delivered to all members of the process group
If
.Fa checkctty
is non-zero, the signal is only sent to processes which have a
controlling terminal. See
controlling terminal.
See
.Fn psignal
below for a complete description of the signal scheduling semantics.
.It void Fn trapsignal "struct proc *p" "int signum" "u_long code"
@ -281,8 +285,9 @@ does not by itself cause a context switch to happen.
The target process is not marked as runnable in the following cases:
.Bl -bullet -offset indent
.It
The target process is sleeping uninterruptibly. The signal will be
noticed when the process returns from the system call or trap.
The target process is sleeping uninterruptibly.
The signal will be noticed when the process returns from the system
call or trap.
.It
The target process is currently ignoring the signal.
.It
@ -342,15 +347,15 @@ The
.Fn postsig
function is used to invoke the action for the signal
.Fa signum
in the current process. If the default action of a signal
is to terminate the process, and the signal does not have
a registered handler, the process exits using
in the current process.
If the default action of a signal is to terminate the process, and the
signal does not have a registered handler, the process exits using
.Fn sigexit ,
dumping a core image if necessary.
.It void Fn killproc "struct proc *p" "const char *why"
.Pp
This function sends a SIGKILL signal to the specified process. The
message provided by
This function sends a SIGKILL signal to the specified process.
The message provided by
.Fa why
is sent to the system log and is also displayed on the process's
controlling terminal.
@ -360,8 +365,8 @@ This function forces the process
.Fa p
to exit with the signal
.Fa signum ,
generating a core file if appropriate. No checks are made for masked
or caught signals; the process always exits.
generating a core file if appropriate.
No checks are made for masked or caught signals; the process always exits.
.It int Fn sigmasked "struct proc *p" "int signum"
.Pp
This function returns non-zero if the signal specified by
@ -377,8 +382,8 @@ must prepare the registers and stack of the current process to
invoke the signal handler stored in the process's
.Fa struct sigacts .
This may include switching to an alternate signal
stack specified by the process. The previous register, stack,
and signal state are stored in a
stack specified by the process.
The previous register, stack, and signal state are stored in a
.Fa struct sigcontext ,
which is then copied out to the user's stack.
.Pp
@ -396,8 +401,9 @@ is a signal-specific code, and
.Fa scp
is the pointer to the
.Fa struct sigcontext
on the user's stack. The registers and stack must also
arrange for the signal handler to return to the signal trampoline.
on the user's stack.
The registers and stack must also arrange for the signal handler to
return to the signal trampoline.
The trampoline is then used to return to the code which was executing
when the signal was delivered using the
.Xr sigreturn 2
@ -406,29 +412,32 @@ system call.
For performance reasons, it is recommended that
.Fn sendsig
arrange for the signal handler to be invoked directly on architectures
where it is convenient to do so. In this case, the trampoline is used
only for the signal return path. If it is not feasible to directly
invoke the signal handler, the trampoline is also used to invoke the
handler, performing any final set up that was not possible for
where it is convenient to do so.
In this case, the trampoline is used only for the signal return path.
If it is not feasible to directly invoke the signal handler, the
trampoline is also used to invoke the handler, performing any final
set up that was not possible for
.Fn sendsig
to perform.
.Pp
.Fn sendsig
must invoke the signal trampoline with the correct ABI. The ABI of
the signal trampoline is specified on a per-signal basis in the
must invoke the signal trampoline with the correct ABI.
The ABI of the signal trampoline is specified on a per-signal basis in the
.Fn sigacts
structure for the process. Trampoline version 0 is reserved for the
legacy kernel-provided, on-stack signal trampoline. All other trampoline
versions indicate a specific trampoline ABI. This ABI is coordinated
with machine-dependent code in the system C library.
structure for the process.
Trampoline version 0 is reserved for the legacy kernel-provided,
on-stack signal trampoline.
All other trampoline versions indicate a specific trampoline ABI.
This ABI is coordinated with machine-dependent code in the system
C library.
.El
.Ss SIGNAL TRAMPOLINE
The signal trampoline is a special piece of code which provides
support for invoking the signal handlers for a process. The trampoline
is used to return from the signal handler back to the code which was
executing when the signal was delivered, and is also used to invoke the
handler itself on architectures where it is not feasible to have the
kernel invoke the handler directly.
support for invoking the signal handlers for a process.
The trampoline is used to return from the signal handler back to the
code which was executing when the signal was delivered, and is also used
to invoke the handler itself on architectures where it is not feasible to
have the kernel invoke the handler directly.
.Pp
In traditional
.Ux
@ -436,22 +445,24 @@ systems, the signal trampoline, also referred to as the
.Dq sigcode ,
is provided by the kernel and copied to the top of the user's
stack when a new process is created or a new program image is
exec'd. Starting in
exec'd.
Starting in
.Nx 2.0 ,
the signal trampoline is provided by the system C library. This
allows for more flexibility when the signal facility is extended,
the signal trampoline is provided by the system C library.
This allows for more flexibility when the signal facility is extended,
makes dealing with signals easier in debuggers, such as
.Xr gdb 1 ,
and may also enhance system security by allowing the kernel to
disallow execution of code on the stack.
.Pp
The signal trampoline is specified on a per-signal basis. The
correct trampoline is selected automatically by the C library
The signal trampoline is specified on a per-signal basis.
The correct trampoline is selected automatically by the C library
when a signal handler is registered by a process.
.Pp
Signal trampolines have a special naming convention which enables
debuggers to determine the characteristics of the signal handler
and its arguments. Trampoline functions are named like so:
and its arguments.
Trampoline functions are named like so:
.Bd -literal -offset indent
__sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt]
.Ed
@ -459,7 +470,8 @@ __sigtramp_\*[Lt]flavor\*[Gt]_\*[Lt]version\*[Gt]
where:
.Bl -tag -width versionXX
.It \*[Lt]flavor\*[Gt]
The flavor of the signal handler. The following flavors are valid:
The flavor of the signal handler.
The following flavors are valid:
.Bl -tag -width sigcontextXX
.It sigcontext
Specifies a traditional BSD-style signal handler with the following
@ -483,8 +495,8 @@ handlers is not yet implemented in the
kernel.
.El
.It \*[Lt]version\*[Gt]
Specifies the ABI version of the signal trampoline. The trampoline
ABI is coordinated with the machine-dependent kernel
Specifies the ABI version of the signal trampoline.
The trampoline ABI is coordinated with the machine-dependent kernel
.Fn sendsig
function.
.El

12
share/man/man9/softintr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: softintr.9,v 1.9 2002/02/13 08:18:51 ross Exp $
.\" $NetBSD: softintr.9,v 1.10 2002/10/14 13:43:33 wiz Exp $
.\"
.\" Copyright (c) 2000 Christopher G. Demetriou.
.\" All rights reserved.
@ -54,11 +54,11 @@ The
.Nx
machine-independent software interrupt framework is designed to provide
a generic software interrupt mechanism which can be used any time a
low-priority callback is needed. It allows dynamic registration of
software interrupts for loadable drivers and protocol stacks,
prioritization and fair queueing of software interrupts, and
allows machine-dependent optimizations to reduce cost and code
complexity.
low-priority callback is needed.
It allows dynamic registration of software interrupts for loadable
drivers and protocol stacks, prioritization and fair queueing of software
interrupts, and allows machine-dependent optimizations to reduce cost
and code complexity.
.Pp
In order to provide this framework, the machine-dependent
.Aq Pa machine/types.h

102
share/man/man9/spl.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: spl.9,v 1.19 2002/09/25 00:10:53 wiz Exp $
.\" $NetBSD: spl.9,v 1.20 2002/10/14 13:43:33 wiz Exp $
.\"
.\" Copyright (c) 2000, 2001 Jason R. Thorpe. All rights reserved.
.\" Copyright (c) 1997 Michael Long.
@ -92,8 +92,8 @@ a locking primitive) or to ensure uninterrupted access to
hardware devices which are sensitive to timing.
.Pp
Interrupt priorities are not arranged in a strict hierarchy, although
interrupt hardware sometimes is. For this reason the priorities
listed here are arranged from
interrupt hardware sometimes is.
For this reason the priorities listed here are arranged from
.Dq highest
to
.Dq lowest .
@ -101,42 +101,44 @@ In other words, if a platform's hardware interrupts are arranged in
a hierarchical manner, a priority level should also block all of the
levels listed below it.
.Pp
Note that a strict hierarchy is not required. For example,
Note that a strict hierarchy is not required.
For example,
.Fn splnet
is not required to block disk controller interrupts, as they
do not access the same data structures. However, the priorities
are presented as a hierarchy in order to minimize data loss due
to blocked interrupts, or interrupts not being serviced in a
timely fashion.
do not access the same data structures.
However, the priorities are presented as a hierarchy in order to
minimize data loss due to blocked interrupts, or interrupts not being
serviced in a timely fashion.
.Pp
A
.Nm
function exists for each distinct priority level which can exist in
the system, as well as for some special priority levels that are
designed to be used in conjunction with multiprocessor-safe locking
primitives. These levels may be divided into two main types: hard
and soft. Hard interrupts are generated by hardware devices. Soft
interrupts are a way of deferring hardware interrupts to do more
primitives.
These levels may be divided into two main types: hard and soft.
Hard interrupts are generated by hardware devices.
Soft interrupts are a way of deferring hardware interrupts to do more
expensive processing at a lower interrupt priority, and are explicitly
scheduled by the higher-level interrupt handler. The most common use
of this is in the networking code, where network interface drivers
defer the more expensive TCP/IP processing in order to avoid dropping
additional incoming packets. Software interrupts are further described
by
scheduled by the higher-level interrupt handler.
The most common use of this is in the networking code, where network
interface drivers defer the more expensive TCP/IP processing in order
to avoid dropping additional incoming packets.
Software interrupts are further described by
.Xr softintr 9 .
.Pp
In order of highest to lowest priority, the priority-raising functions
are:
.Bl -tag -width splsoftserialXX
.It Fn splhigh
blocks all hard and soft interrupts. It is used for code that cannot
tolerate any interrupts, like hardware context switching code and
the
blocks all hard and soft interrupts.
It is used for code that cannot tolerate any interrupts, like hardware
context switching code and the
.Xr ddb 4
in-kernel debugger.
.It Fn spllock
blocks all hard and soft interrupts that can acquire a simple lock. This
is provided as a distinct level from
blocks all hard and soft interrupts that can acquire a simple lock.
This is provided as a distinct level from
.Fn splhigh
as some platforms may need to make use of extremely high priority
interrupts while locks are spinning, which would be blocked by
@ -145,14 +147,15 @@ interrupts while locks are spinning, which would be blocked by
blocks hard interrupts from serial interfaces (IPL_SERIAL).
Code running at this level may not access the tty subsystem.
Generally, all code run at this level must schedule additional
processing to run in a software interrupt. Note that code running
at this priority is not blocked by
processing to run in a software interrupt.
Note that code running at this priority is not blocked by
.Fn splvm
(described below), and is therefore prohibited from using the
kernel memory allocators.
.It Fn splsched
blocks all hard and soft interrupts that may access scheduler data
structures. Code running at or above this level may not call
structures.
Code running at or above this level may not call
.Fn sleep ,
.Fn tsleep ,
.Fn ltsleep ,
@ -160,7 +163,8 @@ or
.Fn wakeup ,
nor may it post signals.
.It Fn splclock
blocks the hardware clock interrupt. It is used by
blocks the hardware clock interrupt.
It is used by
.Fn hardclock
to update kernel and process times, and must be used by any other code
that accesses time-related data, specifically the
@ -174,11 +178,13 @@ data structures, and nothing running at or above this level may
schedule, cancel, or otherwise access any callout-related data
structures.
.It Fn splstatclock
blocks the hardware statistics clock interrupt. It is used by
blocks the hardware statistics clock interrupt.
It is used by
.Fn statclock
to update kernel profiling and other statistics, and must be used by
any code that accesses that data. This is the clock that drives
scheduling. This level is identical to
any code that accesses that data.
This is the clock that drives scheduling.
This level is identical to
.Fn splclock
if there is no separate statistics clock.
.It Fn splvm
@ -186,14 +192,14 @@ blocks hard interrupts from all devices that are allowed to use the
kernel
.Xr malloc 9 ,
or any virtual memory operations.
That includes all disk, network, and tty device interrupts. The
temptation to abuse the semantics of
That includes all disk, network, and tty device interrupts.
The temptation to abuse the semantics of
.Fn splvm
should be avoided; if you feel as if you need to block more than
one class of interrupts at a time, use software interrupts instead.
.It Fn spltty
blocks hard and soft interrupts from TTY devices (IPL_TTY). This
must also block soft serial interrupts.
blocks hard and soft interrupts from TTY devices (IPL_TTY).
This must also block soft serial interrupts.
.It Fn splsoftserial
blocks soft interrupts generated by serial devices (IPL_SOFTSERIAL).
.It Fn splnet
@ -202,20 +208,24 @@ blocks hard interrupts from network interfaces (IPL_NET).
blocks hard interrupts from disks and other mass-storage
devices (IPL_BIO).
.It Fn splsoftnet
blocks soft network interrupts (IPL_SOFTNET). Soft interrupts blocked
by this priority are also blocked by all of the priorities listed
above.
blocks soft network interrupts (IPL_SOFTNET).
Soft interrupts blocked by this priority are also blocked by all
of the priorities listed above.
.It Fn splsoftclock
blocks soft clock interrupts. This is the priority at which the
blocks soft clock interrupts.
This is the priority at which the
.Xr callout 9
facility runs. Soft interrupts blocked by this priority are also blocked
by all of the priorities listed above. In particular,
facility runs.
Soft interrupts blocked by this priority are also blocked by all
of the priorities listed above.
In particular,
.Fn splsoftnet
must be a higher priority than
.Fn splsoftclock .
.El
.Pp
Two functions lower the system priority level. They are:
Two functions lower the system priority level.
They are:
.Bl -tag -width spllowersoftclockXX
.It Fn spllowersoftclock
unblocks all interrupts but the soft clock interrupt.
@ -238,19 +248,21 @@ Note that the functions which lower the system priority level
and
.Fn splx
.Pc
do not return a value. They should only be used
in places where the system priority level is being decreased
permanently. It is inappropriate to attempt to use them where the
do not return a value.
They should only be used in places where the system priority level
is being decreased permanently.
It is inappropriate to attempt to use them where the
system priority level is being decreased temporarily, and would
need to be restored to a previous value before continuing.
.Sh HISTORY
In
.Bx 4.4 ,
.Fn splnet
was used to block network software interrupts. Most device drivers used
was used to block network software interrupts.
Most device drivers used
.Fn splimp
to block hardware interrupts. To avoid unnecessarily blocking other
interrupts, in
to block hardware interrupts.
To avoid unnecessarily blocking other interrupts, in
.Nx 1.1
a new function was added that blocks only network hardware interrupts.
For consistency with other

8
share/man/man9/suser.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: suser.9,v 1.2 2002/06/25 20:28:36 wiz Exp $
.\" $NetBSD: suser.9,v 1.3 2002/10/14 13:43:34 wiz Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -49,11 +49,13 @@
.Fn suser
tests whether the specified credentials
.Fa cred
imply super-user privilege. The argument
imply super-user privilege.
The argument
.Fa acflag ,
if non-NULL, is a pointer to the
.Em ac_flag
in the accounting structure. If super-user privilege is implied by
in the accounting structure.
If super-user privilege is implied by
the credentials, and
.Fa acflag
is not NULL,

33
share/man/man9/tc.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: tc.9,v 1.5 2002/02/13 08:18:52 ross Exp $
.\" $NetBSD: tc.9,v 1.6 2002/10/14 13:43:34 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -77,9 +77,9 @@ The
.Nm
device provides support for the DEC TURBOchannel bus found on all DEC
TURBOchannel machines with MIPS (DECstation 5000 series, excluding the
5000/200) and Alpha (3000-series) systems. TURBOchannel is a 32-bit
wide synchronous DMA-capable bus, running at 25 MHz on higher-end
machines and at 12.5 MHz on lower-end machines.
5000/200) and Alpha (3000-series) systems.
TURBOchannel is a 32-bit wide synchronous DMA-capable bus, running
at 25 MHz on higher-end machines and at 12.5 MHz on lower-end machines.
.Sh DATA TYPES
Drivers for devices attached to the TURBOchannel bus will make use of
the following data types:
@ -101,7 +101,8 @@ It contains the following members:
The
.Em ta_busspeed
member specifies the TURBOchannel bus speed and is useful for
time-related functions. Values values are
time-related functions.
Values values are
.Em TC_SPEED_12_5_MHZ
for the 12.5 MHz bus and
.Em TC_SPEED_25_MHZ
@ -136,12 +137,13 @@ Do interrupt event counting with device
for the event described completely by
.Fa cookie .
.It Fn tc_mb ""
A read/write memory barrier. Any CPU-to-memory reads/writes before
the barrier must complete before any CPU-to-memory reads/writes after
it.
A read/write memory barrier.
Any CPU-to-memory reads/writes before the barrier must complete before
any CPU-to-memory reads/writes after it.
.It Fn tc_wmb ""
A write memory barrier. Any CPU-to-memory writes before before the
barrier must complete before any CPU-to-memory writes after it.
A write memory barrier.
Any CPU-to-memory writes before before the barrier must complete
before any CPU-to-memory writes after it.
.It Fn tc_syncbus ""
Synchronise writes on the TURBOchannel bus by ensuring CPU writes are
propagated across the TURBOchannel bus.
@ -161,13 +163,14 @@ to the physical address of the corresponding region that is not
cached.
.El
.Sh AUTOCONFIGURATION
The TURBOchannel bus is a direct-connection bus. During
autoconfiguration, the parent specifies the name of the found
The TURBOchannel bus is a direct-connection bus.
During autoconfiguration, the parent specifies the name of the found
TURBOchannel module into the
.Fa ta_modname
member of the
.Em tc_attach_args
structure. Drivers should match on this name.
structure.
Drivers should match on this name.
.Sh DMA SUPPORT
The TURBOchannel bus supports 32-bit, bidirectional DMA transfers.
Support is provided by the standard
@ -177,8 +180,8 @@ interface.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent TURBOchannel subsystem can be found. All pathnames are
relative to
machine-independent TURBOchannel subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The TURBOchannel subsystem itself is implemented within the file

13
share/man/man9/time.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: time.9,v 1.12 2002/08/07 13:43:33 wiz Exp $
.\" $NetBSD: time.9,v 1.13 2002/10/14 13:43:34 wiz Exp $
.\"
.\" Copyright (c) 1994 Christopher G. Demetriou
.\" All rights reserved.
@ -63,7 +63,8 @@ system call and by periodic clock interrupts.
.Pp
The
.Va boottime
variable holds the system boot time. It is set from
variable holds the system boot time.
It is set from
.Va time
at system boot, and is updated when the system time is adjusted
with
@ -85,11 +86,11 @@ function, rather than being copied from
.Pp
The
.Va mono_time
variable is a monotonically increasing system clock. It is set
from
variable is a monotonically increasing system clock.
It is set from
.Va time
at boot, and is updated by the periodic timer interrupt. (It is
not updated by
at boot, and is updated by the periodic timer interrupt.
(It is not updated by
.Xr settimeofday 2 . )
.Pp
All of these variables contain times

20
share/man/man9/todr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: todr.9,v 1.3 2002/02/13 08:18:52 ross Exp $
.\" $NetBSD: todr.9,v 1.4 2002/10/14 13:43:34 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -64,10 +64,12 @@ The
.Fn todr_*
functions provide an interface to read, set and control
.Ql time-of-day
devices. The
devices.
The
.Fa todr_chip_handle_t
should be obtained from a driver for a particular hardware device that
implements this interface. Examples of such drivers currently include
implements this interface.
Examples of such drivers currently include
.Xr mk48txx 4
and
.Xr intersil7170 4 .
@ -87,8 +89,10 @@ argument.
.Pp
.Fn todr_setcal
specifies a calibration value in PPM units to be programmed in the TODR
device. Positive values shall speed up the TODR clock, negative values
shall slow it down. If the device in not capable of handling calibration,
device.
Positive values shall speed up the TODR clock, negative values
shall slow it down.
If the device in not capable of handling calibration,
this function shall return
.Va EOPNOTSUPP .
The measurement and calculations necessary to utilize this method is
@ -103,7 +107,8 @@ and
are provided to convert a time value in seconds to and from a structure
representing the date and time as a
.Aq year,month,day,weekday,hour,minute,seconds
tuple. This structure is defined as follows:
tuple.
This structure is defined as follows:
.Bd -literal
struct clock_ymdhms {
u_short dt_year; /* Year */
@ -123,7 +128,8 @@ The
functions return 0 if the requested operation was successful;
otherwise an error code from
.Aq Pa sys/errno.h
shall be returned. However, behaviour is undefined if an invalid
shall be returned.
However, behaviour is undefined if an invalid
.Fa todr_chip_handle_t
is passed to any of these functions.
The

19
share/man/man9/ucom.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: ucom.9,v 1.10 2002/06/01 09:16:08 wiz Exp $
.\" $NetBSD: ucom.9,v 1.11 2002/10/14 13:43:35 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -83,7 +83,8 @@ struct ucom_attach_args {
.It Dv int portno
identifies the port if the devices should have more than one
.Nm
attached. Use the value
attached.
Use the value
.Dv UCOM_UNK_PORTNO
if there is only one port.
.It Dv int bulkin
@ -93,12 +94,14 @@ the number of the bulk output pipe.
.It Dv u_int ibufsize
the size of the read requests on the bulk in pipe.
.It Dv u_int ibufsizepad
the size of the input buffer. This is usually the same as
the size of the input buffer.
This is usually the same as
.Dv ibufsize .
.It Dv u_int obufsize
the size of the write requests on the bulk out pipe.
.It Dv u_int ibufsizepad
the size of the output buffer. This is usually the same as
the size of the output buffer.
This is usually the same as
.Dv obufsize .
.It Dv usbd_device_handle device
a handle to the device.
@ -116,8 +119,9 @@ The
.Dv ucom_methods
struct contains a number of function pointers used by the
.Nm
driver at various stages. If the device is not interested
in being called at a particular point it should just use a
driver at various stages.
If the device is not interested in being called at a particular point
it should just use a
.Dv NULL
pointer and the
.Nm
@ -185,7 +189,8 @@ raw characters from
.Fa src
into the buffer at
.Fa dst
and do the appropriate padding. The
and do the appropriate padding.
The
.Fa count
should be updated to the new size.
The buffer at

8
share/man/man9/usbdi.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: usbdi.9,v 1.4 2002/02/13 08:18:53 ross Exp $
.\" $NetBSD: usbdi.9,v 1.5 2002/10/14 13:43:35 wiz Exp $
.\"
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -189,9 +189,9 @@ This
interface first appeared in
.Nx 1.4 .
The interface is based on an early definition from the OpenUSBDI group
within the USB organisation. Right after this definition the OpenUSBDI
development got closed for open source developers, so this interface
has not followed the further changes.
within the USB organisation.
Right after this definition the OpenUSBDI development got closed for open
source developers, so this interface has not followed the further changes.
The OpenUSBDI specification is now available again, but looks different.
.Sh BUGS
This man page is under development, so its biggest shortcoming is

8
share/man/man9/vattr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vattr.9,v 1.3 2002/02/13 08:18:54 ross Exp $
.\" $NetBSD: vattr.9,v 1.4 2002/10/14 13:43:35 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -80,7 +80,8 @@ struct vattr {
.Ed
.Pp
A field value of VNOVAL represents a field whose value is unavailable
or which is not to be changed. Valid flag values for
or which is not to be changed.
Valid flag values for
.Em va_flags
are:
.Pp
@ -111,7 +112,8 @@ This function is an alias for
This section describes places within the
.Nx
source tree where actual code implementing or utilising the vnode
attributes can be found. All pathnames are relative to
attributes can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The vnode attributes ares implemented within the file

9
share/man/man9/vfs.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vfs.9,v 1.5 2002/08/20 15:52:25 wiz Exp $
.\" $NetBSD: vfs.9,v 1.6 2002/10/14 13:43:35 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -43,9 +43,10 @@
.Sh DESCRIPTION
The virtual file system,
.Nm "" ,
is the kernel interface to file systems. The interface specifies the
calls for the kernel to access file systems. It also specifies the
core functionality that a file system must provide to the kernel.
is the kernel interface to file systems.
The interface specifies the calls for the kernel to access file systems.
It also specifies the core functionality that a file system must provide
to the kernel.
.Pp
The focus of
.Nm

127
share/man/man9/vfsops.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vfsops.9,v 1.6 2002/08/15 03:23:55 wiz Exp $
.\" $NetBSD: vfsops.9,v 1.7 2002/10/14 13:43:36 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -102,16 +102,18 @@ operations on a file system without knowing its construction or type.
.Pp
All supported file systems in the kernel have an entry in the
.Va vfs_list_initial
table. This table is generated by
table.
This table is generated by
.Xr config 8
and is a
.Dv NULL Ns No -terminated
list of
.Em vfsops
structures. The vfsops structure describes the operations that can be
done to a specific file system type. The following table list the
elements of the vfsops vector, the corresponding invocation macro, and
a description of the element.
structures.
The vfsops structure describes the operations that can be done to a
specific file system type.
The following table list the elements of the vfsops vector, the
corresponding invocation macro, and a description of the element.
.Pp
.nf
.ta \w'int (*vfs_mountroot)()'u+2n +\w'VFS_QUOTACTL'u+2n +\w'Get the file system root vnode'u
@ -143,9 +145,9 @@ and a reference count
.Ns Em vfs_refcount .
It is not mandatory for a file system type to support a particular
operation, but it must assign each member function pointer to a
suitable function to do the minimum required of it. In most cases,
such functions either do nothing or return an error value to the
effect that it is not supported.
suitable function to do the minimum required of it.
In most cases, such functions either do nothing or return an error
value to the effect that it is not supported.
.Em vfs_reinit
and
.Em vfs_mountroot
@ -155,13 +157,13 @@ be
.Pp
At system boot, each file system with an entry in
.Va vfs_list_initial
is established and initialised. Each initialised file system
is recorded by the kernel in the list
is established and initialised.
Each initialised file system is recorded by the kernel in the list
.Va vfs_list
and the file system specific initialisation function
.Em vfs_init
in its vfsops vector is invoked. When the file system is not longer
needed
in its vfsops vector is invoked.
When the file system is not longer needed
.Em vfs_done
is invoked to run file system specific cleanups and the file system is
removed from the kernel list.
@ -169,15 +171,17 @@ removed from the kernel list.
At system boot, the root filesystem is mounted by invoking the file
system type specific
.Em vfs_mountroot
function in the vfsops vector. All filesystems that can be mounted as
a root file system must define this function. It is responsible for
initialising to list of mount structures for all future mounted file
systems.
function in the vfsops vector.
All filesystems that can be mounted as a root file system must define
this function.
It is responsible for initialising to list of mount structures for
all future mounted file systems.
.Pp
Kernel state which affects a specific file system type can be
queried and modified using the
.Xr sysctl 8
interface. The
interface.
The
.Em vfs_sysctl
member of the vfsops structure is invoked by file system independent
code for sysctl operations which are file system specific.
@ -186,8 +190,8 @@ code for sysctl operations which are file system specific.
.It Fn vfs_rootmountalloc "fstypename" "devname" "mpp"
Lookup a file system type specied by the name
.Fa fstypename
and if found allocate and initialise a mount structure for it. The
allocated mount structure is returned in the address specified by
and if found allocate and initialise a mount structure for it.
The allocated mount structure is returned in the address specified by
.Fa mpp .
The device the root file system was mounted from is specified by the
argument
@ -199,9 +203,9 @@ mount structure
.Fa mp .
The argument
.Fa nam
is the address of the networked client. This function is used by file
system type specific functions to verify that the client can access
the file system.
is the address of the networked client.
This function is used by file system type specific functions to verify
that the client can access the file system.
.It Fn vfs_getnewfsid "mp"
Get a new unique file system id type for the file system specified by
the mount structure
@ -226,24 +230,27 @@ call on the pathname of the mount point and
.Fa p
is the calling process.
.Fn VFS_MOUNT
initialises the mount structure for the mounted file system. This
structure records mount-specific information for the file system and
records the list of vnodes associated with the file system. This
function is invoked both to mount new file systems and to change the
attributes of an existing file system. If the MNT_UPDATE flag is set
in
initialises the mount structure for the mounted file system.
This structure records mount-specific information for the file system and
records the list of vnodes associated with the file system.
This function is invoked both to mount new file systems and to change the
attributes of an existing file system.
If the MNT_UPDATE flag is set in
.Em mp-\*[Gt]mnt_flag
then the filesystem should update its internal state from the value of
.Em mp-\*[Gt]mnt_flag .
This can be used, for instance, to convert a read-only filesystem to
read-write. If the MNT_UPDATE flag is not specified, then this is a
newly mounted filesystem.
read-write.
If the MNT_UPDATE flag is not specified, then this is a newly
mounted filesystem.
.It Fn VFS_START " mp" "flags" "p"
Make the file system specified by the mount structure
.Fa mp
operational. The argument
operational.
The argument
.Fa p
is the calling process. The argument
is the calling process.
The argument
.Fa flags
is a set of flags for controlling the operation of
.Fn VOP_START .
@ -258,12 +265,12 @@ The argument
is the calling process.
.Fa VFS_UNMOUNT
performs any file system type specific operations required before the
file system is unmounted, such are flushing buffers. If MNT_FORCE is
specified in the flags
file system is unmounted, such are flushing buffers.
If MNT_FORCE is specified in the flags
.Fa mntflags
then open files are forcibly closed. The function also deallocates
space associated with data structure that were allocated for the file
system when it was mounted.
then open files are forcibly closed.
The function also deallocates space associated with data structure
that were allocated for the file system when it was mounted.
.It Fn VFS_ROOT "mp" "vpp"
Get the root vnode of the file system specified by the mount
structure
@ -280,8 +287,8 @@ file system.
Query/modify user space quotas for the file system specified by the
mount structure
.Fa mp .
The argument specifies the control command to perform. The userid is
specified in
The argument specifies the control command to perform.
The userid is specified in
.Fa id ,
the calling process is
.Fa p
@ -299,8 +306,8 @@ structure
.Fa mp .
The argument
.Fa p
is the calling process. A statfs structure filled with the
statistics is returned in
is the calling process.
A statfs structure filled with the statistics is returned in
.Fa sbp .
.Fn VFS_STATFS
is the file system type specific implementation of the
@ -315,7 +322,8 @@ structure
The
.Fa waitfor
argument indicates whether a partial flush or complete flush should be
performed. The arguments
performed.
The arguments
.Fa p
and
.Fa cred
@ -330,10 +338,10 @@ for the file system specified by the mount structure
The vnode is returned in the address specified
.Fa vpp .
The function is optional for file systems which have a unique id
number for every file in the file system. It is used internally by
the UFS file system and also by the NFSv3 server to implement the
READDIRPLUS nfs call. If the file system does not support this
function, it should return
number for every file in the file system.
It is used internally by the UFS file system and also by the NFSv3
server to implement the READDIRPLUS nfs call.
If the file system does not support this function, it should return
.Er EOPNOTSUPP .
.It Fn VFS_FHTOVP "mp" "fhp" "vpp"
Get the vnode for the NFS file specified by the file handle
@ -354,10 +362,10 @@ Get a unique NFS file handle for the file specified by the vnode
The file handle is returned in
.Fa fhp .
The contents of the file handle are defined by the file system and are
not examined by any other subsystems. It should contain enough
information to uniquely identify a file within the file system as well
as noticing when a file has been removed and the file system resources
have been recycled for a new file.
not examined by any other subsystems.
It should contain enough information to uniquely identify a file within
the file system as well as noticing when a file has been removed and
the file system resources have been recycled for a new file.
.It Fn VFS_CHECKEXP "mp" "nam" "extflagsp" "credanonp"
Check if the file system specified by the mount structure
.Fa mp
@ -365,15 +373,15 @@ is exported to a client with anonymous credentials
.Fa credanonp .
The argument
.Fa nam
is an mbuf containing the network address of the client. The return
parameters for the export flags for the client are returned in the
address specified by
is an mbuf containing the network address of the client.
The return parameters for the export flags for the client are returned
in the address specified by
.Fa exflagsp .
This function is used by the NFS server. It is generally invoked
before
This function is used by the NFS server.
It is generally invoked before
.Fn VFS_FHTOVP
to validate that client has access to the file system. The file
system should call
to validate that client has access to the file system.
The file system should call
.Fn vfs_export_lookup
with the address of an appropriate netexport structure and the address
of the client to verify that the client can access this file system.
@ -382,7 +390,8 @@ of the client to verify that the client can access this file system.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the vfs
operations can be found. All pathnames are relative to
operations can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The vfs operations are implemented within the files

73
share/man/man9/vme.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vme.9,v 1.5 2002/02/13 08:18:55 ross Exp $
.\" $NetBSD: vme.9,v 1.6 2002/10/14 13:43:36 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -107,18 +107,19 @@
.Sh DESCRIPTION
The
.Nm
bus provides support for VME devices. The VME bus is a
high-performance backplane bus for use in computer systems. It is
based on the VMEbus specification initially released by the VMEbus
International Trade Association (VITA) in August of 1982. It has
since undergone IEC and IEEE standardisation.
bus provides support for VME devices.
The VME bus is a high-performance backplane bus for use in computer systems.
It is based on the VMEbus specification initially released by the VMEbus
International Trade Association (VITA) in August of 1982.
It has since undergone IEC and IEEE standardisation.
.Pp
The VME bus supports 8, 16, and 32-bit transfers over non-multiplexed
32-bit data and address paths. The latest revisions allow 64-bit,
multiplexed transfers. It supports asynchronous, fully handshaken
transfers at speeds up to 80 MB/sec. It has a master-slave
architecture, encouraging multiprocessing and supports up to seven
interrupt levels.
32-bit data and address paths.
The latest revisions allow 64-bit, multiplexed transfers.
It supports asynchronous, fully handshaken transfers at speeds
up to 80 MB/sec.
It has a master-slave architecture, encouraging multiprocessing and
supports up to seven interrupt levels.
.Sh DATA TYPES
Drivers attached to the
.Nm
@ -129,23 +130,23 @@ An opaque type identifying the bus controller.
.It Fa vme_addr_t
Addresses on the bus.
.It Fa vme_am_t
Address modifiers. Valid values are VME_AM_A32, VME_AM_A16,
VME_AM_A24, VME_AM_USERDEF (user/vendor definable), VME_AM_MBO,
VME_AM_SUPER, VME_AM_USER, VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and
VME_AM_BLT64.
Address modifiers.
Valid values are VME_AM_A32, VME_AM_A16, VME_AM_A24, VME_AM_USERDEF
(user/vendor definable), VME_AM_MBO, VME_AM_SUPER, VME_AM_USER,
VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and VME_AM_BLT64.
.It Fa vme_datasize_t
The datasize of the address space. Valid values are
VME_D8, VME_D16, and VME_D32.
The datasize of the address space.
Valid values are VME_D8, VME_D16, and VME_D32.
.It Fa vme_mapresc_t
Generic placeholder for any resources needed for a mapping.
.It Fa vme_intr_handle_t
An opaque type describing an interrupt mapping.
.It Fa vme_swap_t
Hardware swap capabilities for controlling data endianness. Valid
values have not been specified yet.
Hardware swap capabilities for controlling data endianness.
Valid values have not been specified yet.
.It Fa struct vme_range
A structure used to describe an address range on the VME bus. It
contains the following members:
A structure used to describe an address range on the VME bus.
It contains the following members:
.Bd -literal
vme_addr_t offset;
vme_size_t size;
@ -153,7 +154,8 @@ contains the following members:
.Ed
.It Fa struct vme_attach_args
A structure used to inform the driver of the
device properties. It contains the following members:
device properties.
It contains the following members:
.Bd -literal
vme_chipset_tag_t va_vct;
bus_dma_tag_t va_bdt;
@ -176,7 +178,8 @@ with address modifiers
.Fa am
and datasize
.Fa datasize
for a device. If a VME device is found, the function
for a device.
If a VME device is found, the function
.Fa callback()
(if it is not NULL) is called to perform device-specific
identification.
@ -201,7 +204,8 @@ datasize
.Fa datasize
and endianness
.Fa swap
for a device. If the mapping is successful
for a device.
If the mapping is successful
.Fa tag
contains the bus-space tag and
.Fa handle
@ -254,8 +258,8 @@ Increment the interrupt event counter for the interrupt specified by
.Fa "flags" "map"
.Fc
Allocates a DMA handle and initializes it according to the parameters
provided. The VME-specific parameters describe the
address-space modifiers
provided.
The VME-specific parameters describe the address-space modifiers
.Fa am ,
datasize
.Fa datasize ,
@ -264,8 +268,8 @@ and endianness
The remaining parameters are described in
.Xr bus_dma 9 .
.It Fn vme_dmamap_destroy "vc" "map"
Frees all resources associated with a given DMA handle. The parameters
are described in
Frees all resources associated with a given DMA handle.
The parameters are described in
.Xr bus_dma 9 .
.It Fo vme_dmamem_alloc
.Fa "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags"
@ -314,12 +318,14 @@ and address-space modifiers
Returns EINVAL on invalid inputs.
.El
.Sh AUTOCONFIGURATION
The VME bus is an indirect-connection bus. During autoconfiguration
each driver is required to probe the bus for the presence of a
device. A VME driver will receive a pointer to a
The VME bus is an indirect-connection bus.
During autoconfiguration each driver is required to probe the bus
for the presence of a device.
A VME driver will receive a pointer to a
.Fa struct vme_attach_args
hinting at "locations" (address ranges) on the VME bus where the
device may be located. The driver should check the number of address
device may be located.
The driver should check the number of address
ranges, allocate the address space of these ranges using
.Fn vme_space_alloc ,
and probe the address space for the device using
@ -342,7 +348,8 @@ This section describes places within the
source tree where actual code implementing or utilising the
machine-independent
.Nm
subsystem can be found. All pathnames are relative to
subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The

71
share/man/man9/vnfileops.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vnfileops.9,v 1.1 2002/10/14 04:56:49 gmcgarry Exp $
.\" $NetBSD: vnfileops.9,v 1.2 2002/10/14 13:43:36 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -67,14 +67,15 @@
.Fn vn_write "struct file *fp" "off_t *offset" "struct uio *uio" "struct ucred *cred" "int flags"
.Sh DESCRIPTION
The functions described in this page are the vnode-specific file
descriptor operations. They should only be accessed through the
opaque function pointers in the file descriptor entries. They are
described here only for completeness.
descriptor operations.
They should only be accessed through the opaque function pointers
in the file descriptor entries.
They are described here only for completeness.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn vn_closefile "fp" "p"
Common code for a file table vnode close operation. The file is
described by
Common code for a file table vnode close operation.
The file is described by
.Fa fp
and
.Fa p
@ -86,8 +87,8 @@ with the appropriate arguments.
.It Fn vn_fcntl "fp" "com" "data" "p"
Common code for a file table vnode
.Xr fcntl 2
operation. The file is
specified by
operation.
The file is specified by
.Fa fp .
The argument
.Fa p
@ -99,11 +100,12 @@ with the command
.Fa com
and buffer
.Fa data .
The vnode is unlocked on return. If the operation is successful zero
is returned, otherwise an appropriate error is returned.
The vnode is unlocked on return.
If the operation is successful zero is returned, otherwise an
appropriate error is returned.
.It Fn vn_ioctl "fp" "com" "data" "p"
Common code for a file table vnode ioctl operation. The file is
specified by
Common code for a file table vnode ioctl operation.
The file is specified by
.Fa fp .
The argument
.Fa p
@ -115,23 +117,27 @@ with the command
.Fa com
and buffer
.Fa data .
The vnode is unlocked on return. If the operation is successful zero
is returned, otherwise an appropriate error is returned.
The vnode is unlocked on return.
If the operation is successful zero is returned, otherwise an
appropriate error is returned.
.It Fn vn_read "fp" "offset" "uio" "cred" "flags"
Common code for a file table vnode read. The argument
Common code for a file table vnode read.
The argument
.Fa fp
is the file structure, The argument
.Fa offset
is the offset into the file. The argument
is the offset into the file.
The argument
.Fa uio
is the uio structure describing the memory to read into. The caller's
credentials are specified in
is the uio structure describing the memory to read into.
The caller's credentials are specified in
.Fa cred .
The
.Fa flags
argument can define FOF_UPDATE_OFFSET to update the read position in
the file. If the operation is successful zero is returned, otherwise
an appropriate error is returned.
the file.
If the operation is successful zero is returned, otherwise an
appropriate error is returned.
.It Fn vn_poll "fp" "events" "p"
Common code for a file table vnode poll operation.
.Fn vn_poll
@ -144,12 +150,13 @@ and the calling process
If the operation is success zero is returned, otherwise an appropriate
error code is returned.
.It Fn vn_statfile "fp" "sb" "p"
Common code for a stat operation. The file descriptor is specified by
the argument
Common code for a stat operation.
The file descriptor is specified by the argument
.Fa fp
and
.Fa sb
is the buffer to return the stat information. The argument
is the buffer to return the stat information.
The argument
.Fa p
is the calling process.
.Fn vn_statfile
@ -159,26 +166,30 @@ and transfer the contents of a vattr structure into a struct stat.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vn_write "fp" "offset" "uio" "cred" "flags"
Common code for a file table vnode write. The argument
Common code for a file table vnode write.
The argument
.Fa fp
is the file structure, The argument
.Fa offset
is the offset into the file. The argument
is the offset into the file.
The argument
.Fa uio
is the uio structure describing the memory to read from. The caller's
credentials are specified in
is the uio structure describing the memory to read from.
The caller's credentials are specified in
.Fa cred .
The
.Fa flags
argument can define FOF_UPDATE_OFFSET to update the read position in
the file. If the operation is successful zero is returned, otherwise
an appropriate error is returned.
the file.
If the operation is successful zero is returned, otherwise an
appropriate error is returned.
.El
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the vnode
framework can be found. All pathnames are relative to
framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The high-level convenience functions are implemented within the file

254
share/man/man9/vnode.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vnode.9,v 1.9 2002/08/15 03:22:49 wiz Exp $
.\" $NetBSD: vnode.9,v 1.10 2002/10/14 13:43:36 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -125,19 +125,20 @@
The vnode is the focus of all file activity in
.Nx .
There is a unique vnode allocated for each active file, directory,
mounted-on file, fifo, domain socket, symbolic link and device. The kernel
has no concept of a file's underlying structure and so it relies on the
information stored in the vnode to describe the file. Thus, the vnode
associated with a file holds all the administration information
pertaining to it.
mounted-on file, fifo, domain socket, symbolic link and device.
The kernel has no concept of a file's underlying structure and so it
relies on the information stored in the vnode to describe the file.
Thus, the vnode associated with a file holds all the administration
information pertaining to it.
.Pp
When a process requests an operation on a file, the
.Xr vfs 9
interface passes control to a file system type dependent function to carry
out the operation. If the file system type dependent function finds that
a vnode representing the file is not in main memory, it dynamically
allocates a new vnode from the system main memory pool. Once
allocated, the vnode is attached to the data structure pointer
out the operation.
If the file system type dependent function finds that a vnode
representing the file is not in main memory, it dynamically allocates
a new vnode from the system main memory pool.
Once allocated, the vnode is attached to the data structure pointer
associated with the cause of the vnode allocation and it remains
resident in the main memory until the system decides that it is no
longer needed and can be recycled.
@ -182,14 +183,14 @@ struct vnode {
.Ed
.Pp
Most members of the vnode structure should be treated as opaque and
only manipulated using the proper functions. There are some rather
common exceptions detailed throughout this page.
only manipulated using the proper functions.
There are some rather common exceptions detailed throughout this page.
.Pp
Files and file systems are inextricably linked with the virtual memory
system and
.Em v_uobj
contains the data maintained by the virtual memory system. For
compatibility with code written before the integration of
contains the data maintained by the virtual memory system.
For compatibility with code written before the integration of
.Xr uvm 9
into
.Nx
@ -221,8 +222,8 @@ Waiting for output associated with this vnode to complete.
.It VALIASED
This vnode has an alias.
.It VDIROP
This vnode is involved in a directory operation. This flag is used
exclusively by LFS.
This vnode is involved in a directory operation.
This flag is used exclusively by LFS.
.It VLAYER
This vnode is on a layered file system.
.It VONWORKLST
@ -232,13 +233,16 @@ This vnode possibly has dirty pages.
.El
.Pp
The VXLOCK flag is used to prevent multiple processes from entering
the vnode reclamation code. It is also used as a flag to indicate that
reclamation is in progress. The VXWANT flag is set by threads that
wish to be awaken when reclamation is finished. Before
the vnode reclamation code.
It is also used as a flag to indicate that reclamation is in progress.
The VXWANT flag is set by threads that wish to be awaken when
reclamation is finished.
Before
.Em v_flag
can be modified, the
.Em v_interlock
simplelock must be acquired. See
simplelock must be acquired.
See
.Xr lock 9
for details on the kernel locking API.
.Pp
@ -248,19 +252,22 @@ Each vnode has three reference counts:
and
.Em v_holdcnt .
The first is the number of active references within the
kernel to the vnode. This count is maintained by
kernel to the vnode.
This count is maintained by
.Fn vref ,
.Fn vrele ,
and
.Fn vput .
The second is the number of active references within the kernel to the
vnode performing write access to the file. It is maintained by the
vnode performing write access to the file.
It is maintained by the
.Xr open 2
and
.Xr close 2
system calls. The third is the number of references within the kernel
requiring the vnode to remain active and not be recycled. This count
is maintained by
system calls.
The third is the number of references within the kernel
requiring the vnode to remain active and not be recycled.
This count is maintained by
.Fn vhold
and
.Fn holdrele .
@ -269,8 +276,8 @@ When both the
and
.Em v_holdcnt
reach zero, the vnode is recycled to the freelist and may be reused
for another file. The transition to and from the freelist is handled
by
for another file.
The transition to and from the freelist is handled by
.Fn getnewvnode ,
.Fn ungetnewvnode
and
@ -289,8 +296,8 @@ vnode are recorded in
.Em v_numoutput .
It is used by
.Xr fsync 2
to wait for all writes to complete before returning to the user. Its
value must only be modified at splbio (see
to wait for all writes to complete before returning to the user.
Its value must only be modified at splbio (see
.Xr spl 9 ) .
It does not track the number of dirty buffers attached to the
vnode.
@ -298,11 +305,13 @@ vnode.
Every time a vnode is reassigned to a new file, the vnode capability
identifier
.Em v_id
is changed. It is used to maintain the name lookup cache consistency
by providing a unique \*[Lt]vnode *,v_id\*[Gt] tuple without requiring the cache
to hold a reference. The name lookup cache can later compare the
vnode's capability identifier to its copy and see if the vnode still
points to the same file. See
is changed.
It is used to maintain the name lookup cache consistency by providing
a unique \*[Lt]vnode *,v_id\*[Gt] tuple without requiring the cache to
hold a reference.
The name lookup cache can later compare the vnode's capability identifier
to its copy and see if the vnode still points to the same file.
See
.Xr namecache 9
for details on the name lookup cache.
.Pp
@ -314,21 +323,25 @@ for further information of file system mount status.
.Pp
The
.Em v_op
pointer points to its vnode operations vector. This vector describes
what operations can be done to the file associated with the vnode.
pointer points to its vnode operations vector.
This vector describes what operations can be done to the file associated
with the vnode.
The system maintains one vnode operations vector for each file system
type configured into the kernel. The vnode operations vector contains
a pointer to a function for each operation supported by the file
system. See
type configured into the kernel.
The vnode operations vector contains a pointer to a function for
each operation supported by the file system.
See
.Xr vnodeops 9
for a description of vnode operations.
.Pp
When not in use, vnodes are kept on the freelist through
.Em v_freelist .
The vnodes still reference valid files but may be reused to refer to a
new file at any time. Often, these vnodes are also held in caches in
the system, such as the name lookup cache. When a valid vnode which
is on the freelist is used again, the user must call
new file at any time.
Often, these vnodes are also held in caches in the system, such as
the name lookup cache.
When a valid vnode which is on the freelist is used again, the user
must call
.Fn vget
to increment the reference count and retrieve it from the freelist.
When a user wants a new vnode for another file
@ -339,7 +352,8 @@ the new file.
The type of object the vnode represents is recorded by
.Em v_type .
It is used by generic code to perform checks to ensure operations are
performed on valid file system objects. Valid types are:
performed on valid file system objects.
Valid types are:
.Pp
.Bl -tag -offset indent -width VFIFO -compact
.It VNON
@ -364,12 +378,15 @@ The vnode represents a bad file (not currently used).
.Pp
Vnode tag types are used by external programs only (e.g.,
.Xr pstat 8 ) ,
and should never be inspected by the kernel. Its use is deprecated
and should never be inspected by the kernel.
Its use is deprecated
since new
.Em v_tag
values cannot be defined for loadable file systems. The
values cannot be defined for loadable file systems.
The
.Em v_tag
member is read-only. Valid tag types are:
member is read-only.
Valid tag types are:
.Pp
.Bl -tag -offset indent -width "VT_FILECORE " -compact
.It VT_NON
@ -436,19 +453,22 @@ with extra checks, while the unlocking step usually does not need
additional checks and thus has no wrapper.
.Pp
The vnode locking operation is complicated because it is used for many
purposes. Sometimes it is used to bundle a series of vnode operations
(see
purposes.
Sometimes it is used to bundle a series of vnode operations (see
.Xr vnodeops 9 )
into an atomic group. Many file systems rely on it to prevent race
conditions in updating file system type specific data structures
rather than using their own private locks. The vnode lock operates as
a multiple-reader (shared-access lock) or single-writer lock
(exclusive access lock). The lock may be held while sleeping. While
the
into an atomic group.
Many file systems rely on it to prevent race conditions in updating
file system type specific data structures rather than using their
own private locks.
The vnode lock operates as a multiple-reader (shared-access lock)
or single-writer lock (exclusive access lock).
The lock may be held while sleeping.
While the
.Em v_vnlock
is acquired, the holder is guaranteed that the vnode will not be
reclaimed or invalidated. Most file system functions require that you
hold the vnode lock on entry. See
reclaimed or invalidated.
Most file system functions require that you hold the vnode lock on entry.
See
.Xr lock 9
for details on the kernel locking API.
.Pp
@ -460,19 +480,22 @@ For stacked file systems,
.Em v_vnlock
will generally point to
.Em v_vlock
of the lowest file system. Additionally, the implementation of the
vnode lock is the responsibility of the individual file systems and
of the lowest file system.
Additionally, the implementation of the vnode lock is the
responsibility of the individual file systems and
.Em v_vnlock
may also be NULL indicating that a leaf node does not export a lock
for vnode locking. In this case, stacked file systems (such as
nullfs) must call the underlying file system directly for locking.
for vnode locking.
In this case, stacked file systems (such as nullfs) must call the
underlying file system directly for locking.
.Pp
Each file system underlying a vnode allocates its own private area and
hangs it from
.Em v_data .
.Pp
Most functions discussed in this page that operate on vnodes cannot be
called from interrupt context. The members
called from interrupt context.
The members
.Em v_numoutput ,
.Em v_holdcnt ,
.Em v_dirtyblkhd ,
@ -483,8 +506,8 @@ and
are modified in interrupt context and must be protected by
.Xr splbio 9
unless it is certain that there is no chance an interrupt handler will
modify them. The vnode lock must not be acquired within interrupt
context.
modify them.
The vnode lock must not be acquired within interrupt context.
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn vcount "vp"
@ -509,11 +532,13 @@ of unlocked vnode
.Em vp .
Any code in the system which is using a vnode should call
.Fn vrele
when it is finished with the vnode. If
when it is finished with the vnode.
If
.Em v_usecount
of the vnode reaches zero and
.Em v_holdcnt
is greater than zero, the vnode is placed on the holdlist. If both
is greater than zero, the vnode is placed on the holdlist.
If both
.Em v_usecount
and
.Em v_holdcnt
@ -521,29 +546,30 @@ are zero, the vnode is placed on the freelist.
.It Fn vget "vp" "lockflags"
Reclaim vnode
.Fa vp
from the freelist, increment its reference count and lock it. The
argument
from the freelist, increment its reference count and lock it.
The argument
.Fa lockflags
specifies the
.Xr lockmgr 9
flags used to lock the vnode. If the VXLOCK is set in
flags used to lock the vnode.
If the VXLOCK is set in
.Fa vp Ns 's
.Em v_flag ,
vnode
.Fa vp
is being recycled in
.Fn vgone
and the calling thread sleeps until the transition is complete. When
it is awakened, an error is returned to indicate that the vnode is no
longer usable (possibly having been recycled to a new file system
type).
and the calling thread sleeps until the transition is complete.
When it is awakened, an error is returned to indicate that the vnode is
no longer usable (possibly having been recycled to a new file system type).
.It Fn vput "vp"
Unlock vnode
.Fa vp
and decrement its
.Em v_usecount .
Depending of the reference counts, move the vnode to the holdlist or
the freelist. This operation is functionally equivalent to calling
the freelist.
This operation is functionally equivalent to calling
.Xr VOP_UNLOCK 9
followed by
.Fn vrele .
@ -552,8 +578,9 @@ Mark the vnode
.Fa vp
as active by incrementing
.Em vp-\*[Gt]v_holdcnt
and moving the vnode from the freelist to the holdlist. Once on the
holdlist, the vnode will not be recycled until it is released with
and moving the vnode from the freelist to the holdlist.
Once on the holdlist, the vnode will not be recycled until it is
released with
.Fn holdrele .
.It Fn VHOLD "vp"
This function is an alias for
@ -571,20 +598,22 @@ This function is an alias for
Retrieve the next vnode from the freelist.
.Fn getnewvnode
must choose whether to allocate a new vnode or recycle an existing
one. The criterion for allocating a new one is that the total number
of vnodes is less than the number desired or there are no vnodes on
either free list. Generally only vnodes that have no buffers
associated with them are recycled and the next vnode from the freelist
is retrieved. If the freelist is empty, vnodes on the holdlist are
considered. The new vnode is returned in the address specified by
one.
The criterion for allocating a new one is that the total number of
vnodes is less than the number desired or there are no vnodes on either
free list.
Generally only vnodes that have no buffers associated with them are
recycled and the next vnode from the freelist is retrieved.
If the freelist is empty, vnodes on the holdlist are considered.
The new vnode is returned in the address specified by
.Fa vpp .
.Pp
The argument
.Fa mp
is the mount point for the file system requested the new vnode.
Before retrieving the new vnode, the file system is checked if it is
busy (such as currently unmounting). An error is returned if the file
system is unmounted.
busy (such as currently unmounting).
An error is returned if the file system is unmounted.
.Pp
The argument
.Fa tag
@ -593,14 +622,16 @@ is the vnode tag assigned to
The argument
.Fa vops
is the vnode operations vector of the file system requesting the new
vnode. If a vnode is successfully retrieved zero is returned,
otherwise an appropriate error code is returned.
vnode.
If a vnode is successfully retrieved zero is returned, otherwise an
appropriate error code is returned.
.It Fn ungetnewvnode "vp"
Undo the operation of
.Fn getnewvnode .
The argument
.Fa vp
is the vnode to return to the freelist. This function is needed for
is the vnode to return to the freelist.
This function is needed for
.Xr VFS_VGET 9
which may need to push back a vnode in case of a locking race
condition.
@ -619,14 +650,15 @@ Remove any vnodes in the vnode table belonging to mount point
.Fa mp .
If
.Fa skipvp
is not NULL it is exempt from being flushed. The argument
is not NULL it is exempt from being flushed.
The argument
.Fa flags
is a set of flags modifying the operation of
.Fn vflush .
If MNT_NOFORCE is specified, there should not be any active vnodes and
an error is returned if any are found (this is a user error, not a
system error). If MNT_FORCE is specified, active vnodes that are
found are detached.
system error).
If MNT_FORCE is specified, active vnodes that are found are detached.
.It Fn vaccess "type" "file_mode" "uid" "gid" "acc_mode" "cred"
Do access checking by comparing the file's permissions to the caller's
desired access type
@ -637,9 +669,10 @@ and credentials
Check to see if the new vnode
.Fa vp
represents a special device for which another vnode represents the
same device. If such an aliases exists the existing contents and the
aliased vnode are deallocated. The caller is responsible for filling
the new vnode with its new contents.
same device.
If such an aliases exists the existing contents and the aliased vnode
are deallocated.
The caller is responsible for filling the new vnode with its new contents.
.It Fn bdevvp "dev" "vpp"
Create a vnode for a block device.
.Fn bdevvp
@ -650,8 +683,8 @@ Create a vnode for a character device.
.Fn cdevvp
is used for the console and kernfs special devices.
.It Fn vfinddev "dev" "vtype" "vpp"
Lookup a vnode by device number. The vnode is returned in the address
specified by
Lookup a vnode by device number.
The vnode is returned in the address specified by
.Fa vpp .
.It Fn vdevgone "int maj" "int min" "int minh" "enum vtype type"
Reclaim all vnodes that correspond to the specified minor number range
@ -687,14 +720,16 @@ The argument
.Fa p
and
.Fa cred
specified the calling process and its credentials. The
specified the calling process and its credentials.
The
.Xr sleep 9
flag and timeout are specified by the arguments
.Fa slpflag
and
.Fa slptimeo
respectively. If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
respectively.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vtruncbuf "vp" "lbn" "slpflag" "slptimeo"
Destroy any in-core buffers past the file truncation length for the
locked vnode
@ -708,12 +743,14 @@ flag and timeout are specified by the arguments
.Fa slpflag
and
.Fa slptimeo
respectively. If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
respectively.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vprint "label" "vp"
This function is used by the kernel to dump vnode information during a
panic. It is only used if the kernel option DIAGNOSTIC is compiled into
the kernel. The argument
panic.
It is only used if the kernel option DIAGNOSTIC is compiled into the kernel.
The argument
.Fa label
is a string to prefix the information dump of vnode
.Fa vp .
@ -722,7 +759,8 @@ is a string to prefix the information dump of vnode
This section describes places within the
.Nx
source tree where actual code implementing or utilizing the vnode
framework can be found. All pathnames are relative to
framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The vnode framework is implemented within the file
@ -739,11 +777,13 @@ The vnode framework is implemented within the file
.Xr vnodeops 9 ,
.Xr vnsubr 9
.Sh BUGS
The locking protocol is inconsistent. Many vnode operations are
passed locked vnodes on entry but release the lock before they exit.
The locking protocol is inconsistent.
Many vnode operations are passed locked vnodes on entry but release
the lock before they exit.
The locking protocol is used in some places to attempt to make a
series of operations atomic (e.g., access check then operation). This
does not work for non-local file systems that do not support locking
(e.g. NFS). The
series of operations atomic (e.g., access check then operation).
This does not work for non-local file systems that do not support locking
(e.g. NFS).
The
.Nm
interface would benefit from a simpler locking protocol.

716
share/man/man9/vnodeops.9
View File

File diff suppressed because it is too large Load Diff

70
share/man/man9/vnsubr.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: vnsubr.9,v 1.8 2002/10/14 04:56:49 gmcgarry Exp $
.\" $NetBSD: vnsubr.9,v 1.9 2002/10/14 13:43:37 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -97,7 +97,8 @@ functions for simplied access to the vnode operations described in
.It Fn vn_bwrite "ap"
Common code for block write operations.
.It Fn vn_close "vp" "flags" "cred" "p"
Common code for a vnode close. The argument
Common code for a vnode close.
The argument
.Fa vp
is the locked vnode of the vnode to close.
.Fn vn_close
@ -105,15 +106,17 @@ simply locks the vnode, invokes the vnode operation
.Xr VOP_CLOSE 9
and calls
.Fn vput
to return the vnode to the freelist or holdlist. Note that
to return the vnode to the freelist or holdlist.
Note that
.Fn vn_close
expects an unlocked, referenced vnode and will dereference the vnode
prior to returning. If the operation is successful zero is returned,
prior to returning.
If the operation is successful zero is returned,
otherwise an appropriate error is returned.
.It Fn vn_default_error "v"
A generic "default" routine that just returns error. It is used by a
file system to specify unsupported operations in the vnode operations
vector.
A generic "default" routine that just returns error.
It is used by a file system to specify unsupported operations in
the vnode operations vector.
.It Fn vn_isunder "dvp" "rvp" "p"
Common code to check if one directory specified by the vnode
.Fa rvp
@ -129,8 +132,8 @@ is intended to be used in
.Xr fchdir 2 ,
etc., to ensure that
.Xr chroot 2
actually means something. If the operation is successful zero is
returned, otherwise 1 is returned.
actually means something.
If the operation is successful zero is returned, otherwise 1 is returned.
.It Fn vn_lock "vp" "flags"
Common code to acquire the lock for vnode
.Fa vp .
@ -138,14 +141,16 @@ The argument
.Fa flags
specifies the
.Xr lockmgr 9
flags used to lock the vnode. If the operation is successful zero is
returned, otherwise an appropriate error code is returned. The vnode
interlock
flags used to lock the vnode.
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
The vnode interlock
.Em v_interlock
is releases on return.
.Pp
.Fn vn_lock
must not be called when the vnode's reference count is zero. Instead,
must not be called when the vnode's reference count is zero.
Instead,
.Xr vget 9
should be used.
.It Fn vn_markexec "vp"
@ -169,8 +174,8 @@ Common code to restore the vnode lock flags for the vnode
It is called when done with
.Fn vn_setrecurse .
.It Fn vn_open "ndp" "fmode" "cmode"
Common code for vnode open operations. The pathname is described in
the nameidata pointer (see
Common code for vnode open operations.
The pathname is described in the nameidata pointer (see
.Xr namei 9 ) .
The arguments
.Fa fmode
@ -184,31 +189,35 @@ checks permissions and invokes the
.Xr VOP_OPEN 9
or
.Xr VOP_CREATE 9
vnode operations. If the operation is successful zero is returned,
vnode operations.
If the operation is successful zero is returned,
otherwise an appropriate error code is returned.
.It Fo vn_rdwr
.Fa "rw" "vp" "base" "len" "offset" "segflg" "ioflg"
.Fa "cred" "aresid" "p"
.Fc
Common code to package up an I/O request on a vnode into a uio and
then perform the I/O. The argument
then perform the I/O.
The argument
.Fa rw
specifies whether the I/O is a read (UIO_READ) or write (UIO_WRITE)
operation. The unlocked vnode is specified by
operation.
The unlocked vnode is specified by
.Fa vp .
The arguments
.Fa p
and
.Fa cred
are the calling process and its credentials. The remaining arguments
specify the uio parameters. For further information on these
parameters see
are the calling process and its credentials.
The remaining arguments specify the uio parameters.
For further information on these parameters see
.Xr uiomove 9 .
.It Fo vn_readdir
.Fa "fp" "buf" "segflg" "count" "done" "p" "cookies"
.Fa "ncookies"
.Fc
Common code for reading the contents of a directory. The argument
Common code for reading the contents of a directory.
The argument
.Fa fp
is the file structure,
.Fa buf
@ -218,7 +227,8 @@ The arguments
and
.Fa ncookies
specify the addresses for the list and number of directory seek
cookies generated for NFS. Both
cookies generated for NFS.
Both
.Fa cookies
and
.Fa ncookies
@ -227,12 +237,13 @@ should be NULL is they aren't required to be returned by
If the operation is successful zero is returned, otherwise an
appropriate error code is returned.
.It Fn vn_stat "vp" "sb" "p"
Common code for a vnode stat operation. The vnode is specified by the
argument
Common code for a vnode stat operation.
The vnode is specified by the argument
.Fa vp
and
.Fa sb
is the buffer to return the stat information. The argument
is the buffer to return the stat information.
The argument
.Fa p
is the calling process.
.Fn vn_stat
@ -253,8 +264,8 @@ returned to indicate that the vnode can be written to.
.It Bq Er ETXTBSY
Cannot write to a vnode since is a process's text image.
.It Bq Er ENOENT
The vnode has been reclaimed and is dead. This error is only returned
if the LK_RETRY flag is not passed to
The vnode has been reclaimed and is dead.
This error is only returned if the LK_RETRY flag is not passed to
.Fn vn_lock .
.It Bq Er EBUSY
The LK_NOWAIT flag was set and
@ -265,7 +276,8 @@ would have slept.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the vnode
framework can be found. All pathnames are relative to
framework can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The high-level convenience functions are implemented within the file

21
share/man/man9/wscons.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: wscons.9,v 1.4 2002/09/20 03:35:33 uebayasi Exp $
.\" $NetBSD: wscons.9,v 1.5 2002/10/14 13:43:37 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -44,24 +44,25 @@
The
.Nm
driver provides a machine-independent framework for workstation
consoles. It consists of several cooperating modules:
consoles.
It consists of several cooperating modules:
.Bl -bullet
.It
display adapters (see
display adapters (see
.Xr wsdisplay 9 )
.It
keyboards (see
keyboards (see
.Xr wskbd 9 )
.It
pointers and mice (see
pointers and mice (see
.Xr wsmouse 9 )
.It
input event multiplexor
input event multiplexor
.It
font handling (see
font handling (see
.Xr wsfont 9 )
.It
terminal emulation (see
terminal emulation (see
.Xr wsdisplay 9 )
.El
.Pp
@ -71,8 +72,8 @@ the various machine-dependent console implementations.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent wscons subsystem can be found. All pathnames are
relative to
machine-independent wscons subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory

121
share/man/man9/wsdisplay.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: wsdisplay.9,v 1.10 2002/09/19 00:52:54 uebayasi Exp $
.\" $NetBSD: wsdisplay.9,v 1.11 2002/10/14 13:43:37 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -66,31 +66,32 @@ The
.Nm
module is a component of the
.Xr wscons 9
framework to provide machine-independent display support. Most of the
support is provided by the
framework to provide machine-independent display support.
Most of the support is provided by the
.Xr wsdisplay 4
device driver, which must be a child of the hardware device driver.
.Pp
The wscons display interface is complicated by the fact that there are
two different interfaces. The first interface corresponds to the
simple bit-mapped display which doesn't provide terminal-emulation and
console facilities. The second interface provides machine-independent
terminal emulation for displays that can support glass-tty terminal
emulations. These are character-oriented displays, with row and
column numbers starting at zero in the upper left hand corner of the
screen. Display drivers which cannot emulate terminals use the first
interface. In most cases, the low-level hardware driver can use the
two different interfaces.
The first interface corresponds to the simple bit-mapped display which
doesn't provide terminal-emulation and console facilities.
The second interface provides machine-independent terminal emulation
for displays that can support glass-tty terminal emulations.
These are character-oriented displays, with row and column numbers
starting at zero in the upper left hand corner of the screen.
Display drivers which cannot emulate terminals use the first interface.
In most cases, the low-level hardware driver can use the
.Xr rasops 9
interface to provide enough support to allow glass-tty terminal
emulation. If the display is not the console, terminal emulation does
not make sense and the display operates using the bit-mapped
interface.
emulation.
If the display is not the console, terminal emulation does not make
sense and the display operates using the bit-mapped interface.
.Pp
The wscons framework allows concurrent displays to be active. It also
provides support for multiple screens for each display and therefore
allows a virtual terminal on each screen. Multiple terminal
emulations and fonts can be active at the same time allowing different
emulations and fonts for each screen.
The wscons framework allows concurrent displays to be active.
It also provides support for multiple screens for each display and
therefore allows a virtual terminal on each screen.
Multiple terminal emulations and fonts can be active at the same
time allowing different emulations and fonts for each screen.
.Pp
Font manipulation facilities for the terminal emulation interface are
available through the
@ -102,10 +103,11 @@ of the following data types:
.Bl -tag -width compact
.It Fa struct wsdisplay_accessops
A structure used to specify the display access functions invoked by
userland program which require direct device access, such as X11. All
displays must provide this structure and pass it to the
userland program which require direct device access, such as X11.
All displays must provide this structure and pass it to the
.Xr wsdisplay 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
int (*ioctl)(void *v, u_long cmd, caddr_t data,
int flag, struct proc *p);
@ -124,18 +126,24 @@ child device. It has the following members:
The
.Fa ioctl
member defines the function to be called to perform display-specific
ioctl calls. The
ioctl calls.
The
.Fa mmap
member defines the function for mapping a part of the display device
into user address space. The
into user address space.
The
.Fa alloc_screen
member defines a function for allocating a new screen which can be
used as a virtual terminal. The
used as a virtual terminal.
The
.Fa free_screen
member defines a function for de-allocating a screen. The
member defines a function for de-allocating a screen.
The
.Fa show_screen
member defines a function for mapping a screen onto the physical
display. This function is used for between switching screens. The
display.
This function is used for between switching screens.
The
.Fa load_font
member defines a function for loading a new font into the display.
The
@ -149,10 +157,11 @@ functions, which is passed to them when they are invoked.
.It Fa struct wsdisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the simple bit-mapped interface. If the full
terminal-emulation interface is to be used, then
child device for the simple bit-mapped interface.
If the full terminal-emulation interface is to be used, then
.Em struct wsemuldisplaydev_attach_args
should be used instead. It has the following members:
should be used instead.
It has the following members:
.Bd -literal
const struct wsdisplay_accessops *accessops;
void *accesscookie;
@ -160,10 +169,11 @@ should be used instead. It has the following members:
.It Fa struct wsemuldisplaydev_attach_args
A structure used to attach the
.Xr wsdisplay 4
child device for the full terminal emulation interface. If the simple
bit-mapped interface is to be used, then
child device for the full terminal emulation interface.
If the simple bit-mapped interface is to be used, then
.Em struct wsdisplaydev_attach_args
should be used instead. It has the following members:
should be used instead.
It has the following members:
.Bd -literal
int console;
const struct wsscreen_list *scrdata;
@ -171,11 +181,12 @@ should be used instead. It has the following members:
void *accesscookie;
.Ed
.It Fa struct wsdisplay_emulops
A structure used to specify the display emulation functions. All
displays intending to provide terminal emulation must provide
A structure used to specify the display emulation functions.
All displays intending to provide terminal emulation must provide
this structure and pass it to the
.Xr wsdisplay 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
void (*cursor)(void *c, int on, int row, int col);
int (*mapchar)(void *, int, unsigned int *);
@ -198,10 +209,12 @@ cookie provided by the display driver associated with these
functions, which is passed to them when they are invoked.
.It Fa struct wsscreen_descr
A structure passed to wscons by the display driver to describe a
screen. All displays which can operate as a console must provide this
structure and pass it to the
screen.
All displays which can operate as a console must provide this structure
and pass it to the
.Xr wsdisplay 4
child device. It contains the following members:
child device.
It contains the following members:
.Bd -literal
char *name;
int ncols, nrows;
@ -212,8 +225,8 @@ child device. It contains the following members:
.Pp
The
.Em capabilities
member is a set of flags describing the screen capabilities. It can
contain the following flags:
member is a set of flags describing the screen capabilities.
It can contain the following flags:
.Pp
.Bl -tag -offset indent -width WSSCREEN_UNDERLINE -compact
.It WSSCREEN_WSCOLORS
@ -229,7 +242,8 @@ can underline
.El
.It Fa struct wsscreen_list
A structure passed to wscons by the display driver to tell about its
capabilities. It contains the following members:
capabilities.
It contains the following members:
.Bd -literal
int nscreens;
const struct wsscreen_descr **screens;
@ -238,8 +252,8 @@ capabilities. It contains the following members:
A structure passed to wscons by the display driver describing the
interface for external screen switching/process synchronization.
This structure is optional and only required by displays operating
with terminal emulation and intending to support multiple screens. It
contains the following members:
with terminal emulation and intending to support multiple screens.
It contains the following members:
.Bd -literal
int (*detach)(void *, int, void (*)(), void *);
int (*attach)(void *, int, void (*)(), void *);
@ -270,8 +284,8 @@ and number of rows
.Fa crows .
The argument
.Fa defattr
specifies the default attribute (color) for the console. Different
terminal emulations can be active at the same time on one display.
specifies the default attribute (color) for the console.
Different terminal emulations can be active at the same time on one display.
.It Fn wsdisplaydevprint "aux" "pnp"
The default wsdisplay printing routine used by
.Fn config_found .
@ -287,7 +301,8 @@ The default wsemul printing routine used by
Display drivers which want to utilize the wsdisplay module must be a
parent to the
.Xr wsdisplay 4
device and provide an attachment interface. To attach the
device and provide an attachment interface.
To attach the
.Xr wsdisplay 4
device, the display driver must allocate and populate a
.Fa wsdisplaydev_attach_args
@ -305,8 +320,9 @@ structure instead of the standard
.Fa wsdisplaydev_attach_args
to
.Fn config_found
to perform the attach. If the display is not the console the
attachment is the same as wsdisplaydev_attach_args.
to perform the attach.
If the display is not the console the attachment is the same
as wsdisplaydev_attach_args.
.Sh OPERATION
If the display belongs to the system console, it must describe the
default screen by invoking
@ -316,7 +332,8 @@ at console attach time.
All display manipulation is performed by the wscons interface by using
the callbacks defined in the
.Em wsdisplay_accessops
structure. The
structure.
The
.Fn ioctl
function is called by the wscons interface to perform display-specific
ioctl operations (see
@ -339,8 +356,8 @@ structure.
This section describes places within the
.Nx
source tree where actual code implementing or utilizing the
machine-independent wscons subsystem can be found. All pathnames are
relative to
machine-independent wscons subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory

38
share/man/man9/wsfont.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: wsfont.9,v 1.6 2002/03/16 12:10:18 ad Exp $
.\" $NetBSD: wsfont.9,v 1.7 2002/10/14 13:43:38 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -80,11 +80,12 @@ The
.Nm
module is a component of the
.Xr wscons 9
framework to provide access to display fonts. Fonts may be loaded
dynamically into the kernel or included statically in the kernel at
compile time. Display drivers which emulate a glass-tty console on a
bit-mapped display can add, remove and find fonts for use by
device-dependent blitter operations.
framework to provide access to display fonts.
Fonts may be loaded dynamically into the kernel or included statically
in the kernel at compile time.
Display drivers which emulate a glass-tty console on a bit-mapped
display can add, remove and find fonts for use by device-dependent
blitter operations.
.Pp
The primary data type for manipulating fonts is the
.Em wsdisplay_font
@ -142,8 +143,8 @@ Return zero if not matched and non-zero if matched.
.It Fn wsfont_find "name" "width" "height" "stride" "bitorder" "byteorder"
Find the font called
.Fa name
from the fonts loaded into the kernel. The font aspect is specified
by
from the fonts loaded into the kernel.
The font aspect is specified by
.Fa width ,
.Fa height ,
and
@ -151,16 +152,16 @@ and
If
.Fn wsfont_find
is called with any of the parameters as 0, it indicates that we don't
care about that aspect of the font. If the font is found a
(nonnegative-valued) cookie is returned which can used with the other
functions.
care about that aspect of the font.
If the font is found a (nonnegative-valued) cookie is returned which
can used with the other functions.
.Pp
The
.Fa bitorder
and
.Fa byteorder
arguments are the bit order and byte order required. Valid values
are:
arguments are the bit order and byte order required.
Valid values are:
.Bl -tag -width compact
.It WSDISPLAY_FONTORDER_KNOWN
The font is in known ordered format and doesn't need converting.
@ -188,7 +189,8 @@ from the font list.
The value of cookie was returned by
.Fn wsfont_add .
.It Fn wsfont_enum "callback"
Enumerate the list of fonts. For each font in the font list, the
Enumerate the list of fonts.
For each font in the font list, the
.Fa callback
function argument is called with the arguments specifying the font
name, width, height and stride.
@ -199,8 +201,8 @@ so that it cannot be unloaded from the kernel while is being used.
If the bit or byte order of the font to be locked differs from what
has been requested with
.Fn wsfont_find
then the glyph data will be modified to match. At this point it may be
necessary for
then the glyph data will be modified to match.
At this point it may be necessary for
.Fn wsfont_lock
to make a copy of the font data; this action is transparent to the caller.
A later call to
@ -229,8 +231,8 @@ Returns the glyph or success or -1 on error.
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent wsfont subsystem can be found. All pathnames are
relative to
machine-independent wsfont subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory

63
share/man/man9/wskbd.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: wskbd.9,v 1.6 2002/03/19 10:34:50 wiz Exp $
.\" $NetBSD: wskbd.9,v 1.7 2002/10/14 13:43:38 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -66,8 +66,8 @@ The
.Nm
module is a component of the
.Xr wscons 9
framework to provide machine-indpendent keyboard support. Most of the
support is provided by the
framework to provide machine-indpendent keyboard support.
Most of the support is provided by the
.Xr wskbd 4
device driver, which must be a child of the hardware device driver.
.Sh DATA TYPES
@ -79,10 +79,11 @@ An opaque type describing keyboard properties.
.It Fa keysym_t
The wscons keyboard-independent symbolic representation of the keypress.
.It Fa struct wskbd_accessops
A structure used to specify the keyboard access functions. All
keyboards must provide this structure and pass it to the
A structure used to specify the keyboard access functions.
All keyboards must provide this structure and pass it to the
.Xr wskbd 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
int (*enable)(void *, int);
void (*set_leds)(void *, int);
@ -93,10 +94,12 @@ child device. It has the following members:
The
.Fa enable
member defines the function to be called to enable keypress passing to
wscons. The
wscons.
The
.Fa set_leds
member defined the function to be called to set the LEDs on the
keyboard. The
keyboard.
The
.Fa ioctl
member defines the function to be called to perform keyboard-specific
ioctl calls.
@ -106,12 +109,14 @@ There is a
cookie provided by the keyboard driver associated with these
functions, which is passed to them when they are invoked.
.It Fa struct wskbd_consops
A structure used to specify the keyboard console operations. All
keyboards which can operate as a console must provide this structure
A structure used to specify the keyboard console operations.
All keyboards which can operate as a console must provide this structure
and pass it to the
.Xr wskbd 4
child device. If the keyboard cannot be a console, it is not
necessary to specify this structure. It has the following members:
child device.
If the keyboard cannot be a console, it is not
necessary to specify this structure.
It has the following members:
.Bd -literal
void (*getc)(void *, u_int *, int *);
void (*pollc)(void *, int);
@ -124,7 +129,8 @@ cookie provided by the keyboard driver associated with these
functions, which is passed to them when they are invoked.
.It Fa struct wscons_keydesc
A structure used to describe a keyboard mapping table to convert
keyboard-specific keycodes to wscons keysyms. It has the
keyboard-specific keycodes to wscons keysyms.
It has the
following members:
.Bd -literal
kbd_t name; /* name of this map */
@ -134,7 +140,8 @@ following members:
.Ed
.It Fa struct wskbd_mapdata
A structure used to describe the keyboard layout and operation to
interpret the keyboard layout. it contains the following members:
interpret the keyboard layout.
it contains the following members:
.Bd -literal
const struct wscons_keydesc *keydesc;
kbd_t layout;
@ -142,7 +149,8 @@ interpret the keyboard layout. it contains the following members:
.It Fa struct wskbd_attach_args
A structure used to attach the
.Xr wskbd 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
int console;
const struct wskbd_mapdata *keymap;
@ -219,7 +227,8 @@ Pass the keypress of value
.Fa value
and type
.Fa type
to wscons keyboard driver. Valid values of
to wscons keyboard driver.
Valid values of
.Fa type
are:
.Bl -tag -width compact
@ -231,9 +240,11 @@ Key pressed.
.It Fn wskbd_rawinput "kbddev" "buf" "len"
Pass the raw keypress in the buffer
.Fa buf
to the wscons keyboard driver. The buffer is
to the wscons keyboard driver.
The buffer is
.Fa len
bytes long. This function should only be called if the kernel option
bytes long.
This function should only be called if the kernel option
.Em WSDISPLAY_COMPAT_RAWKBD
is enabled.
.It Fn wskbd_cnattach "consops" "conscookie" "mapdata"
@ -259,7 +270,8 @@ The default wskbd printing routine used by
Keyboard drivers which want to utilise the wskbd module must be a
parent to the
.Xr wskbd 4
device and provide an attachment interface. To attach the
device and provide an attachment interface.
To attach the
.Xr wskbd 4
device, the keyboard driver must allocate and populate a
.Fa wskbd_attach_args
@ -271,7 +283,8 @@ The
.Fa keymap
member points to the
.Em wskbd_mapdata
structure which describes the keycode mapping operations. The
structure which describes the keycode mapping operations.
The
.Fa accessops
member points to the
.Em wskbd_accessops
@ -300,11 +313,13 @@ wscons via
The wscons framework calls back into the hardware driver by invoking
the functions that are specified in the
.Em accessops
structure. The
structure.
The
.Fn enable
and
.Fn set_leds
functions are relatively simple and self-explanatory. The
functions are relatively simple and self-explanatory.
The
.Fn ioctl
function is called by the wscons interface to perform
keyboard-specific ioctl operations (see
@ -321,8 +336,8 @@ Valid commands are listed in
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent wscons subsystem can be found. All pathnames are
relative to
machine-independent wscons subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory

42
share/man/man9/wsmouse.9
View File

@ -1,4 +1,4 @@
.\" $NetBSD: wsmouse.9,v 1.3 2002/02/13 08:18:58 ross Exp $
.\" $NetBSD: wsmouse.9,v 1.4 2002/10/14 13:43:38 wiz Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
@ -55,8 +55,8 @@ The
.Nm
module is a component of the
.Xr wscons 9
framework to provide machine-indpendent mouse support. Most of the
support is provided by the
framework to provide machine-indpendent mouse support.
Most of the support is provided by the
.Xr wsmouse 4
device driver, which must be a child of the hardware device driver.
.Sh DATA TYPES
@ -64,10 +64,11 @@ Mouse drivers providing support for wscons pointer devices will make use
of the following data types:
.Bl -tag -width compact
.It Fa struct wsmouse_accessops
A structure used to specify the mouse access functions. All pointer
devices must provide this structure and pass it to the
A structure used to specify the mouse access functions.
All pointer devices must provide this structure and pass it to the
.Xr wsmouse 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
int (*enable)(void *);
int (*ioctl)(void *v, u_long cmd, caddr_t data,
@ -79,7 +80,8 @@ The
.Fa enable
member defines the function to be called to enable monitoring pointer
movements and passing these events to
wscons. The
wscons.
The
.Fa disable
member defines the function to disable movement events.
The
@ -94,7 +96,8 @@ which is passed to them when they are invoked.
.It Fa struct wsmouse_attach_args
A structure used to attach the
.Xr wsmouse 4
child device. It has the following members:
child device.
It has the following members:
.Bd -literal
const struct wsmouse_accessops *accessops;
void *accesscookie;
@ -106,15 +109,17 @@ child device. It has the following members:
Callback from the mouse driver to the wsmouse interface driver.
The argument
.Fa btns
specifies the current button configuration. The pointer coordinate is
specified by the
specifies the current button configuration.
The pointer coordinate is specified by the
.Fa x ,
.Fa y ,
.Fa z
tuple. The
tuple.
The
.Fa flags
argument specify whether the pointer device and the measurement is in
relative or absolute mode. Valid values for
relative or absolute mode.
Valid values for
.Fa flags
are:
.Bl -tag -width compact
@ -137,7 +142,8 @@ The default wsmouse printing routine used by
Mouse drivers which want to utilise the wsmouse module must be a
parent to the
.Xr wsmouse 4
device and provide an attachment interface. To attach the
device and provide an attachment interface.
To attach the
.Xr wsmouse 4
device, the mouse driver must allocate and populate a
.Fa wsmouse_attach_args
@ -154,11 +160,13 @@ events to wscons via
The wscons framework calls back into the hardware driver by invoking
the functions that are specified in the
.Em accessops
structure. The
structure.
The
.Fn enable
and
.Fn disable
functions are relatively simple and self-explanatory. The
functions are relatively simple and self-explanatory.
The
.Fn ioctl
function is called by the wscons interface to perform
mouse-specific ioctl operations (see
@ -175,8 +183,8 @@ Valid commands are listed in
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent wscons subsystem can be found. All pathnames are
relative to
machine-independent wscons subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The wscons subsystem is implemented within the directory