1.\" $NetBSD: disk.9,v 1.19 2002/11/06 03:55:01 enami 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 *" "long bcount" "int read" 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_rxfer; /* total number of read transfers */ 89 u_int64_t dk_wxfer; /* total number of write transfers */ 90 u_int64_t dk_seek; /* total independent seek operations */ 91 u_int64_t dk_rbytes; /* total bytes read */ 92 u_int64_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_init 126Initialize the disklist and other data structures used by the framework. 127Called by 128.Fn main 129before autoconfiguration. 130.It Fn disk_attach 131Attach a disk; allocate storage for the disklabel, set the 132.Dq attached time 133timestamp, insert the disk into the disklist, and increment the 134system disk count. 135.It Fn disk_detach 136Detach a disk; free storage for the disklabel, remove the disk 137from the disklist, and decrement the system disk count. 138If the count drops below zero, panic. 139.It Fn disk_busy 140Increment the disk's 141.Dq busy counter . 142If this counter goes from 0 to 1, set the timestamp corresponding to 143this transfer. 144.It Fn disk_unbusy 145Decrement a disk's busy counter. 146If the count drops below zero, panic. 147Get the current time, subtract it from the disk's timestamp, and add 148the difference to the disk's running total. 149Set the disk's timestamp to the current time. 150If the provided byte count is greater than 0, add it to the disk's 151running total and increment the number of transfers performed by the disk. 152The third argument 153.Ar read 154specifies the direction of I/O; 155if non-zero it means reading from the disk, 156otherwise it means writing to the disk. 157.It Fn disk_resetstat 158Reset the running byte, transfer, and time totals. 159.It Fn disk_find 160Return a pointer to the disk structure corresponding to the name provided, 161or NULL if the disk does not exist. 162.El 163.Pp 164The functions typically called by device drivers are 165.Fn disk_attach , 166.Fn disk_detach , 167.Fn disk_busy , 168.Fn disk_unbusy , 169and 170.Fn disk_resetstat . 171The function 172.Fn disk_find 173is provided as a utility function. 174.Sh USING THE FRAMEWORK 175This section includes a description on basic use of the framework 176and example usage of its functions. 177Actual implementation of a device driver which utilizes the framework 178may vary. 179.Pp 180A special routine, 181.Fn disk_init , 182is provided to perform basic initialization of data structures used by 183the framework. 184It is called exactly once by the system, in 185.Fn main , 186before device autoconfiguration. 187.Pp 188Each device in the system uses a 189.Dq softc 190structure which contains autoconfiguration and state information for that 191device. 192In the case of disks, the softc should also contain one instance 193of the disk structure, e.g.: 194.Bd -literal 195struct foo_softc { 196 struct device sc_dev; /* generic device information */ 197 struct disk sc_dk; /* generic disk information */ 198 [ . . . more . . . ] 199}; 200.Ed 201.Pp 202In order for the system to gather metrics data about a disk, the disk must 203be registered with the system. 204The 205.Fn disk_attach 206routine performs all of the functions currently required to register a disk 207with the system including allocation of disklabel storage space, 208recording of the time since boot that the disk was attached, and insertion 209into the disklist. 210Note that since this function allocates storage space for the disklabel, 211it must be called before the disklabel is read from the media or used in 212any other way. 213Before 214.Fn disk_attach 215is called, a portions of the disk structure must be initialized with 216data specific to that disk. 217For example, in the 218.Dq foo 219disk driver, the following would be performed in the autoconfiguration 220.Dq attach 221routine: 222.Bd -literal 223void 224fooattach(parent, self, aux) 225 struct device *parent, *self; 226 void *aux; 227{ 228 struct foo_softc *sc = (struct foo_softc *)self; 229 [ . . . ] 230 231 /* Initialize and attach the disk structure. */ 232 sc-\*[Gt]sc_dk.dk_driver = \*[Am]foodkdriver; 233 sc-\*[Gt]sc_dk.dk_name = sc-\*[Gt]sc_dev.dv_xname; 234 disk_attach(\*[Am]sc-\*[Gt]sc_dk); 235 236 /* Read geometry and fill in pertinent parts of disklabel. */ 237 [ . . . ] 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 utilizing 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 utilize 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 utilize 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 404Jason R. Thorpe \*[Lt]thorpej@NetBSD.ORG\*[Gt]. 405