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

   1 '\" te
   2 .\"  Copyright 1989 AT&T  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_COPYOUT 9F "Apr 19, 2000"
   7 .SH NAME
   8 ddi_copyout \- copy data from a driver
   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_copyout\fR(\fBconst void *\fR\fIdriverbuf\fR, \fBvoid *\fR\fIbuf\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\fIdriverbuf\fR\fR
  30 .ad
  31 .RS 13n
  32 Source address in the driver from which the data is transferred.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIbuf\fR\fR
  39 .ad
  40 .RS 13n
  41 Destination address to which the 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 to copy.
  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_copyout()\fR copies data from a driver
  67 buffer to a destination address, \fIbuf\fR.
  68 .sp
  69 .LP
  70 The \fIflags\fR argument determines the address space information about
  71 \fIbuf\fR. If the \fBFKIOCTL\fR flag is set, this indicates that \fIbuf\fR is a
  72 kernel address, and  \fBddi_copyout()\fR behaves like \fBbcopy\fR(9F).
  73 Otherwise,  \fIbuf\fR is interpreted as a user buffer address, and
  74 \fBddi_copyout()\fR behaves like \fBcopyout\fR(9F).
  75 .sp
  76 .LP
  77 Addresses that are word-aligned are moved most efficiently.  However, the
  78 driver developer is not obliged to ensure alignment.  This function
  79 automatically finds the most efficient move algorithm according to address
  80 alignment.
  81 .SH RETURN VALUES
  82 .sp
  83 .LP
  84 Under normal conditions, \fB0\fR is returned to indicate a successful copy.
  85 Otherwise, \(mi\fB1\fR is returned 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_copyout()\fR can be called from user or kernel context only.
 121 .SH EXAMPLES
 122 .LP
 123 \fBExample 1 \fR\fBddi_copyout()\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. In the \fBXX_GETREGS\fR condition (line 25), the
 128 driver copies the current device register values to another data area.  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
 141  7  struct device_state {
 142  8     volatile struct device *regsp;   /* pointer to device registers */
 143  9     kmutex_t reg_mutex;              /* protect device registers */
 144        . . .
 145 10  };
 146
 147 11  static void *statep; /* for soft state routines */
 148
 149 12  xxioctl(dev_t dev, int cmd, int arg, int mode,
 150 13      cred_t *cred_p, int *rval_p)
 151 14  {
 152 15      struct device_state *sp;
 153 16      volatile struct device *rp;
 154 17      struct device reg_buf;     /* temporary buffer for registers */
 155 18      int instance;
 156
 157 19      instance = getminor(dev);
 158 20      sp = ddi_get_soft_state(statep, instance);
 159 21      if (sp == NULL)
 160 22          return (ENXIO);
 161 23      rp = sp->regsp;
 162         . . .
 163 24      switch (cmd)  {
 164
 165 25      case XX_GETREGS:   /* copy registers to arg */
 166 26            mutex_enter(&sp->reg_mutex);
 167 27            /*
 168 28             * Copy data from device registers to
 169 29             * temporary device register buffer
 170 30             * e.g. reg_buf.control = rp->control;
 171 31             */
 172 32            mutex_exit(&sp->reg_mutex);
 173 33            if (ddi_copyout(&reg_buf, arg,
 174 34                sizeof (struct device), mode) != 0) {
 175 35                    return (EFAULT);
 176 36            }
 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_copyin\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_copyout()\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_copyout()\fR should not be used from a streams driver. See
 203 \fBM_COPYIN\fR and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR.