1.\" $NetBSD: dksubr.9,v 1.7 2019/12/08 12:23:00 mlelstv Exp $ 2.\" 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd November 28, 2016 28.Dt DKSUBR 9 29.Os 30.Sh NAME 31.Nm dk_softc , 32.Nm dk_init , 33.Nm dk_attach , 34.Nm dk_detach , 35.Nm dk_open , 36.Nm dk_close , 37.Nm dk_size , 38.Nm dk_dump , 39.Nm dk_ioctl , 40.Nm dk_strategy , 41.Nm dk_strategy_defer , 42.Nm dk_strategy_pending , 43.Nm dk_start , 44.Nm dk_done , 45.Nm dk_drain , 46.Nm dk_discard , 47.Nm dk_getdefaultlabel , 48.Nm dk_getdisklabel 49.Nd disk driver subroutines 50.Sh SYNOPSIS 51.In sys/bufq.h 52.In sys/disk.h 53.In dev/dkvar.h 54.Ft void 55.Fn dk_init "struct dk_softc *" "device_t" "int dtype" 56.Ft void 57.Fn dk_attach "struct dk_softc *" 58.Ft void 59.Fn dk_detach "struct dk_softc *" 60.Ft int 61.Fn dk_open "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *" 62.Ft int 63.Fn dk_close "struct dk_softc *" "dev_t" "int flags" "int fmt" "struct lwp *" 64.Ft int 65.Fn dk_discard "struct dk_softc *" "dev_t" "off_t pos" "off_t len" 66.Ft int 67.Fn dk_size "struct dk_softc *" "dev_t" 68.Ft int 69.Fn dk_dump "struct dk_softc *" "dev_t" "daddr_t blkno" "void *vav" "size_t size" 70.Ft int 71.Fn dk_ioctl "struct dk_softc *" "dev_t" "u_long cmd" "void *data" "int flag" "struct lwp *" 72.Ft void 73.Fn dk_strategy "struct dk_softc *" "struct buf *" 74.Ft int 75.Fn dk_strategy_defer "struct dk_softc *" "struct buf *" 76.Ft int 77.Fn dk_strategy_pending "struct dk_softc *" 78.Ft void 79.Fn dk_start "struct dk_softc *" "struct buf *" 80.Ft void 81.Fn dk_done "struct dk_softc *" "struct buf *" 82.Ft int 83.Fn dk_drain "struct dk_softc *" 84.Ft void 85.Fn dk_getdefaultlabel "struct dk_softc *" "struct disklabel *" 86.Ft void 87.Fn dk_getdisklabel "struct dk_softc *" "dev_t" 88.Sh DESCRIPTION 89The disk driver subroutines provide common functionality for all disk drivers 90to reduce the amount of replicated code. 91For many disk drivers, their 92corresponding entry points can be made mostly stubs. 93.Pp 94The subroutines encapsulate data structures found in a driver's softc 95into 96.Bd -literal 97struct dk_softc { 98 device_t sc_dev; 99 struct disk sc_dkdev; 100 struct bufq_state sc_bufq; 101 krndsource_t sc_rnd_source; 102\&... 103} 104.Ed 105The 106.Nm dk_softc 107structure therefore replaces the 108.Nm device_t 109member of the driver's softc struct. 110.Pp 111The following is a brief description of each function in the framework: 112.Bl -tag -width ".Fn dk_strategy_pending" 113.It Fn dk_init 114Initialize the dk_softc structure. 115.It Fn dk_attach 116Attach framework after driver has attached the 117.Xr disk 9 118subsystem, created a 119.Xr bufq 9 120and is ready to handle I/O. 121.It Fn dk_detach 122Undo dk_attach. 123.It Fn dk_open 124Handles open steps for the 125.Xr disk 9 126framework, acquires the disklabel and validates open parameters. 127The driver may provide the 128.Nm d_firstopen 129callback to handle initialization steps. 130.It Fn dk_close 131Handles close steps for the 132.Xr disk 9 133framework. 134The driver may provide the 135.Nm d_lastclose 136callback to handle finalization steps. 137.Nm dk_open 138and 139.Nm dk_close 140are serialized by the openlock mutex. 141.It Fn dk_discard 142Validates parameters, computes raw block numbers and passes 143these to the 144.Nm d_discard 145callback. 146.It Fn dk_size 147Returns dump size information from the 148.Xr disklabel 9 149and opens and closes the driver when necessary. 150.It Fn dk_dump 151Validates parameters, computes raw block numbers and iterates 152over the 153.Nm d_dumpblocks 154callback in appropriate chunks determined by the 155.Nm d_iosize 156callback. 157.It Fn dk_ioctl 158Handles the ioctls 159.Dv DIOCKLABEL , 160.Dv DIOCWLABEL , 161.Dv DIOCGDEFLABEL , 162.Dv DIOCGSTRATEGY , 163and 164.Dv DIOCSSTRATEGY 165and passes other disk ioctls through the 166.Xr disk 9 167framework. 168Returns 169.Nm ENOTTY 170when an ioctl isn't implemented. 171This routine is run as a fallback to 172handle commands that are not specific to the driver. 173.It Fn dk_strategy 174Validates parameters, computes raw block numbers, queues a buffer for I/O 175and triggers queue processing by calling 176.Nm dk_start . 177.It Fn dk_strategy_defer 178Alternative to 179.Nm dk_strategy 180that only queues the buffer. 181Drivers that implement a separate I/O thread 182can use 183.Nm dk_strategy_defer 184within their own strategy routine and signal the thread through a private 185interface. 186.It Fn dk_strategy_pending 187This function is called by an I/O thread to determine if work has been 188queued by 189.Nm dk_strategy_defer . 190The driver must then call 191.Nm dk_start 192to trigger queue processing. 193.It Fn dk_start 194If 195.Ar bp != Dv NULL 196put it into the queue. 197Run the 198.Nm d_diskstart 199callback for every buffer until the queue is empty or the callback returns 200.Nm EAGAIN . 201In the latter case, the buffer is saved and issued on the 202next queue run. 203This also calls 204.Nm disk_busy 205accordingly to handle I/O metrics. 206.It Fn dk_done 207Called by the driver when an I/O operation completed. 208.Nm dk_done 209logs errors, calls 210.Nm disk_unbusy 211to handle I/O metrics and collects entropy for the 212.Xr cprng 9 . 213.It Fn dk_drain 214Aborts all queued I/O. 215This function must be called instead of 216.Fn bufq_drain 217to cooperate with 218.Nm dk_start . 219.It Fn dk_getdefaultlabel 220Compute a common default disklabel for all disk drivers. 221Some drivers provide device specific information or assign specific 222disk formats to partitions. 223Such drivers may implement the 224.Nm d_label 225callback that is called by 226.Nm dk_getdefaultlabel 227after initializing the label with common values. 228.It Fn dk_getdisklabel 229Read disklabel with machine dependent low-level function 230.Nm readdisklabel 231and do sanity checks. 232.El 233.Sh DRIVER INTERFACE 234The driver needs to provide a common set of entry points that are 235used by the disk driver subroutines and the 236.Xr disk 9 237framework. 238.Bd -literal 239struct dkdriver { 240 void (*d_strategy)(struct buf *); 241 void (*d_minphys)(struct buf *); 242 int (*d_open)(dev_t, int, int, struct lwp *); 243 int (*d_close)(dev_t, int, int, struct lwp *); 244 int (*d_diskstart)(device_t, struct buf *); 245 void (*d_iosize)(device_t, int *); 246 int (*d_dumpblocks)(device_t, void *, daddr_t, int); 247 int (*d_lastclose)(device_t); 248 int (*d_discard)(device_t, off_t, off_t); 249 int (*d_firstopen)(device_t, dev_t, int, int); 250 void (*d_label)(device_t, struct disklabel *); 251}; 252.Ed 253.Bl -tag -width ".Fn dk_firstopen" 254.It Fn d_strategy 255The driver strategy routine queues a single buffer for I/O 256and starts queue processing as appropriate. 257.It Fn d_minphys 258The driver minphys routine limits the buffer 259.Nm b_bcount 260to the maximum size for an I/O transfer supported by the driver 261and hardware. 262It also calls 263.Nm minphys 264to apply the platform limit. 265.It Fn d_open 266The driver open routine. 267.It Fn d_close 268The driver close routine. 269.It Fn d_diskstart 270Issues a single I/O request, called by 271.Nm dk_start . 272.It Fn d_iosize 273Truncate I/O size to the driver limit. 274This is similar to 275.Nm minphys 276but operates on an integer value instead of a buffer. 277.It Fn d_dumpblocks 278Issue a single I/O requests, called by 279.Nm dk_dump . 280.It Fn d_lastclose 281Private cleanup after last user is finished. 282Often used to flush write caches. 283.It Fn d_discard 284Issue a single I/O request to invalidate a disk region. 285.It Fn d_firstopen 286Private initialization when first user opens the driver. 287.El 288.Sh SEE ALSO 289.Xr cgd 4 , 290.Xr ld 4 , 291.Xr cprng 9 , 292.Xr disk 9 , 293.Xr driver 9 294.Sh HISTORY 295The 296.Nx 297common disk driver subroutines appeared in 298.Nx 2.0 299as a base for the cryptographic disk driver and was extended 300to handle disk wedges in 301.Nx 4.0 . 302Most functionality provided by 303.Xr ld 4 304was included and extended in 305.Nx 8.0 306to support other disk drivers. 307The callback interface used by the 308.Xr disk 9 309framework has been merged as well. 310