Module Name: src
Committed By: mlelstv
Date: Mon Nov 28 11:00:24 UTC 2016
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: dksubr.9
Log Message:
Provide a man page for the disk driver subroutines (dksubr).
To generate a diff of this commit:
cvs rdiff -u -r1.2075 -r1.2076 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.397 -r1.398 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/dksubr.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2075 src/distrib/sets/lists/comp/mi:1.2076
--- src/distrib/sets/lists/comp/mi:1.2075 Sat Nov 26 03:17:58 2016
+++ src/distrib/sets/lists/comp/mi Mon Nov 28 11:00:24 2016
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2075 2016/11/26 03:17:58 ozaki-r Exp $
+# $NetBSD: mi,v 1.2076 2016/11/28 11:00:24 mlelstv Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10242,6 +10242,7 @@
./usr/share/man/cat9/disk_resetstat.0 comp-obsolete obsolete
./usr/share/man/cat9/disk_unbusy.0 comp-sys-catman .cat
./usr/share/man/cat9/disklabel.0 comp-sys-catman .cat
+./usr/share/man/cat9/dksubr.0 comp-sys-catman .cat
./usr/share/man/cat9/dmover.0 comp-sys-catman .cat
./usr/share/man/cat9/dmover_backend_register.0 comp-sys-catman .cat
./usr/share/man/cat9/dmover_backend_unregister.0 comp-sys-catman .cat
@@ -17462,6 +17463,7 @@
./usr/share/man/html9/disk_init.html comp-sys-htmlman html
./usr/share/man/html9/disk_unbusy.html comp-sys-htmlman html
./usr/share/man/html9/disklabel.html comp-sys-htmlman html
+./usr/share/man/html9/dksubr.html comp-sys-htmlman html
./usr/share/man/html9/dmover.html comp-sys-htmlman html
./usr/share/man/html9/dmover_backend_register.html comp-sys-htmlman html
./usr/share/man/html9/dmover_backend_unregister.html comp-sys-htmlman html
@@ -24826,6 +24828,7 @@
./usr/share/man/man9/disk_resetstat.9 comp-obsolete obsolete
./usr/share/man/man9/disk_unbusy.9 comp-sys-man .man
./usr/share/man/man9/disklabel.9 comp-sys-man .man
+./usr/share/man/man9/dksubr.9 comp-sys-man .man
./usr/share/man/man9/dmover.9 comp-sys-man .man
./usr/share/man/man9/dmover_backend_register.9 comp-sys-man .man
./usr/share/man/man9/dmover_backend_unregister.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.397 src/share/man/man9/Makefile:1.398
--- src/share/man/man9/Makefile:1.397 Sat Aug 20 12:37:06 2016
+++ src/share/man/man9/Makefile Mon Nov 28 11:00:24 2016
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.397 2016/08/20 12:37:06 hannken Exp $
+# $NetBSD: Makefile,v 1.398 2016/11/28 11:00:24 mlelstv Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -16,7 +16,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht
cpu_startup.9 cpu_switchto.9 cpufreq.9 \
csf.9 ctod.9 \
curproc.9 \
- delay.9 devsw_attach.9 disk.9 ddc.9 disklabel.9 dofileread.9 \
+ delay.9 devsw_attach.9 disk.9 ddc.9 disklabel.9 dksubr.9 dofileread.9 \
dopowerhooks.9 do_setresuid.9 doshutdownhooks.9 driver.9 \
edid.9 errno.9 ethersubr.9 evcnt.9 extattr.9 extent.9 \
fetch.9 file.9 fileassoc.9 filedesc.9 firmload.9 flash.9 \
Added files:
Index: src/share/man/man9/dksubr.9
diff -u /dev/null src/share/man/man9/dksubr.9:1.1
--- /dev/null Mon Nov 28 11:00:24 2016
+++ src/share/man/man9/dksubr.9 Mon Nov 28 11:00:24 2016
@@ -0,0 +1,287 @@
+.\" $NetBSD: dksubr.9,v 1.1 2016/11/28 11:00:24 mlelstv Exp $
+.\"
+.\" Copyright (c) 2016 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd November 28, 2016
+.Dt DKSUBR 9
+.Os
+.Sh NAME
+.Nm dk_softc ,
+.Nm dk_init ,
+.Nm dk_attach ,
+.Nm dk_detach ,
+.Nm dk_open ,
+.Nm dk_close ,
+.Nm dk_size ,
+.Nm dk_dump ,
+.Nm dk_ioctl ,
+.Nm dk_strategy ,
+.Nm dk_strategy_defer ,
+.Nm dk_strategy_pending ,
+.Nm dk_start ,
+.Nm dk_done ,
+.Nm dk_drain ,
+.Nm dk_discard ,
+.Nm dk_getdefaultlabel ,
+.Nm dk_getdisklabel ,
+.Nd disk driver subroutines
+.Sh SYNOPSIS
+.In sys/bufq.h
+.In sys/disk.h
+.In dev/dkvar.h
+.Ft void
+.Fn dk_init "struct dk_softc *" "device_t" "int dtype"
+.Ft void
+.Fn dk_attach "struct dk_softc *"
+.Ft void
+.Fn dk_detach "struct dk_softc *"
+.Ft int
+.Fn dk_open "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *"
+.Ft int
+.Fn dk_close "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *"
+.Ft int
+.Fn dk_discard "struct dk_softc *" "dev_t" "off_t pos" "off_t len"
+.Ft int
+.Fn dk_size "struct dk_softc *" "dev_t"
+.Ft int
+.Fn dk_dump "struct dk_softc *" "dev_t" "daddr_t blkno" "void *vav" "size_t size"
+.Ft int
+.Fn dk_ioctl "struct dk_softc *" "dev_t" "u_long cmd" "void *data" "int flag" "struct lwp *"
+.Ft void
+.Fn dk_strategy "struct dk_softc *" "struct buf *"
+.Ft int
+.Fn dk_strategy_defer "struct dk_softc *" "struct buf *"
+.Ft int
+.Fn dk_strategy_pending "struct dk_softc *"
+.Ft void
+.Fn dk_start "struct dk_softc *" "struct buf *"
+.Ft void
+.Fn dk_done "struct dk_softc *" "struct buf *"
+.Ft int
+.Fn dk_drain "struct dk_softc *"
+.Ft void
+.Fn dk_getdefaultlabel "struct dk_softc *" "struct disklabel *"
+.Ft void
+.Fn dk_getdisklabel "struct dk_softc *" "dev_t"
+.Sh DESCRIPTION
+The disk driver subroutines provide common functionality for all disk drivers
+to reduce the amount of replicated code. For many disk drivers, their
+corresponding entry points can be made mostly stubs.
+.Pp
+The subroutines encapsulate data structures found in a driver's softc
+into
+.Bd -literal
+struct dk_softc {
+ device_t sc_dev;
+ struct disk sc_dkdev;
+ struct bufq_state sc_bufq;
+ krndsoruce_t sc_rnd_source;
+...
+}
+.Ed
+The
+.Nm dk_softc
+structure therefore replaces the
+.Nm device_t
+member of the driver's softc struct.
+.Pp
+The following is a brief description of each function in the framework:
+.Bl -tag -width ".Fn dk_strategy_pending"
+.It Fn dk_init
+Initialize the dk_softc structure.
+.It Fn dk_attach
+Attach framework after driver has attached the
+.Xr disk 9
+subsystem, created a
+.Xr bufq 9
+and is ready to handle I/O.
+.It Fn dk_detach
+Undo dk_attach.
+.It Fn dk_open
+Handles open steps for the
+.Xr disk 9
+framework, acquires the disklabel and validates open parameters.
+The driver may provide the
+.Nm d_firstopen
+callback to handle initialization steps.
+.It Fn dk_close
+Handles close steps for the
+.Xr disk 9
+framework. The driver may provide the
+.Nm d_lastclose
+callback to handle finalization steps.
+.Nm dk_open
+and
+.Nm dk_close
+are serialized by the openlock mutex.
+.It Fn dk_discard
+Validates parameters, computes raw block numbers and passes
+these to the
+.Nm d_discard
+callback.
+.It Fn dk_size
+returns dump size information from the
+.Xr disklabel 9
+and opens and closes the driver when necessary.
+.It Fn dk_dump
+Validates parameters, computes raw block numbers and iterates
+over the
+.Nm d_dumpblocks
+callback in appropriate chunks determined by the
+.Nm d_iosize
+callback.
+.It Fn dk_ioctl
+Handles the ioctls
+.Nm DIOCKLABEL
+.Nm DIOCWLABEL
+.Nm DIOCGDEFLABEL
+.Nm DIOCGSTRATEGY
+.Nm DIOCSSTRATEGY
+and passes other disk ioctls through the
+.Xr disk 9
+framework. Returns
+.Nm ENOTTY
+when an ioctl isn't implemented. This routine is run as a fallback to
+handle commands, that are not specific to the driver.
+.It Fn dk_strategy
+Validates parameters, computes raw block numbers, queues a buffer for I/O
+and triggers queue processing by calling
+.Nm dk_start .
+.It Fn dk_strategy_defer
+Alternative to
+.Nm dk_strategy
+that only queues the buffer. Drivers that implement a separate I/O thread
+can use
+.Nm dk_strategy_defer
+within their own strategy routine and signal the thread through a private
+interface.
+.It Fn dk_strategy_pending
+This function is called by an I/O thread to determine if work has been
+queued by
+.Nm dk_strategy_defer .
+The driver must then call
+.Nm dk_start
+to trigger queue processing.
+.It Fn dk_start
+If bp != NULL put it into the queue. Run the
+.Nm d_diskstart
+callback for every buffer until the queue is empty or the callback returns
+.Nm EAGAIN .
+In the latter case, the buffer is saved and issued on the
+next queue run. This also calls
+.Nm disk_busy
+accordingly to handle I/O metrics.
+.It Fn dk_done
+Called by the driver when an I/O operation completed.
+.Nm dk_done
+logs errors, calls
+.Nm disk_unbusy
+to handle I/O metrics and collects entropy for the
+.Xr cprng 9 .
+.It Fn dk_drain
+Aborts all queued I/O. This function must be called instead
+of
+.Fn bufq_drain
+to cooperate with
+.Nm dk_start .
+.It Fn dk_getdefaultlabel
+Compute a common default disklabel for all disk drivers.
+.It Fn dk_getdisklabel
+Read disklabel with machine dependent low-level function
+.Nm readdisklabel
+and do sanity checks.
+.El
+.Sh DRIVER INTERFACE
+The driver needs to provide a common set of entry points that are
+used by the disk driver subroutines and the
+.Xr disk 9
+framework.
+.Bd -literal
+struct dkdriver {
+ void (*d_strategy)(struct buf *);
+ void (*d_minphys)(struct buf *);
+ int (*d_open)(dev_t, int, int, struct lwp *);
+ int (*d_close)(dev_t, int, int, struct lwp *);
+ int (*d_diskstart)(device_t, struct buf *);
+ void (*d_iosize)(device_t, int *);
+ int (*d_dumpblocks)(device_t, void *, daddr_t, int);
+ int (*d_lastclose)(device_t);
+ int (*d_discard)(device_t, off_t, off_t);
+ int (*d_firstopen)(device_t, dev_t, int, int);
+};
+.Ed
+.Bl -tag -width ".Fn dk_firstopen"
+.It Fn d_strategy
+The driver strategy routine.
+.It Fn d_minphys
+The driver minphys routine.
+.It Fn d_open
+The driver open routine.
+.It Fn d_close
+The driver close routine.
+.It Fn d_diskstart
+Issues a single I/O request, called by
+.Nm dk_start .
+.It Fn d_iosize
+Truncate I/O size to the driver limit.
+.It Fn d_dumpblocks
+Issue a single I/O requests, called by
+.Nm dk_dump .
+.It Fn d_lastclose
+Private cleanup after last user is finished. Often used to
+flush write caches.
+.It Fn d_discard
+Issue a single I/O request to invalidate a disk region.
+.It Fn d_firstopen
+Private initialization when first user opens the driver.
+.Sh SEE ALSO
+.Xr disk 9 ,
+.Xr cprng 9 ,
+.Xr ld 4 ,
+.Xr cgd 4 .
+.Sh HISTORY
+The
+.Nx
+common disk driver subroutines appeared in
+.Nx 2.0
+as a base for the cryptographic disk driver and was extended
+to handle disk wedges in
+.Nx 4.0 .
+Most functionality provided by
+.Xr ld 4
+was included and extended in
+.Nx 8.0
+to support other disk drivers.
+The callback interface used by the
+.Xr disk 9
+framework has been merged as well.
+.Sh BUGS
+The framework includes a
+.Nm dk_lookup
+helper function, that is used by the
+.Xr cgd 4
+driver to open a vnode for a block device. This looks too generic
+and should be put somewhere better (and be renamed).
+
