share/man/man9f/physio.9f

   1 '\" te
   2 .\" Copyright (c) 1997, Sun Microsystems, Inc.,
   3 .\" All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH PHYSIO 9F "Apr 2, 1993"
   8 .SH NAME
   9 physio, minphys \- perform physical I/O
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/buf.h>
  15 #include <sys/uio.h>
  16
  17
  18
  19 \fBint\fR \fBphysio\fR(\fBint\fR(\fI*strat\fR)(\fIstruct buf *\fR), \fBstruct buf\fR \fI*bp\fR, \fBdev_t\fR \fIdev\fR,
  20      \fBint\fR \fIrw\fR, \fBvoid\fR (\fI*mincnt\fR)(\fIstruct buf *\fR), \fBstruct uio\fR \fI*uio\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBminphys\fR(\fBstruct buf\fR \fI*bp\fR);
  26 .fi
  27
  28 .SH INTERFACE LEVEL
  29 .sp
  30 .LP
  31 Solaris DDI specific (Solaris DDI).
  32 .SH PARAMETERS
  33 .SS "\fBphysio()\fR"
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIstrat\fR \fR
  38 .ad
  39 .RS 11n
  40 Pointer to device strategy routine.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIbp\fR \fR
  47 .ad
  48 .RS 11n
  49 Pointer to a \fBbuf\fR(9S) structure describing the transfer. If \fIbp\fR is
  50 set to \fINULL\fR then \fBphysio()\fR allocates one which is automatically
  51 released upon completion.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIdev\fR \fR
  58 .ad
  59 .RS 11n
  60 The device number.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIrw\fR \fR
  67 .ad
  68 .RS 11n
  69 Read/write flag. This is either \fBB_READ\fR when reading from the device, or
  70 \fBB_WRITE\fR when writing to the device.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fImincnt\fR \fR
  77 .ad
  78 .RS 11n
  79 Routine which bounds the maximum transfer unit size.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIuio\fR \fR
  86 .ad
  87 .RS 11n
  88 Pointer to the \fBuio\fR structure which describes the user \fBI/O\fR request.
  89 .RE
  90
  91 .SS "\fBminphys()\fR"
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIbp\fR \fR
  96 .ad
  97 .RS 7n
  98 Pointer to a \fBbuf\fR structure.
  99 .RE
 100
 101 .SH DESCRIPTION
 102 .sp
 103 .LP
 104 \fBphysio()\fR performs unbuffered \fBI/O\fR operations between the device
 105 \fIdev\fR and the address space described in the \fBuio\fR structure.
 106 .sp
 107 .LP
 108 Prior to the start of the transfer \fBphysio()\fR verifies the requested
 109 operation is valid by checking the protection of the address space specified in
 110 the \fBuio\fR structure. It then locks the pages involved in the \fBI/O\fR
 111 transfer so they can not be paged out. The device strategy routine,
 112 \fBstrat()\fR, is then called one or more times to perform the physical
 113 \fBI/O\fR operations. \fBphysio()\fR uses \fBbiowait\fR(9F) to block until
 114 \fBstrat()\fR has completed each transfer. Upon completion, or detection of an
 115 error, \fBphysio()\fR unlocks the pages and returns the error status.
 116 .sp
 117 .LP
 118 \fBphysio()\fR uses \fBmincnt()\fR to bound the maximum transfer unit size to
 119 the system, or device, maximum length. \fBminphys()\fR is the system
 120 \fBmincnt()\fR routine for use with \fBphysio()\fR operations. Drivers which do
 121 not provide their own local \fBmincnt()\fR routines should call \fBphysio()\fR
 122 with \fBminphys()\fR.
 123 .sp
 124 .LP
 125 \fBminphys()\fR limits the value of \fIbp\fR\fB->b_bcount\fR to a sensible
 126 default for the capabilities of the system. Drivers that provide their own
 127 \fBmincnt()\fR routine should also call \fBminphys()\fR to make sure they do
 128 not exceed the system limit.
 129 .SH RETURN VALUES
 130 .sp
 131 .LP
 132 \fBphysio()\fR returns:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fB0\fR \fR
 137 .ad
 138 .RS 12n
 139 Upon success.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBnon-zero\fR\fR
 146 .ad
 147 .RS 12n
 148 Upon failure.
 149 .RE
 150
 151 .SH CONTEXT
 152 .sp
 153 .LP
 154 \fBphysio()\fR can be called from user context only.
 155 .SH SEE ALSO
 156 .sp
 157 .LP
 158 \fBstrategy\fR(9E), \fBbiodone\fR(9F), \fBbiowait\fR(9F), \fBbuf\fR(9S),
 159 \fBuio\fR(9S)
 160 .sp
 161 .LP
 162 \fIWriting Device Drivers\fR
 163 .SH WARNINGS
 164 .sp
 165 .LP
 166 Since \fBphysio()\fR calls \fBbiowait()\fR to block until each buf transfer is
 167 complete, it is the drivers responsibility to call \fBbiodone\fR(9F) when the
 168 transfer is complete, or \fBphysio()\fR will block forever.