1.\" $NetBSD: disk.9,v 1.17 2002/02/13 08:18:40 ross 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 January 7, 1996 34.Dt DISK 9 35.Os 36.Sh NAME 37.Nm disk , 38.Nm disk_init , 39.Nm disk_attach , 40.Nm disk_detach , 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 \*[Lt]sys/types.h\*[Gt] 48.Fd #include \*[Lt]sys/disklabel.h\*[Gt] 49.Fd #include \*[Lt]sys/disk.h\*[Gt] 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 66.Nx 67generic disk framework is designed to provide flexible, 68scalable, and consistent handling of disk state and metrics information. 69The fundamental component of this framework is the 70.Nm disk 71structure, which is defined as follows: 72.Bd -literal 73struct disk { 74 TAILQ_ENTRY(disk) dk_link; /* link in global disklist */ 75 char *dk_name; /* disk name */ 76 int dk_bopenmask; /* block devices open */ 77 int dk_copenmask; /* character devices open */ 78 int dk_openmask; /* composite (bopen|copen) */ 79 int dk_state; /* label state */ 80 int dk_blkshift; /* shift to convert DEV_BSIZE to blks */ 81 int dk_byteshift; /* shift to convert bytes to blks */ 82 83 /* 84 * Metrics data; note that some metrics may have no meaning 85 * on certain types of disks. 86 */ 87 int dk_busy; /* busy counter */ 88 u_int64_t dk_xfer; /* total number of transfers */ 89 u_int64_t dk_seek; /* total independent seek operations */ 90 u_int64_t dk_bytes; /* total bytes transfered */ 91 struct timeval dk_attachtime; /* time disk was attached */ 92 struct timeval dk_timestamp; /* timestamp of last unbusy */ 93 struct timeval dk_time; /* total time spent busy */ 94 95 struct dkdriver *dk_driver; /* pointer to driver */ 96 97 /* 98 * Disk label information. Storage for the in-core disk label 99 * must be dynamically allocated, otherwise the size of this 100 * structure becomes machine-dependent. 101 */ 102 daddr_t dk_labelsector; /* sector containing label */ 103 struct disklabel *dk_label; /* label */ 104 struct cpu_disklabel *dk_cpulabel; 105}; 106.Ed 107.Pp 108The system maintains a global linked-list of all disks attached to the 109system. This list, called 110.Nm disklist , 111may grow or shrink over time as disks are dynamically added and removed 112from the system. Drivers which currently make use of the detachment 113capability of the framework are the 114.Nm ccd 115and 116.Nm vnd 117pseudo-device drivers. 118.Pp 119The following is a brief description of each function in the framework: 120.Bl -tag -width "disk_resetstat()" 121.It Fn disk_init 122Initialize the disklist and other data structures used by the framework. 123Called by 124.Fn main 125before autoconfiguration. 126.It Fn disk_attach 127Attach a disk; allocate storage for the disklabel, set the 128.Dq attached time 129timestamp, insert the disk into the disklist, and increment the 130system disk count. 131.It Fn disk_detach 132Detach a disk; free storage for the disklabel, remove the disk 133from the disklist, and decrement the system disk count. If the count 134drops below zero, panic. 135.It Fn disk_busy 136Increment the disk's 137.Dq busy counter . 138If this counter goes from 0 to 1, set the timestamp corresponding to 139this transfer. 140.It Fn disk_unbusy 141Decrement a disk's busy counter. If the count drops below zero, panic. 142Get the current time, subtract it from the disk's timestamp, and add 143the difference to the disk's running total. Set the disk's timestamp 144to the current time. If the provided byte count is greater than 0, 145add it to the disk's running total and increment the number of transfers 146performed by the disk. 147.It Fn disk_resetstat 148Reset the running byte, transfer, and time totals. 149.It Fn disk_find 150Return a pointer to the disk structure corresponding to the name provided, 151or NULL if the disk does not exist. 152.El 153.Pp 154The functions typically called by device drivers are 155.Fn disk_attach , 156.Fn disk_detach , 157.Fn disk_busy , 158.Fn disk_unbusy , 159and 160.Fn disk_resetstat . 161The function 162.Fn disk_find 163is provided as a utility function. 164.Sh USING THE FRAMEWORK 165This section includes a description on basic use of the framework 166and example usage of its functions. Actual 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. It is called exactly once by the system, in 173.Fn main , 174before device autoconfiguration. 175.Pp 176Each device in the system uses a 177.Dq softc 178structure which contains autoconfiguration and state information for that 179device. In the case of disks, the softc should also contain one instance 180of the disk structure, e.g.: 181.Bd -literal 182struct foo_softc { 183 struct device sc_dev; /* generic device information */ 184 struct disk sc_dk; /* generic disk information */ 185 [ . . . more . . . ] 186}; 187.Ed 188.Pp 189In order for the system to gather metrics data about a disk, the disk must 190be registered with the system. The 191.Fn disk_attach 192routine performs all of the functions currently required to register a disk 193with the system including allocation of disklabel storage space, 194recording of the time since boot that the disk was attached, and insertion 195into the disklist. Note that since this function allocates storage space 196for the disklabel, it must be called before the disklabel is read from the 197media or used in any other way. Before 198.Fn disk_attach 199is called, a portions of the disk structure must be initialized with 200data specific to that disk. For example, in the 201.Dq foo 202disk driver, the following would be performed in the autoconfiguration 203.Dq attach 204routine: 205.Bd -literal 206void 207fooattach(parent, self, aux) 208 struct device *parent, *self; 209 void *aux; 210{ 211 struct foo_softc *sc = (struct foo_softc *)self; 212 [ . . . ] 213 214 /* Initialize and attach the disk structure. */ 215 sc-\*[Gt]sc_dk.dk_driver = \*[Am]foodkdriver; 216 sc-\*[Gt]sc_dk.dk_name = sc-\*[Gt]sc_dev.dv_xname; 217 disk_attach(\*[Am]sc-\*[Gt]sc_dk); 218 219 /* Read geometry and fill in pertinent parts of disklabel. */ 220 [ . . . ] 221} 222.Ed 223.Pp 224The 225.Nm foodkdriver 226above is the disk's 227.Dq driver 228switch. This switch currently includes a pointer to the disk's 229.Dq strategy 230routine. This switch needs to have global scope and should be initialized 231as follows: 232.Bd -literal 233void foostrategy(struct buf *); 234struct dkdriver foodkdriver = { foostrategy }; 235.Ed 236.Pp 237Once the disk is attached, metrics may be gathered on that disk. In order 238to gather metrics data, the driver must tell the framework when the disk 239starts and stops operations. This functionality is provided by the 240.Fn disk_busy 241and 242.Fn disk_unbusy 243routines. The 244.Fn disk_busy 245routine should be called immediately before a command to the disk is 246sent, e.g.: 247.Bd -literal 248void 249foostart(sc) 250 struct foo_softc *sc; 251{ 252 [ . . . ] 253 254 /* Get buffer from drive's transfer queue. */ 255 [ . . . ] 256 257 /* Build command to send to drive. */ 258 [ . . . ] 259 260 /* Tell the disk framework we're going busy. */ 261 disk_busy(\*[Am]sc-\*[Gt]sc_dk); 262 263 /* Send command to the drive. */ 264 [ . . . ] 265} 266.Ed 267.Pp 268When 269.Fn disk_busy 270is called, a timestamp is taken if the disk's busy counter moves from 2710 to 1, indicating the disk has gone from an idle to non-idle state. 272Note that 273.Fn disk_busy 274must be called at 275.Fn splbio . 276At the end of a transaction, the 277.Fn disk_unbusy 278routine should be called. This routine performs some consistency checks, 279such as ensuring that the calls to 280.Fn disk_busy 281and 282.Fn disk_unbusy 283are balanced. This routine also performs the actual metrics calculation. 284A timestamp is taken, and the difference from the timestamp taken in 285.Fn disk_busy 286is added to the disk's total running time. The disk's timestamp is then 287updated in case there is more than one pending transfer on the disk. 288A byte count is also added to the disk's running total, and if greater than 289zero, the number of transfers the disk has performed is incremented. 290.Bd -literal 291void 292foodone(xfer) 293 struct foo_xfer *xfer; 294{ 295 struct foo_softc = (struct foo_softc *)xfer-\*[Gt]xf_softc; 296 struct buf *bp = xfer-\*[Gt]xf_buf; 297 long nbytes; 298 [ . . . ] 299 300 /* 301 * Get number of bytes transfered. If there is no buf 302 * associated with the xfer, we are being called at the 303 * end of a non-I/O command. 304 */ 305 if (bp == NULL) 306 nbytes = 0; 307 else 308 nbytes = bp-\*[Gt]b_bcount - bp-\*[Gt]b_resid; 309 310 [ . . . ] 311 312 /* Notify the disk framework that we've completed the transfer. */ 313 disk_unbusy(\*[Am]sc-\*[Gt]sc_dk, nbytes); 314 315 [ . . . ] 316} 317.Ed 318.Pp 319Like 320.Fn disk_busy , 321.Fn disk_unbusy 322must be called at 323.Fn splbio . 324.Pp 325At some point a driver may wish to reset the metrics data gathered on a 326particular disk. For this function, the 327.Fn disk_resetstat 328routine is provided. 329.Sh CODE REFERENCES 330This section describes places within the 331.Nx 332source tree where actual 333code implementing or utilizing the disk framework can be found. All 334pathnames are relative to 335.Pa /usr/src . 336.Pp 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.Nx 344machine-independent SCSI disk and CD-ROM drivers utilize the 345disk framework. They are located in 346.Pa sys/scsi/sd.c 347and 348.Pa sys/scsi/cd.c . 349.Pp 350The 351.Nx 352.Nm ccd 353and 354.Nm vnd 355drivers utilize the detachment capability of the framework. 356They are located in 357.Pa sys/dev/ccd.c 358and 359.Pa sys/dev/vnd.c . 360.Sh SEE ALSO 361.Xr ccd 4 , 362.Xr vnd 4 , 363.Xr spl 9 364.Sh HISTORY 365The 366.Nx 367generic disk framework appeared in 368.Nx 1.2 . 369.Sh AUTHORS 370The 371.Nx 372generic disk framework was architected and implemented by 373Jason R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt]. 374