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