/share/man/man9/disk.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 226 lines · 226 code · 0 blank · 0 comment · 0 complexity · 91ca75fe36b048d80d025c97646f8bb8 MD5 · raw file

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