1.\" $NetBSD: disk.9,v 1.18 2002/10/14 13:43:21 wiz 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. 110This list, called 111.Nm disklist , 112may grow or shrink over time as disks are dynamically added and removed 113from the system. 114Drivers which currently make use of the detachment 115capability of the framework are the 116.Nm ccd 117and 118.Nm vnd 119pseudo-device drivers. 120.Pp 121The following is a brief description of each function in the framework: 122.Bl -tag -width "disk_resetstat()" 123.It Fn disk_init 124Initialize the disklist and other data structures used by the framework. 125Called by 126.Fn main 127before autoconfiguration. 128.It Fn disk_attach 129Attach a disk; allocate storage for the disklabel, set the 130.Dq attached time 131timestamp, insert the disk into the disklist, and increment the 132system disk count. 133.It Fn disk_detach 134Detach a disk; free storage for the disklabel, remove the disk 135from the disklist, and decrement the system disk count. 136If the count drops below zero, panic. 137.It Fn disk_busy 138Increment the disk's 139.Dq busy counter . 140If this counter goes from 0 to 1, set the timestamp corresponding to 141this transfer. 142.It Fn disk_unbusy 143Decrement a disk's busy counter. 144If the count drops below zero, panic. 145Get the current time, subtract it from the disk's timestamp, and add 146the difference to the disk's running total. 147Set the disk's timestamp to the current time. 148If the provided byte count is greater than 0, add it to the disk's 149running total and increment the number of transfers performed by the disk. 150.It Fn disk_resetstat 151Reset the running byte, transfer, and time totals. 152.It Fn disk_find 153Return a pointer to the disk structure corresponding to the name provided, 154or NULL if the disk does not exist. 155.El 156.Pp 157The functions typically called by device drivers are 158.Fn disk_attach , 159.Fn disk_detach , 160.Fn disk_busy , 161.Fn disk_unbusy , 162and 163.Fn disk_resetstat . 164The function 165.Fn disk_find 166is provided as a utility function. 167.Sh USING THE FRAMEWORK 168This section includes a description on basic use of the framework 169and example usage of its functions. 170Actual implementation of a device driver which utilizes the framework 171may vary. 172.Pp 173A special routine, 174.Fn disk_init , 175is provided to perform basic initialization of data structures used by 176the framework. 177It is called exactly once by the system, in 178.Fn main , 179before device autoconfiguration. 180.Pp 181Each device in the system uses a 182.Dq softc 183structure which contains autoconfiguration and state information for that 184device. 185In the case of disks, the softc should also contain one instance 186of the disk structure, e.g.: 187.Bd -literal 188struct foo_softc { 189 struct device sc_dev; /* generic device information */ 190 struct disk sc_dk; /* generic disk information */ 191 [ . . . more . . . ] 192}; 193.Ed 194.Pp 195In order for the system to gather metrics data about a disk, the disk must 196be registered with the system. 197The 198.Fn disk_attach 199routine performs all of the functions currently required to register a disk 200with the system including allocation of disklabel storage space, 201recording of the time since boot that the disk was attached, and insertion 202into the disklist. 203Note that since this function allocates storage space for the disklabel, 204it must be called before the disklabel is read from the media or used in 205any other way. 206Before 207.Fn disk_attach 208is called, a portions of the disk structure must be initialized with 209data specific to that disk. 210For example, in the 211.Dq foo 212disk driver, the following would be performed in the autoconfiguration 213.Dq attach 214routine: 215.Bd -literal 216void 217fooattach(parent, self, aux) 218 struct device *parent, *self; 219 void *aux; 220{ 221 struct foo_softc *sc = (struct foo_softc *)self; 222 [ . . . ] 223 224 /* Initialize and attach the disk structure. */ 225 sc-\*[Gt]sc_dk.dk_driver = \*[Am]foodkdriver; 226 sc-\*[Gt]sc_dk.dk_name = sc-\*[Gt]sc_dev.dv_xname; 227 disk_attach(\*[Am]sc-\*[Gt]sc_dk); 228 229 /* Read geometry and fill in pertinent parts of disklabel. */ 230 [ . . . ] 231} 232.Ed 233.Pp 234The 235.Nm foodkdriver 236above is the disk's 237.Dq driver 238switch. 239This switch currently includes a pointer to the disk's 240.Dq strategy 241routine. 242This switch needs to have global scope and should be initialized as follows: 243.Bd -literal 244void foostrategy(struct buf *); 245struct dkdriver foodkdriver = { foostrategy }; 246.Ed 247.Pp 248Once the disk is attached, metrics may be gathered on that disk. 249In order to gather metrics data, the driver must tell the framework when 250the disk starts and stops operations. 251This functionality is provided by the 252.Fn disk_busy 253and 254.Fn disk_unbusy 255routines. 256The 257.Fn disk_busy 258routine should be called immediately before a command to the disk is 259sent, e.g.: 260.Bd -literal 261void 262foostart(sc) 263 struct foo_softc *sc; 264{ 265 [ . . . ] 266 267 /* Get buffer from drive's transfer queue. */ 268 [ . . . ] 269 270 /* Build command to send to drive. */ 271 [ . . . ] 272 273 /* Tell the disk framework we're going busy. */ 274 disk_busy(\*[Am]sc-\*[Gt]sc_dk); 275 276 /* Send command to the drive. */ 277 [ . . . ] 278} 279.Ed 280.Pp 281When 282.Fn disk_busy 283is called, a timestamp is taken if the disk's busy counter moves from 2840 to 1, indicating the disk has gone from an idle to non-idle state. 285Note that 286.Fn disk_busy 287must be called at 288.Fn splbio . 289At the end of a transaction, the 290.Fn disk_unbusy 291routine should be called. 292This routine performs some consistency checks, 293such as ensuring that the calls to 294.Fn disk_busy 295and 296.Fn disk_unbusy 297are balanced. 298This routine also performs the actual metrics calculation. 299A timestamp is taken, and the difference from the timestamp taken in 300.Fn disk_busy 301is added to the disk's total running time. 302The disk's timestamp is then updated in case there is more than one 303pending transfer on the disk. 304A byte count is also added to the disk's running total, and if greater than 305zero, the number of transfers the disk has performed is incremented. 306.Bd -literal 307void 308foodone(xfer) 309 struct foo_xfer *xfer; 310{ 311 struct foo_softc = (struct foo_softc *)xfer-\*[Gt]xf_softc; 312 struct buf *bp = xfer-\*[Gt]xf_buf; 313 long nbytes; 314 [ . . . ] 315 316 /* 317 * Get number of bytes transfered. If there is no buf 318 * associated with the xfer, we are being called at the 319 * end of a non-I/O command. 320 */ 321 if (bp == NULL) 322 nbytes = 0; 323 else 324 nbytes = bp-\*[Gt]b_bcount - bp-\*[Gt]b_resid; 325 326 [ . . . ] 327 328 /* Notify the disk framework that we've completed the transfer. */ 329 disk_unbusy(\*[Am]sc-\*[Gt]sc_dk, nbytes); 330 331 [ . . . ] 332} 333.Ed 334.Pp 335Like 336.Fn disk_busy , 337.Fn disk_unbusy 338must be called at 339.Fn splbio . 340.Pp 341At some point a driver may wish to reset the metrics data gathered on a 342particular disk. 343For this function, the 344.Fn disk_resetstat 345routine is provided. 346.Sh CODE REFERENCES 347This section describes places within the 348.Nx 349source tree where actual 350code implementing or utilizing the disk framework can be found. 351All pathnames are relative to 352.Pa /usr/src . 353.Pp 354The disk framework itself is implemented within the file 355.Pa sys/kern/subr_disk.c . 356Data structures and function prototypes for the framework are located in 357.Pa sys/sys/disk.h . 358.Pp 359The 360.Nx 361machine-independent SCSI disk and CD-ROM drivers utilize the 362disk framework. 363They are located in 364.Pa sys/scsi/sd.c 365and 366.Pa sys/scsi/cd.c . 367.Pp 368The 369.Nx 370.Nm ccd 371and 372.Nm vnd 373drivers utilize the detachment capability of the framework. 374They are located in 375.Pa sys/dev/ccd.c 376and 377.Pa sys/dev/vnd.c . 378.Sh SEE ALSO 379.Xr ccd 4 , 380.Xr vnd 4 , 381.Xr spl 9 382.Sh HISTORY 383The 384.Nx 385generic disk framework appeared in 386.Nx 1.2 . 387.Sh AUTHORS 388The 389.Nx 390generic disk framework was architected and implemented by 391Jason R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt]. 392