1.\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved. 2.\" Copyright 1989 AT&T 3.\" The contents of this file are subject to the terms of the 4.\" Common Development and Distribution License (the "License"). 5.\" You may not use this file except in compliance with the License. 6.\" 7.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 8.\" or http://www.opensolaris.org/os/licensing. 9.\" See the License for the specific language governing permissions 10.\" and limitations under the License. 11.\" 12.\" When distributing Covered Code, include this CDDL HEADER in each 13.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 14.\" If applicable, add the following below this CDDL HEADER, with the 15.\" fields enclosed by brackets "[]" replaced with your own identifying 16.\" information: Portions Copyright [yyyy] [name of copyright owner] 17.Dd July 9, 2018 18.Dt BUF 9S 19.Os 20.Sh NAME 21.Nm buf 22.Nd block I/O data transfer structure 23.Sh SYNOPSIS 24.In sys/ddi.h 25.In sys/sunddi.h 26.Sh INTERFACE LEVEL 27Architecture independent level 1 (DDI/DKI) 28.Sh DESCRIPTION 29The 30.Vt buf 31structure is the basic data structure for block 32.Sy I/O 33transfers. 34Each block 35.Sy I/O 36transfer has an associated buffer header. 37The header contains all the buffer control and status information. 38For drivers, the buffer header pointer is the sole argument to a block driver 39.Xr strategy 9E 40routine. 41Do not depend on the size of the 42.Vt buf 43structure when writing a driver. 44.Pp 45A buffer header can be linked in multiple lists simultaneously. 46Because of 47this, most of the members in the buffer header cannot be changed by the driver, 48even when the buffer header is in one of the driver's work lists. 49.Pp 50Buffer headers are also used by the system for unbuffered or physical 51.Sy I/O 52for block drivers. 53In this case, the buffer describes a portion of user data 54space that is locked into memory. 55.Pp 56Block drivers often chain block requests so that overall throughput for the 57device is maximized. 58The 59.Fa av_forw 60and the 61.Fa av_back 62members of the 63.Vt buf 64structure can serve as link pointers for chaining block requests. 65.Sh STRUCTURE MEMBERS 66.Bd -literal -offset 2n 67int b_flags; /* Buffer status */ 68struct buf *av_forw; /* Driver work list link */ 69struct buf *av_back; /* Driver work list link */ 70size_t b_bcount; /* # of bytes to transfer */ 71union { 72 caddr_t b_addr; /* Buffer's virtual address */ 73} b_un; 74daddr_t b_blkno; /* Block number on device */ 75diskaddr_t b_lblkno; /* Expanded block number on dev. */ 76size_t b_resid; /* # of bytes not xferred */ 77size_t b_bufsize; /* size of alloc. buffer */ 78int (*b_iodone)(struct buf *); /* function called */ 79 /* by biodone */ 80int b_error; /* expanded error field */ 81void *b_private; /* "opaque" driver private area */ 82dev_t b_edev; /* expanded dev field */ 83.Ed 84.Pp 85The members of the buffer header available to test or set by a driver are as 86follows: 87.Pp 88.Fa b_flags 89stores the buffer status and indicates to the driver whether to 90read or write to the device. 91The driver must never clear the 92.Fa b_flags 93member. 94If this is done, unpredictable results can occur including loss of disk 95sanity and the possible failure of other kernel processes. 96.Pp 97All 98.Fa b_flags 99bit values not otherwise specified above are reserved by the 100kernel and may not be used. 101.Pp 102Valid flags are as follows: 103.Bl -tag -width "B_PAGEIO" 104.It Dv B_BUSY 105Indicates the buffer is in use. 106The driver must not change this flag unless it allocated the buffer with 107.Xr getrbuf 9F 108and no 109.Sy I/O 110operation is in progress. 111.It Dv B_DONE 112Indicates the data transfer has completed. 113This flag is read-only. 114.It Dv B_ERROR 115Indicates an 116.Sy I/O 117transfer error. 118It is set in conjunction with the 119.Fa b_error 120field. 121.Xr bioerror 9F 122should be used in preference to setting the 123.Dv B_ERROR 124bit. 125.It Dv B_PAGEIO 126Indicates the buffer is being used in a paged 127.Sy I/O 128request. 129See the description of the 130.Fa b_un.b_addr 131field for more information. 132This flag is read-only. 133.It Dv B_PHYS 134indicates the buffer header is being used for physical (direct) 135.Sy I/O 136to a user data area. 137See the description of the 138.Fa b_un.b_addr 139field for more information. 140This flag is read-only. 141.It Dv B_READ 142Indicates that data is to be read from the peripheral device into main memory. 143.It Dv B_WRITE 144Indicates that the data is to be transferred from main memory to the peripheral 145device. 146.Dv B_WRITE 147is a pseudo flag and cannot be directly tested; it is 148only detected as the NOT form of 149.Dv B_READ . 150.El 151.Pp 152.Fa av_forw 153and 154.Fa av_back 155can be used by the driver to link the buffer into driver work lists. 156.Pp 157.Fa b_bcount 158specifies the number of bytes to be transferred in both a paged and a non-paged 159.Sy I/O 160request. 161.Pp 162.Fa b_un.b_addr 163is the virtual address of the 164.Sy I/O 165request, unless 166.Dv B_PAGEIO 167is set. 168The address is a kernel virtual address, unless 169.Dv B_PHYS 170is set, in which case it is a user virtual address. 171If 172.Dv B_PAGEIO 173is set, 174.Fa b_un.b_addr 175contains kernel private data. 176Note that either one of 177.Dv B_PHYS 178and 179.Dv B_PAGEIO , 180or neither, can be set, but 181not both. 182.Pp 183.Fa b_blkno 184identifies which logical block on the device (the device is 185defined by the device number) is to be accessed. 186The driver might have to 187convert this logical block number to a physical location such as a cylinder, 188track, and sector of a disk. 189This is a 32-bit value. 190The driver should use 191.Fa b_blkno 192or 193.Fa b_lblkno , 194but not both. 195.Pp 196.Fa b_lblkno 197identifies which logical block on the device (the device is 198defined by the device number) is to be accessed. 199The driver might have to 200convert this logical block number to a physical location such as a cylinder, 201track, and sector of a disk. 202This is a 64-bit value. 203The driver should use 204.Fa b_lblkno 205or 206.Fa b_blkno , 207but not both. 208.Pp 209.Fa b_resid 210should be set to the number of bytes not transferred because of an error. 211.Pp 212.Fa b_bufsize 213contains the size of the allocated buffer. 214.Pp 215.Fa b_iodone 216identifies a specific 217.Xr biodone 9F 218routine to be called by the driver when the 219.Sy I/O 220is complete. 221.Pp 222.Fa b_error 223can hold an error code that should be passed as a return code 224from the driver. 225.Fa b_error 226is set in conjunction with the 227.Dv B_ERROR 228bit 229set in the 230.Fa b_flags 231member. 232.Xr bioerror 9F 233should be used in 234preference to setting the 235.Fa b_error 236field. 237.Pp 238.Fa b_private 239is for the private use of the device driver. 240.Pp 241.Fa b_edev 242contains the major and minor device numbers of the device 243accessed. 244.Sh SEE ALSO 245.Xr strategy 9E , 246.Xr aphysio 9F , 247.Xr bioclone 9F , 248.Xr biodone 9F , 249.Xr bioerror 9F , 250.Xr bioinit 9F , 251.Xr clrbuf 9F , 252.Xr getrbuf 9F , 253.Xr physio 9F , 254.Xr iovec 9S , 255.Xr uio 9S 256.Rs 257.%T Writing Device Drivers 258.Re 259.Sh WARNINGS 260Buffers are a shared resource within the kernel. 261Drivers should read or write only the members listed in this section. 262Drivers that attempt to use undocumented members of the 263.Fa buf 264structure risk corrupting data in the kernel or on the device. 265