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