Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Provide a man page for the disk driver subroutines (dksubr).
details: https://anonhg.NetBSD.org/src/rev/1db24ba80c5b
branches: trunk
changeset: 349195:1db24ba80c5b
user: mlelstv <mlelstv%NetBSD.org@localhost>
date: Mon Nov 28 11:00:24 2016 +0000
description:
Provide a man page for the disk driver subroutines (dksubr).
diffstat:
distrib/sets/lists/comp/mi | 5 +-
share/man/man9/Makefile | 4 +-
share/man/man9/dksubr.9 | 287 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 293 insertions(+), 3 deletions(-)
diffs (truncated from 342 to 300 lines):
diff -r abd501864cc4 -r 1db24ba80c5b distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Mon Nov 28 08:42:20 2016 +0000
+++ b/distrib/sets/lists/comp/mi Mon Nov 28 11:00:24 2016 +0000
@@ -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
diff -r abd501864cc4 -r 1db24ba80c5b share/man/man9/Makefile
--- a/share/man/man9/Makefile Mon Nov 28 08:42:20 2016 +0000
+++ b/share/man/man9/Makefile Mon Nov 28 11:00:24 2016 +0000
@@ -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 @@
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 \
diff -r abd501864cc4 -r 1db24ba80c5b share/man/man9/dksubr.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/dksubr.9 Mon Nov 28 11:00:24 2016 +0000
@@ -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
Home |
Main Index |
Thread Index |
Old Index