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

   1 '\" te
   2 .\"  Copyright (c) 1996, 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_DEVICE_COPY 9F "Nov 15, 1996"
   7 .SH NAME
   8 ddi_device_copy \- copy data from one device register to another device
   9 register
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint\fR \fBddi_device_copy\fR(\fBddi_acc_handle_t\fR \fIsrc_handle\fR, \fBcaddr_t\fR \fIsrc_addr\fR,
  19      \fBssize_t\fR \fIsrc_advcnt\fR, \fBddi_acc_handle_t\fR \fIdest_handle\fR,
  20      \fBcaddr_t\fR \fIdest_addr\fR, \fBssize_t\fR \fIdest_advcnt\fR,
  21      \fBsize_t\fR \fIbytecount\fR, \fBuint_t\fR \fIdev_datasz\fR);
  22 .fi
  23
  24 .SH INTERFACE LEVEL
  25 .sp
  26 .LP
  27 Solaris DDI specific (Solaris DDI).
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIsrc_handle\fR \fR
  33 .ad
  34 .RS 16n
  35 The data access handle of the source device.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIsrc_addr\fR \fR
  42 .ad
  43 .RS 16n
  44 Base data source address.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIsrc_advcnt\fR \fR
  51 .ad
  52 .RS 16n
  53 Number of  \fIdev_datasz\fR units to advance on every access.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIdest_handle\fR \fR
  60 .ad
  61 .RS 16n
  62 The data access handle of the destination device.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fIdest_addr\fR \fR
  69 .ad
  70 .RS 16n
  71 Base data destination address.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIdest_advcnt\fR \fR
  78 .ad
  79 .RS 16n
  80 Number of  \fIdev_datasz\fR units to advance on every access.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fIbytecount\fR \fR
  87 .ad
  88 .RS 16n
  89 Number of bytes to transfer.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fIdev_datasz\fR \fR
  96 .ad
  97 .RS 16n
  98 The size of each data word. Possible values are defined as:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBDDI_DATA_SZ01_ACC\fR \fR
 103 .ad
 104 .RS 22n
 105 1 byte data size
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBDDI_DATA_SZ02_ACC\fR \fR
 112 .ad
 113 .RS 22n
 114 2 bytes data size
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBDDI_DATA_SZ04_ACC\fR \fR
 121 .ad
 122 .RS 22n
 123 4 bytes data size
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBDDI_DATA_SZ08_ACC\fR \fR
 130 .ad
 131 .RS 22n
 132 8 bytes data size
 133 .RE
 134
 135 .RE
 136
 137 .SH DESCRIPTION
 138 .sp
 139 .LP
 140 \fBddi_device_copy()\fR copies  \fIbytecount\fR bytes from the source  address,
 141 \fIsrc_addr\fR, to the destination address,  \fIdest_addr\fR. The attributes
 142 encoded in the access handles, \fIsrc_handle\fR and \fIdest_handle\fR, govern
 143 how data is actually copied from the  source to the destination. Only matching
 144 data sizes between the source and destination are supported.
 145 .sp
 146 .LP
 147 Data will automatically be translated to maintain a consistent  view between
 148 the source and the destination. The translation may  involve byte-swapping if
 149 the source and the destination devices  have incompatible endian
 150 characteristics.
 151 .sp
 152 .LP
 153 The  \fIsrc_advcnt\fR and  \fIdest_advcnt\fR arguments specifies the number of
 154 \fIdev_datasz\fR units to advance with each access to the device addresses. A
 155 value of  \fB0\fR will use the same source and destination device address  on
 156 every access. A positive value increments the corresponding device  address by
 157 certain number of data size units in the next access.  On the other hand, a
 158 negative value decrements the device address.
 159 .sp
 160 .LP
 161 The \fIdev_datasz\fR argument determines the size of the data word on each
 162 access. The data size must be the same between the source and destination.
 163 .SH RETURN VALUES
 164 .sp
 165 .LP
 166 \fBddi_device_copy()\fR returns:
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBDDI_SUCCESS\fR \fR
 171 .ad
 172 .RS 16n
 173 Successfully transferred the data.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBDDI_FAILURE\fR \fR
 180 .ad
 181 .RS 16n
 182 The byte count is not a multiple \fIdev_datasz\fR.
 183 .RE
 184
 185 .SH CONTEXT
 186 .sp
 187 .LP
 188 \fBddi_device_copy()\fR can be called from user, kernel, or interrupt context.
 189 .SH SEE ALSO
 190 .sp
 191 .LP
 192 \fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F)
 193 .sp
 194 .LP
 195 \fIWriting Device Drivers\fR