1.\" $OpenBSD: physio.9,v 1.11 2019/12/06 19:12:37 jmc Exp $ 2.\" $NetBSD: physio.9,v 1.5 1999/03/16 00:40:47 garbled Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: December 6 2019 $ 32.Dt PHYSIO 9 33.Os 34.Sh NAME 35.Nm physio 36.Nd initiate I/O on raw devices 37.Sh SYNOPSIS 38.Ft int 39.Fo physio 40.Fa "void (*strategy)(struct buf *)" 41.Fa "dev_t dev" 42.Fa "int flags" 43.Fa "void (*minphys)(struct buf *)" 44.Fa "struct uio *uio" 45.Fc 46.Sh DESCRIPTION 47.Fn physio 48is a helper function typically called from character device read and write 49routines to start I/O on a user process buffer. 50It calls back on the provided 51.Fa strategy 52routine one or more times to complete the transfer described by 53.Fa uio . 54The maximum amount of data to transfer with each call to 55.Fa strategy 56is determined by the 57.Fa minphys 58routine. 59Since 60.Fa uio 61normally describes user space addresses, 62.Fn physio 63needs to lock the appropriate data area into memory before each transaction 64with 65.Fa strategy 66(see 67.Xr uvm_vslock_device 9 68and 69.Xr uvm_vsunlock_device 9 ) . 70.Fn physio 71always awaits the completion of the entire requested transfer before 72returning, unless an error condition is detected earlier. 73.Pp 74In all cases, a temporary buffer is allocated from a system pool. 75This buffer will have the 76.Dv B_BUSY , 77.Dv B_PHYS , 78and 79.Dv B_RAW 80flags set when passed to the strategy routine. 81.Pp 82A break-down of the arguments follows: 83.Bl -tag -width indent 84.It Fa strategy 85The device strategy routine to call for each chunk of data to initiate 86device I/O. 87.It Fa dev 88The device number identifying the device to interact with. 89.It Fa flags 90Direction of transfer; the only valid settings are 91.Dv B_READ 92or 93.Dv B_WRITE . 94.It Fa minphys 95A device specific routine called to determine the maximum transfer size 96that the device's strategy routine can handle. 97.It Fa uio 98The description of the entire transfer as requested by the user process. 99Currently, the results of passing a 100.Fa uio 101structure with the 102.Sq uio_segflg 103set to anything other than 104.Dv UIO_USERSPACE , 105are undefined. 106.El 107.Sh RETURN VALUES 108If successful, 109.Fn physio 110returns 0. 111.Er EFAULT 112is returned if the address range described by 113.Fa uio 114is not accessible by the requesting process. 115.Fn physio 116will return any error resulting from calls to the device strategy routine, 117by examining the 118.Dv B_ERROR 119buffer flag and the 120.Sq b_error 121field. 122Note that the actual transfer size may be less than requested by 123.Fa uio 124if the device signals an 125.Dq end of file 126condition. 127.Sh SEE ALSO 128.Xr read 2 , 129.Xr write 2 , 130.Xr uvm_vslock 9 131