Copyright (c) 2003 Robert N. M. Watson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice(s), this list of conditions and the following disclaimer as
the first lines of this file unmodified other than the possible
addition of one or more copyright notices.
2. Redistributions in binary form must reproduce the above copyright
notice(s), this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

$FreeBSD: head/share/man/man9/disk.9 120497 2003-09-26 22:08:23Z rwatson $

.Dd September 26, 2003 .Dt disk 9 .Os .Sh NAME .Nm disk .Nd Kernel disk storage API .Sh SYNOPSIS n sys/geom_disk.h .Ft void .Fn disk_create "int unit" "struct disk *disk" "int flags" "void *unused" "void *unused2" .Ft void .Fn disk_destroy "struct disk *disk" .Sh DESCRIPTION The disk storage API permits kernel device drivers providing access to disk-like storage devices to advertise the device to other kernel components, including .Xr GEOM 4 , and .Xr devfs 5 .

p Each disk device is described by a .Vt "struct disk" structure, which contains a variety of parameters for the disk device, function pointers for various methods that may be performed on the device, as well as private data storage for the device driver. In addition, some fields are reserved for use by GEOM in managing access to the device and its statistics. Because of storage driver framework private data stored in .Vt "struct disk" , instances of the structure should be allocated out of writable, pre-zero'd memory.

p Public fields in the structure will generally be assumed not to change once the structure is submitted to .Fn disk_create , and so no explicit locking is employed; drivers that change the values of any of these fields do so at their own risk.

p Memory associated with the .Vt "struct disk" is owned by the device driver, but should not be released until after the completion of a call to .Fn disk_destroy . .Ss Descriptive Fields

p The following fields identify the disk device described by the structure instance, and must be filled in prior to submitting the structure to .Fn disk_create : l -tag -width XXX t Vt u_int Va d_flags Optional flags indicating to the storage framework what optional features or descriptions the storage device driver supports. Currently supported flags are .Dv DISKFLAG_NOGIANT (maintained by device driver), .Dv DISKFLAG_OPEN (maintained by storage framework), and .Dv DISKFLAG_CANDELETE (maintained by device driver).

p t Vt "const char *" Va d_name Holds the name of the storage device class, e.g., .Dq ahd . This value typically uniquely identifies a particular driver device, and must not conflict with devices serviced by other device drivers. t Vt u_int Va d_unit Holds the instance of the storage device class, e.g., .Dq 4 . This namespace is managed by the device driver, and assignment of unit numbers might be a property of probe order, or in some cases topology. Together, the .Va d_name and .Va d_unit values will uniquely identify a disk storage device. .El .Ss Disk Device Methods The following fields identify various disk device methods, if implemented: l -tag -width XXX t Vt "disk_open_t *" Va d_open Invoked when the disk device is opened. t Vt "disk_close_t *" Va d_close Invoked when the disk device is closed. t Vt "disk_strategy_t *" Va d_strategy Invoked when a new .Vt struct bio is to be initiated on the disk device. t Vt "disk_ioctl_t *" Va d_ioctl Invoked when a I/O control operation is initiated on the disk device. t Vt "dumper_t *" Va d_dump Invoked when a kernel crash dump is performed on the disk device. .El .Ss Media Properties The following fields identify the size, layout, and other media properties of the disk device. l -tag -width XXX t Vt u_int Va d_sectorsize The sectorsize of the disk device. t Vt off_t Va d_mediasize The size of the disk device in bytes. t Vt u_int Va d_fwsectors The number of sectors advertised on the disk device by the firmware or BIOS. t Vt u_int Va d_fwheads The number of heads advertised on the disk device by the firmeware or BIOS. t Vt u_int Va d_maxsize The maximum I/O request the disk device supports. t Vt u_int Va d_stripeoffset If the disk device supports an optimal stripe size and offset, such as a RAID device, it may advertise that offset using this field. t Vt u_int Va d_stripesize If the disk device supports an optimal stripe size and offset, such as a RAID device, it may advertise that size using this field. .El .Ss Driver Private Data This field may be used by the device driver to store a pointer to private data to implement the disk service. l -tag -width XXX t Vt "void *" Va d_drv1 Private data pointer. .El .Sh SEE ALSO .Xr GEOM 4 , .Xr devfs 5 .Sh AUTHORS This man page was written by .An Robert Watson .