12062 Convert buf(9S) to mandoc
1 BUF(9S) Data Structures for Drivers BUF(9S) 2 3 4 5 NAME 6 buf - block I/O data transfer structure 7 8 SYNOPSIS 9 #include <sys/ddi.h> 10 #include <sys/sunddi.h> 11 12 13 INTERFACE LEVEL 14 Architecture independent level 1 (DDI/DKI) 15 16 DESCRIPTION 17 The buf structure is the basic data structure for block I/O transfers. 18 Each block I/O transfer has an associated buffer header. The header 19 contains all the buffer control and status information. For drivers, 20 the buffer header pointer is the sole argument to a block driver 21 strategy(9E) routine. Do not depend on the size of the buf structure 22 when writing a driver. 23 24 25 A buffer header can be linked in multiple lists simultaneously. Because 26 of this, most of the members in the buffer header cannot be changed by 27 the driver, even when the buffer header is in one of the driver's work 28 lists. 29 30 31 Buffer headers are also used by the system for unbuffered or physical 32 I/O for block drivers. In this case, the buffer describes a portion of 33 user data space that is locked into memory. 34 35 36 Block drivers often chain block requests so that overall throughput for 37 the device is maximized. The av_forw and the av_back members of the buf 38 structure can serve as link pointers for chaining block requests. 39 40 STRUCTURE MEMBERS 41 int b_flags; /* Buffer status */ 42 struct buf *av_forw; /* Driver work list link */ 43 struct buf *av_back; /* Driver work list link */ 44 size_t b_bcount; /* # of bytes to transfer */ 45 union { 46 caddr_t b_addr; /* Buffer's virtual address */ 47 } b_un; 48 daddr_t b_blkno; /* Block number on device */ 49 diskaddr_t b_lblkno; /* Expanded block number on dev. */ 50 size_t b_resid; /* # of bytes not xferred */ 51 size_t b_bufsize; /* size of alloc. buffer */ 52 int (*b_iodone)(struct buf *); /* function called */ 53 /* by biodone */ 54 int b_error; /* expanded error field */ 55 void *b_private; /* "opaque" driver private area */ 56 dev_t b_edev; /* expanded dev field */ 57 58 59 60 61 The members of the buffer header available to test or set by a driver 62 are as follows: 63 64 65 b_flags stores the buffer status and indicates to the driver whether to 66 read or write to the device. The driver must never clear the b_flags 67 member. If this is done, unpredictable results can occur including loss 68 of disk sanity and the possible failure of other kernel processes. 69 70 71 All b_flags bit values not otherwise specified above are reserved by 72 the kernel and may not be used. 73 74 75 Valid flags are as follows: 76 77 B_BUSY 78 Indicates the buffer is in use. The driver must not change 79 this flag unless it allocated the buffer with getrbuf(9F) 80 and no I/O operation is in progress. 81 82 83 B_DONE 84 Indicates the data transfer has completed. This flag is 85 read-only. 86 87 88 B_ERROR 89 Indicates an I/O transfer error. It is set in conjunction 90 with the b_error field. bioerror(9F) should be used in 91 preference to setting the B_ERROR bit. 92 93 94 B_PAGEIO 95 Indicates the buffer is being used in a paged I/O request. 96 See the description of the b_un.b_addr field for more 97 information. This flag is read-only. 98 99 100 B_PHYS 101 indicates the buffer header is being used for physical 102 (direct) I/O to a user data area. See the description of 103 the b_un.b_addr field for more information. This flag is 104 read-only. 105 106 107 B_READ 108 Indicates that data is to be read from the peripheral 109 device into main memory. 110 111 112 B_WRITE 113 Indicates that the data is to be transferred from main 114 memory to the peripheral device. B_WRITE is a pseudo flag 115 and cannot be directly tested; it is only detected as the 116 NOT form of B_READ. 117 118 119 120 av_forw and av_back can be used by the driver to link the buffer into 121 driver work lists. 122 123 124 b_bcount specifies the number of bytes to be transferred in both a 125 paged and a non-paged I/O request. 126 127 128 b_un.b_addr is the virtual address of the I/O request, unless B_PAGEIO 129 is set. The address is a kernel virtual address, unless B_PHYS is set, 130 in which case it is a user virtual address. If B_PAGEIO is set, 131 b_un.b_addr contains kernel private data. Note that either one of 132 B_PHYS and B_PAGEIO, or neither, can be set, but not both. 133 134 135 b_blkno identifies which logical block on the device (the device is 136 defined by the device number) is to be accessed. The driver might have 137 to convert this logical block number to a physical location such as a 138 cylinder, track, and sector of a disk. This is a 32-bit value. The 139 driver should use b_blkno or b_lblkno, but not both. 140 141 142 b_lblkno identifies which logical block on the device (the device is 143 defined by the device number) is to be accessed. The driver might have 144 to convert this logical block number to a physical location such as a 145 cylinder, track, and sector of a disk. This is a 64-bit value. The 146 driver should use b_lblkno or b_blkno, but not both. 147 148 149 b_resid should be set to the number of bytes not transferred because of 150 an error. 151 152 153 b_bufsize contains the size of the allocated buffer. 154 155 156 b_iodone identifies a specific biodone routine to be called by the 157 driver when the I/O is complete. 158 159 160 b_error can hold an error code that should be passed as a return code 161 from the driver. b_error is set in conjunction with the B_ERROR bit set 162 in the b_flags member. bioerror(9F) should be used in preference to 163 setting the b_error field. 164 165 166 b_private is for the private use of the device driver. 167 168 169 b_edev contains the major and minor device numbers of the device 170 accessed. 171 172 SEE ALSO 173 strategy(9E), aphysio(9F), bioclone(9F), biodone(9F), bioerror(9F), 174 bioinit(9F), clrbuf(9F), getrbuf(9F), physio(9F), iovec(9S), uio(9S) 175 176 177 Writing Device Drivers 178 179 WARNINGS 180 Buffers are a shared resource within the kernel. Drivers should read or 181 write only the members listed in this section. Drivers that attempt to 182 use undocumented members of the buf structure risk corrupting data in 183 the kernel or on the device. 184 185 186 187 September 19, 2002 BUF(9S) --- EOF ---