[src/trunk]: src/share/man/man9 Add d_label and add a few words to minphys an...

[mlelstv <mlelstv%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b4764d6bdf2c
branches:  trunk
changeset: 349410:b4764d6bdf2c
user:      mlelstv <mlelstv%NetBSD.org@localhost>
date:      Sat Dec 10 09:49:00 2016 +0000

description:
Add d_label and add a few words to minphys and strategy.

Update disk man page for other users of the disk driver switch and
add reference to dksubr(9).

diffstat:

 share/man/man9/disk.9   |  34 ++++++++++++++++++++++++++++------
 share/man/man9/dksubr.9 |  24 ++++++++++++++++++++----
 2 files changed, 48 insertions(+), 10 deletions(-)

diffs (124 lines):

diff -r acc293cfdead -r b4764d6bdf2c share/man/man9/disk.9
--- a/share/man/man9/disk.9     Sat Dec 10 09:44:06 2016 +0000
+++ b/share/man/man9/disk.9     Sat Dec 10 09:49:00 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: disk.9,v 1.40 2014/12/31 20:13:41 mlelstv Exp $
+.\"    $NetBSD: disk.9,v 1.41 2016/12/10 09:49:00 mlelstv Exp $
 .\"
 .\" Copyright (c) 1995, 1996 Jason R. Thorpe.
 .\" All rights reserved.
@@ -368,15 +368,36 @@
 above is the disk's
 .Dq driver
 switch.
-This switch currently includes a pointer to the disk's
-.Dq strategy
-routine.
+This switch currently includes pointers to several driver entry points,
+where only the
+.Nm d_strategy
+entry point is used by the disk framework.
 This switch needs to have global scope and should be initialized as follows:
 .Bd -literal
-void foostrategy(struct buf *);
+void    (foostrategy)(struct buf *);
+void    (foominphys)(struct buf *);
+int     (fooopen)(dev_t, int, int, struct lwp *);
+int     (fooclose)(dev_t, int, int, struct lwp *);
+int     (foo_discard)(device_t, off_t, off_t);
+int     (foo_diskstart)(device_t, struct buf *);
+void    (foo_iosize)(device_t, int *);
+int     (foo_dumpblocks)(device_t, void *, daddr_t, int);
+int     (foo_lastclose)(device_t);
+int     (foo_firstopen)(device_t, dev_t, int, int);
+int     (foo_label)(device_t, struct disklabel *);
 
 const struct dkdriver foodkdriver = {
+       .d_open = fooopen,
+       .d_close = fooclose,
        .d_strategy = foostrategy,
+       .d_minphys = foominphys,
+       .d_discard = foo_discard,
+       .d_diskstart = foo_diskstart,   /* optional */
+       .d_dumpblocks = foo_dumpblocks, /* optional */
+       .d_iosize = foo_iosize,         /* optional */
+       .d_firstopen = foo_firstopen,   /* optional */
+       .d_lastclose = foo_lastclose,   /* optional */
+       .d_label = foo_label,           /* optional */
 };
 .Ed
 .Pp
@@ -519,7 +540,8 @@
 .Sh SEE ALSO
 .Xr ccd 4 ,
 .Xr dm 4 ,
-.Xr vnd 4
+.Xr vnd 4 ,
+.Xr dksubr 4
 .Sh HISTORY
 The
 .Nx
diff -r acc293cfdead -r b4764d6bdf2c share/man/man9/dksubr.9
--- a/share/man/man9/dksubr.9   Sat Dec 10 09:44:06 2016 +0000
+++ b/share/man/man9/dksubr.9   Sat Dec 10 09:49:00 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: dksubr.9,v 1.2 2016/11/28 11:54:18 wiz Exp $
+.\"    $NetBSD: dksubr.9,v 1.3 2016/12/10 09:49:00 mlelstv Exp $
 .\"
 .\" Copyright (c) 2016 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -218,6 +218,12 @@
 .Nm dk_start .
 .It Fn dk_getdefaultlabel
 Compute a common default disklabel for all disk drivers.
+Some drivers provide device specific information or assign specific
+disk formats to partitions. Such drivers may implement the
+.Nm d_label
+callback that is called by
+.Nm dk_getdefaultlabel
+after initializing the label with common values.
 .It Fn dk_getdisklabel
 Read disklabel with machine dependent low-level function
 .Nm readdisklabel
@@ -240,13 +246,20 @@
         int     (*d_lastclose)(device_t);
         int     (*d_discard)(device_t, off_t, off_t);
         int     (*d_firstopen)(device_t, dev_t, int, int);
+        void    (*d_label)(device_t, struct disklabel *);
 };
 .Ed
 .Bl -tag -width ".Fn dk_firstopen"
 .It Fn d_strategy
-The driver strategy routine.
+The driver strategy routine queues a single buffer for I/O
+and starts queue processing as appropriate.
 .It Fn d_minphys
-The driver minphys routine.
+The driver minphys routine limits the buffer
+.Nm b_bcount
+to the maximum size for an I/O transfer supported by the driver
+and hardware. It also calls
+.Nm minphys
+to apply the platform limit.
 .It Fn d_open
 The driver open routine.
 .It Fn d_close
@@ -255,7 +268,9 @@
 Issues a single I/O request, called by
 .Nm dk_start .
 .It Fn d_iosize
-Truncate I/O size to the driver limit.
+Truncate I/O size to the driver limit. This is similar to
+.Nm minphys
+but operates on an integer value instead of a buffer.
 .It Fn d_dumpblocks
 Issue a single I/O requests, called by
 .Nm dk_dump .
@@ -267,6 +282,7 @@
 .It Fn d_firstopen
 Private initialization when first user opens the driver.
 .Sh SEE ALSO
+.Xr driver 9 ,
 .Xr disk 9 ,
 .Xr cprng 9 ,
 .Xr ld 4 ,