xref: /freebsd/share/man/man9/disk.9 (revision 1a720cbec513210fa2e85c3882741ef2f6dc5f35)
1ef43d3b5SRobert Watson.\"
2ef43d3b5SRobert Watson.\" Copyright (c) 2003 Robert N. M. Watson
3ef43d3b5SRobert Watson.\" All rights reserved.
4ef43d3b5SRobert Watson.\"
5ef43d3b5SRobert Watson.\" Redistribution and use in source and binary forms, with or without
6ef43d3b5SRobert Watson.\" modification, are permitted provided that the following conditions
7ef43d3b5SRobert Watson.\" are met:
8ef43d3b5SRobert Watson.\" 1. Redistributions of source code must retain the above copyright
9ef43d3b5SRobert Watson.\"    notice(s), this list of conditions and the following disclaimer as
10ef43d3b5SRobert Watson.\"    the first lines of this file unmodified other than the possible
11ef43d3b5SRobert Watson.\"    addition of one or more copyright notices.
12ef43d3b5SRobert Watson.\" 2. Redistributions in binary form must reproduce the above copyright
13ef43d3b5SRobert Watson.\"    notice(s), this list of conditions and the following disclaimer in the
14ef43d3b5SRobert Watson.\"    documentation and/or other materials provided with the distribution.
15ef43d3b5SRobert Watson.\"
16ef43d3b5SRobert Watson.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
17ef43d3b5SRobert Watson.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18ef43d3b5SRobert Watson.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19ef43d3b5SRobert Watson.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
20ef43d3b5SRobert Watson.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21ef43d3b5SRobert Watson.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22ef43d3b5SRobert Watson.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23ef43d3b5SRobert Watson.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24ef43d3b5SRobert Watson.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25ef43d3b5SRobert Watson.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
26ef43d3b5SRobert Watson.\" DAMAGE.
27ef43d3b5SRobert Watson.\"
288c63b2dbSBenedict Reuschling.Dd April 30, 2020
29aad6efccSHiten Pandya.Dt DISK 9
30ef43d3b5SRobert Watson.Os
31ef43d3b5SRobert Watson.Sh NAME
32ef43d3b5SRobert Watson.Nm disk
331b2f42a9SRuslan Ermilov.Nd kernel disk storage API
34ef43d3b5SRobert Watson.Sh SYNOPSIS
352f6e000aSHiten Pandya.In geom/geom_disk.h
3609313993SRobert Watson.Ft struct disk *
371b2f42a9SRuslan Ermilov.Fn disk_alloc void
38ef43d3b5SRobert Watson.Ft void
391b2f42a9SRuslan Ermilov.Fn disk_create "struct disk *disk" "int version"
40ef43d3b5SRobert Watson.Ft void
41cbc1fff1SEdward Tomasz Napierala.Fn disk_gone "struct disk *disk"
42cbc1fff1SEdward Tomasz Napierala.Ft void
43ef43d3b5SRobert Watson.Fn disk_destroy "struct disk *disk"
44207c7ec8SEdward Tomasz Napierala.Ft int
45207c7ec8SEdward Tomasz Napierala.Fn disk_resize "struct disk *disk" "int flags"
46d3517d30SWarner Losh.Ft void
47d3517d30SWarner Losh.Fn disk_add_alias "struct disk *disk" "const char *alias"
48ef43d3b5SRobert Watson.Sh DESCRIPTION
49ef43d3b5SRobert WatsonThe disk storage API permits kernel device drivers providing access to
50ef43d3b5SRobert Watsondisk-like storage devices to advertise the device to other kernel
51ef43d3b5SRobert Watsoncomponents, including
521b2f42a9SRuslan Ermilov.Xr GEOM 4
53ef43d3b5SRobert Watsonand
54*1a720cbeSAlexander Ziaee.Xr devfs 4 .
555e50629bSRobert Watson.Pp
56ef43d3b5SRobert WatsonEach disk device is described by a
57ef43d3b5SRobert Watson.Vt "struct disk"
58ef43d3b5SRobert Watsonstructure, which contains a variety of parameters for the disk device,
59ef43d3b5SRobert Watsonfunction pointers for various methods that may be performed on the device,
60ef43d3b5SRobert Watsonas well as private data storage for the device driver.
61ef43d3b5SRobert WatsonIn addition, some fields are reserved for use by GEOM in managing access
62ef43d3b5SRobert Watsonto the device and its statistics.
630aef5c84SPoul-Henning Kamp.Pp
640aef5c84SPoul-Henning KampGEOM has the ownership of
655e50629bSRobert Watson.Vt "struct disk" ,
660aef5c84SPoul-Henning Kampand drivers must allocate storage for it with the
670aef5c84SPoul-Henning Kamp.Fn disk_alloc
680aef5c84SPoul-Henning Kampfunction,
690aef5c84SPoul-Henning Kampfill in the fields and call
700aef5c84SPoul-Henning Kamp.Fn disk_create
710aef5c84SPoul-Henning Kampwhen the device is ready to service requests.
72d3517d30SWarner Losh.Fn disk_add_alias
73d3517d30SWarner Loshadds an alias for the disk and must be called before
74d3517d30SWarner Losh.Fn disk_create ,
75d3517d30SWarner Loshbut may be called multiple times.
76d3517d30SWarner LoshFor each alias added, a device node will be created with
77d3517d30SWarner Losh.Xr make_dev_alias 9
78d3517d30SWarner Loshin the same way primary device nodes are created with
79d3517d30SWarner Losh.Xr make_dev 9
80d3517d30SWarner Loshfor
81d3517d30SWarner Losh.Va d_name
82d3517d30SWarner Loshand
83d3517d30SWarner Losh.Va d_unit .
84d3517d30SWarner LoshCare should be taken to ensure that only one driver creates aliases
85d3517d30SWarner Loshfor any given name.
86207c7ec8SEdward Tomasz Napierala.Fn disk_resize
87207c7ec8SEdward Tomasz Napieralacan be called by the driver after modifying
88207c7ec8SEdward Tomasz Napierala.Va d_mediasize
89207c7ec8SEdward Tomasz Napieralato notify GEOM about the disk capacity change.
90207c7ec8SEdward Tomasz NapieralaThe
91207c7ec8SEdward Tomasz Napierala.Fa flags
92207c7ec8SEdward Tomasz Napieralafield should be set to either M_WAITOK, or M_NOWAIT.
93cbc1fff1SEdward Tomasz Napierala.Fn disk_gone
94cbc1fff1SEdward Tomasz Napieralaorphans all of the providers associated with the drive, setting an error
95cbc1fff1SEdward Tomasz Napieralacondition of ENXIO in each one.
96cbc1fff1SEdward Tomasz NapieralaIn addition, it prevents a re-taste on last close for writing if an error
97cbc1fff1SEdward Tomasz Napieralacondition has been set in the provider.
980aef5c84SPoul-Henning KampAfter calling
991b2f42a9SRuslan Ermilov.Fn disk_destroy ,
1001b2f42a9SRuslan Ermilovthe device driver is not allowed to access the contents of
1011b2f42a9SRuslan Ermilov.Vt "struct disk"
1020aef5c84SPoul-Henning Kampanymore.
1035e50629bSRobert Watson.Pp
1041b2f42a9SRuslan ErmilovThe
1050aef5c84SPoul-Henning Kamp.Fn disk_create
1061b2f42a9SRuslan Ermilovfunction
1071b2f42a9SRuslan Ermilovtakes a second parameter,
1081b2f42a9SRuslan Ermilov.Fa version ,
1090aef5c84SPoul-Henning Kampwhich must always be passed
1100aef5c84SPoul-Henning Kamp.Dv DISK_VERSION .
1111b2f42a9SRuslan ErmilovIf GEOM detects that the driver is compiled against an unsupported version,
1120aef5c84SPoul-Henning Kampit will ignore the device and print a warning on the console.
113ef43d3b5SRobert Watson.Ss Descriptive Fields
114ef43d3b5SRobert WatsonThe following fields identify the disk device described by the structure
115ef43d3b5SRobert Watsoninstance, and must be filled in prior to submitting the structure to
1160aef5c84SPoul-Henning Kamp.Fn disk_create
1170aef5c84SPoul-Henning Kampand may not be subsequently changed:
1181b2f42a9SRuslan Ermilov.Bl -tag -width indent
119ef43d3b5SRobert Watson.It Vt u_int Va d_flags
120ef43d3b5SRobert WatsonOptional flags indicating to the storage framework what optional features
121ef43d3b5SRobert Watsonor descriptions the storage device driver supports.
122ef43d3b5SRobert WatsonCurrently supported flags are
123ef43d3b5SRobert Watson.Dv DISKFLAG_OPEN
124ef43d3b5SRobert Watson(maintained by storage framework),
125ef43d3b5SRobert Watson.Dv DISKFLAG_CANDELETE
1261d2aee20SPawel Jakub Dawidek(maintained by device driver),
1271d2aee20SPawel Jakub Dawidekand
1281d2aee20SPawel Jakub Dawidek.Dv DISKFLAG_CANFLUSHCACHE
129ef43d3b5SRobert Watson(maintained by device driver).
130ef43d3b5SRobert Watson.It Vt "const char *" Va d_name
131ef43d3b5SRobert WatsonHolds the name of the storage device class, e.g.,
1321b2f42a9SRuslan Ermilov.Dq Li ahd .
133ef43d3b5SRobert WatsonThis value typically uniquely identifies a particular driver device,
134ef43d3b5SRobert Watsonand must not conflict with devices serviced by other device drivers.
135ef43d3b5SRobert Watson.It Vt u_int Va d_unit
136ef43d3b5SRobert WatsonHolds the instance of the storage device class, e.g.,
1371b2f42a9SRuslan Ermilov.Dq Li 4 .
138ef43d3b5SRobert WatsonThis namespace is managed by the device driver, and assignment of unit
139ef43d3b5SRobert Watsonnumbers might be a property of probe order, or in some cases topology.
140ef43d3b5SRobert WatsonTogether, the
141ef43d3b5SRobert Watson.Va d_name
142ef43d3b5SRobert Watsonand
143ef43d3b5SRobert Watson.Va d_unit
144ef43d3b5SRobert Watsonvalues will uniquely identify a disk storage device.
145ef43d3b5SRobert Watson.El
146ef43d3b5SRobert Watson.Ss Disk Device Methods
147ef43d3b5SRobert WatsonThe following fields identify various disk device methods, if implemented:
1481b2f42a9SRuslan Ermilov.Bl -tag -width indent
149ef43d3b5SRobert Watson.It Vt "disk_open_t *" Va d_open
1501b2f42a9SRuslan ErmilovOptional: invoked when the disk device is opened.
1511b2f42a9SRuslan ErmilovIf no method is provided, open will always succeed.
152ef43d3b5SRobert Watson.It Vt "disk_close_t *" Va d_close
1531b2f42a9SRuslan ErmilovOptional: invoked when the disk device is closed.
1540aef5c84SPoul-Henning KampAlthough an error code may be returned, the call should always terminate
1552988974bSMike Pritchardany state setup by the corresponding open method call.
156ef43d3b5SRobert Watson.It Vt "disk_strategy_t *" Va d_strategy
1571b2f42a9SRuslan ErmilovMandatory: invoked when a new
1581b2f42a9SRuslan Ermilov.Vt "struct bio"
159ef43d3b5SRobert Watsonis to be initiated on the disk device.
160ef43d3b5SRobert Watson.It Vt "disk_ioctl_t *" Va d_ioctl
1611b2f42a9SRuslan ErmilovOptional: invoked when an I/O control operation is initiated on the disk device.
1620aef5c84SPoul-Henning KampPlease note that for security reasons these operations should not
1630aef5c84SPoul-Henning Kampbe able to affect other devices than the one on which they are performed.
164ef43d3b5SRobert Watson.It Vt "dumper_t *" Va d_dump
1651b2f42a9SRuslan ErmilovOptional: if configured with
1661b2f42a9SRuslan Ermilov.Xr dumpon 8 ,
1670aef5c84SPoul-Henning Kampthis function is invoked from a very restricted system state after a
1681b2f42a9SRuslan Ermilovkernel panic to record a copy of the system RAM to the disk.
169c3fb2891SKenneth D. Merry.It Vt "disk_getattr_t *" Va d_getattr
170c3fb2891SKenneth D. MerryOptional: if this method is provided, it gives the disk driver the
171c3fb2891SKenneth D. Merryopportunity to override the default GEOM response to BIO_GETATTR requests.
172c3fb2891SKenneth D. MerryThis function should return -1 if the attribute is not handled, 0 if the
1739512f75fSGordon Berglingattribute is handled, or an errno to be passed to
1749512f75fSGordon Bergling.Fn g_io_deliver .
175c3fb2891SKenneth D. Merry.It Vt "disk_gone_t *" Va d_gone
1769512f75fSGordon BerglingOptional: if this method is provided, it will be called after
1779512f75fSGordon Bergling.Fn disk_gone
178c3fb2891SKenneth D. Merryis called, once GEOM has finished its cleanup process.
179c3fb2891SKenneth D. MerryOnce this callback is called, it is safe for the disk driver to free all of
180c3fb2891SKenneth D. Merryits resources, as it will not be receiving further calls from GEOM.
181ef43d3b5SRobert Watson.El
1820aef5c84SPoul-Henning Kamp.Ss Mandatory Media Properties
1830aef5c84SPoul-Henning KampThe following fields identify the size and granularity of the disk device.
1840aef5c84SPoul-Henning KampThese fields must stay stable from return of the drivers open method until
1850aef5c84SPoul-Henning Kampthe close method is called, but it is perfectly legal to modify them in
1860aef5c84SPoul-Henning Kampthe open method before returning.
1871b2f42a9SRuslan Ermilov.Bl -tag -width indent
188ef43d3b5SRobert Watson.It Vt u_int Va d_sectorsize
1890aef5c84SPoul-Henning KampThe sector size of the disk device in bytes.
190ef43d3b5SRobert Watson.It Vt off_t Va d_mediasize
191ef43d3b5SRobert WatsonThe size of the disk device in bytes.
192ef43d3b5SRobert Watson.It Vt u_int Va d_maxsize
1931b2f42a9SRuslan ErmilovThe maximum supported size in bytes of an I/O request.
1940aef5c84SPoul-Henning KampRequests larger than this size will be chopped up by GEOM.
1950aef5c84SPoul-Henning Kamp.El
1960aef5c84SPoul-Henning Kamp.Ss Optional Media Properties
1970aef5c84SPoul-Henning KampThese optional fields can provide extra information about the disk
1980aef5c84SPoul-Henning Kampdevice.
1990aef5c84SPoul-Henning KampDo not initialize these fields if the field/concept does not apply.
2000aef5c84SPoul-Henning KampThese fields must stay stable from return of the drivers open method until
2010aef5c84SPoul-Henning Kampthe close method is called, but it is perfectly legal to modify them in
2020aef5c84SPoul-Henning Kampthe open method before returning.
2031b2f42a9SRuslan Ermilov.Bl -tag -width indent
2041b2f42a9SRuslan Ermilov.It Vt u_int Va d_fwsectors , Vt u_int Va d_fwheads
2050aef5c84SPoul-Henning KampThe number of sectors and heads advertised on the disk device by the
2060aef5c84SPoul-Henning Kampfirmware or BIOS.
2070aef5c84SPoul-Henning KampThese values are almost universally bogus, but on some architectures
2080aef5c84SPoul-Henning Kampnecessary for the correct calculation of disk partitioning.
2091b2f42a9SRuslan Ermilov.It Vt u_int Va d_stripeoffset , Vt u_int Va d_stripesize
2100aef5c84SPoul-Henning KampThese two fields can be used to describe the width and location of
2110aef5c84SPoul-Henning Kampnatural performance boundaries for most disk technologies.
2120aef5c84SPoul-Henning KampPlease see
2131b2f42a9SRuslan Ermilov.Pa src/sys/geom/notes
2140aef5c84SPoul-Henning Kampfor details.
215d0c11f9eSPawel Jakub Dawidek.It Vt char Va d_ident[DISK_IDENT_SIZE]
216c3fb2891SKenneth D. MerryThis field can and should be used to store disk's serial number if the
217c3fb2891SKenneth D. Merryd_getattr method described above isn't implemented, or if it does not
218c3fb2891SKenneth D. Merrysupport the GEOM::ident attribute.
219c3fb2891SKenneth D. Merry.It Vt char Va d_descr[DISK_IDENT_SIZE]
220c3fb2891SKenneth D. MerryThis field can be used to store the disk vendor and product description.
221c3fb2891SKenneth D. Merry.It Vt uint16_t Va d_hba_vendor
222c3fb2891SKenneth D. MerryThis field can be used to store the PCI vendor ID for the HBA connected to
223c3fb2891SKenneth D. Merrythe disk.
224c3fb2891SKenneth D. Merry.It Vt uint16_t Va d_hba_device
225c3fb2891SKenneth D. MerryThis field can be used to store the PCI device ID for the HBA connected to
226c3fb2891SKenneth D. Merrythe disk.
227c3fb2891SKenneth D. Merry.It Vt uint16_t Va d_hba_subvendor
228c3fb2891SKenneth D. MerryThis field can be used to store the PCI subvendor ID for the HBA connected to
229c3fb2891SKenneth D. Merrythe disk.
230c3fb2891SKenneth D. Merry.It Vt uint16_t Va d_hba_subdevice
231c3fb2891SKenneth D. MerryThis field can be used to store the PCI subdevice ID for the HBA connected to
232c3fb2891SKenneth D. Merrythe disk.
233ef43d3b5SRobert Watson.El
234ef43d3b5SRobert Watson.Ss Driver Private Data
235ef43d3b5SRobert WatsonThis field may be used by the device driver to store a pointer to
236ef43d3b5SRobert Watsonprivate data to implement the disk service.
2371b2f42a9SRuslan Ermilov.Bl -tag -width indent
238ef43d3b5SRobert Watson.It Vt "void *" Va d_drv1
239ef43d3b5SRobert WatsonPrivate data pointer.
2401b2f42a9SRuslan ErmilovTypically used to store a pointer to the drivers
2411b2f42a9SRuslan Ermilov.Vt softc
2421b2f42a9SRuslan Ermilovstructure for this disk device.
243ef43d3b5SRobert Watson.El
2449512f75fSGordon Bergling.Sh SEE ALSO
245*1a720cbeSAlexander Ziaee.Xr devfs 4 ,
246*1a720cbeSAlexander Ziaee.Xr GEOM 4
2478c63b2dbSBenedict Reuschling.Sh HISTORY
2488c63b2dbSBenedict ReuschlingThe
2498c63b2dbSBenedict Reuschling.Nm kernel disk storage API
2502b02de2cSBenedict Reuschlingfirst appeared in
2518c63b2dbSBenedict Reuschling.Fx 4.9 .
252ef43d3b5SRobert Watson.Sh AUTHORS
253aad6efccSHiten PandyaThis manual page was written by
254ef43d3b5SRobert Watson.An Robert Watson .
255d3517d30SWarner Losh.Sh BUGS
256d3517d30SWarner LoshDisk aliases are not a general purpose aliasing mechanism, but are
257d3517d30SWarner Loshintended only to ease the transition from one name to another.
258d3517d30SWarner LoshThey can be used to ensure that nvd0 and nda0 are the same thing.
259d3517d30SWarner LoshThey cannot be used to implement the diskX concept from macOS.
260