1.\" $OpenBSD: disk.9,v 1.34 2015/11/23 17:53:57 jmc Exp $ 2.\" $NetBSD: disk.9,v 1.2 1996/04/08 20:41:25 jtc Exp $ 3.\" 4.\" Copyright (c) 1995, 1996 Jason R. Thorpe. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Jason R. Thorpe. 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: November 23 2015 $ 35.Dt DISK_INIT 9 36.Os 37.Sh NAME 38.Nm disk_init , 39.Nm disk_attach , 40.Nm disk_detach , 41.Nm disk_busy , 42.Nm disk_unbusy 43.Nd generic disk framework 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/disklabel.h 47.In sys/disk.h 48.Ft void 49.Fn disk_init "void" 50.Ft void 51.Fn disk_attach "struct disk *" 52.Ft void 53.Fn disk_detach "struct disk *" 54.Ft void 55.Fn disk_busy "struct disk *" 56.Ft void 57.Fn disk_unbusy "struct disk *" "long bcount" "int read" 58.Sh DESCRIPTION 59The 60.Ox 61generic disk framework is designed to provide flexible, 62scalable, and consistent handling of disk state and metrics information. 63The fundamental component of this framework is the 64.Nm 65structure, which is defined as follows: 66.Bd -literal 67struct disk { 68 TAILQ_ENTRY(disk) dk_link; /* link in global disklist */ 69 struct rwlock dk_lock; /* disk lock */ 70 struct mutex dk_mtx; /* busy/unbusy mtx */ 71 char *dk_name; /* disk name */ 72 struct device *dk_device; /* disk device structure. */ 73 dev_t dk_devno; /* disk device number. */ 74 int dk_flags; /* disk flags */ 75#define DKF_CONSTRUCTED 0x0001 76#define DKF_OPENED 0x0002 77#define DKF_NOLABELREAD 0x0004 78 79 /* 80 * Metrics data; note that some metrics may have no meaning 81 * on certain types of disks. 82 */ 83 int dk_busy; /* busy counter */ 84 u_int64_t dk_rxfer; /* total number of read transfers */ 85 u_int64_t dk_wxfer; /* total number of write transfers */ 86 u_int64_t dk_seek; /* total independent seek operations */ 87 u_int64_t dk_rbytes; /* total bytes read */ 88 u_int64_t dk_wbytes; /* total bytes written */ 89 struct timeval dk_attachtime; /* time disk was attached */ 90 struct timeval dk_timestamp; /*time of first busy or any unbusy*/ 91 struct timeval dk_time; /* total time spent busy */ 92 93 int dk_bopenmask; /* block devices open */ 94 int dk_copenmask; /* character devices open */ 95 int dk_openmask; /* composite (bopen|copen) */ 96 int dk_state; /* label state ### */ 97 int dk_blkshift; /*shift to convert DEV_BSIZE to blks*/ 98 int dk_byteshift; /* shift to convert bytes to blks */ 99 100 /* 101 * Disk label information. Storage for the in-core disk label 102 * must be dynamically allocated, otherwise the size of this 103 * structure becomes machine-dependent. 104 */ 105 struct disklabel *dk_label; 106}; 107.Ed 108.Pp 109The system maintains a global linked-list of all disks attached to the 110system. 111This list, called 112.Nm disklist , 113may grow or shrink over time as disks are dynamically added and removed 114from the system. 115An example of a driver which currently makes use of the detachment 116capability of the framework is the 117.Xr vnd 4 118pseudo-device driver. 119.Pp 120The following is a brief description of each function in the framework: 121.Bl -tag -width "disk_unbusy()" 122.It Fn disk_init 123Initialize the disklist and other data structures used by the framework. 124Called by 125.Fn main 126before autoconfiguration. 127.It Fn disk_attach 128Attach a disk; allocate storage for the disklabel, set the 129.Dq attached time 130timestamp, insert the disk into the disklist, and increment the 131system disk count. 132.It Fn disk_detach 133Detach a disk; free storage for the disklabel, remove the disk 134from the disklist, and decrement the system disk count. 135If the count drops below zero, panic. 136.It Fn disk_busy 137Increment the disk's 138.Dq busy counter . 139If this counter goes from 0 to 1, set the timestamp corresponding to 140this transfer. 141.It Fn disk_unbusy 142Decrement a disk's busy counter. 143If the count drops below zero, print a warning message. 144Get the current time, subtract it from the disk's timestamp, and add 145the difference to the disk's running total. 146Set the disk's timestamp to the current time. 147If the provided byte count is greater than 0, 148add it to the disk's running total and increment the number of transfers 149performed by the disk. 150The third argument 151.Ar read 152specifies the direction of I/O; 153if non-zero it means reading from the disk, 154otherwise it means writing to the disk. 155.El 156.Pp 157The functions typically called by device drivers are 158.Fn disk_attach , 159.Fn disk_detach , 160.Fn disk_busy 161and 162.Fn disk_unbusy . 163.Sh USING THE FRAMEWORK 164This section includes a description on basic use of the framework 165and example usage of its functions. 166Actual implementation of 167a device driver which utilizes the framework may vary. 168.Pp 169A special routine, 170.Fn disk_init , 171is provided to perform basic initialization of data structures used by 172the framework. 173It is called exactly once by the system, in 174.Fn main , 175before device autoconfiguration. 176.Pp 177Each device in the system uses a 178.Dq softc 179structure which contains autoconfiguration and state information for that 180device. 181In the case of disks, the softc should also contain one instance 182of the disk structure, e.g.: 183.Bd -literal 184struct foo_softc { 185 struct device *sc_dev; /* generic device information */ 186 struct disk *sc_dk; /* generic disk information */ 187 [ . . . more . . . ] 188}; 189.Ed 190.Pp 191In order for the system to gather metrics data about a disk, the disk must 192be registered with the system. 193The 194.Fn disk_attach 195routine performs all of the functions currently required to register a disk 196with the system including allocation of disklabel storage space, 197recording of the time since boot that the disk was attached, and insertion 198into the disklist. 199Note that since this function allocates storage space 200for the disklabel, it must be called before the disklabel is read from the 201media or used in any other way. 202Before 203.Fn disk_attach 204is called, a portion of the disk structure must be initialized with 205data specific to that disk. 206For example, in the 207.Dq foo 208disk driver, the following would be performed in the autoconfiguration 209.Dq attach 210routine: 211.Bd -literal 212void 213fooattach(parent, self, aux) 214 struct device *parent, *self; 215 void *aux; 216{ 217 struct foo_softc *sc = (struct foo_softc *)self; 218 [ . . . ] 219 220 /* Initialize and attach the disk structure. */ 221 sc->sc_dk.dk_driver = &foodkdriver; 222 sc->sc_dk.dk_name = sc->sc_dev.dv_xname; 223 disk_attach(&sc->sc_dk); 224 225 /* Read geometry and fill in pertinent parts of disklabel. */ 226 [ . . . ] 227} 228.Ed 229.Pp 230The 231.Nm foodkdriver 232above is the disk's 233.Dq driver 234switch. 235This switch currently includes a pointer to the disk's 236.Dq strategy 237routine. 238This switch needs to have global scope and should be initialized as follows: 239.Bd -literal 240void foostrategy(struct buf *); 241struct dkdriver foodkdriver = { foostrategy }; 242.Ed 243.Pp 244Once the disk is attached, metrics may be gathered on that disk. 245In order to gather metrics data, the driver must tell the framework 246when the disk starts and stops operations. 247This functionality is provided by the 248.Fn disk_busy 249and 250.Fn disk_unbusy 251routines. 252The 253.Fn disk_busy 254routine should be called immediately before a command to the disk is 255sent, e.g.: 256.Bd -literal 257void 258foostart(sc) 259 struct foo_softc *sc; 260{ 261 [ . . . ] 262 263 /* Get buffer from drive's transfer queue. */ 264 [ . . . ] 265 266 /* Build command to send to drive. */ 267 [ . . . ] 268 269 /* Tell the disk framework we're going busy. */ 270 disk_busy(&sc->sc_dk); 271 272 /* Send command to the drive. */ 273 [ . . . ] 274} 275.Ed 276.Pp 277When 278.Fn disk_busy 279is called, a timestamp is taken if the disk's busy counter moves from 2800 to 1, indicating the disk has gone from an idle to non-idle state. 281Note that 282.Fn disk_busy 283must be called at 284.Fn splbio . 285At the end of a transaction, the 286.Fn disk_unbusy 287routine should be called. 288This routine performs some consistency checks, 289such as ensuring that the calls to 290.Fn disk_busy 291and 292.Fn disk_unbusy 293are balanced. 294This routine also performs the actual metrics calculation. 295A timestamp is taken, and the difference from the timestamp taken in 296.Fn disk_busy 297is added to the disk's total running time. 298The disk's timestamp is then 299updated in case there is more than one pending transfer on the disk. 300A byte count is also added to the disk's running total, and if greater than 301zero, the number of transfers the disk has performed is incremented. 302.Bd -literal 303void 304foodone(xfer) 305 struct foo_xfer *xfer; 306{ 307 struct foo_softc = (struct foo_softc *)xfer->xf_softc; 308 struct buf *bp = xfer->xf_buf; 309 long nbytes; 310 [ . . . ] 311 312 /* 313 * Get number of bytes transferred. If there is no buf 314 * associated with the xfer, we are being called at the 315 * end of a non-I/O command. 316 */ 317 if (bp == NULL) 318 nbytes = 0; 319 else 320 nbytes = bp->b_bcount - bp->b_resid; 321 322 [ . . . ] 323 324 /* Notify the disk framework that we've completed the transfer. */ 325 disk_unbusy(&sc->sc_dk, nbytes); 326 327 [ . . . ] 328} 329.Ed 330.Pp 331Like 332.Fn disk_busy , 333.Fn disk_unbusy 334must be called at 335.Fn splbio . 336.Sh CODE REFERENCES 337The disk framework itself is implemented within the file 338.Pa sys/kern/subr_disk.c . 339Data structures and function prototypes for the framework are located in 340.Pa sys/sys/disk.h . 341.Pp 342The 343.Ox 344machine-independent SCSI disk and CD-ROM drivers utilize the disk framework. 345They are located in 346.Pa sys/scsi/sd.c 347and 348.Pa sys/scsi/cd.c . 349.Pp 350The 351.Ox 352.Xr vnd 4 353driver utilizes the detachment capability of the framework. 354This is located in 355.Pa sys/dev/vnd.c . 356.Sh SEE ALSO 357.Xr vnd 4 , 358.Xr spl 9 359.Sh HISTORY 360The 361.Ox 362generic disk framework first appeared in 363.Nx 1.2 . 364.Sh AUTHORS 365The 366.Ox 367generic disk framework was architected and implemented within 368.Nx 369by 370.An Jason R. Thorpe Aq Mt thorpej@NetBSD.ORG . 371