Mon Mar 30 13:10:04 2015 UTC ()
Correct documentation of asynchronous/callback buffer I/O.

Asynchronous is not the same as callback: asynchronous means there is
no completion notification, and can be used only with buffer-cached
buffers.


(riastradh)
diff -r1.5 -r1.6 src/share/man/man9/bufferio.9
cvs diff -r1.5 -r1.6 src/share/man/man9/bufferio.9 (expand / switch to unified diff)

--- src/share/man/man9/bufferio.9 2015/03/29 21:08:36 1.5
+++ src/share/man/man9/bufferio.9 2015/03/30 13:10:04 1.6
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: bufferio.9,v 1.5 2015/03/29 21:08:36 riastradh Exp $ 1.\" $NetBSD: bufferio.9,v 1.6 2015/03/30 13:10:04 riastradh Exp $
2.\" 2.\"
3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Taylor R. Campbell. 7.\" by Taylor R. Campbell.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -81,88 +81,99 @@ The parameters to an I/O transfer descri @@ -81,88 +81,99 @@ The parameters to an I/O transfer descri
81.Fa bp 81.Fa bp
82are specified by the following 82are specified by the following
83.Vt "struct buf" 83.Vt "struct buf"
84fields: 84fields:
85.Bl -tag -offset abcd 85.Bl -tag -offset abcd
86.It Fa bp Ns Li "->b_flags" 86.It Fa bp Ns Li "->b_flags"
87Flags specifying the type of transfer. 87Flags specifying the type of transfer.
88.Bl -tag -compact 88.Bl -tag -compact
89.It Dv B_READ 89.It Dv B_READ
90Transfer is read from device. 90Transfer is read from device.
91If not set, transfer is write to device. 91If not set, transfer is write to device.
92.It Dv B_ASYNC 92.It Dv B_ASYNC
93Asynchronous I/O. 93Asynchronous I/O.
94Caller must provide 94Caller must not provide
95.Fa bp Ns Li "->b_iodone" 95.Fa bp Ns Li "->b_iodone"
96and must not call 96and must not call
97.Fn biowait bp . 97.Fn biowait bp .
98.El 98.El
99For legibility, callers should indicate writes by passing the 99For legibility, callers should indicate writes by passing the
100pseudo-flag 100pseudo-flag
101.Dv B_WRITE , 101.Dv B_WRITE ,
102which is zero. 102which is zero.
103.It Fa bp Ns Li "->b_data" 103.It Fa bp Ns Li "->b_data"
104Pointer to kernel virtual address of source/target for transfer. 104Pointer to kernel virtual address of source/target for transfer.
105.It Fa bp Ns Li "->b_bcount" 105.It Fa bp Ns Li "->b_bcount"
106Nonnegative number of bytes requested for transfer. 106Nonnegative number of bytes requested for transfer.
107.It Fa bp Ns Li "->b_blkno" 107.It Fa bp Ns Li "->b_blkno"
108Block number at which to do transfer. 108Block number at which to do transfer.
109.It Fa bp Ns Li "->b_iodone" 109.It Fa bp Ns Li "->b_iodone"
110If 110I/O completion callback.
111.Dv B_ASYNC 111.Dv B_ASYNC
112is set in 112must not be set in
113.Fa bp Ns Li "->b_flags" , 113.Fa bp Ns Li "->b_flags" .
114an I/O completion callback. 
115.El 114.El
116.Pp 115.Pp
117Additionally, if the I/O transfer is a write associated with a 116Additionally, if the I/O transfer is a write associated with a
118.Xr vnode 9 117.Xr vnode 9
119.Fa vp , 118.Fa vp ,
120then before the user submits it to a block device, the user must 119then before the user submits it to a block device, the user must
121increment 120increment
122.Fa vp Ns Li "->v_numoutput" . 121.Fa vp Ns Li "->v_numoutput" .
123The user must not acquire 122The user must not acquire
124.Fa vp Ns Ap s 123.Fa vp Ns Ap s
125vnode lock between incrementing 124vnode lock between incrementing
126.Fa vp Ns Li "->v_numoutput" 125.Fa vp Ns Li "->v_numoutput"
127and submitting 126and submitting
128.Fa bp 127.Fa bp
129to a block device -- doing so will likely cause deadlock with the 128to a block device -- doing so will likely cause deadlock with the
130syncer. 129syncer.
131.Pp 130.Pp
132Block I/O transfers may be synchronous or asynchronous: 131Block I/O transfer completion may be notified by the
 132.Fa bp Ns Li "->b_iodone"
 133callback, by signalling
 134.Fn biowait
 135waiters, or not at all in the
 136.Dv B_ASYNC
 137case.
133.Bl -dash 138.Bl -dash
134.It 139.It
135If synchronous, after submitting the transfer to a block device, the 140If the user sets the
136user must call 141.Fa bp Ns Li "->b_iodone"
 142callback to a nonnull function pointer, it will be called in soft
 143interrupt context when the I/O transfer is complete.
 144The user
 145.Em may not
 146call
137.Fn biowait bp 147.Fn biowait bp
138in order to wait until the transfer has completed. 148in this case.
139.It 149.It
140If asynchronous, the user must set 150If
141.Dv B_ASYNC 151.Dv B_ASYNC
142in 152is set, then the I/O transfer is asynchronous and the user will not be
143.Fa bp Ns Li "->b_flags" 153notified when it is completed.
144and provide 
145.Fa bp Ns Li "->b_iodone" . 
146After submitting the transfer to a block device, 
147.Fa bp Ns Li "->b_iodone" 
148will eventually be called with 
149.Fa bp 
150as its argument when the transfer has completed. 
151The user 154The user
152.Em may not 155.Em may not
153call 156call
154.Fn biowait bp 157.Fn biowait bp
155in this case. 158in this case.
 159.It
 160Otherwise, if
 161.Fa bp Ns Li "->b_iodone"
 162is null and
 163.Dv B_ASYNC
 164is not specified, the user may wait for the I/O transfer to complete
 165with
 166.Fn biowait bp .
156.El 167.El
157.Sh NESTED I/O TRANSFERS 168.Sh NESTED I/O TRANSFERS
158Sometimes an I/O transfer from a single buffer in memory cannot go to a 169Sometimes an I/O transfer from a single buffer in memory cannot go to a
159single location on a block device: it must be split up into smaller 170single location on a block device: it must be split up into smaller
160transfers for each segment of the memory buffer. 171transfers for each segment of the memory buffer.
161.Pp 172.Pp
162After initializing the 173After initializing the
163.Li b_flags , 174.Li b_flags ,
164.Li b_data , 175.Li b_data ,
165and 176and
166.Li b_bcount 177.Li b_bcount
167parameters of an I/O transfer for the buffer, called the 178parameters of an I/O transfer for the buffer, called the
168.Em master 179.Em master
@@ -319,52 +330,61 @@ to an error code and @@ -319,52 +330,61 @@ to an error code and
319.Fa bp Ns Li "->b_resid" 330.Fa bp Ns Li "->b_resid"
320to the number of bytes remaining to transfer. 331to the number of bytes remaining to transfer.
321.It Fn biowait bp 332.It Fn biowait bp
322Wait for the synchronous I/O transfer described by 333Wait for the synchronous I/O transfer described by
323.Fa bp 334.Fa bp
324to complete. 335to complete.
325Returns the value of 336Returns the value of
326.Fa bp Ns Li "->b_error" . 337.Fa bp Ns Li "->b_error" .
327.Pp 338.Pp
328To be called by a user requesting the I/O transfer. 339To be called by a user requesting the I/O transfer.
329.Pp 340.Pp
330May not be called if 341May not be called if
331.Fa bp 342.Fa bp
332represents an asynchronous transfer, i.e. if 343has a callback or is asynchronous -- that is, if
 344.Fa bp Ns Li "->b_iodone"
 345is set, or if
333.Dv B_ASYNC 346.Dv B_ASYNC
334is set in 347is set in
335.Fa bp Ns Li "->b_flags" . 348.Fa bp Ns Li "->b_flags" .
336.It Fn getiobuf vp waitok 349.It Fn getiobuf vp waitok
337Allocate a 350Allocate a
338.Fa struct buf 351.Fa struct buf
339for an I/O transfer. 352for an I/O transfer.
340If 353If
341.Fa vp 354.Fa vp
342is nonnull, the transfer is associated with it. 355is nonnull, the transfer is associated with it.
343If 356If
344.Fa waitok 357.Fa waitok
345is false, 358is false,
346returns null if none can be allocated immediately. 359returns null if none can be allocated immediately.
347.Pp 360.Pp
348The resulting 361The resulting
349.Li struct buf 362.Li struct buf
350pointer must eventually be passed to 363pointer must eventually be passed to
351.Fn putiobuf 364.Fn putiobuf
352to release it. 365to release it.
353Do 366Do
354.Em not 367.Em not
355use 368use
356.Xr brelse 9 . 369.Xr brelse 9 .
357.Pp 370.Pp
 371The buffer may not be used for an asynchronous I/O transfer, because
 372there is no way to know when it is completed and may be safely passed
 373to
 374.Fn putiobuf .
 375Asynchronous I/O transfers are allowed only for buffers in the
 376.Xr buffercache 9 .
 377.Pp
358May sleep if 378May sleep if
359.Fa waitok 379.Fa waitok
360is true. 380is true.
361.It Fn putiobuf bp 381.It Fn putiobuf bp
362Free 382Free
363.Fa bp , 383.Fa bp ,
364which must have been allocated by 384which must have been allocated by
365.Fn getiobuf . 385.Fn getiobuf .
366Either 386Either
367.Fa bp 387.Fa bp
368must never have been submitted to a block device, or the I/O transfer 388must never have been submitted to a block device, or the I/O transfer
369must have completed. 389must have completed.
370.El 390.El