1.\" 2.\" Copyright (c) 2003 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd September 26, 2003 31.Dt DISK 9 32.Os 33.Sh NAME 34.Nm disk 35.Nd Kernel disk storage API 36.Sh SYNOPSIS 37.In geom/geom_disk.h 38.Ft void 39.Fo disk_create 40.Fa "int unit" 41.Fa "struct disk *disk" 42.Fa "int flags" 43.Fa "void *unused" 44.Fa "void *unused2" 45.Fc 46.Ft void 47.Fn disk_destroy "struct disk *disk" 48.Sh DESCRIPTION 49The disk storage API permits kernel device drivers providing access to 50disk-like storage devices to advertise the device to other kernel 51components, including 52.Xr GEOM 4 , 53and 54.Xr devfs 5 . 55.Pp 56Each disk device is described by a 57.Vt "struct disk" 58structure, which contains a variety of parameters for the disk device, 59function pointers for various methods that may be performed on the device, 60as well as private data storage for the device driver. 61In addition, some fields are reserved for use by GEOM in managing access 62to the device and its statistics. 63Because of storage driver framework private data stored in 64.Vt "struct disk" , 65instances of the structure should be allocated out of writable, pre-zero'd 66memory. 67.Pp 68Public fields in the structure will generally be assumed not to change once 69the structure is submitted to 70.Fn disk_create , 71and so no explicit locking is employed; drivers that change the values of 72any of these fields do so at their own risk. 73.Pp 74Memory associated with the 75.Vt "struct disk" 76is owned by the device driver, but should not be released until after 77the completion of a call to 78.Fn disk_destroy . 79.Ss Descriptive Fields 80.Pp 81The following fields identify the disk device described by the structure 82instance, and must be filled in prior to submitting the structure to 83.Fn disk_create : 84.Bl -tag -width XXX 85.It Vt u_int Va d_flags 86Optional flags indicating to the storage framework what optional features 87or descriptions the storage device driver supports. 88Currently supported flags are 89.Dv DISKFLAG_NOGIANT 90(maintained by device driver), 91.Dv DISKFLAG_OPEN 92(maintained by storage framework), 93and 94.Dv DISKFLAG_CANDELETE 95(maintained by device driver). 96.Pp 97.It Vt "const char *" Va d_name 98Holds the name of the storage device class, e.g., 99.Dq ahd . 100This value typically uniquely identifies a particular driver device, 101and must not conflict with devices serviced by other device drivers. 102.It Vt u_int Va d_unit 103Holds the instance of the storage device class, e.g., 104.Dq 4 . 105This namespace is managed by the device driver, and assignment of unit 106numbers might be a property of probe order, or in some cases topology. 107Together, the 108.Va d_name 109and 110.Va d_unit 111values will uniquely identify a disk storage device. 112.El 113.Ss Disk Device Methods 114The following fields identify various disk device methods, if implemented: 115.Bl -tag -width XXX 116.It Vt "disk_open_t *" Va d_open 117Invoked when the disk device is opened. 118.It Vt "disk_close_t *" Va d_close 119Invoked when the disk device is closed. 120.It Vt "disk_strategy_t *" Va d_strategy 121Invoked when a new 122.Vt struct bio 123is to be initiated on the disk device. 124.It Vt "disk_ioctl_t *" Va d_ioctl 125Invoked when a I/O control operation is initiated on the disk device. 126.It Vt "dumper_t *" Va d_dump 127Invoked when a kernel crash dump is performed on the disk device. 128.El 129.Ss Media Properties 130The following fields identify the size, layout, and other media properties 131of the disk device. 132.Bl -tag -width XXX 133.It Vt u_int Va d_sectorsize 134The sectorsize of the disk device. 135.It Vt off_t Va d_mediasize 136The size of the disk device in bytes. 137.It Vt u_int Va d_fwsectors 138The number of sectors advertised on the disk device by the firmware or 139BIOS. 140.It Vt u_int Va d_fwheads 141The number of heads advertised on the disk device by the firmeware or 142BIOS. 143.It Vt u_int Va d_maxsize 144The maximum I/O request the disk device supports. 145.It Vt u_int Va d_stripeoffset 146If the disk device supports an optimal stripe size and offset, such as 147a RAID device, it may advertise that offset using this field. 148.It Vt u_int Va d_stripesize 149If the disk device supports an optimal stripe size and offset, such as 150a RAID device, it may advertise that size using this field. 151.El 152.Ss Driver Private Data 153This field may be used by the device driver to store a pointer to 154private data to implement the disk service. 155.Bl -tag -width XXX 156.It Vt "void *" Va d_drv1 157Private data pointer. 158.El 159.Sh SEE ALSO 160.Xr GEOM 4 , 161.Xr devfs 5 162.Sh AUTHORS 163This manual page was written by 164.An Robert Watson . 165