share/man/man9/disk.9

   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 October 30, 2012
  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 struct disk *
  39 .Fn disk_alloc void
  40 .Ft void
  41 .Fn disk_create "struct disk *disk" "int version"
  42 .Ft void
  43 .Fn disk_gone "struct disk *disk"
  44 .Ft void
  45 .Fn disk_destroy "struct disk *disk"
  46 .Ft int
  47 .Fn disk_resize "struct disk *disk" "int flags"
  48 .Sh DESCRIPTION
  49 The disk storage API permits kernel device drivers providing access to
  50 disk-like storage devices to advertise the device to other kernel
  51 components, including
  52 .Xr GEOM 4
  53 and
  54 .Xr devfs 5 .
  55 .Pp
  56 Each disk device is described by a
  57 .Vt "struct disk"
  58 structure, which contains a variety of parameters for the disk device,
  59 function pointers for various methods that may be performed on the device,
  60 as well as private data storage for the device driver.
  61 In addition, some fields are reserved for use by GEOM in managing access
  62 to the device and its statistics.
  63 .Pp
  64 GEOM has the ownership of
  65 .Vt "struct disk" ,
  66 and drivers must allocate storage for it with the
  67 .Fn disk_alloc
  68 function,
  69 fill in the fields and call
  70 .Fn disk_create
  71 when the device is ready to service requests.
  72 .Fn disk_resize
  73 can be called by the driver after modifying
  74 .Va d_mediasize
  75 to notify GEOM about the disk capacity change.
  76 The
  77 .Fa flags
  78 field should be set to either M_WAITOK, or M_NOWAIT.
  79 .Fn disk_gone
  80 orphans all of the providers associated with the drive, setting an error
  81 condition of ENXIO in each one.
  82 In addition, it prevents a re-taste on last close for writing if an error
  83 condition has been set in the provider.
  84 After calling
  85 .Fn disk_destroy ,
  86 the device driver is not allowed to access the contents of
  87 .Vt "struct disk"
  88 anymore.
  89 .Pp
  90 The
  91 .Fn disk_create
  92 function
  93 takes a second parameter,
  94 .Fa version ,
  95 which must always be passed
  96 .Dv DISK_VERSION .
  97 If GEOM detects that the driver is compiled against an unsupported version,
  98 it will ignore the device and print a warning on the console.
  99 .Ss Descriptive Fields
 100 The following fields identify the disk device described by the structure
 101 instance, and must be filled in prior to submitting the structure to
 102 .Fn disk_create
 103 and may not be subsequently changed:
 104 .Bl -tag -width indent
 105 .It Vt u_int Va d_flags
 106 Optional flags indicating to the storage framework what optional features
 107 or descriptions the storage device driver supports.
 108 Currently supported flags are
 109 .Dv DISKFLAG_NEEDSGIANT
 110 (maintained by device driver),
 111 .Dv DISKFLAG_OPEN
 112 (maintained by storage framework),
 113 .Dv DISKFLAG_CANDELETE
 114 (maintained by device driver),
 115 and
 116 .Dv DISKFLAG_CANFLUSHCACHE
 117 (maintained by device driver).
 118 .It Vt "const char *" Va d_name
 119 Holds the name of the storage device class, e.g.,
 120 .Dq Li ahd .
 121 This value typically uniquely identifies a particular driver device,
 122 and must not conflict with devices serviced by other device drivers.
 123 .It Vt u_int Va d_unit
 124 Holds the instance of the storage device class, e.g.,
 125 .Dq Li 4 .
 126 This namespace is managed by the device driver, and assignment of unit
 127 numbers might be a property of probe order, or in some cases topology.
 128 Together, the
 129 .Va d_name
 130 and
 131 .Va d_unit
 132 values will uniquely identify a disk storage device.
 133 .El
 134 .Ss Disk Device Methods
 135 The following fields identify various disk device methods, if implemented:
 136 .Bl -tag -width indent
 137 .It Vt "disk_open_t *" Va d_open
 138 Optional: invoked when the disk device is opened.
 139 If no method is provided, open will always succeed.
 140 .It Vt "disk_close_t *" Va d_close
 141 Optional: invoked when the disk device is closed.
 142 Although an error code may be returned, the call should always terminate
 143 any state setup by the corresponding open method call.
 144 .It Vt "disk_strategy_t *" Va d_strategy
 145 Mandatory: invoked when a new
 146 .Vt "struct bio"
 147 is to be initiated on the disk device.
 148 .It Vt "disk_ioctl_t *" Va d_ioctl
 149 Optional: invoked when an I/O control operation is initiated on the disk device.
 150 Please note that for security reasons these operations should not
 151 be able to affect other devices than the one on which they are performed.
 152 .It Vt "dumper_t *" Va d_dump
 153 Optional: if configured with
 154 .Xr dumpon 8 ,
 155 this function is invoked from a very restricted system state after a
 156 kernel panic to record a copy of the system RAM to the disk.
 157 .It Vt "disk_getattr_t *" Va d_getattr
 158 Optional: if this method is provided, it gives the disk driver the
 159 opportunity to override the default GEOM response to BIO_GETATTR requests.
 160 This function should return -1 if the attribute is not handled, 0 if the
 161 attribute is handled, or an errno to be passed to g_io_deliver().
 162 .It Vt "disk_gone_t *" Va d_gone
 163 Optional: if this method is provided, it will be called after disk_gone()
 164 is called, once GEOM has finished its cleanup process.
 165 Once this callback is called, it is safe for the disk driver to free all of
 166 its resources, as it will not be receiving further calls from GEOM.
 167 .El
 168 .Ss Mandatory Media Properties
 169 The following fields identify the size and granularity of the disk device.
 170 These fields must stay stable from return of the drivers open method until
 171 the close method is called, but it is perfectly legal to modify them in
 172 the open method before returning.
 173 .Bl -tag -width indent
 174 .It Vt u_int Va d_sectorsize
 175 The sector size of the disk device in bytes.
 176 .It Vt off_t Va d_mediasize
 177 The size of the disk device in bytes.
 178 .It Vt u_int Va d_maxsize
 179 The maximum supported size in bytes of an I/O request.
 180 Requests larger than this size will be chopped up by GEOM.
 181 .El
 182 .Ss Optional Media Properties
 183 These optional fields can provide extra information about the disk
 184 device.
 185 Do not initialize these fields if the field/concept does not apply.
 186 These fields must stay stable from return of the drivers open method until
 187 the close method is called, but it is perfectly legal to modify them in
 188 the open method before returning.
 189 .Bl -tag -width indent
 190 .It Vt u_int Va d_fwsectors , Vt u_int Va d_fwheads
 191 The number of sectors and heads advertised on the disk device by the
 192 firmware or BIOS.
 193 These values are almost universally bogus, but on some architectures
 194 necessary for the correct calculation of disk partitioning.
 195 .It Vt u_int Va d_stripeoffset , Vt u_int Va d_stripesize
 196 These two fields can be used to describe the width and location of
 197 natural performance boundaries for most disk technologies.
 198 Please see
 199 .Pa src/sys/geom/notes
 200 for details.
 201 .It Vt char Va d_ident[DISK_IDENT_SIZE]
 202 This field can and should be used to store disk's serial number if the
 203 d_getattr method described above isn't implemented, or if it does not
 204 support the GEOM::ident attribute.
 205 .It Vt char Va d_descr[DISK_IDENT_SIZE]
 206 This field can be used to store the disk vendor and product description.
 207 .It Vt uint16_t Va d_hba_vendor
 208 This field can be used to store the PCI vendor ID for the HBA connected to
 209 the disk.
 210 .It Vt uint16_t Va d_hba_device
 211 This field can be used to store the PCI device ID for the HBA connected to
 212 the disk.
 213 .It Vt uint16_t Va d_hba_subvendor
 214 This field can be used to store the PCI subvendor ID for the HBA connected to
 215 the disk.
 216 .It Vt uint16_t Va d_hba_subdevice
 217 This field can be used to store the PCI subdevice ID for the HBA connected to
 218 the disk.
 219 .El
 220 .Ss Driver Private Data
 221 This field may be used by the device driver to store a pointer to
 222 private data to implement the disk service.
 223 .Bl -tag -width indent
 224 .It Vt "void *" Va d_drv1
 225 Private data pointer.
 226 Typically used to store a pointer to the drivers
 227 .Vt softc
 228 structure for this disk device.
 229 .El
 230 .Sh SEE ALSO
 231 .Xr GEOM 4 ,
 232 .Xr devfs 5
 233 .Sh AUTHORS
 234 This manual page was written by
 235 .An Robert Watson .