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