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