usr/src/man/man9f/ddi_copyin.9f

   1 '\" te
   2 .\"  Copyright (c) 2000, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DDI_COPYIN 9F "Apr 19, 2000"
   7 .SH NAME
   8 ddi_copyin \- copy data to a driver buffer
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint\fR \fBddi_copyin\fR(\fBconst void *\fR\fIbuf\fR, \fBvoid *\fR\fIdriverbuf\fR, \fBsize_t\fR \fIcn\fR, \fBint\fR \fIflags\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIbuf\fR\fR
  30 .ad
  31 .RS 13n
  32 Source address from which data is transferred.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIdriverbuf\fR\fR
  39 .ad
  40 .RS 13n
  41 Driver destination address to which data is transferred.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIcn\fR\fR
  48 .ad
  49 .RS 13n
  50 Number of bytes transferred.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIflags\fR\fR
  57 .ad
  58 .RS 13n
  59 Set of flag bits that provide address space information about \fIbuf\fR.
  60 .RE
  61
  62 .SH DESCRIPTION
  63 .sp
  64 .LP
  65 This routine is designed for use in driver \fBioctl\fR(9E) routines for drivers
  66 that support layered ioctls. \fBddi_copyin()\fR copies data from a source
  67 address to a driver buffer.  The driver developer must ensure that adequate
  68 space is allocated for the destination address.
  69 .sp
  70 .LP
  71 The \fIflags\fR argument determines the address space information about
  72 \fIbuf\fR. If the \fBFKIOCTL\fR flag is set, this indicates that \fIbuf\fR is a
  73 kernel address, and  \fBddi_copyin()\fR behaves like \fBbcopy\fR(9F).
  74 Otherwise, \fIbuf\fR is interpreted as a user buffer address, and
  75 \fBddi_copyin()\fR behaves like \fBcopyin\fR(9F).
  76 .sp
  77 .LP
  78 Addresses that are word-aligned are moved most efficiently.  However, the
  79 driver developer is not obliged to ensure alignment.  This function
  80 automatically finds the most efficient move according to address alignment.
  81 .SH RETURN VALUES
  82 .sp
  83 .LP
  84 \fBddi_copyin()\fR returns \fB0\fR, indicating a successful copy. It returns
  85 \(mi\fB1\fR if one of the following occurs:
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 Paging fault; the driver tried to access a page of memory for which it did not
  91 have read or write access.
  92 .RE
  93 .RS +4
  94 .TP
  95 .ie t \(bu
  96 .el o
  97 Invalid user address, such as a user area or stack area.
  98 .RE
  99 .RS +4
 100 .TP
 101 .ie t \(bu
 102 .el o
 103 Invalid address that would have resulted in data being copied into the user
 104 block.
 105 .RE
 106 .RS +4
 107 .TP
 108 .ie t \(bu
 109 .el o
 110 Hardware fault; a hardware error prevented access to the specified user memory.
 111 For example, an uncorrectable parity or \fBECC\fR error occurred.
 112 .RE
 113 .sp
 114 .LP
 115 If \(mi\fB1\fR is returned to the caller, driver entry point routines should
 116 return \fBEFAULT\fR.
 117 .SH CONTEXT
 118 .sp
 119 .LP
 120 \fBddi_copyin()\fR can be called from user or kernel context only.
 121 .SH EXAMPLES
 122 .LP
 123 \fBExample 1 \fR\fBddi_copyin()\fR example
 124 .sp
 125 .LP
 126 A driver \fBioctl\fR(9E) routine (line 12) can be used to get or set device
 127 attributes or registers. For the \fBXX_SETREGS\fR condition (line 25), the
 128 driver copies the user data in \fIarg\fR to the device registers.  If the
 129 specified argument contains an invalid address, an error code is returned.
 130
 131 .sp
 132 .in +2
 133 .nf
 134 1 struct device {           /* layout of physical device registers */
 135  2     int      control;     /* physical device control word */
 136  3     int      status;      /* physical device status word  */
 137  4     short    recv_char;   /* receive character from device */
 138  5     short    xmit_char    /* transmit character to device */
 139  6  };
 140  7  struct device_state {
 141  8     volatile struct device *regsp;   /* pointer to device registers */
 142  9     kmutex_t reg_mutex;              /* protect device registers */
 143        . . .
 144 10  };
 145
 146 11  static void *statep;        /* for soft state routines */
 147
 148 12  xxioctl(dev_t dev, int cmd, int arg, int mode,
 149 13      cred_t *cred_p, int *rval_p)
 150 14  {
 151 15      struct device_state *sp;
 152 16      volatile struct device *rp;
 153 17      struct device reg_buf;  /* temporary buffer for registers */
 154 18      int instance;
 155
 156 19      instance = getminor(dev);
 157 20      sp = ddi_get_soft_state(statep, instance);
 158 21      if (sp == NULL)
 159 22          return (ENXIO);
 160 23      rp = sp->regsp;
 161         . . .
 162 24      switch (cmd)  {
 163
 164 25      case XX_GETREGS:        /* copy data to temp. regs. buf */
 165 26            if (ddi_copyin(arg, &reg_buf,
 166 27                sizeof (struct device), mode) != 0) {
 167 28                    return (EFAULT);
 168 29            }
 169
 170 30            mutex_enter(&sp->reg_mutex);
 171 31            /*
 172 32             * Copy data from temporary device register
 173 33             * buffer to device registers.
 174 34             * e.g. rp->control = reg_buf.control;
 175 35             */
 176 36            mutex_exit(&sp->reg_mutex);
 177
 178 37            break;
 179 38      }
 180 39  }
 181 .fi
 182 .in -2
 183
 184 .SH SEE ALSO
 185 .sp
 186 .LP
 187 \fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyin\fR(9F), \fBcopyout\fR(9F),
 188 \fBddi_copyout\fR(9F), \fBuiomove\fR(9F)
 189 .sp
 190 .LP
 191 \fIWriting Device Drivers\fR
 192 .SH NOTES
 193 .sp
 194 .LP
 195 The value of the \fIflags\fR argument to \fBddi_copyin()\fR should be passed
 196 through directly from the \fImode\fR argument of \fBioctl()\fR untranslated.
 197 .sp
 198 .LP
 199 Driver defined locks should not be held across calls to this function.
 200 .sp
 201 .LP
 202 \fBddi_copyin()\fR should not be used from a streams driver. See \fBM_COPYIN\fR
 203 and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR.