From 770eef2122c1bb22d40d54fcd69ce7da284c1117 Mon Sep 17 00:00:00 2001 From: wiz Date: Mon, 14 Oct 2002 13:43:14 +0000 Subject: [PATCH] New sentence, new line. --- share/man/man9/audio.9 | 118 ++-- share/man/man9/autoconf.9 | 6 +- share/man/man9/bcopy.9 | 5 +- share/man/man9/bufq.9 | 5 +- share/man/man9/bus_dma.9 | 191 ++++--- share/man/man9/bus_space.9 | 585 ++++++++++--------- share/man/man9/callout.9 | 32 +- share/man/man9/cardbus.9 | 65 ++- share/man/man9/cnmagic.9 | 40 +- share/man/man9/config.9 | 137 +++-- share/man/man9/cons.9 | 25 +- share/man/man9/copy.9 | 8 +- share/man/man9/cpu_configure.9 | 9 +- share/man/man9/cpu_coredump.9 | 9 +- share/man/man9/cpu_dumpconf.9 | 5 +- share/man/man9/cpu_exit.9 | 6 +- share/man/man9/cpu_fork.9 | 11 +- share/man/man9/cpu_initclocks.9 | 6 +- share/man/man9/cpu_reboot.9 | 8 +- share/man/man9/cpu_swapout.9 | 8 +- share/man/man9/cpu_sysctl.9 | 6 +- share/man/man9/disk.9 | 86 +-- share/man/man9/dmover.9 | 160 +++--- share/man/man9/doshutdownhooks.9 | 5 +- share/man/man9/driver.9 | 185 +++--- share/man/man9/ethersubr.9 | 5 +- share/man/man9/evcnt.9 | 66 ++- share/man/man9/extent.9 | 80 +-- share/man/man9/fetch.9 | 8 +- share/man/man9/fork1.9 | 22 +- share/man/man9/inittodr.9 | 10 +- share/man/man9/ioctl.9 | 33 +- share/man/man9/ipkdb.9 | 32 +- share/man/man9/isa.9 | 99 ++-- share/man/man9/isapnp.9 | 49 +- share/man/man9/kprintf.9 | 26 +- share/man/man9/kthread.9 | 21 +- share/man/man9/linedisc.9 | 13 +- share/man/man9/lock.9 | 174 +++--- share/man/man9/ltsleep.9 | 13 +- share/man/man9/malloc.9 | 6 +- share/man/man9/mbuf.9 | 8 +- share/man/man9/mca.9 | 69 ++- share/man/man9/memcpy.9 | 5 +- share/man/man9/namei.9 | 89 +-- share/man/man9/pci.9 | 140 +++-- share/man/man9/pci_configure_bus.9 | 59 +- share/man/man9/pci_intr.9 | 16 +- share/man/man9/pcmcia.9 | 92 +-- share/man/man9/pfil.9 | 53 +- share/man/man9/pmc.9 | 48 +- share/man/man9/pool.9 | 5 +- share/man/man9/powerhook_establish.9 | 18 +- share/man/man9/properties.9 | 82 +-- share/man/man9/ras.9 | 20 +- share/man/man9/rasops.9 | 20 +- share/man/man9/ratecheck.9 | 21 +- share/man/man9/resettodr.9 | 5 +- share/man/man9/rnd.9 | 42 +- share/man/man9/rt_timer.9 | 36 +- share/man/man9/scsipi.9 | 124 ++-- share/man/man9/setjmp.9 | 5 +- share/man/man9/shutdownhook_establish.9 | 15 +- share/man/man9/signal.9 | 106 ++-- share/man/man9/softintr.9 | 12 +- share/man/man9/spl.9 | 102 ++-- share/man/man9/suser.9 | 8 +- share/man/man9/tc.9 | 33 +- share/man/man9/time.9 | 13 +- share/man/man9/todr.9 | 20 +- share/man/man9/ucom.9 | 19 +- share/man/man9/usbdi.9 | 8 +- share/man/man9/vattr.9 | 8 +- share/man/man9/vfs.9 | 9 +- share/man/man9/vfsops.9 | 127 +++-- share/man/man9/vme.9 | 73 +-- share/man/man9/vnfileops.9 | 71 ++- share/man/man9/vnode.9 | 254 +++++---- share/man/man9/vnodeops.9 | 716 ++++++++++++++---------- share/man/man9/vnsubr.9 | 70 ++- share/man/man9/wscons.9 | 21 +- share/man/man9/wsdisplay.9 | 121 ++-- share/man/man9/wsfont.9 | 38 +- share/man/man9/wskbd.9 | 63 ++- share/man/man9/wsmouse.9 | 42 +- 85 files changed, 2997 insertions(+), 2287 deletions(-) diff --git a/share/man/man9/audio.9 b/share/man/man9/audio.9 index ae28ee11faed..1b6b71e775d7 100644 --- a/share/man/man9/audio.9 +++ b/share/man/man9/audio.9 @@ -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 @@ -224,16 +228,17 @@ to 1 to .Va factor_denom , .Dv AUDIO_ENCODING_SLINEAR_LE -to +to .Va hw_encoding 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 @@ -261,7 +267,7 @@ and respectively. .Pp Note: The order of conversion is -.Va sw_code +.Va sw_code followed by sampling rate and mono-stereo in playing, and sampling rate and mono-stereo followed by .Va sw_code @@ -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 diff --git a/share/man/man9/autoconf.9 b/share/man/man9/autoconf.9 index d178715cb5cf..8ba61ec118da 100644 --- a/share/man/man9/autoconf.9 +++ b/share/man/man9/autoconf.9 @@ -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 diff --git a/share/man/man9/bcopy.9 b/share/man/man9/bcopy.9 index 3c8b3cf51fda..b8db931bec12 100644 --- a/share/man/man9/bcopy.9 +++ b/share/man/man9/bcopy.9 @@ -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 diff --git a/share/man/man9/bufq.9 b/share/man/man9/bufq.9 index 7f4baddc5f52..4ea8af2df577 100644 --- a/share/man/man9/bufq.9 +++ b/share/man/man9/bufq.9 @@ -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" diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9 index dc2ca731ee98..dfe7c4c6441b 100644 --- a/share/man/man9/bus_dma.9 +++ b/share/man/man9/bus_dma.9 @@ -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 diff --git a/share/man/man9/bus_space.9 b/share/man/man9/bus_space.9 index f8a3ddaf9885..b448372bc4eb 100644 --- a/share/man/man9/bus_space.9 +++ b/share/man/man9/bus_space.9 @@ -1,4 +1,4 @@ -.\" $NetBSD: bus_space.9,v 1.27 2002/10/09 19:18:44 wiz Exp $ +.\" $NetBSD: bus_space.9,v 1.28 2002/10/14 13:43:16 wiz Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -351,21 +351,22 @@ The .Nm functions exist to allow device drivers -machine-independent access to bus memory and register areas. All of the -functions and types described in this document can be used by including -the +machine-independent access to bus memory and register areas. +All of the functions and types described in this document can be used +by including the .Pa Aq machine/bus.h header file. .Pp Many common devices are used on multiple architectures, but are accessed differently on each because of architectural constraints. For instance, a device which is mapped in one system's I/O space may be -mapped in memory space on a second system. On a third system, architectural -limitations might change the way registers need to be accessed (e.g. -creating a non-linear register space). +mapped in memory space on a second system. +On a third system, architectural limitations might change the way +registers need to be accessed (e.g., creating a non-linear register space). In some cases, a single driver may need to access the same type of device in multiple ways in a -single system or architecture. The goal of the +single system or architecture. +The goal of the .Nm functions is to allow a single driver source file to manipulate a set of devices on different system architectures, and to allow a single driver @@ -374,36 +375,38 @@ single architecture. .Pp Not all busses have to implement all functions described in this document, though that is encouraged if the operations are logically -supported by the bus. Unimplemented functions should cause -compile-time errors if possible. +supported by the bus. +Unimplemented functions should cause compile-time errors if possible. .Pp All of the interface definitions described in this document are shown as function prototypes and discussed as if they were required to be -functions. Implementations are encouraged to implement prototyped -(type-checked) versions of these interfaces, but may implement them as -macros if appropriate. Machine-dependent types, variables, and functions -should be marked clearly in +functions. +Implementations are encouraged to implement prototyped (type-checked) +versions of these interfaces, but may implement them as macros if appropriate. +Machine-dependent types, variables, and functions should be marked clearly in .Pa Aq machine/bus.h to avoid confusion with the machine-independent types and functions, and, if possible, should be given names which make the machine-dependence clear. .Sh CONCEPTS AND GUIDELINES Bus spaces are described by bus space tags, which can be created only by -machine-dependent code. A given machine may have several different types -of bus space (e.g. memory space and I/O space), and thus may provide -multiple different bus space tags. +machine-dependent code. +A given machine may have several different types of bus space +(e.g., memory space and I/O space), and thus may provide multiple different +bus space tags. Individual busses or devices on a machine may use more than one bus space -tag. For instance, ISA devices are -given an ISA memory space tag and an ISA I/O space tag. Architectures -may have several different tags which represent the same type of -space, for instance because of multiple different host bus interface -chipsets. +tag. +For instance, ISA devices are given an ISA memory space tag and an +ISA I/O space tag. +Architectures may have several different tags which represent the same +type of space, for instance because of multiple different host bus +interface chipsets. .Pp -A range in bus space is described by a bus address and a bus size. The -bus address describes the start of the range in bus space. The bus -size describes the size of the range in bytes. Busses which are not byte -addressable may require use of bus space ranges with appropriately -aligned addresses and properly rounded sizes. +A range in bus space is described by a bus address and a bus size. +The bus address describes the start of the range in bus space. +The bus size describes the size of the range in bytes. +Busses which are not byte addressable may require use of bus space ranges +with appropriately aligned addresses and properly rounded sizes. .Pp Access to regions of bus space is facilitated by use of bus space handles, which are usually created by mapping a specific range of a bus space. @@ -417,11 +420,12 @@ argument, at least one handle argument, and at least one offset argument (a bus size). The bus space tag specifies the space, each handle specifies a region in the space, and each offset specifies the offset into the region of the -actual location(s) to be accessed. Offsets are given in bytes, though busses -may impose alignment constraints. The offset used to access data -relative to a given handle must be such that all of the data being -accessed is in the mapped region that the handle describes. Trying to -access data outside that region is an error. +actual location(s) to be accessed. +Offsets are given in bytes, though busses may impose alignment constraints. +The offset used to access data relative to a given handle must be such +that all of the data being accessed is in the mapped region that the +handle describes. +Trying to access data outside that region is an error. .Pp Because some architectures' memory systems use buffering to improve memory and device access performance, there is a mechanism which can be @@ -433,31 +437,35 @@ There are two types of barriers: ordering barriers and completion barriers. .Pp Ordering barriers prevent some operations from bypassing other -operations. They are relatively light weight and described in terms -of the operations they are intended to order. The important thing -to note is that they create specific ordering constraint surrounding -bus accesses but do not necessarily force any synchronization themselves. +operations. +They are relatively light weight and described in terms of the +operations they are intended to order. +The important thing to note is that they create specific ordering +constraint surrounding bus accesses but do not necessarily force any +synchronization themselves. So, if there is enough distance between the memory operations being ordered, the preceeding ones could complete by themselves resulting in no performance penalty. .Pp For instance, a write before read barrier will force any writes issued before the barrier instruction to complete before any reads -after the barrier are issued. This forces processors -with write buffers to read data from memory rather than from the -pending write in the write buffer. +after the barrier are issued. +This forces processors with write buffers to read data from memory rather +than from the pending write in the write buffer. .Pp Ordering barriers are usually sufficient for most circumstances, -and can be combined together. For instance a read before write -barrier can be combined with a write before write barrier to force -all memory operations to complete before the next write is started. +and can be combined together. +For instance a read before write barrier can be combined with a write +before write barrier to force all memory operations to complete before +the next write is started. .Pp Completion barriers force all memory operations and any pending exceptions to be completed before any instructions after the -barrier may be issued. Completion barriers are extremely expensive -and almost never required in device driver code. A single completion -barrier can force the processor to stall on memory for hundreds -of cycles on some machines. +barrier may be issued. +Completion barriers are extremely expensive and almost never required +in device driver code. +A single completion barrier can force the processor to stall on memory +for hundreds of cycles on some machines. .Pp Correctly-written drivers will include all appropriate barriers, and assume only the read/write ordering imposed by the barrier @@ -466,26 +474,27 @@ operations. People trying to write portable drivers with the .Nm functions should -try to make minimal assumptions about what the system allows. In particular, -they should expect that the system requires bus space addresses being -accessed to be naturally aligned (i.e. base address of handle added to -offset is a multiple of the access size), and that the system does -alignment checking on pointers (i.e. pointer to objects being read and -written must point to properly-aligned data). +try to make minimal assumptions about what the system allows. +In particular, they should expect that the system requires bus space +addresses being accessed to be naturally aligned (i.e., base address of +handle added to offset is a multiple of the access size), and that the +system does alignment checking on pointers (i.e., pointer to objects being +read and written must point to properly-aligned data). .Pp The descriptions of the .Nm functions given below all assume that -they are called with proper arguments. If called with invalid arguments -or arguments that are out of range (e.g. trying to access data outside of -the region mapped when a given handle was created), undefined behaviour -results. In that case, they may cause the -system to halt, either intentionally (via panic) or unintentionally (by -causing a fatal trap or by some other means) or may cause improper -operation which is not immediately fatal. Functions which return -void or which return data read from bus space (i.e., functions which -don't obviously return an error code) do not fail. They could only fail -if given invalid arguments, and in that case their behaviour is undefined. +they are called with proper arguments. +If called with invalid arguments or arguments that are out of range +(e.g., trying to access data outside of the region mapped when a given +handle was created), undefined behaviour results. +In that case, they may cause the system to halt, either intentionally +(via panic) or unintentionally (by causing a fatal trap or by some other +means) or may cause improper operation which is not immediately fatal. +Functions which return void or which return data read from bus space +(i.e., functions which don't obviously return an error code) do not fail. +They could only fail if given invalid arguments, and in that case their +behaviour is undefined. Functions which take a count of bytes have undefined results if the specified .Fa count is zero. @@ -501,19 +510,19 @@ functions by drivers. .Pp The .Fa bus_addr_t -type is used to describe bus addresses. It must be an -unsigned integral type -capable of holding the largest bus address usable by the architecture. This -type is primarily used when mapping and unmapping bus space. +type is used to describe bus addresses. +It must be an unsigned integral type capable of holding the largest bus +address usable by the architecture. +This type is primarily used when mapping and unmapping bus space. .Pp .It Fa bus_size_t .Pp The .Fa bus_size_t -type is used to describe sizes of ranges in bus space. It must be an -unsigned integral type capable of holding the size of the largest bus -address range usable on the architecture. This type is used by virtually all -of the +type is used to describe sizes of ranges in bus space. +It must be an unsigned integral type capable of holding the size of the +largest bus address range usable on the architecture. +This type is used by virtually all of the .Nm functions, describing sizes when mapping regions and offsets into regions when performing space access operations. @@ -522,9 +531,10 @@ offsets into regions when performing space access operations. .Pp The .Fa bus_space_tag_t -type is used to describe a particular bus space on a machine. Its -contents are machine-dependent and should be considered opaque by -machine-independent code. This type is used by all +type is used to describe a particular bus space on a machine. +Its contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used by all .Nm functions to name the space on which they're operating. .Pp @@ -532,21 +542,23 @@ functions to name the space on which they're operating. .Pp The .Fa bus_space_handle_t -type is used to describe a mapping of a range of bus space. Its -contents are machine-dependent and should be considered opaque by -machine-independent code. This type is used when performing bus space -access operations. +type is used to describe a mapping of a range of bus space. +Its contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used when performing bus space access operations. .El .Sh MAPPING AND UNMAPPING BUS SPACE Bus space must be mapped before it can be used, and should be -unmapped when it is no longer needed. The +unmapped when it is no longer needed. +The .Fn bus_space_map and .Fn bus_space_unmap functions provide these capabilities. .Pp Some drivers need to be able to pass a subregion of already-mapped bus -space to another driver or module within a driver. The +space to another driver or module within a driver. +The .Fn bus_space_subregion function allows such subregions to be created. .Pp @@ -560,24 +572,27 @@ function maps the region of bus space named by the .Fa address , and .Fa size -arguments. If successful, it returns zero -and fills in the bus space handle pointed to by +arguments. +If successful, it returns zero and fills in the bus space handle pointed +to by .Fa handlep with the handle -that can be used to access the mapped region. If unsuccessful, -it will return non-zero and leave the bus space handle pointed -to by +that can be used to access the mapped region. +If unsuccessful, it will return non-zero and leave the bus space handle +pointed to by .Fa handlep in an undefined state. .Pp The .Fa flags -argument controls how the space is to be mapped. Supported flags include: +argument controls how the space is to be mapped. +Supported flags include: .Bl -tag -width BUS_SPACE_MAP_CACHEABLE -offset indent .It Dv BUS_SPACE_MAP_CACHEABLE Try to map the space so that accesses can be cached -by the system cache. If this flag is not specified, the -implementation should map the space so that it will not be cached. +by the system cache. +If this flag is not specified, the implementation should map the space so +that it will not be cached. This mapping method will only be useful in very rare occasions. .Pp This flag must have a value of 1 on all implementations for backward @@ -585,7 +600,8 @@ compatibility. .It Dv BUS_SPACE_MAP_PREFETCHABLE Try to map the space so that accesses can be prefetched by the system, and writes can be buffered. -This means, accesses should be side effect free (idempotent). The +This means, accesses should be side effect free (idempotent). +The .Fn bus_space_barrier methods will flush the write buffer or force actual read accesses. If this flag is not specified, the @@ -593,17 +609,18 @@ implementation should map the space so that it will not be prefetched or delayed. .It Dv BUS_SPACE_MAP_LINEAR Try to map the space so that its contents can be accessed linearly via -normal memory access methods (e.g. pointer dereferencing and structure -accesses). The +normal memory access methods (e.g., pointer dereferencing and structure +accesses). +The .Fn bus_space_vaddr method can be used to obtain the kernel virtual address of the mapped range. This is useful when software wants to do direct access to a memory -device, e.g. a frame buffer. If this flag is specified and linear -mapping is not possible, the +device, e.g., a frame buffer. +If this flag is specified and linear mapping is not possible, the .Fn bus_space_map -call should fail. If this -flag is not specified, the system may map the space in whatever way is -most convenient. +call should fail. +If this flag is not specified, the system may map the space in whatever +way is most convenient. Use of this mapping method is not encouraged for normal device access; where linear access is not essential, use of the .Fn bus_space_read/write @@ -611,7 +628,8 @@ methods is strongly recommended. .El .Pp Not all combinations of flags make sense or are supported with all -spaces. For instance, +spaces. +For instance, .Dv BUS_SPACE_MAP_CACHEABLE may be meaningless when used on many systems' I/O port spaces, and on some systems @@ -620,22 +638,21 @@ without .Dv BUS_SPACE_MAP_PREFETCHABLE may never work. When the system hardware or firmware provides hints as to how spaces should be -mapped (e.g. the PCI memory mapping registers' "prefetchable" bit), those -hints should be followed for maximum compatibility. On some systems, -requesting a mapping that cannot be satisfied (e.g. requesting a -non-prefetchable mapping when the system can only provide a prefetchable one) -will cause the request to fail. +mapped (e.g., the PCI memory mapping registers' "prefetchable" bit), those +hints should be followed for maximum compatibility. +On some systems, requesting a mapping that cannot be satisfied (e.g., +requesting a non-prefetchable mapping when the system can only provide +a prefetchable one) will cause the request to fail. .Pp Some implementations may keep track of use of bus space for some or all -bus spaces and refuse to allow duplicate allocations. This is encouraged -for bus spaces which have no notion of slot-specific space addressing, -such as ISA and VME, and for spaces which coexist with those spaces -(e.g. EISA and PCI memory and I/O spaces co-existing with ISA memory and -I/O spaces). +bus spaces and refuse to allow duplicate allocations. +This is encouraged for bus spaces which have no notion of slot-specific +space addressing, such as ISA and VME, and for spaces which coexist with +those spaces (e.g., EISA and PCI memory and I/O spaces co-existing with +ISA memory and I/O spaces). .Pp -Mapped regions may contain areas for which there is no device on the -bus. If space in those areas is accessed, the results are -bus-dependent. +Mapped regions may contain areas for which there is no device on the bus. +If space in those areas is accessed, the results are bus-dependent. .Pp .It Fn bus_space_unmap "space" "handle" "size" .Pp @@ -652,13 +669,13 @@ when mapping that region. .Pp After .Fn bus_space_unmap -is called on a handle, that handle is no longer -valid. (If copies were made of the handle they are no longer valid, -either.) +is called on a handle, that handle is no longer valid. +(If copies were made of the handle they are no longer valid, either.) .Pp -This function will never fail. If it would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, +This function will never fail. +If it would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, .Fn bus_space_unmap will never return. .Pp @@ -685,17 +702,21 @@ If unsuccessful, it returns non-zero and leaves the bus space handle pointed to by .Fa nhandlep in an -undefined state. In either case, the handle described by +undefined state. +In either case, the handle described by .Fa handle remains valid and is unmodified. .Pp When done with a handle created by .Fn bus_space_subregion , the handle should -be thrown away. Under no circumstances should +be thrown away. +Under no circumstances should .Fn bus_space_unmap -be used on the handle. Doing so may confuse any resource management -being done on the space, and will result in undefined behaviour. When +be used on the handle. +Doing so may confuse any resource management being done on the space, +and will result in undefined behaviour. +When .Fn bus_space_unmap or .Fn bus_space_free @@ -706,7 +727,8 @@ is called on a handle, all subregions of that handle become invalid. This method returns the kernel virtual address of a mapped bus space if and only if it was mapped with the .Dv BUS_SPACE_MAP_LINEAR -flag. The range can be accessed by normal (volatile) pointer dereferences. +flag. +The range can be accessed by normal (volatile) pointer dereferences. If mapped with the .Dv BUS_SPACE_MAP_PREFETCHABLE flag, the @@ -716,8 +738,8 @@ method must be used to force a particular access order. .It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" .Pp This method is used to provide support for memory mapping bus space -into user applications. If an address space is addressable via -volatile pointer dereferences, +into user applications. +If an address space is addressable via volatile pointer dereferences, .Fn bus_space_mmap will return the physical address (possibly encoded as a machine-dependent cookie) of the bus space indicated by @@ -746,15 +768,18 @@ call be mapped into a .Fn bus_space_mmap is called once per .Dv PAGE_SIZE -page in the range. The +page in the range. +The .Fa prot argument indicates the memory protection requested by the user application for the range. .El .Sh ALLOCATING AND FREEING BUS SPACE Some devices require or allow bus space to be allocated by the operating -system for device use. When the devices no longer need the space, the -operating system should free it for use by other devices. The +system for device use. +When the devices no longer need the space, the +operating system should free it for use by other devices. +The .Fn bus_space_alloc and .Fn bus_space_free @@ -772,8 +797,8 @@ The .Fn bus_space_alloc function allocates and maps a region of bus space with the size given by .Fa size , -corresponding to the given constraints. If successful, it returns -zero, fills in the bus address pointed to by +corresponding to the given constraints. +If successful, it returns zero, fills in the bus address pointed to by .Fa addrp with the bus space address of the allocated region, and fills in the bus space handle pointed to by @@ -791,14 +816,16 @@ Constraints on the allocation are given by the .Fa alignment , and .Fa boundary -parameters. The allocated region will start at or after +parameters. +The allocated region will start at or after .Fa reg_start and end before or at .Fa reg_end . The .Fa alignment constraint must be a power of two, and the allocated region will start at -an address that is an even multiple of that power of two. The +an address that is an even multiple of that power of two. +The .Fa boundary constraint, if non-zero, ensures that the region is allocated so that .Fa "first address in region" @@ -810,8 +837,8 @@ has the same value as .Fa boundary . If the constraints cannot be met, .Fn bus_space_alloc -will fail. It is an error to specify a set of -constraints that can never be met +will fail. +It is an error to specify a set of constraints that can never be met .Po for example, .Fa size @@ -832,10 +859,10 @@ should only be freed with .Fn bus_space_free . Trying to use .Fn bus_space_unmap -on them causes undefined behaviour. The +on them causes undefined behaviour. +The .Fn bus_space_subregion -function can be used on -handles created by +function can be used on handles created by .Fn bus_space_alloc . .Pp .It Fn bus_space_free "space" "handle" "size" @@ -853,18 +880,20 @@ when allocating the region. .Pp After .Fn bus_space_free -is called on a handle, that handle is no longer valid. (If copies were -made of the handle, they are no longer valid, either.) +is called on a handle, that handle is no longer valid. +(If copies were made of the handle, they are no longer valid, either.) .Pp -This function will never fail. If it would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, +This function will never fail. +If it would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, .Fn bus_space_free will never return. .El .Sh READING AND WRITING SINGLE DATA ITEMS The simplest way to access bus space is to read or write a single data -item. The +item. +The .Fn bus_space_read_N and .Fn bus_space_write_N @@ -904,9 +933,10 @@ order is enforced by use of the .Fn bus_space_barrier function. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .Pp .It Fn bus_space_write_1 "space" "handle" "offset" "value" .It Fn bus_space_write_2 "space" "handle" "offset" "value" @@ -929,8 +959,9 @@ the bus space region specified by For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data item being -written. On some systems, not obeying this requirement may cause -incorrect data to be written, on others it may cause a system crash. +written. +On some systems, not obeying this requirement may cause incorrect data +to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_N @@ -940,9 +971,10 @@ unless order is enforced by use of the .Fn bus_space_barrier function. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .El .Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND One problem with the @@ -951,8 +983,10 @@ and .Fn bus_space_write_N family of functions is that they provide no protection against exceptions which can occur when no physical hardware or -device responds to the read or write cycles. In such a situation, -the system typically would panic due to a kernel-mode bus error. The +device responds to the read or write cycles. +In such a situation, the system typically would panic due to a kernel-mode +bus error. +The .Fn bus_space_peek_N and .Fn bus_space_poke_N @@ -965,8 +999,8 @@ and .Fn bus_space_write_N , the peek and poke functions provide the ability to read and write 1, 2, 4, and 8 byte data items on busses which support those -access sizes. All of the constraints specified in the descriptions of -the +access sizes. +All of the constraints specified in the descriptions of the .Fn bus_space_read_N and .Fn bus_space_write_N @@ -986,11 +1020,12 @@ The return value indicates the outcome of the peek or poke operation. A return value of zero implies that a hardware device is responding to the operation at the specified offset in the bus space. A non-zero return value indicates that the kernel intercepted a -hardware exception (e.g. bus error) when the peek or poke operation +hardware exception (e.g., bus error) when the peek or poke operation was attempted. Note that some busses are incapable of generating exceptions when -non-existent hardware is accessed. In such cases, these functions -will always return zero and the value of the data read by +non-existent hardware is accessed. +In such cases, these functions will always return zero and the value of +the data read by .Fn bus_space_peek_N will be unspecified. .Pp @@ -1043,7 +1078,8 @@ of the bus space specified by .Sh BARRIERS In order to allow high-performance buffering implementations to avoid bus activity on every operation, read and write ordering should be specified -explicitly by drivers when necessary. The +explicitly by drivers when necessary. +The .Fn bus_space_barrier function provides that ability. .Pp @@ -1093,11 +1129,12 @@ specified type(s) of operation done after the barrier. .Pp Example: Consider a hypothetical device with two single-byte ports, one write-only input port (at offset 0) and a read-only output port (at -offset 1). Operation of the device is as follows: data bytes are written -to the input port, and are placed by the device on a stack, the top of -which is read by reading from the output port. The sequence to correctly -write two data bytes to the device then read those two data bytes back -would be: +offset 1). +Operation of the device is as follows: data bytes are written to the +input port, and are placed by the device on a stack, the top of +which is read by reading from the output port. +The sequence to correctly write two data bytes to the device then read +those two data bytes back would be: .Pp .Bd -literal /* @@ -1116,23 +1153,24 @@ ndata0 = bus_space_read_1(t, h, 1); .Pp The first barrier makes sure that the first write finishes before the second write is issued, so that two writes to the input port are done -in order and are not collapsed into a single write. This ensures that -the data bytes are written to the device correctly and in order. +in order and are not collapsed into a single write. +This ensures that the data bytes are written to the device correctly and +in order. .Pp The second barrier forces the writes to the output port finish before any of the reads to the input port are issued, thereby making sure -that all of the writes are finished before data is read. This ensures -that the first byte read from the device really is the last one that was -written. +that all of the writes are finished before data is read. +This ensures that the first byte read from the device really is the last +one that was written. .Pp The third barrier makes sure that the first read finishes before the second read is issued, ensuring that data is read correctly and in order. .Pp The barriers in the example above are specified to cover the absolute -minimum number of bus space locations. It is correct (and often -easier) to make barrier operations cover the device's whole range of bus -space, that is, to specify an offset of zero and the size of the -whole region. +minimum number of bus space locations. +It is correct (and often easier) to make barrier operations cover the +device's whole range of bus space, that is, to specify an offset of zero +and the size of the whole region. .Pp The following barrier operations are obsolete and should be removed from existing code: @@ -1146,9 +1184,9 @@ Synchronize write operations. .Sh REGION OPERATIONS Some devices use buffers which are mapped as regions in bus space. Often, drivers want to copy the contents of those buffers to or from -memory, e.g. into mbufs which can be passed to higher levels of the -system or from mbufs to be output to a network. In order to allow -drivers to do this as efficiently as possible, the +memory, e.g., into mbufs which can be passed to higher levels of the +system or from mbufs to be output to a network. +In order to allow drivers to do this as efficiently as possible, the .Fn bus_space_read_region_N and .Fn bus_space_write_region_N @@ -1156,7 +1194,8 @@ families of functions are provided. .Pp Drivers occasionally need to copy one region of a bus space to another, or to set all locations in a region of bus space to contain a single -value. The +value. +The .Fn bus_space_copy_region_N family of functions and the .Fn bus_space_set_region_N @@ -1183,31 +1222,33 @@ and writes them into the array specified by .Fa datap . Each successive data item is read from an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which -function is used). All locations being read must lie within the bus -space region specified by +function is used). +All locations being read must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being -read and the data array pointer should be properly aligned. On some -systems, not obeying these requirements may cause incorrect data to be -read, on others it may cause a system crash. +read and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be read, on others it may cause a system crash. .Pp Read operations done by the .Fn bus_space_read_region_N -functions may be executed in any order. They may also be executed out -of order with respect to other pending read and write operations unless -order is enforced by use of the +functions may be executed in any order. +They may also be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the .Fn bus_space_barrier -function. There is no way to insert barriers between reads of -individual bus space locations executed by the +function. +There is no way to insert barriers between reads of individual bus +space locations executed by the .Fn bus_space_read_region_N functions. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates a +software bug which should cause a panic. +In that case, they will never return. .Pp .It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" .It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" @@ -1230,32 +1271,34 @@ by .Fa space . Each successive data item is written to an offset 1, 2, 4, or 8 bytes after the previous data item (depending on which function is -used). All locations being written must lie within the bus space region -specified by +used). +All locations being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being -written and the data array pointer should be properly aligned. On some -systems, not obeying these requirements may cause incorrect data to be -written, on others it may cause a system crash. +written and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_region_N functions may be -executed in any order. They may also be executed out of order with -respect to other pending read and write operations unless order is -enforced by use of the +executed in any order. +They may also be executed out of order with respect to other pending read +and write operations unless order is enforced by use of the .Fn bus_space_barrier -function. There is no way to insert barriers between writes of -individual bus space locations executed by the +function. +There is no way to insert barriers between writes of individual bus +space locations executed by the .Fn bus_space_write_region_N functions. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .Pp .It Fn bus_space_copy_region_1 "space" "srchandle" "srcoffset" "dsthandle" \ "dstoffset" "count" @@ -1281,22 +1324,23 @@ to the area starting at byte offset .Fa dstoffset in the region specified by .Fa dsthandle -in the same bus space. Each successive data item read or written has -an offset 1, 2, 4, or 8 bytes after the previous data item (depending -on which function is used). All locations being read and written must -lie within the bus space region specified by their respective handles. +in the same bus space. +Each successive data item read or written has an offset 1, 2, 4, or 8 +bytes after the previous data item (depending on which function is used). +All locations being read and written must lie within the bus space +region specified by their respective handles. .Pp For portability, the starting addresses of the regions specified by each handle plus its respective offset should be a multiple of the size -of data items being copied. On some systems, not obeying this -requirement may cause incorrect data to be copied, on others it may cause -a system crash. +of data items being copied. +On some systems, not obeying this requirement may cause incorrect data +to be copied, on others it may cause a system crash. .Pp Read and write operations done by the .Fn bus_space_copy_region_N -functions may be executed in any order. They may also be executed out -of order with respect to other pending read and write operations unless -order is enforced by use of the +functions may be executed in any order. +They may also be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the .Fn bus_space_barrier function . There is no way to insert barriers between reads or writes of individual bus space locations executed by the @@ -1308,9 +1352,10 @@ of bus space are handled correctly by the .Fn bus_space_copy_region_N functions. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .Pp .It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" .It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" @@ -1331,38 +1376,42 @@ in the region specified by of the bus space specified by .Fa space . Each successive data item has an offset 1, 2, 4, or 8 bytes after the -previous data item (depending on which function is used). All -locations being written must lie within the bus space region specified -by +previous data item (depending on which function is used). +All locations being written must lie within the bus space region +specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being -written. On some systems, not obeying this requirement may cause -incorrect data to be written, on others it may cause a system crash. +written. +On some systems, not obeying this requirement may cause incorrect data +to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_set_region_N functions may be -executed in any order. They may also be executed out of order with -respect to other pending read and write operations unless order is -enforced by use of the +executed in any order. +They may also be executed out of order with respect to other pending read +and write operations unless order is enforced by use of the .Fn bus_space_barrier -function. There is no way to insert barriers between writes of +function. +There is no way to insert barriers between writes of individual bus space locations executed by the .Fn bus_space_set_region_N functions. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .El .Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES Some devices implement single locations in bus space which are to be read -or written multiple times to communicate data, e.g. some ethernet -devices' packet buffer FIFOs. In order to allow drivers to manipulate -these types of devices as efficiently as possible, the +or written multiple times to communicate data, e.g., some ethernet +devices' packet buffer FIFOs. +In order to allow drivers to manipulate these types of devices as +efficiently as possible, the .Fn bus_space_read_multi_N and .Fn bus_space_write_multi_N @@ -1388,16 +1437,16 @@ of the bus space specified by and writes them into the array specified by .Fa datap . Each successive data item is read from the same location in bus -space. The location being read must lie within the bus space region -specified by +space. +The location being read must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being -read and the data array pointer should be properly aligned. On some -systems, not obeying these requirements may cause incorrect data to be -read, on others it may cause a system crash. +read and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be read, on others it may cause a system crash. .Pp Read operations done by the .Fn bus_space_read_multi_N @@ -1405,15 +1454,17 @@ functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier -function. Because the +function. +Because the .Fn bus_space_read_multi_N functions read the same bus space location multiple times, they place an implicit read barrier between each successive read of that bus space location. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .Pp .It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" .It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" @@ -1434,40 +1485,42 @@ in the region specified by of the bus space specified by .Fa space . Each successive data item is written to the same location in -bus space. The location being written must lie within the bus space -region specified by +bus space. +The location being written must lie within the bus space region specified by .Fa handle . .Pp For portability, the starting address of the region specified by .Fa handle plus the offset should be a multiple of the size of data items being -written and the data array pointer should be properly aligned. On some -systems, not obeying these requirements may cause incorrect data to be -written, on others it may cause a system crash. +written and the data array pointer should be properly aligned. +On some systems, not obeying these requirements may cause incorrect data +to be written, on others it may cause a system crash. .Pp Write operations done by the .Fn bus_space_write_multi_N functions may be executed out of order with respect to other pending read and write operations unless order is enforced by use of the .Fn bus_space_barrier -function. Because the +function. +Because the .Fn bus_space_write_multi_N functions write the same bus space location multiple times, they place an implicit write barrier between each successive write of that bus space location. .Pp -These functions will never fail. If they would fail (e.g. because of an -argument error), that indicates a software bug which should cause a -panic. In that case, they will never return. +These functions will never fail. +If they would fail (e.g., because of an argument error), that indicates +a software bug which should cause a panic. +In that case, they will never return. .El .Sh STREAM FUNCTIONS Most of the .Nm functions imply a host byte-order and a bus byte-order and take care of -any translation for the caller. In some cases, however, hardware may -map a FIFO or some other memory region for which the caller may want to -use multi-word, yet untranslated access. Access to these types of memory -regions should be with the +any translation for the caller. +In some cases, however, hardware may map a FIFO or some other memory region +for which the caller may want to use multi-word, yet untranslated access. +Access to these types of memory regions should be with the .Fn bus_space_*_stream_N functions. .Pp @@ -1503,24 +1556,27 @@ except that they provide no byte-order translation. .Sh EXPECTED CHANGES TO THE BUS_SPACE FUNCTIONS The definition of the .Nm -functions should not yet be considered finalized. There are several -changes and improvements which should be explored, including: +functions should not yet be considered finalized. +There are several changes and improvements which should be explored, +including: .Pp .Bl -bullet .It Providing a mechanism by which incorrectly-written drivers will be automatically given barriers and properly-written drivers won't be forced -to use more barriers than they need. This should probably be done via a +to use more barriers than they need. +This should probably be done via a .Li #define in the incorrectly-written drivers. Unfortunately, at this time, few drivers actually use barriers correctly -(or at all). Because of that, +(or at all). +Because of that, .Nm implementations on architectures which do buffering must always do the barriers inside the .Nm -calls, to be safe. That has a potentially significant -performance impact. +calls, to be safe. +That has a potentially significant performance impact. .It Exporting the .Nm @@ -1529,8 +1585,8 @@ functions to user-land so that applications .It Redefining bus space tags and handles so that machine-independent bus interface drivers (for example PCI to VME bridges) could define and -implement bus spaces without requiring machine-dependent code. If this -is done, it should be done in such a way that machine-dependent +implement bus spaces without requiring machine-dependent code. +If this is done, it should be done in such a way that machine-dependent optimizations should remain possible. .It Converting bus spaces (such as PCI configuration space) which currently @@ -1540,12 +1596,12 @@ functions where that is appropriate. .It Redefining the way bus space is mapped and allocated, so that mapping and allocation are done with bus specific functions which return bus -space tags. This would allow further optimization than is currently -possible, and would also ease translation of the +space tags. +This would allow further optimization than is currently possible, and +would also ease translation of the .Nm -functions -into user space (since mapping in user space would look like it just used -a different bus-specific mapping function). +functions into user space (since mapping in user space would look like +it just used a different bus-specific mapping function). .El .Sh COMPATIBILITY The current version of the @@ -1582,7 +1638,8 @@ The interfaces were designed and implemented by the .Nx developer -community. Primary contributors and implementors were Chris Demetriou, +community. +Primary contributors and implementors were Chris Demetriou, Jason Thorpe, and Charles Hannum, but the rest of the .Nx developers and the user community played a significant role in development. diff --git a/share/man/man9/callout.9 b/share/man/man9/callout.9 index 2de8d1bd5097..d274b652ad85 100644 --- a/share/man/man9/callout.9 +++ b/share/man/man9/callout.9 @@ -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 diff --git a/share/man/man9/cardbus.9 b/share/man/man9/cardbus.9 index 5e87bccf065e..1e583ffa3439 100644 --- a/share/man/man9/cardbus.9 +++ b/share/man/man9/cardbus.9 @@ -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 , diff --git a/share/man/man9/cnmagic.9 b/share/man/man9/cnmagic.9 index b6517ace354d..b584ca5a4f21 100644 --- a/share/man/man9/cnmagic.9 +++ b/share/man/man9/cnmagic.9 @@ -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 diff --git a/share/man/man9/config.9 b/share/man/man9/config.9 index 75167ba7b9f2..b35ac800fbb0 100644 --- a/share/man/man9/config.9 +++ b/share/man/man9/config.9 @@ -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 diff --git a/share/man/man9/cons.9 b/share/man/man9/cons.9 index d045040c5206..be03299cc436 100644 --- a/share/man/man9/cons.9 +++ b/share/man/man9/cons.9 @@ -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 diff --git a/share/man/man9/copy.9 b/share/man/man9/copy.9 index f4325c401f12..77dbde5a1e9d 100644 --- a/share/man/man9/copy.9 +++ b/share/man/man9/copy.9 @@ -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 diff --git a/share/man/man9/cpu_configure.9 b/share/man/man9/cpu_configure.9 index 66086d05b8a8..e425da164c25 100644 --- a/share/man/man9/cpu_configure.9 +++ b/share/man/man9/cpu_configure.9 @@ -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: diff --git a/share/man/man9/cpu_coredump.9 b/share/man/man9/cpu_coredump.9 index 43abe38730cd..194ce4910459 100644 --- a/share/man/man9/cpu_coredump.9 +++ b/share/man/man9/cpu_coredump.9 @@ -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 diff --git a/share/man/man9/cpu_dumpconf.9 b/share/man/man9/cpu_dumpconf.9 index 134daa36414d..f0df6e9f05a5 100644 --- a/share/man/man9/cpu_dumpconf.9 +++ b/share/man/man9/cpu_dumpconf.9 @@ -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 diff --git a/share/man/man9/cpu_exit.9 b/share/man/man9/cpu_exit.9 index caea67c3419e..f729a4157c0a 100644 --- a/share/man/man9/cpu_exit.9 +++ b/share/man/man9/cpu_exit.9 @@ -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 diff --git a/share/man/man9/cpu_fork.9 b/share/man/man9/cpu_fork.9 index a9c06c08d141..9dd5d62ce996 100644 --- a/share/man/man9/cpu_fork.9 +++ b/share/man/man9/cpu_fork.9 @@ -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 diff --git a/share/man/man9/cpu_initclocks.9 b/share/man/man9/cpu_initclocks.9 index bdefd2fa16d0..43f51adf58ea 100644 --- a/share/man/man9/cpu_initclocks.9 +++ b/share/man/man9/cpu_initclocks.9 @@ -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 diff --git a/share/man/man9/cpu_reboot.9 b/share/man/man9/cpu_reboot.9 index d1308627a5ef..86e7dd68e50d 100644 --- a/share/man/man9/cpu_reboot.9 +++ b/share/man/man9/cpu_reboot.9 @@ -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 , diff --git a/share/man/man9/cpu_swapout.9 b/share/man/man9/cpu_swapout.9 index 7499f5e2147a..788963909971 100644 --- a/share/man/man9/cpu_swapout.9 +++ b/share/man/man9/cpu_swapout.9 @@ -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 diff --git a/share/man/man9/cpu_sysctl.9 b/share/man/man9/cpu_sysctl.9 index f8c95616a2a4..5a140787b50b 100644 --- a/share/man/man9/cpu_sysctl.9 +++ b/share/man/man9/cpu_sysctl.9 @@ -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 diff --git a/share/man/man9/disk.9 b/share/man/man9/disk.9 index 4445c82e6edb..1cd6216045c2 100644 --- a/share/man/man9/disk.9 +++ b/share/man/man9/disk.9 @@ -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 . diff --git a/share/man/man9/dmover.9 b/share/man/man9/dmover.9 index fc61e95212e5..f14dce565a9f 100644 --- a/share/man/man9/dmover.9 +++ b/share/man/man9/dmover.9 @@ -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. diff --git a/share/man/man9/doshutdownhooks.9 b/share/man/man9/doshutdownhooks.9 index 5736ca8e9ffb..1a41010662dc 100644 --- a/share/man/man9/doshutdownhooks.9 +++ b/share/man/man9/doshutdownhooks.9 @@ -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 diff --git a/share/man/man9/driver.9 b/share/man/man9/driver.9 index 14527f07310b..84532e9bb1ef 100644 --- a/share/man/man9/driver.9 +++ b/share/man/man9/driver.9 @@ -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.. For example, the driver +must be aware of its existence. +his is done by including an entry in majors.. +For example, the driver .Dq foo with character device interfaces, a character major device number .Dq cmaj , diff --git a/share/man/man9/ethersubr.9 b/share/man/man9/ethersubr.9 index e6838eae3598..c68ea794f309 100644 --- a/share/man/man9/ethersubr.9 +++ b/share/man/man9/ethersubr.9 @@ -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. diff --git a/share/man/man9/evcnt.9 b/share/man/man9/evcnt.9 index fd4050969094..22dee6a1f11d 100644 --- a/share/man/man9/evcnt.9 +++ b/share/man/man9/evcnt.9 @@ -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 diff --git a/share/man/man9/extent.9 b/share/man/man9/extent.9 index 3a273e5c7584..b800b1090c67 100644 --- a/share/man/man9/extent.9 +++ b/share/man/man9/extent.9 @@ -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. diff --git a/share/man/man9/fetch.9 b/share/man/man9/fetch.9 index 9fbcdbe5874c..b7d4c856b980 100644 --- a/share/man/man9/fetch.9 +++ b/share/man/man9/fetch.9 @@ -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. diff --git a/share/man/man9/fork1.9 b/share/man/man9/fork1.9 index a654eec30c23..97487c0fab22 100644 --- a/share/man/man9/fork1.9 +++ b/share/man/man9/fork1.9 @@ -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. diff --git a/share/man/man9/inittodr.9 b/share/man/man9/inittodr.9 index 8c553a0d0fea..0a674f473e5a 100644 --- a/share/man/man9/inittodr.9 +++ b/share/man/man9/inittodr.9 @@ -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. diff --git a/share/man/man9/ioctl.9 b/share/man/man9/ioctl.9 index a7d9c882457c..87a2b88fa817 100644 --- a/share/man/man9/ioctl.9 +++ b/share/man/man9/ioctl.9 @@ -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 , diff --git a/share/man/man9/ipkdb.9 b/share/man/man9/ipkdb.9 index 42bcb4828850..e581aecb4625 100644 --- a/share/man/man9/ipkdb.9 +++ b/share/man/man9/ipkdb.9 @@ -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 diff --git a/share/man/man9/isa.9 b/share/man/man9/isa.9 index e9832fc87b50..6297233ce764 100644 --- a/share/man/man9/isa.9 +++ b/share/man/man9/isa.9 @@ -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. diff --git a/share/man/man9/isapnp.9 b/share/man/man9/isapnp.9 index 8dd2e5af7815..8abbfa51bdf9 100644 --- a/share/man/man9/isapnp.9 +++ b/share/man/man9/isapnp.9 @@ -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 , diff --git a/share/man/man9/kprintf.9 b/share/man/man9/kprintf.9 index ba7942feaab0..69ed6a0c42fb 100644 --- a/share/man/man9/kprintf.9 +++ b/share/man/man9/kprintf.9 @@ -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. diff --git a/share/man/man9/kthread.9 b/share/man/man9/kthread.9 index ac461307368a..0c1ff6fe4ad8 100644 --- a/share/man/man9/kthread.9 +++ b/share/man/man9/kthread.9 @@ -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 diff --git a/share/man/man9/linedisc.9 b/share/man/man9/linedisc.9 index b2bf6e18c03d..e05bb3a68e49 100644 --- a/share/man/man9/linedisc.9 +++ b/share/man/man9/linedisc.9 @@ -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 . diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9 index 634f1e9ccf3f..f33f6cb44622 100644 --- a/share/man/man9/lock.9 +++ b/share/man/man9/lock.9 @@ -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 diff --git a/share/man/man9/ltsleep.9 b/share/man/man9/ltsleep.9 index 1129fc5c2271..834e65b28f6d 100644 --- a/share/man/man9/ltsleep.9 +++ b/share/man/man9/ltsleep.9 @@ -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 . diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9 index 7d3cfde0f3d1..639c500527ca 100644 --- a/share/man/man9/malloc.9 +++ b/share/man/man9/malloc.9 @@ -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 diff --git a/share/man/man9/mbuf.9 b/share/man/man9/mbuf.9 index b9198631f207..4263b8a1d8c7 100644 --- a/share/man/man9/mbuf.9 +++ b/share/man/man9/mbuf.9 @@ -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. diff --git a/share/man/man9/mca.9 b/share/man/man9/mca.9 index 3a09d664d0f0..2b0c70afbb4d 100644 --- a/share/man/man9/mca.9 +++ b/share/man/man9/mca.9 @@ -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. diff --git a/share/man/man9/memcpy.9 b/share/man/man9/memcpy.9 index 06c0d184e31d..d0725c8078e4 100644 --- a/share/man/man9/memcpy.9 +++ b/share/man/man9/memcpy.9 @@ -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 diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 index b844c5922ed9..5a7616afff60 100644 --- a/share/man/man9/namei.9 +++ b/share/man/man9/namei.9 @@ -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. diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9 index 015f48ccc47f..045c442940f9 100644 --- a/share/man/man9/pci.9 +++ b/share/man/man9/pci.9 @@ -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 , diff --git a/share/man/man9/pci_configure_bus.9 b/share/man/man9/pci_configure_bus.9 index f614d5a30a10..4280a92a422d 100644 --- a/share/man/man9/pci_configure_bus.9 +++ b/share/man/man9/pci_configure_bus.9 @@ -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 diff --git a/share/man/man9/pci_intr.9 b/share/man/man9/pci_intr.9 index 2de59a0e5212..18009b91301f 100644 --- a/share/man/man9/pci_intr.9 +++ b/share/man/man9/pci_intr.9 @@ -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 diff --git a/share/man/man9/pcmcia.9 b/share/man/man9/pcmcia.9 index 1d55fef584bf..6b2695b25384 100644 --- a/share/man/man9/pcmcia.9 +++ b/share/man/man9/pcmcia.9 @@ -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 , diff --git a/share/man/man9/pfil.9 b/share/man/man9/pfil.9 index f65480aa3c86..12a011cdc5d9 100644 --- a/share/man/man9/pfil.9 +++ b/share/man/man9/pfil.9 @@ -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 , diff --git a/share/man/man9/pmc.9 b/share/man/man9/pmc.9 index 6c19e81dc3a0..85ab02946721 100644 --- a/share/man/man9/pmc.9 +++ b/share/man/man9/pmc.9 @@ -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 diff --git a/share/man/man9/pool.9 b/share/man/man9/pool.9 index 30c6df4c35b1..6223d644b909 100644 --- a/share/man/man9/pool.9 +++ b/share/man/man9/pool.9 @@ -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 diff --git a/share/man/man9/powerhook_establish.9 b/share/man/man9/powerhook_establish.9 index fda3a145ab78..c439869d6597 100644 --- a/share/man/man9/powerhook_establish.9 +++ b/share/man/man9/powerhook_establish.9 @@ -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 diff --git a/share/man/man9/properties.9 b/share/man/man9/properties.9 index ff2e987bdebf..2dcddcddfb4d 100644 --- a/share/man/man9/properties.9 +++ b/share/man/man9/properties.9 @@ -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 diff --git a/share/man/man9/ras.9 b/share/man/man9/ras.9 index 242e0ee41ff1..a4ef006c8ddd 100644 --- a/share/man/man9/ras.9 +++ b/share/man/man9/ras.9 @@ -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 diff --git a/share/man/man9/rasops.9 b/share/man/man9/rasops.9 index 135c598f2797..946c4494a562 100644 --- a/share/man/man9/rasops.9 +++ b/share/man/man9/rasops.9 @@ -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 diff --git a/share/man/man9/ratecheck.9 b/share/man/man9/ratecheck.9 index 55eeba58e329..7c92c665b0c6 100644 --- a/share/man/man9/ratecheck.9 +++ b/share/man/man9/ratecheck.9 @@ -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. diff --git a/share/man/man9/resettodr.9 b/share/man/man9/resettodr.9 index 77964ce595fd..18c647632dd9 100644 --- a/share/man/man9/resettodr.9 +++ b/share/man/man9/resettodr.9 @@ -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. diff --git a/share/man/man9/rnd.9 b/share/man/man9/rnd.9 index 4f42448cb93a..09945ed29be6 100644 --- a/share/man/man9/rnd.9 +++ b/share/man/man9/rnd.9 @@ -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 diff --git a/share/man/man9/rt_timer.9 b/share/man/man9/rt_timer.9 index 94c067dc803c..f572e6a9ca05 100644 --- a/share/man/man9/rt_timer.9 +++ b/share/man/man9/rt_timer.9 @@ -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 diff --git a/share/man/man9/scsipi.9 b/share/man/man9/scsipi.9 index c1013d1bd633..d161c4d08dbf 100644 --- a/share/man/man9/scsipi.9 +++ b/share/man/man9/scsipi.9 @@ -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. diff --git a/share/man/man9/setjmp.9 b/share/man/man9/setjmp.9 index 862eb07386e4..76556b1d7e12 100644 --- a/share/man/man9/setjmp.9 +++ b/share/man/man9/setjmp.9 @@ -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 diff --git a/share/man/man9/shutdownhook_establish.9 b/share/man/man9/shutdownhook_establish.9 index f61da0851509..c789a3859061 100644 --- a/share/man/man9/shutdownhook_establish.9 +++ b/share/man/man9/shutdownhook_establish.9 @@ -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 diff --git a/share/man/man9/signal.9 b/share/man/man9/signal.9 index 6dffc667d8ae..aeb21201c352 100644 --- a/share/man/man9/signal.9 +++ b/share/man/man9/signal.9 @@ -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 diff --git a/share/man/man9/softintr.9 b/share/man/man9/softintr.9 index ff5dadefd09c..8134b1bbb820 100644 --- a/share/man/man9/softintr.9 +++ b/share/man/man9/softintr.9 @@ -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 diff --git a/share/man/man9/spl.9 b/share/man/man9/spl.9 index af71abc6abff..09580ab5044f 100644 --- a/share/man/man9/spl.9 +++ b/share/man/man9/spl.9 @@ -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 diff --git a/share/man/man9/suser.9 b/share/man/man9/suser.9 index 6e59882408a7..c692ac48fa02 100644 --- a/share/man/man9/suser.9 +++ b/share/man/man9/suser.9 @@ -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, diff --git a/share/man/man9/tc.9 b/share/man/man9/tc.9 index 840bf501e8cd..8ccef055920a 100644 --- a/share/man/man9/tc.9 +++ b/share/man/man9/tc.9 @@ -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 diff --git a/share/man/man9/time.9 b/share/man/man9/time.9 index 44fa942cfe1d..f59416e8f9a3 100644 --- a/share/man/man9/time.9 +++ b/share/man/man9/time.9 @@ -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 diff --git a/share/man/man9/todr.9 b/share/man/man9/todr.9 index 6bf76817b308..6a47cf5e224e 100644 --- a/share/man/man9/todr.9 +++ b/share/man/man9/todr.9 @@ -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 diff --git a/share/man/man9/ucom.9 b/share/man/man9/ucom.9 index f988a7e884a8..4c77210865b1 100644 --- a/share/man/man9/ucom.9 +++ b/share/man/man9/ucom.9 @@ -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 diff --git a/share/man/man9/usbdi.9 b/share/man/man9/usbdi.9 index b50b400e687f..9f564a02d6c8 100644 --- a/share/man/man9/usbdi.9 +++ b/share/man/man9/usbdi.9 @@ -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 diff --git a/share/man/man9/vattr.9 b/share/man/man9/vattr.9 index f2194286c028..e1ec11da91d3 100644 --- a/share/man/man9/vattr.9 +++ b/share/man/man9/vattr.9 @@ -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 diff --git a/share/man/man9/vfs.9 b/share/man/man9/vfs.9 index a42b65065e6b..07dad39bdc68 100644 --- a/share/man/man9/vfs.9 +++ b/share/man/man9/vfs.9 @@ -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 diff --git a/share/man/man9/vfsops.9 b/share/man/man9/vfsops.9 index b27dd503c1e9..159499d7e344 100644 --- a/share/man/man9/vfsops.9 +++ b/share/man/man9/vfsops.9 @@ -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 diff --git a/share/man/man9/vme.9 b/share/man/man9/vme.9 index fb006aa1b45e..a824ff43af73 100644 --- a/share/man/man9/vme.9 +++ b/share/man/man9/vme.9 @@ -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 diff --git a/share/man/man9/vnfileops.9 b/share/man/man9/vnfileops.9 index b97bd36ea672..2161c70b0c9c 100644 --- a/share/man/man9/vnfileops.9 +++ b/share/man/man9/vnfileops.9 @@ -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 diff --git a/share/man/man9/vnode.9 b/share/man/man9/vnode.9 index f2ef33e3d02c..161d016c1f66 100644 --- a/share/man/man9/vnode.9 +++ b/share/man/man9/vnode.9 @@ -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. diff --git a/share/man/man9/vnodeops.9 b/share/man/man9/vnodeops.9 index 76dad7b703ad..cab13d8c6bdc 100644 --- a/share/man/man9/vnodeops.9 +++ b/share/man/man9/vnodeops.9 @@ -1,4 +1,4 @@ -.\" $NetBSD: vnodeops.9,v 1.13 2002/10/14 05:05:02 gmcgarry Exp $ +.\" $NetBSD: vnodeops.9,v 1.14 2002/10/14 13:43:36 wiz Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -233,19 +233,20 @@ Not all header files are required for each function. .Sh DESCRIPTION The vnode operations 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. Many of the -functions described in the vnode operations vector are closely related -to their corresponding system calls. In most cases, they are called -as a result of the system call associated with the operation being -invoked. +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. +Many of the functions described in the vnode operations vector are +closely related to their corresponding system calls. +In most cases, they are called as a result of the system call +associated with the operation being invoked. .Pp Functions in the vnode operations vector are invoked using specialised -macros. The following table lists the elements of the vnode -operations vector, the corresponding invocation macro, and a -description of the element. +macros. +The following table lists the elements of the vnode operations vector, +the corresponding invocation macro, and a description of the element. .Pp .nf .ta \w'int (*vop_reallocblks)()'u+2n +\w'VOP_REALLOCBLKS'u+2n +\w'Map file into user address space'u @@ -307,13 +308,15 @@ quite what is described here. .Pp If the file system type does not support a specific operation, it must nevertheless assign an appropriate function in the vnode operations -vector 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. +vector 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. .Pp Many of the functions in the vnode operations vector take a -componentname structure. Is is used to encapsulate many parameters -into a singla function argument. It has the following structure: +componentname structure. +Is is used to encapsulate many parameters into a singla function +argument. +It has the following structure: .Bd -literal struct componentname { /* @@ -337,8 +340,9 @@ struct componentname { The top half of the structure is used exclusively for the pathname lookups using .Fn VOP_LOOKUP -and is initialised by the caller. The semantics of the lookup are -affected by the lookup operation specified in +and is initialised by the caller. +The semantics of the lookup are affected by the lookup operation +specified in .Em cn_nameiop and the flags specified in .Em cn_flags . @@ -379,10 +383,11 @@ do not follow symbolic links (pseudo) mask of operational modifiers .El .Pp -No vnode operations may be called from interrupt context. Most -operations also require the vnode to be locked on entry. To prevent -deadlocks, when acquiring locks on multiple vnodes, the lock of parent -directory must be acquired before the lock on the child directory. +No vnode operations may be called from interrupt context. +Most operations also require the vnode to be locked on entry. +To prevent deadlocks, when acquiring locks on multiple vnodes, the +lock of parent directory must be acquired before the lock on the child +directory. .Pp Vnode operations for a file system type generally should not be called directly from the kernel, but accessed indirectly through the @@ -391,13 +396,14 @@ high-level convenience functions discussed in .Sh FUNCTIONS .Bl -tag -width compact .It Fn VOP_LOOKUP "dvp" "vpp" "cnp" -Lookup a single pathname component in a given directory. The argument +Lookup a single pathname component in a given directory. +The argument .Fa dvp is the locked vnode of the directory to search and .Fa cnp -is the pathname component to be searched for. If the pathname -component is found, the address of the resulting locked vnode is -returned in +is the pathname component to be searched for. +If the pathname component is found, the address of the resulting +locked vnode is returned in .Fa vpp . The operation specified in .Em cnp-\*[Gt]cn_nameiop @@ -407,8 +413,8 @@ hints about the reason for requesting the lookup and uses it to cache file system type specific information in the vnode for subsequent operations. .Pp -There are three types of lookups: ".", ".." (ISDOTDOT), and other. If -the pathname component being searched for is ".", then +There are three types of lookups: ".", ".." (ISDOTDOT), and other. +If the pathname component being searched for is ".", then .Fa dvp has an extra reference added to it and it is returned in .Fa *vpp . @@ -420,15 +426,18 @@ is relocked if and only if LOCKPARENT and ISLASTCN is set in .Em cnp-\*[Gt]cn_flags . If LOCKPARENT or ISLATCN is not set, .Fa dvp -is returned unlocked on a successful lookup. This process preserves -the protocol of always locking nodes from root downward and prevents -deadlock. For other pathname components, +is returned unlocked on a successful lookup. +This process preserves the protocol of always locking nodes from root +downward and prevents deadlock. +For other pathname components, .Fn VOP_LOOKUP checks the accessibility of the directory and searches the name cache -for the pathname component. See +for the pathname component. +See .Xr namecache 9 . If the pathname is not found in the name cache, the directory is -searched for the pathname. The resulting locked vnode is returned in +searched for the pathname. +The resulting locked vnode is returned in .Fa vpp . If LOCKPARENT or ISLATCN is not set, .Fa dvp @@ -438,103 +447,118 @@ On failure .Fa *vpp is NULL, and .Fa *dvp -is left locked. If there was an error relocking +is left locked. +If there was an error relocking .Fa dvp (for instance in the ISDOTDOT case) the error is returned with PDIRUNLOCK set in .Em cnp-\*[Gt]cn_flags . This flag signals to the caller that .Fa dvp ' s -lock state has changed. If the operation is successful +lock state has changed. +If the operation is successful .Fa *vpp -is locked and zero is returned. Typically, if +is locked and zero is returned. +Typically, if .Fa *vpp and .Fa dvp are the same vnode the caller will need to release twice (decrement the reference count) and unlock once. .It Fn VOP_CREATE "dvp" "vpp" "cnp" "vap" -Create a new file in a given directory. The argument +Create a new file in a given directory. +The argument .Fa dvp is the locked vnode of the directory to create the new file in and .Fa cnp -is the pathname component of the new file. The argument +is the pathname component of the new file. +The argument .Fa vap -specifies the attributes that the new file should be created with. If -the file is successfully created, the address of the resulting locked -vnode is returned in +specifies the attributes that the new file should be created with. +If the file is successfully created, the address of the resulting +locked vnode is returned in .Fa vpp and zero is returned. .Pp This function is called after .Fn VOP_LOOKUP -when a file is being created. Normally, +when a file is being created. +Normally, .Fn VOP_LOOKUP will have set the SAVENAME flag in .Em cnp-\*[Gt]cn_flags to keep the memory pointed to by .Em cnp-\*[Gt]cn_pnbuf -valid. If an error is detected when creating the file, this memory is -released. If the file is created successfully it will be released -unless the SAVESTART flags in specified in +valid. +If an error is detected when creating the file, this memory is +released. +If the file is created successfully it will be released unless the +SAVESTART flags in specified in .Em cnp-\*[Gt]cn_flags . .It Fn VOP_MKNOD "dvp" "vpp" "cnp" "vap" -Make a new device-special file in a given directory. The argument +Make a new device-special file in a given directory. +The argument .Fa dvp is the locked vnode of the directory to create the new device-special file in and .Fa cnp -is the pathname component of the new device-special file. The -argument +is the pathname component of the new device-special file. +The argument .Fa vap specifies the attributes that the new device-special file should be -created with. If the file is successfully created, the address of the -resulting locked vnode is returned in +created with. +If the file is successfully created, the address of the resulting +locked vnode is returned in .Fa vpp and zero is returned. .Pp This function is called after .Fn VOP_LOOKUP -when a device-special file is being created. Normally, +when a device-special file is being created. +Normally, .Fn VOP_LOOKUP will have set the SAVENAME flag in .Em cnp-\*[Gt]cn_flags to keep the memory pointed to by .Em cnp-\*[Gt]cn_pnbuf -valid. If an error is detected when creating the device-special file, -this memory is released. If the device-special file is created -successfully it will be released unless the SAVESTART flags in -specified in +valid. +If an error is detected when creating the device-special file, +this memory is released. +If the device-special file is created successfully it will be released +unless the SAVESTART flags in specified in .Em cnp-\*[Gt]cn_flags . .It Fn VOP_OPEN "vp" "mode" "cred" "p" -Open a file. The argument +Open a file. +The argument .Fa vp is the vnode of the file to open and .Fa mode -specifies the access mode required by the calling process. The -calling process and its credentials are specified by +specifies the access mode required by the calling process. +The calling process and its credentials are specified by .Fa p and .Fa cred -respectively. The access mode is a set of flags, including FREAD, -FWRITE, O_NONBLOCK, O_APPEND, etc. +respectively. +The access mode is a set of flags, including FREAD, FWRITE, +O_NONBLOCK, O_APPEND, etc. .Fn VOP_OPEN -must be called before a file can be accessed by a thread. The vnode -reference count is incremented. +must be called before a file can be accessed by a thread. +The vnode reference count is incremented. .Pp .Fn VOP_OPEN expects the vnode .Fa vp -to be locked on entry and will leave it locked on return. If the -operation is successful zero is returned, otherwise an appropriate -error code is returned. +to be locked on entry and will leave it locked on return. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .It Fn VOP_CLOSE "vp" "fflag" "cred" "p" -Close a file. The argument +Close a file. +The argument .Fa vp is the vnode of the file to close and .Fa fflags -specifies the access mode by the calling process. The calling process -and its credentials are specified by +specifies the access mode by the calling process. +The calling process and its credentials are specified by .Fa p and .Fa cred @@ -544,11 +568,12 @@ must be called after a file is finished with. .Pp .Fn VOP_CLOSE expects at least a reference to be associated with the vnode and does -not care whether the vnode is locked. The lock and reference state is -left unchanged on return. +not care whether the vnode is locked. +The lock and reference state is left unchanged on return. .It Fn VOP_ACCESS "vp" "mode" "cred" "p" Determine the accessibility (permissions) of the file against the -specified credentials. The argument +specified credentials. +The argument .Fa vp is the vnode of the file to check, .Fa mode @@ -556,7 +581,8 @@ is the type of access required, .Fa cred contains the user credentials to check and .Fa p -is the process which is checking the credentials. The argument +is the process which is checking the credentials. +The argument .Fa mode is a mask which can contain VREAD, VWRITE or VEXEC. If the file is accessible in the specified way, zero is returned, @@ -566,10 +592,11 @@ The vnode .Fa vp will be locked on entry and should remain locked on return. .It Fn VOP_GETATTR "vp" "vap" "cred" "p" -Get specific vnode attributes on a file. The argument +Get specific vnode attributes on a file. +The argument .Fa vp -is the locked vnode of the file to get the attributes for. The -arguments +is the locked vnode of the file to get the attributes for. +The arguments .Fa p and .Fa cred @@ -588,10 +615,11 @@ Attributes which are not available are set to the value VNOVAL. For more information on vnode attributes see .Xr vattr 9 . .It Fn VOP_SETATTR "vp" "vap" "cred" "p" -Set specific vnode attributes on a file. The argument +Set specific vnode attributes on a file. +The argument .Fa vp -is the locked vnode of the file to set the attributes for. The -arguments +is the locked vnode of the file to set the attributes for. +The arguments .Fa p and .Fa cred @@ -599,21 +627,23 @@ specifies the calling process and its credentials respectively. .Fn VOP_SETATTR uses the file system type specific data object .Em vp-\*[Gt]v_data -to reference the underlying file attributes. The new attributes are -defined in +to reference the underlying file attributes. +The new attributes are defined in .Fa vap . Attributes associated with the file are set by setting the required attribute bits in .Em vap-\*[Gt]va_mask . Attributes which are not being modified by .Fn VOP_SETATTR -should be set to the value VNOVAL. If the operation is successful -zero is returned, otherwise an appropriate error is returned. +should be set to the value VNOVAL. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. .Pp For more information on vnode attributes see .Xr vattr 9 . .It Fn VOP_READ "vp" "uio" "ioflag" "cred" -Read the contents of a file. The argument +Read the contents of a file. +The argument .Fa vp is the vnode of the file to read from, .Fa uio @@ -625,11 +655,11 @@ are the credentials of the calling process. .Pp The .Fa ioflag -argument is used to give directives and hints to the file system. When -attempting a read, the high 16 bits are used to provide a read-ahead -hint (in unit of file system blocks) that the file system should -attempt. The low 16 bits are a bit mask which can contain the -following flags: +argument is used to give directives and hints to the file system. +When attempting a read, the high 16 bits are used to provide a +read-ahead hint (in unit of file system blocks) that the file system +should attempt. +The low 16 bits are a bit mask which can contain the following flags: .Pp .Bl -tag -offset indent -width IO_NODELOCKED -compact .It IO_UNIT @@ -646,10 +676,11 @@ FNDELAY flag set in file table data already in VMIO space .El .Pp -Zero is returned on success, otherwise an error is returned. The vnode -should be locked on entry and remains locked on exit. +Zero is returned on success, otherwise an error is returned. +The vnode should be locked on entry and remains locked on exit. .It Fn VOP_WRITE "vp" "uio" "ioflag" "cred" -Write to a file. The argument +Write to a file. +The argument .Fa vp is the vnode of the file to write to, .Fa uio @@ -661,27 +692,31 @@ are the credentials of the calling process. .Pp The .Fa ioflag -argument is used to give directives and hints to the file system. The -low 16 bits are a bit mask which can contain the same flags as +argument is used to give directives and hints to the file system. +The low 16 bits are a bit mask which can contain the same flags as .Fn VOP_READ . .Pp -Zero is returned on success, otherwise an error is returned. The vnode -should be locked on entry and remains locked on exit. +Zero is returned on success, otherwise an error is returned. +The vnode should be locked on entry and remains locked on exit. .It Fn VOP_IOCTL "vp" "command" "data" "fflag" "cred" "p" -Perform device-specific I/O. The argument +Perform device-specific I/O. +The argument .Fa vp -is the locked vnode of the file, normally representing a device. The -argument +is the locked vnode of the file, normally representing a device. +The argument .Fa command specifies the device-specific operation to perform and .Fa cnp -provides extra data for the specified operation. The argument +provides extra data for the specified operation. +The argument .Fa fflags -is a set of flags. The argument +is a set of flags. +The argument .Fa cred is the caller's credentials and .Fa p -the calling process. If the operation is successful, zero is +the calling process. +If the operation is successful, zero is returned, otherwise an appropriate error code is returned. .Pp Most file systems do not supply a function for @@ -690,30 +725,36 @@ This function implments the .Xr ioctl 2 system call. .It Fn VOP_FCNTL "vp" "command" "data" "fflag" "cred" "p" -Perform file control. The argument +Perform file control. +The argument .Fa vp -is the locked vnode of the file. The -argument +is the locked vnode of the file. +The argument .Fa command specifies the operation to perform and .Fa cnp -provides extra data for the specified operation. The argument +provides extra data for the specified operation. +The argument .Fa fflags -is a set of flags. The argument +is a set of flags. +The argument .Fa cred is the caller's credentials and .Fa p -the calling process. If the operation is successful, zero is -returned, otherwise an appropriate error code is returned. +the calling process. +If the operation is successful, zero is returned, otherwise an +appropriate error code is returned. .It Fn VOP_POLL "vp" "events" "p" -Test if a poll event has occurred. The argument +Test if a poll event has occurred. +The argument .Fa vp is the locked vnode of the file to poll and .Fa p -is the callling process. It returns any events of interest as -specified by +is the callling process. +It returns any events of interest as specified by .Fa events -that may have occurred for the file. The argument +that may have occurred for the file. +The argument .Fa events is a set of flags as specified by .Xr poll 2 . @@ -724,25 +765,29 @@ Eliminate all activity associated with the vnode .Fa vp . The argument .Fa flags -is a set of flags. If REVOKEALL is set in +is a set of flags. +If REVOKEALL is set in .Fa flags all vnodes aliased to the vnode .Fa vp -are also eliminated. If the operation is successful zero is returned, -otherwise an appropriate error is returned. +are also eliminated. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. .It Fn VOP_MMAP "vp" "fflags" "cred" "p" -Map file into user address space. The argument +Map file into user address space. +The argument .Fa vp -is the locked vnode of the file to map into an address space. The -argument +is the locked vnode of the file to map into an address space. +The argument .Fa fflags -is a set of flags. The argument +is a set of flags. +The argument .Fa cred is the caller's credentials and .Fa p -the calling process requesting the map. If the operation is -successful, zero is returned, otherwise an appropriate error code is -returned. +the calling process requesting the map. +If the operation is successful, zero is returned, otherwise an +appropriate error code is returned. .Pp Most file systems do not supply a function for .Fn VOP_MMAP . @@ -750,24 +795,28 @@ This function implements the .Xr mmap 2 system call. .It Fn VOP_FSYNC "vp" "cred" "flags" "offlo" "offhi" "p" -Flush pending data buffers for a file to disk. The argument +Flush pending data buffers for a file to disk. +The argument .Fa vp -is the locked vnode of the file for flush. The argument +is the locked vnode of the file for flush. +The argument .Fa cred is the caller's credentials and .Fa p -the calling process. The argument +the calling process. +The argument .Fa flags -is a set of flags. If FSYNC_WAIT is specified in +is a set of flags. +If FSYNC_WAIT is specified in .Fa flags , the function should wait for I/O to complete before returning. The argument .Fa offlo and .Fa offhi -specify the range of file to flush. If the -operation is successful zero is returned, otherwise an appropriate -error code is returned. +specify the range of file to flush. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .Pp This function implements the .Xr sync 2 @@ -779,156 +828,189 @@ Test if the file is seekable for the specified offset .Fa newoff . The argument .Fa vp -is the locked vnode of the file to test. For most filesystems this -function simply tests if +is the locked vnode of the file to test. +For most filesystems this function simply tests if .Fa newoff -is valid. If the specified +is valid. +If the specified .Fa newoff is less than zero, the function returns error code EINVAL. .It Fn VOP_REMOVE "dvp" "vp" "cnp" -Remove a file. The argument +Remove a file. +The argument .Fa dvp is the locked vnode of the directory to remove the file from and .Fa vp -is the locked vnode of the file to remove. The argument +is the locked vnode of the file to remove. +The argument .Fa cnp -is the pathname component about the file to remove. If the operation -is successful zero is returned, otherwise an appropriate error code is -returned. Both +is the pathname component about the file to remove. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +Both .Fa dvp and .Fa vp should be locked on entry and remain locked on return. .It Fn VOP_LINK "dvp" "vp" "cnp" -Link to a file. The argument +Link to a file. +The argument .Fa dvp is the locked node of the directory to create the new link and .Fa vp -is the vnode of the file to be linked. The argument +is the vnode of the file to be linked. +The argument .Fa cnp -is the pathname component of the the new link. If the operation is -successful zero is returned, otherwise an error code is returned. The -directory vnode +is the pathname component of the the new link. +If the operation is successful zero is returned, otherwise an error +code is returned. +The directory vnode .Fa dvp -should be locked on entry and will remain locked on return. The vnode +should be locked on entry and will remain locked on return. +The vnode .Fa vp should not be locked on entry and will remain unlocked on return. .It Fn VOP_RENAME "fdvp" "fvp" "fcnp" "tdvp" "tvp" "tcnp" -Rename a file. The argument +Rename a file. +The argument .Fa fdvp is the vnode of the old parent directory containing in the file to be renamed and .Fa fvp -is the vnode of the file to be renamed. The argument +is the vnode of the file to be renamed. +The argument .Fa fcnp -is the pathname component about the file to be remained. The argument +is the pathname component about the file to be remained. +The argument .Fa tdvp is the vnode of the new directory of the target file and .Fa tvp -is the vnode of the target file (if it exists). The argument +is the vnode of the target file (if it exists). +The argument .Fa tcnp -is the pathname component about the file's new name. If the operation -is successful zero is returned, otherwise and error code is returned. +is the pathname component about the file's new name. +If the operation is successful zero is returned, otherwise and error +code is returned. .Pp The source directory and file vnodes should be unlocked and their -reference counts should be incremented before entry. The target -directory and file vnodes should both be locked on entry. +reference counts should be incremented before entry. +The target directory and file vnodes should both be locked on entry. .Fn VOP_RENAME updates the reference counts prior to returning. .It Fn VOP_MKDIR "dvp" "vpp" "cnp" "vap" -Make a new directory in a given directory. The argument +Make a new directory in a given directory. +The argument .Fa dvp is the locked vnode of the directory to create the new directory in and .Fa cnp -is the pathname component of the new directory. The argument +is the pathname component of the new directory. +The argument .Fa vap -specifies the attributes that the new directory should be created with. If -the file is successfully created, the address of the resulting locked -vnode is returned in -.Fa vpp -and zero is returned. -.Pp -This function is called after -.Fn VOP_LOOKUP -when a directory is being created. Normally, -.Fn VOP_LOOKUP -will have set the SAVENAME flag in -.Em cnp-\*[Gt]cn_flags -to keep the memory pointed to by -.Em cnp-\*[Gt]cn_pnbuf -valid. If an error is detected when creating the directory, this -memory is released. If the directory is created successfully it will -be released unless the SAVESTART flags in specified in -.Em cnp-\*[Gt]cn_flags . -.It Fn VOP_RMDIR "dvp" "vp" "cnp" -Remove a directory in a given directory. The argument -.Fa dvp -is the locked vnode of the directory to remove the directory from and -.Fa vp -is the locked vnode of the directory to remove. The argument -.Fa cnp -is the pathname component of the directory. Zero is returned on -success, otherwise an error code is returned. Both -.Fa dvp -and -.Fa vp -should be locked on entry and remain locked on return. -.It Fn VOP_SYMLINK "dvp" "vpp" "cnp" "vap" "target" -Create a symbolic link in a given directory. The argument -.Fa dvp -is the locked vnode of the directory to create the symbolic link in -and -.Fa cnp -is the pathname component of the symbolic link. The argument -.Fa vap -specifies the attributes that the symbolic link should be created -with and -.Fa target -specifies the pathname of the target of the symbolic link. If the -symbolic link is successfully created, the address of the resulting +specifies the attributes that the new directory should be created +with. +If the file is successfully created, the address of the resulting locked vnode is returned in .Fa vpp and zero is returned. .Pp This function is called after .Fn VOP_LOOKUP -when a symbolic link is being created. Normally, +when a directory is being created. +Normally, .Fn VOP_LOOKUP will have set the SAVENAME flag in .Em cnp-\*[Gt]cn_flags to keep the memory pointed to by .Em cnp-\*[Gt]cn_pnbuf -valid. If an error is detected when creating the symbolic link, this -memory is released. If the symbolic link is created successfully it -will be released unless the SAVESTART flags in specified in +valid. +If an error is detected when creating the directory, this memory is +released. +If the directory is created successfully it will be released unless +the SAVESTART flags in specified in +.Em cnp-\*[Gt]cn_flags . +.It Fn VOP_RMDIR "dvp" "vp" "cnp" +Remove a directory in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to remove the directory from and +.Fa vp +is the locked vnode of the directory to remove. +The argument +.Fa cnp +is the pathname component of the directory. +Zero is returned on success, otherwise an error code is returned. +Both +.Fa dvp +and +.Fa vp +should be locked on entry and remain locked on return. +.It Fn VOP_SYMLINK "dvp" "vpp" "cnp" "vap" "target" +Create a symbolic link in a given directory. +The argument +.Fa dvp +is the locked vnode of the directory to create the symbolic link in +and +.Fa cnp +is the pathname component of the symbolic link. +The argument +.Fa vap +specifies the attributes that the symbolic link should be created +with and +.Fa target +specifies the pathname of the target of the symbolic link. +If the symbolic link is successfully created, the address of the +resulting locked vnode is returned in +.Fa vpp +and zero is returned. +.Pp +This function is called after +.Fn VOP_LOOKUP +when a symbolic link is being created. +Normally, +.Fn VOP_LOOKUP +will have set the SAVENAME flag in +.Em cnp-\*[Gt]cn_flags +to keep the memory pointed to by +.Em cnp-\*[Gt]cn_pnbuf +valid. +If an error is detected when creating the symbolic link, this memory +is released. +If the symbolic link is created successfully it will be released +unless the SAVESTART flags in specified in .Em cnp-\*[Gt]cn_flags . .It Fn VOP_READDIR "vp" "uio" "cred" "eofflag" "cookies" "ncookies" -Read directory entry. The argument +Read directory entry. +The argument .Fa vp is the vnode of the directory to read the contents of and .Fa uio -is the destination location to read the contents into. The argument +is the destination location to read the contents into. +The argument .Fa cred -is the caller's credientials. The argument +is the caller's credientials. +The argument .Fa eofflag is the pointer to a flag which is set by .Fn VOP_READDIR -to indicate and end-of-file condition. If +to indicate and end-of-file condition. +If .Fa eofflag -is NULL, the end-of-file condition is not returned. The arguments +is NULL, the end-of-file condition is not returned. +The arguments .Fa cookies 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 should be NULL if they aren't required to be returned by .Fn VOP_READDIR . -The directory contents are read into struct dirent structures. If the -operation is successful zero is returned, otherwise an appropriate -error code is returned. +The directory contents are read into struct dirent structures. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .Pp The directory should be locked on entry and will remain locked on return. @@ -940,23 +1022,28 @@ is called from the NFS server, the extra arguments .Fa ncookies and .Fa cookies -are used. The value of +are used. +The value of .Fa *eofflag will be set to TRUE if the end of the directory is reached while -reading. The directory seek cookies are returned to the NFS client -and may be used later to restart a directory read part way through the -directory. There should be one cookie returned per directory entry. +reading. +The directory seek cookies are returned to the NFS client and may be +used later to restart a directory read part way through the directory. +There should be one cookie returned per directory entry. The value of the cookie should be the offset within the directory where the on-disk version of the appropriate directory entry starts. .It Fn VOP_READLINK "vp" "uio" "cred" -Read the contents of a symbolic link. The argument +Read the contents of a symbolic link. +The argument .Fa vp is the locked vnode of the symlink and .Fa uio -is the destination location to read the contents into. The argument +is the destination location to read the contents into. +The argument .Fa cred -is the credentials of the caller. If the operation is successful zero -is returned, otherwise an error code is returned. +is the credentials of the caller. +If the operation is successful zero is returned, otherwise an error +code is returned. .Pp The vnode should be locked on entry and will remain locked on return. .It Fn VOP_ABORTOP "dvp" "cnp" @@ -966,15 +1053,20 @@ This operation is rarely implemented in file systems. .It Fn VOP_INACTIVE "vp" "p" Release the inactive vnode. .Fn VOP_INACTIVE -is called when the kernel is no longer using the vnode. This may be -because the reference count reaches zero or it may be that the file -system is being forcibly unmounted while there are open files. It can -be used to reclaim space for open but deleted files. The argument +is called when the kernel is no longer using the vnode. +This may be because the reference count reaches zero or it may be that +the file system is being forcibly unmounted while there are open +files. +It can be used to reclaim space for open but deleted files. +The argument .Fa vp -is the locked vnode to be released. The argument +is the locked vnode to be released. +The argument .Fa p -is the calling process. If the operation is successful zero is -returned, otherwise an appropriate error code is returned. The vnode +is the calling process. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +The vnode .Fa vp must be locked on entry, and will be unlocked on return. .It Fn VOP_RECLAIM "vp" "p" @@ -982,39 +1074,49 @@ Reclaim the vnode for another file system. .Fn VOP_RECLAIM is called when a vnode is being reused for a different file system. Any file system specific resources associated with the vnode should be -freed. The argument +freed. +The argument .Fa vp -is the locked vnode to be reclaimed. The argument +is the locked vnode to be reclaimed. +The argument .Fa p -is the calling process. If the operation is successful zero is returned, -otherwise an appropriate error code is returned. The vnode +is the calling process. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +The vnode .Fa vp should not be locked on entry, and will remain unlocked on return. .It Fn VOP_LOCK "vp" "flags" -Sleep until vnode lock is free. The argument +Sleep until vnode lock is free. +The argument .Fa vp -is the vnode of the file to be locked. The argument +is the vnode of the file to be locked. +The argument .Fa flags is a set of .Xr lockmgr 9 -flags. If the operation is successful zero is returned, otherwise an +flags. +If the operation is successful zero is returned, otherwise an appropriate error code is returned. .Fn VOP_LOCK is used to serialise access to the file system such as to present two -writes to the same file from happening at the same time. Kernel code -should use +writes to the same file from happening at the same time. +Kernel code should use .Xr vn_lock 9 to lock a vnode rather than calling .Fn VOP_LOCK directly. .It Fn VOP_UNLOCK "vp" "flags" -Wake up process sleeping on lock. The argument +Wake up process sleeping on lock. +The argument .Fa vp -is the vnode of the file to be unlocked. The argument +is the vnode of the file to be unlocked. +The argument .Fa flags is a set of .Xr lockmgr 9 -flags. If the operation is successful zero is returned, otherwise an +flags. +If the operation is successful zero is returned, otherwise an appropriate error code is returned. .Fn VOP_UNLOCK is used to serialise access to the file system such as to present two @@ -1022,14 +1124,16 @@ writes to the same file from happening at the same time. .It Fn VOP_ISLOCKED "vp" Test if the vnode .Fa vp -is locked. A non-zero values is returned if the vnode is not locked, -otherwise zero is returned. +is locked. +A non-zero values is returned if the vnode is not locked, otherwise +zero is returned. .It Fn VOP_BMAP "vp" "bn" "vpp" "bnp" "runp" Convert the logical block number .Fa bn of a file specified by vnode .Fa vp -to its physical block number on the disk. If +to its physical block number on the disk. +If .Fa vpp is not NULL, the vnode of the device vnode for the file system is returned in the address specified by @@ -1040,21 +1144,25 @@ is not NULL, the maximum blocksize is returned in the address specified by .Fa runp . .It Fn VOP_PRINT "vp" -Print debugging information. The argument +Print debugging information. +The argument .Fa vp -is the vnode to print. If the operation is successful zero is -returned, otherwise an appropriate error code is returned. +is the vnode to print. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .It Fn VOP_PATHCONF "vp" "name" "retval" Implement POSIX .Xr pathconf 2 and .Xr fpathconf 2 -support. The argument +support. +The argument .Fa vp -is the locked vnode to get information about. The argument +is the locked vnode to get information about. +The argument .Fa name -specified the type of information to return. The information -is returned in the address specified by +specified the type of information to return. +The information is returned in the address specified by .Fa retval . Valid values for .Fa name @@ -1085,19 +1193,24 @@ is recognised, is set to the specified value and zero is returned, otherwise an appropriate error is returned. .It Fn VOP_ADVLOCK "vp" "id" "op" "fl" "flags" -Manipulate Advisory record locks on a file. The argument +Manipulate Advisory record locks on a file. +The argument .Fa vp -is the vnode is the file for the advisory record lock. The argument +is the vnode is the file for the advisory record lock. +The argument .Fa id is the id token which is changing the lock and .Fa op is the .Xr fcntl 2 -operation to perform. The argument +operation to perform. +The argument .Fa fl -is a description of the lock. The argument +is a description of the lock. +The argument .Fa flags -is the set of flags. Valid values are: +is the set of flags. +Valid values are: .Pp .Bl -tag -offset indent -width F_RDLCK -compact .It F_RDLCK @@ -1131,7 +1244,8 @@ is non-zero, fill it in with a pointer to the remaining space in the directory. .It Fn VOP_VALLOC "pvp" "mode" "cred" "vpp" Allocate file system type specific data a new file in the file -system. The argument +system. +The argument .Fa pvp specifies the vnode of the directory to create the new file. The argument @@ -1139,8 +1253,8 @@ The argument specifies file system type specific flags and .Fa cred -are the credentials of the calling process. The vnode of the new file -is returned in the address specified by +are the credentials of the calling process. +The vnode of the new file is returned in the address specified by .Fa vpp . .It Fn VOP_BALLOC "vp" "startoffset" "size" "cred" "flags" "bpp" Allocate the physical blocks on a device given the vnode @@ -1148,18 +1262,20 @@ Allocate the physical blocks on a device given the vnode and the offset logical block number .Fa startoffset -in a file. The argument +in a file. +The argument .Fa size -specifies the size to be allocated. The credentials of the calling -processing are specified by +specifies the size to be allocated. +The credentials of the calling processing are specified by .Fa cred . If the argument .Fa bpp -is not NULL, the buffer is written to the allocated blocks. The -argument +is not NULL, the buffer is written to the allocated blocks. +The argument .Fa flags is a set of flags controlling the low-level allocation when the buffer -is written. Valid values defined in +is written. +Valid values defined in .Pa \*[Lt]sys/buf.h\*[Gt] are: .Pp @@ -1173,28 +1289,34 @@ do all allocations synchronously If the operation is successful zero is returned, otherwise an appropriate error is returned. .It Fn VOP_REALLOCBLKS "vp" "buflist" -Rearrange block in a file to be contiguous. The argument +Rearrange block in a file to be contiguous. +The argument .Fa vp -is the vnode of the file to manipulate. The argument +is the vnode of the file to manipulate. +The argument .Fa buflist -is a list of buffers to rearrange. If the operation is successful -zero is returned, otherwise an appropriate error is returned. +is a list of buffers to rearrange. +If the operation is successful zero is returned, otherwise an +appropriate error is returned. .It Fn VOP_VFREE "pvp" "ino" "mode" -Release file resources. This function is used by the file system to -release cached file system specific data associated with the file when -the vnode is recycled. +Release file resources. +This function is used by the file system to release cached file system +specific data associated with the file when the vnode is recycled. .It Fn VOP_TRUNCATE "vp" "length" "flags" "cred" "p" Truncate the file specified by the vnode .Fa vp to at most .Fa length -size and free the unused disk blocks. The arguments +size and free the unused disk blocks. +The arguments .Fa p and .Fa cred -is the calling process and its credentials respectively. The argument +is the calling process and its credentials respectively. +The argument .Fa flags -is a set of I/O flags. Valid values are: +is a set of I/O flags. +Valid values are: .Pp .Bl -tag -offset indent -width IO_ALTSEMANTICS -compact .It IO_UNIT @@ -1222,7 +1344,8 @@ The access and modification times are specified by the arguments .Fa access and .Fa modify -respectively. The change time is always taken from the current time. +respectively. +The change time is always taken from the current time. The argument .Fa flags is a set of file system type dependent flags indicating how times @@ -1235,7 +1358,8 @@ wait for completion hint to file system to wait or not .El .It Fn VOP_LEASE "vp" "p" "cred" "flags" -Validate vnode credentials and operation type. The argument +Validate vnode credentials and operation type. +The argument .Fa vp is the locked vnode of the file to validate credentials .Fa cred . @@ -1243,9 +1367,10 @@ The argument .Fa p specifies the calling process and .Fa flags -specifies the operation flags. If the operation is successful zero is -returned, otherwise an appropriate error code is returned. The vnode -must be locked on entry and remains locked on return. +specifies the operation flags. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. +The vnode must be locked on entry and remains locked on return. .It Fn VOP_WHITEOUT "dvp" "cnp" "flags" Whiteout pathname component in directory with vnode .Fa dvp . @@ -1256,42 +1381,49 @@ specifies the pathname component to whiteout. .Fa "vp" "offset" "m" "count" "centeridx" .Fa "access_type" "advice" "flags" .Fc -Read VM pages from file. The argument +Read VM pages from file. +The argument .Fa vp -is the locked vnode to read the VM pages from. The argument +is the locked vnode to read the VM pages from. +The argument .Fa offset is offset in the file to start accessing and .Fa m is an array of VM pages. The argument .Fa count -specifies the number of pages to read. If the operation is successful -zero is returned, otherwise an appropriate error code is returned. +specifies the number of pages to read. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .Pp This function is primarily used by the page-fault handing mechanism. .It Fn VOP_PUTPAGES "vp" "offset" "len" "flags" -Write modified (dirty) VM pages to file. The argument +Write modified (dirty) VM pages to file. +The argument .Fa vp is the locked vnode to write the VM pages to and .Fa offset and .Fa len -specifies the range of VM pages to write. There seems to be some -confusion in the code whether +specifies the range of VM pages to write. +There seems to be some confusion in the code whether .Fa offset and .Fa len specify the start and length of the VM pages for the start and end of -the VM pages. The argument +the VM pages. +The argument .Fa flags specifies whether the pages should be written asynchronously and also whether they should be marked invalid one the write back operation has -completed. If the operation is successful zero is returned, otherwise -an appropriate error code is returned. +completed. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .Pp The function is primarily used by the pageout handling mechanism. .It Fn VOP_STRATEGY "bp" -Read/write a file system buffer. The argument +Read/write a file system buffer. +The argument .Fa bp is the buffer to be read or written. .Fn VOP_STRATEGY @@ -1300,10 +1432,12 @@ will either read or write data to the file depending on the value of If the operation is successful zero is returned, otherwise an appropriate error code is returned. .It Fn VOP_BWRITE "bp" -Write a file system buffer. The argument +Write a file system buffer. +The argument .Fa bp -specifies the buffer to be written. If the operation is successful -zero is returned, otherwise an appropriate error code is returned. +specifies the buffer to be written. +If the operation is successful zero is returned, otherwise an +appropriate error code is returned. .El .Sh ERRORS .Bl -tag -width Er diff --git a/share/man/man9/vnsubr.9 b/share/man/man9/vnsubr.9 index 0caa9487614f..89adebee79de 100644 --- a/share/man/man9/vnsubr.9 +++ b/share/man/man9/vnsubr.9 @@ -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 diff --git a/share/man/man9/wscons.9 b/share/man/man9/wscons.9 index 3c6c30a7b50f..cf6ef45c42da 100644 --- a/share/man/man9/wscons.9 +++ b/share/man/man9/wscons.9 @@ -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 diff --git a/share/man/man9/wsdisplay.9 b/share/man/man9/wsdisplay.9 index c036ce02e46f..de2b3e93499b 100644 --- a/share/man/man9/wsdisplay.9 +++ b/share/man/man9/wsdisplay.9 @@ -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 diff --git a/share/man/man9/wsfont.9 b/share/man/man9/wsfont.9 index d52ec7677a2d..5714e7481693 100644 --- a/share/man/man9/wsfont.9 +++ b/share/man/man9/wsfont.9 @@ -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 diff --git a/share/man/man9/wskbd.9 b/share/man/man9/wskbd.9 index d3f7c263e5c4..533a4fa549f3 100644 --- a/share/man/man9/wskbd.9 +++ b/share/man/man9/wskbd.9 @@ -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 diff --git a/share/man/man9/wsmouse.9 b/share/man/man9/wsmouse.9 index 7b4a053197fa..c4df29ac369b 100644 --- a/share/man/man9/wsmouse.9 +++ b/share/man/man9/wsmouse.9 @@ -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