share/man/man9/physio.9

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