1.\" $OpenBSD: physio.9,v 1.8 2015/09/14 15:14:55 schwarze 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: September 14 2015 $ 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 the 67.Fn uvm_vslock 68and 69.Fn uvm_vsunlock 70functions in 71.Xr uvm 9 ) . 72.Fn physio 73always awaits the completion of the entire requested transfer before 74returning, unless an error condition is detected earlier. 75.Pp 76In all cases, a temporary buffer is allocated from a system pool. 77This buffer will have the 78.Dv B_BUSY , 79.Dv B_PHYS , 80and 81.Dv B_RAW 82flags set when passed to the strategy routine. 83.Pp 84A break-down of the arguments follows: 85.Bl -tag -width indent 86.It Fa strategy 87The device strategy routine to call for each chunk of data to initiate 88device I/O. 89.It Fa dev 90The device number identifying the device to interact with. 91.It Fa flags 92Direction of transfer; the only valid settings are 93.Dv B_READ 94or 95.Dv B_WRITE . 96.It Fa minphys 97A device specific routine called to determine the maximum transfer size 98that the device's strategy routine can handle. 99.It Fa uio 100The description of the entire transfer as requested by the user process. 101Currently, the results of passing a 102.Fa uio 103structure with the 104.Sq uio_segflg 105set to anything other than 106.Dv UIO_USERSPACE , 107are undefined. 108.El 109.Sh RETURN VALUES 110If successful, 111.Fn physio 112returns 0. 113.Er EFAULT 114is returned if the address range described by 115.Fa uio 116is not accessible by the requesting process. 117.Fn physio 118will return any error resulting from calls to the device strategy routine, 119by examining the 120.Dv B_ERROR 121buffer flag and the 122.Sq b_error 123field. 124Note that the actual transfer size may be less than requested by 125.Fa uio 126if the device signals an 127.Dq end of file 128condition. 129.Sh SEE ALSO 130.Xr read 2 , 131.Xr write 2 132